weblogic-ejb-jar.xml的元素解析

        做EJB开发，那是几年前的事儿了。虽然EJB2.0一直为开发者所诟病，但它毕竟还是有其自身的优势，比如事务、安全管理，实例生命周期管理等，当然核心还是其提供的分布计算。在EJB规范之外，作为Application Server Vendor，BEA还在规范基础上提供了不少扩展属性，这些属性不是规范要求的，但它提供了额外的功能，对于开发者而言，还是大有用处的。 这些元素可以在weblogic-ejb-jar.xml中配置，下面我们就逐个看看这些元素的含义、作用， 参考文档位于： http://e-docs.bea.com/wls/docs81/ejb/DDreference-ejb-jar.html#1107234

allows-concurrent-calls ：只能用于stateful session bean，表明业务方法是否支持并发访问。规范中要求ejb container，如果出现对stateful session bean并发访问，则抛出remote exception。weblogic对其作了增强， allows-concurrent-calls设为true的时候，并发访问进入时， ejb container可以block该请求，直到前面的方法调用结束。默认为false。

allow-remove-during-transaction：只能能用于stateful session bean，表明在一个事务环境中，stateful session bean的remove()是否可以被调用。allow-remove-during-transaction为false的话，如果在一个事务环境中调用remove(), 那么ejb container会抛出RemoveException。对于那些实现 Synchronization接口的session bean,不能使用该元素。refer to StatefulEJBObject.java(L83)。

cache-between-transactions：用于entity bean，表明事务之间entiy bean的数据cache模式，为false的话，则entiy bean的数据需要load, 否则使用cache中的数据。refer to DBManager.loadBean()。

cache-type：用于entity bean，表明在cache溢满的情况下，cache中的数据移除顺序，可选项为：LRU（Least recently used ）, NRU（Not recently used）。NRU的cache最小值为8，当 max-beans-in-cache小于3的时候，weblogic会将它调整成8。

client-authentication：用于表明EJB是否支持或许要客户端验证。

client-cert-authentication：用于表明EJB是否支持或许要客户端授权。

clients-on-same-server：适用于enterprise bean，表明该ejb的潜在客户端是否位于ejb所部署的同一台managed server上，默认为false。当ejb被部署到cluster上的时候，所以managed server都会通知其他managed server做jndi tree更新，以便让其他server了解该ejb的位置情况。即home的stub中会纪录所有部署该ejb的managed server。如果ejb和其客户端确定位于同一ear中，则可以将其设为true，这样可以降低很多mutli cast开销(weblogic cluster通过multicast实现heartbeat，以保持server状态、jndi tree的更新)。

concurrency-strategy：用于指定cached entity bean的并发访问策略，可选项包括：
Exclusive：当执行事务方法调用的时候，weblogic将会lock cache中的bean instance,直到tx结束，其他请求才能使用该instance。
Database：weblogic将并发访问控制委托给database，根据database的并发控制策略来决定bean instance的并发访问。
ReadOnly：对于read only，这样的bean不涉及数据修改，每个tx对应一个bean instance,可以并行访问。
Optimistic：该策略不会lock任何对象，有weblogic去检查事务期间数据对象是否发生过变化，没有的话，提交事务，否则会滚事务。

confidentiality：用于表明是否支持或需要加密ejb client&server端的数据传递。

connection-factory-jndi-name & destination-jndi-name：用于MDB，表明MDB在创建jms connection时需要使用的jms connection facory，及连接的destination。

create-as-principal-name：用于表明在ejbCreate()方法中连接其他资源的身份。决定ejbCreate中调用身份有三种：create-as-principal-name，ejb-jar.xml中的 run-as指定的角色，匿名，他们按先后顺序选择，如果前面没有配置的话，则使用后面的身份。这个元素仅在ejbCreate方法中的工作不能通过匿名身份完成的时候需要。注意：这个元素只影响stateless和MDB的ejbCreate，为什么没有stateful?  类似元素： remove-as-principal-name, passivate-as-principal-name, and principal-name.

delay-updates-until-end-of-tx：用于entity bean，表明是否延迟update事务中的entity数据直到事务结束。默认为true，这样可以一定程度上因为避免不必要得update而提高性能，但它无法保证事务中update数据的顺序。如果datasource的事务隔离级别为 TransactionReadCommittedUncommitted，即允许未提交的数据被其他客户端读取，那么可以将delay-updates-until-end-of-tx设为false，此时调用的方法需要更新数据的时候，数据会被发送给database，如ejbStore(). 注意：delay-updates-until-end-of-tx为false的时候，事务期间update到db的数据都是uncommitted的，commit/rollback由事务决定。

