CHAPTER 5 EJBs on JBoss - The EJB Container Configuration and Architecture

A jboss.xml stateless session configuration for HA-RMI/HTTP

<jboss>

<enterprise-beans>

<session>

<ejb-name>HelloWorldViaClusteredHTTP</ejb-name>

<jndi-name>helloworld/HelloHA-HTTP</jndi-name>

<invoker-bindings>

<invoker>

<invoker-proxy-binding-name>stateless-httpHA-invoker</invoker-proxy-binding-name>

</invoker>

</invoker-bindings>

<clustered>true</clustered>

</session>

</enterprise-beans>

 

<invoker-proxy-bindings>

<invoker-proxy-binding>

<name>stateless-httpHA-invoker</name>

<invoker-mbean>jboss:service=invoker,type=httpHA</invoker-mbean>

<proxy-factory>org.jboss.proxy.ejb.ProxyFactoryHA</proxy-factory>

<proxy-factory-config>

<client-interceptors>

<home>

<interceptor>org.jboss.proxy.ejb.HomeInterceptor</interceptor>

<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>

<interceptor>org.jboss.proxy.TransactionInterceptor</interceptor>

<interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>

</home>

<bean>

<interceptor>org.jboss.proxy.ejb.StatelessSessionInterceptor</interceptor>

<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>

<interceptor>org.jboss.proxy.TransactionInterceptor</interceptor>

<interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>

</bean>

</client-interceptors>

</proxy-factory-config>

</invoker-proxy-binding>

</invoker-proxy-bindings>

</jboss>

The "stateless-httpHA-invoker" invoker-proxy-binding references the "jboss:service=invoker,type=httpHA" invoker service. This service is configured in the http-invoker.sar/META-INF/jboss-service.xml descriptor, and its default configuration from the sar descriptor is:

<mbean code="org.jboss.invocation.http.server.HttpInvokerHA"

name="jboss:service=invoker,type=httpHA">

<!-- Use a URL of the form

http://<hostname>:8080/invoker/EJBInvokerHAServlet

where <hostname> is InetAddress.getHostname value on which the server

is running.

-->

<attribute name="InvokerURLPrefix">http://</attribute>

<attribute name="InvokerURLSuffix">:8080/invoker/EJBInvokerHAServlet

</attribute>

<attribute name="UseHostName">true</attribute>

</mbean>

The URL used by the invoker proxy is the EJBInvokerHAServlet mapping as deployed on the cluster node. The HttpInvokerHA instances across the cluster form a collection of candidate http URLs that are made available to the client side proxy for failover and/or load balancing.

FIGURE 5-6. The jboss_3_2 DTD elements related to container configuration.

The container-configuration element and its subelements specify container configuration settings for a type of container as given by the container-name element. Each configuration specifies information such as the default invoker type, the container interceptor makeup, instance caches/pools and their sizes, persistence manager, security, and so on. Because this is a large amount of information that requires a detailed understanding of the JBoss container architecture, JBoss ships with a standard configuration for the four types of EJBs. This configuration file is called standardjboss.xml and it is located in the conf directory of any configuration file set that uses EJBs. See An example of a complex container-configuration element from the server/default/conf/standardjboss.xml file.. gives a sample of a configuration from the standardjboss.xml.

An example of a complex container-configuration element from the server/default/conf/standardjboss.xml file.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE jboss PUBLIC

"-//JBoss//DTD JBOSS 3.2//EN"

"http://www.jboss.org/j2ee/dtd/jboss_3_2.dtd">

 

<jboss>

...

<container-configuration>

<container-name>Standard CMP 2.x EntityBean</container-name>

<call-logging>false</call-logging>

<invoker-proxy-binding-name>entity-rmi-invoker</invoker-proxy-binding-name>

<sync-on-commit-only>false</sync-on-commit-only>

<container-interceptors>

<interceptor>org.jboss.ejb.plugins.ProxyFactoryFinderInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.LogInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.SecurityInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.TxInterceptorCMT</interceptor>

<interceptor metricsEnabled="true">org.jboss.ejb.plugins.MetricsInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.EntityCreationInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.EntityLockInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.EntityInstanceInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.EntityReentranceInterceptor</interceptor>

<interceptor>org.jboss.resource.connectionmanager.CachedConnectionInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.EntitySynchronizationInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.cmp.jdbc.JDBCRelationInterceptor</interceptor>

</container-interceptors>

<instance-pool>org.jboss.ejb.plugins.EntityInstancePool</instance-pool>

<instance-cache>org.jboss.ejb.plugins.InvalidableEntityInstanceCache</instance-cache>

<persistence-manager>org.jboss.ejb.plugins.cmp.jdbc.JDBCStoreManager</persistence-manager>

