Bean-Container Contract

Enterprise Bean-Container Contract

The bean container contract describes how the bean can interact with the container to use the services provided by the container.

The container provides a runtime-environment for an enterprise bean and offers services, like container-managed persistence (cmp-beans), container-managed transactions and container-managed security. When developing cmp-beans the programmer has only to describe these services in the deployment descriptor.

Furthermore, the container can provide ressources for the bean, for example JNDI, JNDI and JDBC.

As a result the bean depends on the container in every aspect. There are three ways in which the bean can interact with the container.

1. By implementing callback methods to inform the bean when the bean changes its state.

2. By using the ejb contex object, the reference to the bean intance for the container.

3. By using JNDI.

Each bean has its own specific life cycle. Different callback methods are invoked on a bean instance at a specific time during its life cycle. This document describes the specific life cycles of Enterprise JavaBeans.

Entity-Bean & Container

For every entity bean exists an own pool of instances in the container. The pool is mainly used to optimize the performance. The instances can be used for different entity objects. From client view an entity bean exists as long as the entity object lives in a database.

The Life Cycle of an Entity Bean

The does not exist-state

No instance of the entity bean exists. There a only some files, like the deployment-descriptor, the interface-classes or the bean class itself.

From does not exist-state to the pooled-state

The container creates new instances from a class by calling a Class.newInstance() method on the bean and the container gives the bean its context by calling setEntityContext() method. A bean instance is now existing but without an identity. Now the bean is in a pooled-state.

The pooled-state

In the pooled-state Find() methods and methods that do not need the identity of the bean can be called. There are two possible transitions from the pooled- to the ready-state: by a creation-process or by calling the ejbActivate() method.

Into the ready-state by creating a new entity

The client calls a create() method. This call is sent to the corresponding method ejbCreate(). During the ejbCreate() method the bean-instance intializes its fields with attributes and creates an entity in the database. Now the bean-instance has an identity and changes into the ready-state.

Into the ready-state by calling the ejbActivate() method

An ejbActivate() methode can only be called if the bean-instance has been passivated before. When the ejbActivate() method is calling, the previous state of the bean has to be recreated. The container takes a bean out of the pool and sets the cmp-fields of the bean-instance again. The ejbLoad() method informs the bean that the cmp-fields are set and the bean changes into the ready-state.

The ready-state

In the ready-state, business methods and ejbSelect() methods can be called. An entity bean instance is associated with a specific entity object identity.

Into the pooled-state by calling the ejbPassivate() method

The container calls the ejbPassivate() method to passivate the bean which optimizes the performance. The ejbPassivate() method is used to release ressources. After the ejbPassivate() method has been used the bean-instance returns into the pool. Client-stub still keeps its connection to ejb-object.

Into the pooled-state by calling the ejbRemove() method

The container calls the ejbRemove() method to remove the bean-object from the database and release all used ressources.

The end of the Life Cycle of an Entity Bean

The container calls the unsetEntityContext() method to move from the pooled-state to the doesn't exist-state and destroys the bean instance. This is the last chance to release ressources that have been created in the setEntityContext() method.

Life Cycle of a Stateless Session Bean

The does not exist-state

No instance of the stateless session bean exists. There are only some files, like the deployment-descriptor, the interface-classes or the bean class itself.

From does not exist- to the method-ready pool-state

The container creates new instances from a class by calling a Class.newInstance() method on the bean. The container gives the bean its context by calling setSessionContext() method followed by ejbCreate() method on the instance. A bean new instance is now existing. Now the stateless session bean is in the method-ready pool-state.

The method-ready pool-state

In the method-ready pool-state business methods can be called on the bean instance. When the client calls a business method, the container takes a bean out of the pool to call the method on the bean. While a bean is used by a client, the bean instance is locked for other clients. After operating the business method the container returns the bean into the method-ready pool.

The end of the life cycle of a stateless session bean

The container can call the ejbRemove() method every time it wants to release ressources, as long as a business method is not used by a client. Only the container can call the ejbRemove() method to remove the bean and move from the pooled-ready state to the does not exist-state. This is the chance to release ressources that have been created in the setSessionContext() method.

Life Cycle of a Stateful Session Bean

The does not exist-state

No instance of the stateful session bean exists. There are only some files, like the deployment-descriptor, the interface-classes or the bean class itself.

From the does not exist-state to the method ready-state

The client calls a create() method, this call is sent to the container. The container calls the Class.newInstance() method to create a new bean instance. In the next step the container calls the setSession() method and the ejbCreate() method on the instance and returns the session object reference to the client. Now the bean is in the method ready state.

The method ready-state

The bean is now ready for business methods. Every business method is executed in a transaction context with all features and restrictions of a transaction service.

From method ready-state to does not exist-state

If the client calls the remove() method this call is sent to the corresponding method ejbRemove(). The container calls the ejbRemove() method on the bean instance and the life of the session bean instance and the associated session object ends.

From method ready-state to the passive-state

When the container decides to passivate the bean, by calling the ejbPassivate() method, the container has to store the instance’s state to secondary storage. A session bean can be passivated only between transactions, and not within a transaction.

The passive-state

If a session bean is passivated and the container removes the session object, all object references and handles will be invalid. From client view the session bean is still available. This can be problematic. The session bean would be removed when a timeout is set off or if the container decides to release ressources.

From passive-state to method-ready state

When a client uses a session object and the session bean instance has been passivated, the container will activate the instance. To activate the session bean instance, the instance’s state must be restored from secondary storage by executing the ejbActive() - method.

The Life Cycle of a Message-Driven Bean

From does not exist-state to method-ready pool

The life of a message-driven bean instance starts when the container calls the Class.newInstance() method to create a new instance. Next, the container calls the setMessageDrivenContext() method and the ejbCreate() method on the instance. The message-driven bean is now in the method-ready state.

The method ready-state

The message-driven bean instance is now ready to receive a message and execute its onMessage() method.

From method ready-state to does not exist-state

When the container decides to reduce instances of the method-ready pool to release ressources, the container calls the ejbRemove() method and the life of the message-driven bean instance ends. Only the Container can create and remove a message-driven bean. There are no interfaces to interact with the message-driven bean by the client.