dispatch-policy：用于指定EJB在哪个线程池上运行，默认线程池为:weblogic.queue.default。对于MDB，使用其他JMS Provider的destination驱动的时候，weblogic可能会忽略diapatch-policy，因为MDB可能会跑在provider的线程上。比如IBM MQSeries的non-tx-queue。对于MQ的tx-queue, nontx-topic & tx-topic，dispatch-policy都是起作用的。对于MDB部署期间，容器负责创建的实例数按照如下算法计算：
default thread pool: maxConcurrentMDBs = Min(max-beans-free-pool, default-thread-pool-size/2+1).如果使用默认thread pool，创建的实例数为max-beans-free-pool和default-thread-pool-size/2+1之间的小者。
customer thread pool: maxConcurrentMDBs = Min(max-beans-free-pool, thread-pool-size).使用定制thread pool的时候，创建的实例数为max-beans-free-pool和thread-pool-size之间的小者。

ejb-local-reference-description & ejb-reference-description：用于指定该bean引用的local/remote ejb的信息，包括ejb-ref-name及jndi-name。name需要和 ejb-ref-name or ejb-local-ref中的匹配。

enable-bean-class-redeploy：默认情况下，ejb的实现类和ejb module中的其他类被同一个class loader加载，他们之间是相互可见的。当 enable-bean-class-redeploy为true的时候，ejb实现类及其父类被ejb module的子类所加载，即ejb实现类和ejb module中的其他类位于不同的class loader中，这样可以使ejb实现类单独redeploy，而无需redeploy module中的其他类。这样用会有个潜在问题，因为ejb实现类和其他类位于不同的class loader中，实现类对于其他类不再可见，其他类不能再引用该实现类。对于该实现类，如果要使用其他类的package protected方法的话，也是不可的，比如EJBHelper，必须将那些方法申明为public。否则会出现 IllegalAccessErrors 。注意：enable这个属性，必须使用two-phase-deploy，关于two-phase-deploy，请参考：http://e-docs.bea.com/wls/docs81/deployment/concepts.html#TwoPhaseDeployment

enable-call-by-reference：用于决定处理ejb方法参数的时候，是传值，还是传引用，而不关心客户端是local or remote。注意：即使enable-call-by-reference为false，下面的情况下还是pass by reference的，
1：local interface的参数传递
2：非序列化的参数
3：When all the business methods in the Remote interface are detected and the Home interface has parameters whose types are immutable.
当enable-call-by-reference为true的时候，因为不需要做参数拷贝，这样可以提高方法性能。

enable-dynamic-queries：该值为true的时候，说明CMP是动态查询的。

entity-cache：用于指定entity bean的cache情况，包括如下子元素： max-beans-in-cache ， idle-timeout-seconds ， read-timeout-seconds ， concurrency-strategy。

entity-cache-ref：用于定义引用 weblogic-application.xml中定义的entity cache信息。

entity-cache-name：为该ejb指定一个app level的cache，app level的cache是为同一app中entity的共享的。这个cache name必须和 weblogic-application.xml定义的name匹配。关于app level entity cache,请参考：http://e-docs.bea.com/wls/docs81/programming/app_xml.html

entity-clustering：指定entity bean在cluster中的复制信息，包括： home-is-clusterable， home-load-algorithm， home call-router-class-name， use-serverside-stubs。

estimated-bean-size：

finders-load-bean：

global-role：


home-is-clusterable：默认为true。如果设定为false，通过initial context lookup到的home stub中只有local server的信息，而不包含cluster中其他server的信息。如果拿到的stub中对应的server为A，如果调用home.create()时，serverA已经crash，那么调用无法被failover到cluster中的其他server，客户端看到的ConnectionException。