<locking-policy>org.jboss.ejb.plugins.lock.QueuedPessimisticEJBLock</locking-policy>

<container-cache-conf>

<cache-policy>org.jboss.ejb.plugins.LRUEnterpriseContextCachePolicy</cache-policy>

<cache-policy-conf>

<min-capacity>50</min-capacity>

<max-capacity>1000000</max-capacity>

<overager-period>300</overager-period>

<max-bean-age>600</max-bean-age>

<resizer-period>400</resizer-period>

<max-cache-miss-period>60</max-cache-miss-period>

<min-cache-miss-period>1</min-cache-miss-period>

<cache-load-factor>0.75</cache-load-factor>

</cache-policy-conf>

</container-cache-conf>

<container-pool-conf>

<MaximumSize>100</MaximumSize>

</container-pool-conf>

<commit-option>B</commit-option>

</container-configuration>

...

</container-configurations>

</jboss>

See The jboss_3_2 DTD elements related to container configuration..and See An example of a complex container-configuration element from the server/default/conf/standardjboss.xml file.. demonstrate how extensive the container configuration options are. The container configuration information can be specified at two levels. The first is in the standardjboss.xml file contained in the configuration file set directory. The second is at the ejb-jar level. By placing a jboss.xml file in the ejb-jar META-INF directory, you can specify either overrides for container configurations in the standardjboss.xml file, or entirely new named container configurations. This provides great flexibility in the configuration of containers. As you have seen, all container configuration attributes have been externalized and as such are easily modifiable. Knowledgeable developers can even implement specialized container components, such as instance pools or caches, and easily integrate them with the standard container configurations to optimize behavior for a particular application or environment.

FIGURE 5-7. The jboss.xml descriptor EJB to container configuration mapping elements

How an EJB deployment chooses its container configuration is based on the explicit or implict jboss/enterprise-beans/<type>/configuration-name element. See The jboss.xml descriptor EJB to container configuration mapping elements. shows the jboss.xml DTD fragment that shows how an EJB can declare which container configuration it should use.

The configuration-name element is a link to a container-configurations/container-configuration element in See The jboss_3_2 DTD elements related to container configuration... It specifies which container configuration to use for the referring EJB. The link is from a configuration-name element to a container-name element. You are able to specify container configurations per class of EJB by including a container-configuration element in the EJB definition. Typically one does not define completely new container configurations, although this is supported. The typical usage of a jboss.xml level container-configuration is to override one or more aspects of a container-configuration coming from the standardjboss.xml descriptor. This is done by specifying conatiner-configuration that references the name of an existing standardjboss.xml container-configuration/container-name as the value for the container-configuration/extends attribute. See An example of overriding the standardjboss.xml container stateless session beans configuration to enable secured access.. shows an example of defining a new "Secured Stateless SessionBean" configuration that is an extension of the standard stateless session configuration whose name is "Standard Stateless SessionBean".

An example of overriding the standardjboss.xml container stateless session beans configuration to enable secured access.

<?xml version="1.0"?>

<jboss>

<enterprise-beans>

<session>

<ejb-name>EchoBean</ejb-name>

<configuration-name>Secured Stateless SessionBean</configuration-name>

...

</session>

</enterprise-beans>

<container-configurations>

<container-configuration extends="Standard Stateless SessionBean">

<container-name>Secured Stateless SessionBean</container-name>

<!-- Override the container security domain -->

<security-domain>java:/jaas/my-security-domain</security-domain>

</container-configuration>

</container-configurations>

</jboss>

If an EJB does not provide a container configuration specification in the deployment unit ejb-jar, the container factory chooses a container configuration from the standardjboss.xml descriptor based on the type of the EJB. So, in reality there is an implicit configuration-name element for every type of EJB, and the mappings from the EJB type to default container configuration name are as follows:

• container-managed persistence entity version 2.0 = Standard CMP 2.x EntityBean
• container-managed persistence entity version 1.1 = Standard CMP EntityBean
• bean-managed persistence entity = Standard BMP EntityBean
• stateless session = Standard Stateless SessionBean
• stateful session = Standard Stateful SessionBean
• message driven = Standard Message Driven Bean

So, it is not necessary to indicate which container configuration an EJB is using if you want to use the default based on the bean type. It probably provides for a more self-contained descriptor to include the configuration-name element, but this is a matter of style.

Now that you know how to specify which container configuration an EJB is using, and that you can define a deployment unit level override, the question is what are all of those container-configuration child elements? This question will be addressed element by element in the following sections. A number of the elements specify interface class implementations whose configuration is affected by other elements, so before starting in on the configuration elements you need to understand the org.jboss.metadata.XmlLoadable interface.

The XmlLoadable interface is a simple interface that consists of a single method. The interface definition is:

