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

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应该全了。呼呼去喽！