home-load-algorithm：指定home的负载算法，默认为 weblogic.cluster.defaultLoadAlgorithm对应的算法，如果没有defaultLoadAlgorithm的话，则为round-robin。可选项包括：
round-robin：说明initial context在lookup home对象的时候，使round-robin的，如果后台有3个server,3个客户端执行lookup，那么返回的home对象分别连接到后端的3个server上。而且home对象上执行的业务方法也是round-robin的，比如serverA上的home在客户端被执行了3次business method，那么这3次business method也是round-robin的，即后端3个server上分别执行了一次。
RoundRobinAffinity：和round-robin基本一样，区别是home business method不是load banlance，而是affinity的，上面例子的结果是：3次business methods都会在serverA上执行。
random | weight-based | RandomAffinity | WeightBasedAffinity

home call-router-class-name：用于指定客户定制的bean method router class名，这个类要求实现weblogic.rmi.cluster.CallRouter，如果指定了这个元素，那么每次方法调用前都会调用该类的一个实例，以根据方法参数决定方法将被route到哪个server上去执行。

idempotent-methods：

identity-assertion：

idle-timeout-seconds：指定stateful session bean在cache中的驻留时间，如果idle-timeout-seconds已过，同时cache中的实例数也达到 max-beans-in-cache，该bean将会从cache中remove，被remove的bean，容器会调用ejbPassivate()，并将从memory中移出。默认为600，最小值为1。

initial-beans-in-free-pool：用于指定deploy的时weblogic在实例池中创建的实例数，默认为0。指定一个具体数值的话，有利于提高首次调用速度（调用时无需再去创建实例），用于stateless session bean, message driven bean, entity bean。

initial-context-factory：用于指定MDB在创建jms connection时使用的jms connection factory的jndi name。

invalidation-target：

is-modified-method-name：

isolation-level：指定ejb的事务隔离级别，可选项为：
TransactionSerializable：
TransactionReadCommitted：只读取其他tx已提交的数据
TransactionReadUncommitted ：允许读取其他tx未提交的数据
TransactionRepeatableRead：如果某数据子集已经被该tx读取过,重复读取相同数据时，将返回同样的结果，尽管期间其他tx可能对该数据作过更新。
下面两个只适用于oracle，同时必须是cmp：
TransactionReadCommittedForUpdate：该值会将isolation-level设为TransactionReadCommitted，同时会在select语句后面加上for update，这将导致select对应的rows被db lock，等待update，然后将其他tx提交后的数据交给该tx。如果在for update的时候，db无法获取到rows的lock，那么select会阻塞，直到获取lock，并得到数据。它可以避免 TRANSACTION_SERIALIZABLE中可能出现的ORA-08177。
TransactionReadCommittedForUpdateNoWait：同上，区别是select后面加上的是for update no wait,如果db无法获取rows的lock，那么select立即返回，同是ejb container会抛出异常。个人理解: for update是锁定对象，不让其他请求进入，否则lock可能被其他对象拿走。

jms-client-id：指定MDB连接到destination时所使用的client id。如果 connection-factory-jndi-name配置了connection factory，而且config.xml中配置了client id，可以使用该id。如果config.xml中没有定义client id，或者没有配置 connection-factory-jndi-name(此时使用默认的connection factory)，那么jms-client-id开始起作用。

jms-polling-interval-seconds：指定在jms server出现故障的时候，MDB重新连接jms server的间隔。MDB为对应destination的consumer，如果destination驻留于其他server或foreign jms provider上，可能因为种种原因，导致remote jms server unreachable，这时MDB就需要主动重现连接。

max-beans-in-free-pool：用于指定实例池中最多能保留实例的个数。pool中实例数大于该值时，ejb container会主动shrink该pool，以减小不必要的内存开销。比如：最大实例数为20，某一时刻并发客户端为50，当这些请求都处理完成时，实例全部还池，那么池中的实例数不做shrink的话，将保持为50，甚至更多。这个最大实例数，需要根据实际应用客户量的情况来做决定。多了浪费内存，少了又影响性能，所以根据实际情况去做权衡。

method-intf：指定哪些接口需要设定isolation level。

max-beans-in-cache：表示cache中的最大实例数，这个数跟entity bean的 concurrency-strategy有关，对于exclusive和readonly， max-beans-in-cache=active beans（ready bean enlisted in a transaction） + ready beans（bean has an identity—an associated primary key， but has not been enlisted in transaction
），对于 concurrency-strategy为 Database的，cache中可以包含 max-beans-in-cache个ready和activate bean实例。

passivate-as-principal-name：类似于create-as-principal name。

persistence-use：用于指定CMP存储相关的信息。