import org.w3c.dom.Element;

public interface XmlLoadable

{

public void importXml(Element element) throws Exception;

}

Classes implement this interface to allow their configuration to be specified via an XML document fragment. The root element of the document fragment is what would be passed to the importXml method. You will see a few examples of this as the container configuration elements are described in the following sections.

The container-name Element

The container-name element specifies a unique name for a given configuration. EJBs link to a particular container configuration by setting their configuration-name element to the value of the container-name for the container configuration.

The call-logging Element

The call-logging element expects a boolean (true or false) as its value to indicate whether or not the LogInterceptor should log method calls to a container. This is somewhat obsolete with the change to log4j, which provides a fine-grained logging API.

The invoker-proxy-binding-name Element

The invoker-proxy-binding-name element specifies the name of the default invoker to use. In the absence of a bean level invoker-bindings specification, the invoker-proxy-binding whose name matches the invoker-proxy-binding-name element value will be used to create home and remote proxies.

The container-interceptors Element

The container-interceptors element specifies one or more interceptor elements that are to be configured as the method interceptor chain for the container. The value of the interceptor element is a fully qualified class name of an org.jboss.ejb.Interceptor interface implementation. The container interceptors form a linked-list structure through which EJB method invocations pass. The first interceptor in the chain is invoked when the MBeanServer passes a method invocation to the container. The last interceptor invokes the business method on the bean. We will discuss the Interceptor interface latter in this chapter when we talk about the container plugin framework. Generally, care must be taken when changing an existing standard EJB interceptor configuration as the EJB contract regarding security, transactions, persistence, and thread safety derive from the interceptors.

The instance-pool and container-pool-conf Elements

 

The instance-cache and container-cache-conf Elements

 

The persistence-manager Element

The persistence-manager element value specifies the fully qualified class name of the persistence manager implementation. The type of the implementation depends on the type of EJB. For stateful session beans it must be an implementation of the org.jboss.ejb.StatefulSessionPersistenceManager interface. For BMP entity beans it must be an implementation of the org.jboss.ejb.EntityPersistenceManager interface, while for CMP entity beans it must be an implementation of the org.jboss.ejb.EntityPersistenceStore interface.

The web-class-loader Element

The web-class-loader element specifies a subclass of org.jboss.web.WebClassLoader that is used in conjunction with the WebService mbean to allow dynamic loading of resources and classes from deployed ears, ejb jars and wars. A WebClassLoader is associated with a Container and must have an org.jboss.mx.loading.UnifiedClassLoader as its parent. It overrides the getURLs() method to return a different set of URLs for remote loading than what is used for local loading.

WebClassLoader has two methods meant to be overriden by subclasses: getKey() and getBytes() . The latter is a no-op in this implementation and should be overriden by subclasses with bytecode generation ability, such as the classloader used by the iiop module.

WebClassLoader subclasses must have a constructor with the same signature as the WebClassLoader(ObjectName containerName, UnifiedClassLoader parent) constructor.

The locking-policy Element

The locking-policy element gives the fully qualified class name of the EJB lock implementation to use. This class must implement the org.jboss.ejb.BeanLock interface. The current JBoss versions include:

• org.jboss.ejb.plugins.lock.MethodOnlyEJBLock , an implementation that does not perform any pessimistic transactional locking. It does provide locking for single-threaded non-reentrant beans. This locking policy is no longer supported as of 3.0.4.
• org.jboss.ejb.plugins.lock.QueuedPessimisticEJBLock , an implementation that holds threads awaiting the transactional lock to be freed in a fair FIFO queue. Non-transactional threads are also put into this wait queue as well. This class pops the next waiting transaction from the queue and notifies only those threads waiting associated with that transaction. The QueuedPessimisticEJBLock is the current default used by the standard configurations.
• org.jboss.ejb.plugins.lock.SimpleReadWriteEJBLock , This lock allows multiple read locks concurrently. Once a writer has requested the lock, future read-lock requests whose transactions do not already have the read lock will block until all writers are done -- then all the waiting readers will concurrently go (depending on the reentrant setting / methodLock). A reader who promotes gets first crack at the write lock -- ahead of other waiting writers. If there is already a reader that is promoting, we throw an inconsistent read exception. Of course, writers have to wait for all read-locks to release before taking the write lock.
• org.jboss.ejb.plugins.lock.NoLock , an anti-locking policy used with the "Instance Per Transaction *" container configurations.
• org.jboss.ejb.plugins.lock.JDBCOptimisticLock , an alternate optimistic locking policy for use with the "Instance Per Transaction CMP 2.x EntityBean" container configuration.

We will talk in more detail about the locking policy usage in section Entity Bean Locking and Deadlock Detection

The commit-option and optiond-refresh-rate Element

