Standard CMP EntityBean

Standard BMP EntityBean

Standard Stateless SessionBean

Standard Stateful SessionBean

jdk1.2.2 CMP EntityBean

jdk1.2.2 BMP EntityBean

jdk1.2.2 Stateless SessionBean

jdk1.2.2 Stateful SessionBean

<call-logging> this tag must have a boolean value: true or false. It tells the container if calls to this bean must be logged or not. It is set to false in standard configurations.

<container-invoker> the container invoker is the entry point to the container. Currently, only the RMI/JRMP container invoker is available.

<container-interceptors> the stack of JBoss interceptors for this bean. You can add your custom interceptor here (for expert use only)

<instance-pool> the instance pool is a set (a "pool") of free (ie not currently associated to a context) instances of the bean. When an instance of the bean is no longer used, it is thrown back to the pool. This is not used for Stateful Session Beans, since the instances are not reusable.

<instance-cache> the cache contains the instances of a bean which are currently associated to a context. If it grows too big, the cache may decide to passivate some of the instances. This is not used for Stateless Session Beans, since these are directly reusable after a call.

<persistence-manager> the persistence manager is in charge of storing permanent information in the instance of a bean. For BMP Entities, it will merely transmit orders to the bean; for Stateful Sessions and CMP Entities, it has to save the state of the bean. This is not used for Stateless Session Beans, since they don't have a state to save.

<container-invoker-conf> configuration of the container invoker.

There are several elements which can nest within container-invoker-conf, one of which is <Optimized>. This controls the behavior of bean method calls within the Java VM in which jboss is running. If the value of Optimized is "false" then the container will behave per the EJB spec and all objects passed into and out of bean remote methods will be marshalled over RMI regardless of whether the client is running remotely or in the same VM as jboss.

If the value of Optimized is "true" then objects passed between bean methods and clients in the jboss java VM will be passed by reference rather than by value. This is much more efficient (and can result in substantial performance improvements) but can result in unexpected behavior. For example, if a bean has a member object and returns that object from a get() method then the EJB-specified behavior is to make a copy of that object which is returned over RMI to the caller. Therefore if the caller modifies the returned object in any way she will modify the copy of the object. If Optimized is "true" then the caller will modify the original object per se, rather than a copy.

<container-cache-conf> configuration of the cache. See below for more details.

<role-mapping-manager>, <security-domain>, <authentication-module> : security options. See the section about JAAS based security in JBoss.

<container-pool-conf> configuration of the pool. Mainly, the size of the pool.

<commit-option> must be A, B, C, D (in CVS version).

Option A: The container caches the beans state between transactions. This options assumes that the bean/container is the only one accessing the persistent data. Therefore the container synchronizes the memory state from the persistent storage only (via ejbLoad) when absolutely neccessary (when the state isn't cached yet), that is before the first business method executes on a found bean or after the bean is passivated and reactivated to serve another business method. This behaviour is regardless of wether the business method executes inside or outside a transaction.

Option B: The container caches the bean between transactions. However, unlike option A the container does not have exclusive access to the persistent storage. Therefore, the container will synchronize the memory state (via ejbLoad) at the beginning of each transaction. Thus business methods executing in a transaction context don't see much benefit from the container caching the bean, whereas business methods executing outside a transaction context (transaction attributes Never, NotSupported or Supports) access the cached (and invalid) state of the bean.

Option C: The container does not cache bean instances and instances memory state is synchronized on every transaction start (via ejbLoad). For business methods executing outside a transaction the synchronization is done too, but as the ejbLoad executes in the same transaction context as the triggering business method, the state must still be considered invalid and might already have changed in the persistent storage when the business method executes.

Option D: This is a JBoss specific feature available in the actual version from CVS only. It enables a lazy read schema, where the beans state is cached between transactions as with option A, but resynchronized from the persistent storage from time to time (via ejbLoad). The default time between resynchronizations is 30 seconds but you may configure the time (in seconds) with <optiond-refresh-rate>42</optiond-refresh-rate>.

With all four commit options the container must synchronize the bean instances cached state with the persistent storage (via ejbStore) at the end of each transaction (just before a commit is done) to be sure the whole transactions state is consistently persistet. As of the EJB specification there is no safe way for the container to decide, if the beans state actually has changed since transaction start, so ejbStore is called, even when all access to the beans business methods was read only. Note, however, that JBoss supports an optional method public boolean isModified() in the beans implementation. If this method returns false, the call to ejbStore is skipped at commit time.

A final note to executing business methods outside of a transaction context: when reading the beans state you always must consider the result as invalid and usable for rough display purposes only, i.e. to fill in a large table, having benefit from bean caching (with options A, B and D) and avoiding unneccessary concurrency; even with commit option A, though you get the actual state initially, another concurrent client might change the beans state a microsecond after your read. Never write access a bean outside a transaction context believing ejbStore will be called for synchronization, it typically will not (though somtimes it might, when the container passivates the bean) be called. Read the EJB specification 1.1 sections 9.1.7.1 and 11.6.3 carefully, if you plan to use the transaction attributes Never, NotSupported or Supports.

To safely write a bean depending on it's current state ever (re)read and write the bean within one and the same transaction context.

<cache-policy-conf> and its subtags are optional, so you can specify none, few or all of them. <min-capacity> specifies the minimum capacity of the cache. The cache can be empty, but will have room for at least 5 beans (in the above case); this value cannot be less than 2; the resizer (see below) will shrink the cache capacity down to but not less than this value.

<max-capacity> specifies the maximum capacity of the cache. The cache can be empty, but will have room for at most 200 beans (in the above case); this value cannot be less than the minimum capacity; the resizer (see below) will enlarge the cache capacity up to but not more than this value.

<overager-period> specifies the period of the overager, that is a periodic task that runs (in the above case) every 300 seconds. Purpose of this periodic task is to see if in the cache there are very old beans, and to passivate them. The age at which a bean is considered too old is also configurable (see below). While the period of this task is 300 seconds, the first run happens at a random time between 0 and 300 seconds. To disable the overager set the period to 0.

<max-bean-age> specifies the max age a bean can have before being passivated by the overager (in this case 600 seconds). The tag <resizer-period> specifies the period of the resizer, that is a periodic task that runs (in the above case) every 400 seconds. Purpose of this periodic task is to shrink / enlarge the cache capacity upon 3 other parameters (see below). While the period of this task is 400 seconds, the first run happens at a random time between 0 and 400 seconds. To disable the resizer set the period to 0.

<max-cache-miss-period>,<min-cache-miss-period> and <cache-load-factor> control the resizer in this way: the number of cache misses is internally recorded. When the resizer runs, it sees what is the cache miss rate from the last time it ran. If there is more than (in the above case) one cache miss every 1 second (min-cache-miss-period) then the resizer tries to enlarge the cache; if there is less than (in this case) one cache miss every 60 seconds (max-cache-miss-period) then the resizer tries to shrink the cache. How much is the cache enlarged / shrinked ? Here is where the load-factor comes in the picture. When the resizer shrinks, it tries to shrink the cache so that (in this case) the ratio number of beans / cache capacity is 0.75; when the resizer enlarges, it tries to enlarge the cache by a factor 1 / 0.75 == 1.333 (in the above case) plus a correction calculated from the cache miss rate (so that the more cache miss rate you have, the more the cache is enlarged, starting from at least 1.333; so if you really have a lot of cache misses, the resizer may decide to enlarge the cache of a factor 2.0 instead of 1.333 - if there is room for that).