persistent-store-dir：指定stateful sesion bean在做passivate\activate时，session信息的存取目录。

principal-name：在配置role时所指定的真实身份名称，定义 security-role-assignment的时候，至少需要一个principal name。

provider-url：指定MDB在new initial context(调用者实际是ejb container)时所用的provider url，MDB在创建consumer的时候，需要知道从哪个jndi tree上去找connection factory, 去找destination。

read-timeout-seconds：ejb container调用ejbLoad()更新readonly bean数据的时间间隔,默认为600，设为0，表示readonly bean只有被载入cache的时候才会调用ejbLoad()。如果运行期间，bean一直没有从cache中被remove,则该bean不做任何更新。

remote-client-timeout：指定rmi客户端在等待请求返回的timeout时间，即如果指定时间内，ejb没有执行完成，客户端将不再继续等待。使用这个参数需要很小心，当客户端线程不再等待的时候，server的请求并没有随之取消，它将会继续执行下去，直到完成或失败。但对于客户端而言，他并不知道后台的结果。事务一致性无法保证，需要客户端自己在使用该参数时处理事务一致性的问题。

remove-as-principal-name：类似于create-as-principal name。

replication-type：InMomory | None，指定stateful session bean的session是否要在cluster范围内复制，以提供fail over。

res-env-ref-name & res-env-ref-name：指定该ejb对其他resource的引用信息，这些resource需要在ejb-jar.xml中已经定义。

role-name：

run-as-principal-name：

run-as-role-assignment：

security-permission：

security-permission-spec：

security-role-assignment：

session-timeout-seconds：指定ejb container何时会将passivated的数据从disk上删除。比如session-timeout-seconds为600，那么在该session bean passivated到disk后，600秒内没有被activate，它将被ejb container从disk上删除。如果session-timeout-seconds没有指定，那么ejb container会依据idle-timeout-seconds执行删除工作。

stateless-bean-is-clusterable：这个和home-is-clusterable类似，说明bean object的方法调用是否能在server出现故障的时候fail over。

stateless-bean-load-algorithm：这个和home-load-algorithm类似。以round-robin-affinity为例，home在创建bean object的时候，bean object是round-robin在不同server上的，而某个特定bean上的business object invocation是affinity在对应server上的。

stateless-bean-methods-are-idempotent：

trans-timeout-seconds：

transport-requirements：

use-serverside-stubs：

太晚了，有几个没有完成的，周一补上。不过常用的除了trans-timeout-seconds应该全了。呼呼去喽！


Enum Serialization with Weblogic EJB Client

Uncommented Bytes (43 reads)

I was trying to setup an ejb client to connect to an ejb running on a Weblogic 9 app server. I could connect fine, but kept getting a Mismatched serialization uids error on a Java 5 Enum class. After some digging I found a fix on JavaRanch. For whatever reason using the wlclient.jar will not work when serializing enums, but using the full blown weblogic.jar is fine. I'm going to ignore the

ONJava.com -- Migrating a WebLogic EJB Application to JBoss

EJB 3 In Action Examples on WebLogic 10

EJB 3 In Action Code Examples on WebLogic 10

In my previous blog, I made the code examples available for first four chapters of EJB 3 In Action for WebLogic 10. However I did not provide you instructions to run these examples (Chapter 2-4) for WebLogic 10.

Chapter 2 example has a stateless session bean, stateful session bean, an MDB and a JPA Entity. The JPA persistence unit requires a JDBC DataSource and the Stateful/MDB uses a JMS queue.

Chapter 3 depends upon a JDBC DataSource and Chapter 4 uses JDBC DataSource and a JMS Queue.

I’ve provided a build script to configure these resources on the default examplesServer that gets created when you install WebLogic 10.

1. Download examples from here and unzip to a directory say c:ejb3inactionweblogic

2. Set the environment variables for your server as follows:

%BEA_HOME%/wlserver_10.0/samples/domains/wl_server/setExamplesEnv

3. Change to your directory to the directory

cd c:ejb3inactionweblogic

ant CreateResources

This will configure resources such as JDBC DataSource, JMS Connection Factory, Queues, etc.

4. To deploy the application, you can use WLS Admin Console. If you prefer you can use ant to deploy the application for a specific chapter.

cd chapter2
ant

4. To run the application client:

ant run

Hope this helps! I'm working on porting rest of the examples and will make these available sooner.