The commit-option value specifies the EJB entity bean persistent storage commit option. It must be one of A, B, C or D. The meaning of the option values is:

• A, the container caches the beans state between transactions. This option assumes that the container is the only user accessing the persistent store. This assumption allows the container to synchronize the in-memory state from the persistent storage only when absolutely necessary. This occurs before the first business method executes on a found bean or after the bean is passivated and reactivated to serve another business method. This behavior is independent of whether the business method executes inside a transaction context.
• B, the container caches the bean state between transactions. However, unlike option A the container does not assume exclusive access to the persistent store. Therefore, the container will synchronize the in-memory state 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 potentially invalid) state of the bean.
• C, the container does not cache bean instances. The in-memory state must be synchronized on every transaction start. For business methods executing outside a transaction the synchronization is still performed, but the ejbLoad executes in the same transaction context as that of the caller.
• D, is a JBoss specific feature which is not described in the EJB specification. It is a lazy read scheme where bean state is cached between transactions as with option A, but the state is periodically resynchronized with that of the persistent store. The default time between reloads is 30 seconds, but may configured using the optiond-refresh-rate element.

The security-domain Element

Inside the EJB org.jboss.ejb.Container classThe security-domain element specifies the JNDI name of the object that implements the org.jboss.security.AuthenticationManager and org.jboss.security.RealmMapping interfaces. Usually one specifies the security-domain globally under the jboss root element so that all EJBs in a given deployment are secured. The details of the security manager interfaces and configuring the security layer are discussed in Security on JBoss - J2EE Security Configuration and Architecture.

cluster-config

 

depends

The org.jboss.ejb.ContainerPlugin interface

public interface ContainerPlugin extends org.jboss.system.Service

{

/** This callback is set by the container so that the plugin

* may access its container

*

* @param con the container which owns the plugin

*/

public void setContainer(Container con);

}

The org.jboss.ejb.Interceptor interface

import org.jboss.invocation.Invocation;

public interface Interceptor extends ContainerPlugin

{

public void setNext(Interceptor interceptor);

public Interceptor getNext();

public Object invokeHome(Invocation mi) throws Exception;

public Object invoke(Invocation mi) throws Exception;

}

All interceptors defined in the container configuration are created and added to the container interceptor chain by the EJBDeployer. The last interceptor is not added by the deployer but rather by the container itself because this is the interceptor that interacts with the EJB bean implementation.

The order of the interceptor in the chain is important. The idea behind ordering is that interceptors that are not tied to a particular EnterpriseContext instance are positioned before interceptors that interact with caches and pools.

Implementers of the Interceptor interface form a linked-list like structure through which the Invocation object is passed. The first interceptor in the chain is invoked when an invoker passes a Invocation to the container via the JMX bus. The last interceptor invokes the business method on the bean. There are usually on the order of five interceptors in a chain depending on the bean type and container configuration. Interceptor semantic complexity ranges from simple to complex. An example of a simple interceptor would be LoggingInterceptor, while a complex example is EntitySynchronizationInterceptor.

One of the main advantages of an interceptor pattern is flexibility in the arrangement of interceptors. Another advantage is the clear functional distinction between different interceptors. For example, logic for transaction and security is cleanly separated between the TXInterceptor and SecurityInterceptor respectively.

If any of the interceptors fail, the call is terminated at that point. This is a fail-quickly type of semantic. For example, if a secured EJB is accessed without proper permissions, the call will fail as the SecurityInterceptor before any transactions are started or instances caches are updated.

The org.jboss.ejb.InstancePool interface

public interface InstancePool extends ContainerPlugin

{

/** Get an instance without identity. Can be used

* by finders and create-methods, or stateless beans

*

* @return Context /w instance

* @exception RemoteException

*/

public EnterpriseContext get() throws Exception;

/** Return an anonymous instance after invocation.

*

* @param ctx

*/

public void free(EnterpriseContext ctx);

/** Discard an anonymous instance after invocation.

* This is called if the instance should not be reused,

* perhaps due to some exception being thrown from it.

*

* @param ctx

*/

public void discard(EnterpriseContext ctx);

/**

* Return the size of the pool.

*

* @return the size of the pool.

*/

public int getCurrentSize();

/**

* Get the maximum size of the pool.

*

* @return the size of the pool.

*/

public int getMaxSize();

}

Depending on the configuration, a container may choose to have a certain size of the pool contain recycled instances, or it may choose to instantiate and initialize an instance on demand.

The pool is used by the InstanceCache implementation to acquire free instances for activation, and it is used by interceptors to acquire instances to be used for Home interface methods (create and finder calls).

The org.jboss.ejb.InstanceCache interface

public interface InstanceCache extends ContainerPlugin

{

/**

* Gets a bean instance from this cache given the identity.

* This method may involve activation if the instance is not
* in the cache.

* Implementation should have O(1) complexity.

* This method is never called for stateless session beans.

*

* @param id the primary key of the bean

* @return the EnterpriseContext related to the given id

* @exception RemoteException in case of illegal calls

* (concurrent / reentrant), NoSuchObjectException if

* the bean cannot be found.

* @see #release

*/

public EnterpriseContext get(Object id)

throws RemoteException, NoSuchObjectException;

/**

* Inserts an active bean instance after creation or activation.

* Implementation should guarantee proper locking and O(1) complexity.

*

* @param ctx the EnterpriseContext to insert in the cache

* @see #remove

*/

public void insert(EnterpriseContext ctx);

/**

* Releases the given bean instance from this cache.

* This method may passivate the bean to get it out of the cache.

* Implementation should return almost immediately leaving the

* passivation to be executed by another thread.

*

* @param ctx the EnterpriseContext to release

* @see #get

*/

public void release(EnterpriseContext ctx);

/** Removes a bean instance from this cache given the identity.

* Implementation should have O(1) complexity and guarantee

* proper locking.

*

* @param id the pimary key of the bean

* @see #insert

*/

public void remove(Object id);

/** Checks whether an instance corresponding to a particular

* id is active

*

* @param id the pimary key of the bean

* @see #insert

*/

public boolean isActive(Object id);

}

In addition to managing the list of active instances, the InstanceCache is also responsible for activating and passivating instances. If an instance with a given identity is requested, and it is not currently active, the InstanceCache must use the InstancePool to acquire a free instance, followed by the persistence manager to activate the instance. Similarly, if the InstanceCache decides to passivate an active instance, it must call the persistence manager to passivate it and release the instance to the InstancePool.

The org.jboss.ejb.EntityPersistenceManager interface

public interface EntityPersistenceManager extends ContainerPlugin

{

/**

* Returns a new instance of the bean class or a subclass of the bean class.

*

* @return the new instance

*/

Object createBeanClassInstance() throws Exception;

/**

* This method is called whenever an entity is to be created. The

* persistence manager is responsible for calling the ejbCreate method

* on the instance and to handle the results properly wrt the persistent

* store.

*

* @param m the create method in the home interface that was

* called

* @param args any create parameters

* @param instance the instance being used for this create call

*/

void createEntity(Method m,

Object[] args,

EntityEnterpriseContext instance)

throws Exception;

/**

* This method is called whenever an entity is to be created. The

* persistence manager is responsible for calling the ejbPostCreate method

* on the instance and to handle the results properly wrt the persistent

* store.

*

* @param m the create method in the home interface that was

* called

* @param args any create parameters

* @param instance the instance being used for this create call

*/

void postCreateEntity(Method m,

Object[] args,

EntityEnterpriseContext instance)

throws Exception;

/**

* This method is called when single entities are to be found. The

* persistence manager must find out whether the wanted instance is

* available in the persistence store, and if so it shall use the

* ContainerInvoker plugin to create an EJBObject to the instance, which

* is to be returned as result.

*

* @param finderMethod the find method in the home interface that was

* called

* @param args any finder parameters

* @param instance the instance to use for the finder call

* @return an EJBObject representing the found entity

*/

Object findEntity(Method finderMethod,

Object[] args,

EntityEnterpriseContext instance)

throws Exception;

/**

* This method is called when collections of entities are to be found. The

* persistence manager must find out whether the wanted instances are

* available in the persistence store, and if so it shall use the

* ContainerInvoker plugin to create EJBObjects to the instances, which are

* to be returned as result.

*

* @param finderMethod the find method in the home interface that was

* called

* @param args any finder parameters

* @param instance the instance to use for the finder call

* @return an EJBObject collection representing the found

* entities

*/

Collection findEntities(Method finderMethod,

Object[] args,

EntityEnterpriseContext instance)

throws Exception;

/**

* This method is called when an entity shall be activated. The persistence

* manager must call the ejbActivate method on the instance.

*

* @param instance the instance to use for the activation

*

* @throws RemoteException thrown if some system exception occurs

*/

void activateEntity(EntityEnterpriseContext instance)

throws RemoteException;

/**

* This method is called whenever an entity shall be load from the

* underlying storage. The persistence manager must load the state from

* the underlying storage and then call ejbLoad on the supplied instance.

*

* @param instance the instance to synchronize

*

* @throws RemoteException thrown if some system exception occurs

*/

void loadEntity(EntityEnterpriseContext instance)

throws RemoteException;

/**

* This method is used to determine if an entity should be stored.

*

* @param instance the instance to check

* @return true, if the entity has been modified

* @throws Exception thrown if some system exception occurs

*/

boolean isModified(EntityEnterpriseContext instance) throws Exception;

/**

* This method is called whenever an entity shall be stored to the

* underlying storage. The persistence manager must call ejbStore on the

* supplied instance and then store the state to the underlying storage.

*

* @param instance the instance to synchronize

*

* @throws RemoteException thrown if some system exception occurs

*/

void storeEntity(EntityEnterpriseContext instance)

throws RemoteException;

/**

* This method is called when an entity shall be passivate. The persistence

* manager must call the ejbPassivate method on the instance.

*

* @param instance the instance to passivate

*

* @throws RemoteException thrown if some system exception occurs

*/

void passivateEntity(EntityEnterpriseContext instance)

throws RemoteException;

/**

* This method is called when an entity shall be removed from the

* underlying storage. The persistence manager must call ejbRemove on the

* instance and then remove its state from the underlying storage.

*

* @param instance the instance to remove

*

* @throws RemoteException thrown if some system exception occurs

* @throws RemoveException thrown if the instance could not be removed

*/

void removeEntity(EntityEnterpriseContext instance)

throws RemoteException, RemoveException;

}

As per the EJB 2.0 specification, JBoss supports two entity bean persistence semantics: Container Managed Persistence (CMP) and Bean Managed Persistence (BMP). The CMP implementation uses an implementation of the org.jboss.ejb.EntityPersistanceStore interface. By default this is the org.jboss.ejb.plugins.cmp.jdbc.JDBCStoreManager which is the entry point for the CMP2 persistence engine. See The org.jboss.ejb.EntityPersistanceStore interface. gives the EntityPersistanceStore interface.

The org.jboss.ejb.EntityPersistanceStore interface

public interface EntityPersistenceStore extends ContainerPlugin

{

/**

* Returns a new instance of the bean class or a subclass of the bean class.

*

* @return the new instance

*

* @throws Exception

*/

Object createBeanClassInstance() throws Exception;

/**

* Initializes the instance context.

*

* <p>This method is called before createEntity, and should

* reset the value of all cmpFields to 0 or null.

*

* @param ctx

*

* @throws RemoteException

*/

void initEntity(EntityEnterpriseContext ctx);

/**

* This method is called whenever an entity is to be created.

* The persistence manager is responsible for handling the results properly

* wrt the persistent store.

*

* @param m the create method in the home interface that was

* called

* @param args any create parameters

* @param instance the instance being used for this create call

* @return The primary key computed by CMP PM or null for BMP

*

* @throws Exception

*/

Object createEntity(Method m,

Object[] args,

EntityEnterpriseContext instance)

throws Exception;

/**

* This method is called when single entities are to be found. The

* persistence manager must find out whether the wanted instance is

* available in the persistence store, if so it returns the primary key of

* the object.

*

* @param finderMethod the find method in the home interface that was

* called

* @param args any finder parameters

* @param instance the instance to use for the finder call

* @return a primary key representing the found entity

*

* @throws RemoteException thrown if some system exception occurs

* @throws FinderException thrown if some heuristic problem occurs

*/

Object findEntity(Method finderMethod,

Object[] args,

EntityEnterpriseContext instance)

throws Exception;

/**

* This method is called when collections of entities are to be found. The

* persistence manager must find out whether the wanted instances are

* available in the persistence store, and if so it must return a

* collection of primaryKeys.

*

* @param finderMethod the find method in the home interface that was

* called

* @param args any finder parameters

* @param instance the instance to use for the finder call

* @return an primary key collection representing the found

* entities

*

* @throws RemoteException thrown if some system exception occurs

* @throws FinderException thrown if some heuristic problem occurs

*/

Collection findEntities(Method finderMethod,

Object[] args,

EntityEnterpriseContext instance)

throws Exception;

/**

* This method is called when an entity shall be activated.

*

* <p>With the PersistenceManager factorization most EJB calls should not

* exists However this calls permits us to introduce optimizations in

* the persistence store. Particularly the context has a

* "PersistenceContext" that a PersistenceStore can use (JAWS does for

* smart updates) and this is as good a callback as any other to set it

* up.

* @param instance the instance to use for the activation

*

* @throws RemoteException thrown if some system exception occurs

*/

void activateEntity(EntityEnterpriseContext instance)

throws RemoteException;

/**

* This method is called whenever an entity shall be load from the

* underlying storage. The persistence manager must load the state from

* the underlying storage and then call ejbLoad on the supplied instance.

*

* @param instance the instance to synchronize

*

* @throws RemoteException thrown if some system exception occurs

*/

void loadEntity(EntityEnterpriseContext instance)

throws RemoteException;

/**

* This method is used to determine if an entity should be stored.

*

* @param instance the instance to check

* @return true, if the entity has been modified

* @throws Exception thrown if some system exception occurs

*/

boolean isModified(EntityEnterpriseContext instance) throws Exception;

/**

* This method is called whenever an entity shall be stored to the

* underlying storage. The persistence manager must call ejbStore on the

* supplied instance and then store the state to the underlying storage.

*

* @param instance the instance to synchronize

*

* @throws RemoteException thrown if some system exception occurs

*/

void storeEntity(EntityEnterpriseContext instance)

throws RemoteException;

/**

* This method is called when an entity shall be passivate. The persistence

* manager must call the ejbPassivate method on the instance.

*

* <p>See the activate discussion for the reason for exposing EJB callback

* calls to the store.

*

* @param instance the instance to passivate

*

* @throws RemoteException thrown if some system exception occurs

*/

void passivateEntity(EntityEnterpriseContext instance)

throws RemoteException;

/**

* This method is called when an entity shall be removed from the

* underlying storage. The persistence manager must call ejbRemove on the

* instance and then remove its state from the underlying storage.

*

* @param instance the instance to remove

*

* @throws RemoteException thrown if some system exception occurs

* @throws RemoveException thrown if the instance could not be removed

*/

void removeEntity(EntityEnterpriseContext instance)

throws RemoteException, RemoveException;

}

The default BMP implementation of the EntityPersistenceManager interface is org.jboss.ejb.plugins.BMPPersistenceManager. The BMP persistence manager is fairly simple since all persistence logic is in the entity bean itself. The only duty of the persistence manager is to perform container callbacks.

The org.jboss.ejb.StatefulSessionPersistenceManager interface

public interface StatefulSessionPersistenceManager extends
ContainerPlugin

{

public void createSession(Method m, Object[] args,

StatefulSessionEnterpriseContext ctx)

throws Exception;

public void activateSession(StatefulSessionEnterpriseContext ctx)

throws RemoteException;

public void passivateSession(StatefulSessionEnterpriseContext ctx)

throws RemoteException;

public void removeSession(StatefulSessionEnterpriseContext ctx)

throws RemoteException, RemoveException;

public void removePassivated(Object key);

}

The default implementation of the StatefulSessionPersistenceManager interface is org.jboss.ejb.plugins.StatefulSessionFilePersistenceManager. As its name implies, StatefulSessionFilePersistenceManager utilizes the file system to persist stateful session beans. More specifically, the persistence manager serializes beans in a flat file whose name is composed of the bean name and session id with a .ser extension. The persistence manager restores a bean's state during activation and respectively stores its state during passivation from the bean's .ser file.

An example blocked transaction table

 

Blocking TX	Tx that holds needed lock
Tx1	Tx2
Tx3	Tx4
Tx4	Tx1

Before the thread actually blocks it tries to detect whether there is deadlock problem. It does this by traversing the block transaction graph. As it traverses the graph, it keeps track of what transactions are blocked. If it sees a blocked node more than once in the graph, then it knows there is deadlock and will throw an ApplicationDeadlockException. This exception will cause a transaction rollback which will cause all locks that transaction holds to be released. The algorithm for the deadlock dection is found in the BeanLockSupport deadlockDetection method. The code for this method is shown in See The org.jboss.ejb.plugins.lock.BeanLockSupport deadlockDetection method..

The org.jboss.ejb.plugins.lock.BeanLockSupport deadlockDetection method

// This following is for deadlock detection

protected static HashMap waiting = new HashMap();

public void deadlockDetection(Transaction miTx) throws Exception

{

HashSet set = new HashSet();

set.add(miTx);

Object checkTx = this.tx;

synchronized(waiting)

{

while (checkTx != null)

{

Object waitingFor = waiting.get(checkTx);

if (waitingFor != null)

{

if (set.contains(waitingFor))

{

log.error("Application deadlock detected: " + miTx + " has deadlock conditions");

throw new ApplicationDeadlockException("application deadlock detected");

}

set.add(waitingFor);

}

checkTx = waitingFor;

}

}

}

Catching ApplicationDeadlockException

Since JBoss can detect application deadlock, you should write your application so that it can retry a transaction if the invocation fails because of the ApplicationDeadlockException. Unfortunately, this exception can be deeply embedded within a RemoteException, so you have to search for it in your catch block. For example:

try

{

...

}

catch (RemoteException ex)

{

Throwable cause = null;

RemoteException rex = ex;

while (rex.detail != null)

{

cause = rex.detail;

if (cause instanceof ApplicationDeadlockException)

{

// ... We have deadlock, force a retry of the transaction.

break;

}

if (cause instanceof RemoteException)

{

rex = (RemoteException)cause;

}

}

}

Viewing Lock Information

A new org.jboss.monitor.EntityLockMonitor MBean service was added in JBoss 3.0.4 that allows one to view basic locking statistics as well as printing out the state of the transaction locking table. To enable this monitor uncomment its configuration in the conf/jboss-service.xml:

<mbean code="org.jboss.monitor.EntityLockMonitor"

name="jboss.monitor:name=EntityLockMonitor"/>

Marking an entity bean read-only using jboss.xml

<jboss>

<enterprise-beans>

<entity>

<ejb-name>MyEntityBean</ejb-name>

<jndi-name>MyEntityHomeRemote</jndi-name>

<read-only>True</read-only>

</entity>

</enterprise-beans>

</jboss>

Defining entity bean methods as read-only

<jboss>

<enterprise-beans>

<entity>

<ejb-name>nextgen.EnterpriseEntity</ejb-name>

<jndi-name>nextgen.EnterpriseEntity</jndi-name>

<method-attributes>

<method>

<method-name>get*</method-name>

<read-only>true</read-only>

</method>

<method>

<method-name>anotherReadOnlyMethod</method-name>

<read-only>true</read-only>

</method>

</method-attributes>

</entity>

</enterprise-beans>

</jboss>

An example of using the Instance Per Transaction policy.

<jboss>

<enterprise-beans>

<entity>

<ejb-name>MyCMP2Bean</ejb-name>

<jndi-name>MyCMP2</jndi-name>

<configuration-name>Instance Per Transaction CMP 2.x EntityBean</configuration-name>

</entity>

<entity>

<ejb-name>MyBMPBean</ejb-name>

<jndi-name>MyBMP</jndi-name>

<configuration-name>Instance Per Transaction BMP EntityBean</configuration-name>

</entity>

</enterprise-beans>

</jboss>

If you're using JBoss 3.0.0, you'll have to setup the configuration yourself within the jboss.xml descriptor. The highlighted code shown in See The Instance Per Transaction configuration . is what is new in the configuration.

The Instance Per Transaction configuration

<jboss>

<container-configurations>

<container-configuration>

<container-name>Instance Per Transaction CMP 2.x EntityBean</container-name>

<call-logging>false</call-logging>

<container-invoker>org.jboss.proxy.ejb.ProxyFactory</container-invoker>

<container-interceptors>

<interceptor>org.jboss.ejb.plugins.LogInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.SecurityInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.TxInterceptorCMT</interceptor>

<interceptor metricsEnabled = "true">org.jboss.ejb.plugins.MetricsInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.EntityCreationInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.EntityLockInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.EntityMultiInstanceInterceptor</interceptor>

<interceptor>org.jboss.resource.connectionmanager.CachedConnectionInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.EntityMultiInstanceSynchronizationInterceptor</interceptor>

<interceptor>org.jboss.ejb.plugins.cmp.jdbc.JDBCRelationInterceptor</interceptor>

</container-interceptors>

<client-interceptors>

<home>

<interceptor>org.jboss.proxy.ejb.HomeInterceptor</interceptor>

<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>

<interceptor>org.jboss.proxy.TransactionInterceptor</interceptor>

<interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>

</home>

<bean>

<interceptor>org.jboss.proxy.ejb.EntityInterceptor</interceptor>

<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>

<interceptor>org.jboss.proxy.TransactionInterceptor</interceptor>

<interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>

</bean>

<list-entity>

<interceptor>org.jboss.proxy.ejb.ListEntityInterceptor</interceptor>

<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>

<interceptor>org.jboss.proxy.TransactionInterceptor</interceptor>

<interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>

</list-entity>

</client-interceptors>

<instance-pool>org.jboss.ejb.plugins.EntityInstancePool</instance-pool>

<instance-cache>org.jboss.ejb.plugins.EntityInstanceCache</instance-cache>

<persistence-manager>org.jboss.ejb.plugins.cmp.jdbc.JDBCStoreManager</persistence-manager>

<transaction-manager>org.jboss.tm.TxManager</transaction-manager>

<locking-policy>org.jboss.ejb.plugins.lock.MethodOnlyEJBLock</locking-policy>

<container-cache-conf>

<cache-policy>org.jboss.ejb.plugins.LRUEnterpriseContextCachePolicy</cache-policy>

<cache-policy-conf>

<min-capacity>50</min-capacity>

<max-capacity>1000000</max-capacity>

<overager-period>300</overager-period>

<max-bean-age>600</max-bean-age>

<resizer-period>400</resizer-period>

<max-cache-miss-period>60</max-cache-miss-period>

<min-cache-miss-period>1</min-cache-miss-period>

<cache-load-factor>0.75</cache-load-factor>

</cache-policy-conf>

</container-cache-conf>

<container-pool-conf>

<MaximumSize>100</MaximumSize>

</container-pool-conf>

<commit-option>B</commit-option>

<container-configuration>