EJB.9.3 The Responsibilities of the Container Provider

This section describes the responsibilities of the container provider to support entity beans. The container provider is responsible for providing the deployment tools, and for managing entity bean instances at runtime.

Because the EJB specification does not define the API between deployment tools and the container, we assume that the deployment tools are provided by the container provider. Alternatively, the deployment tools may be provided by a different vendor who uses the container vendor's specific API.

EJB.9.3.1 Generation of Implementation Classes

The deployment tools provided by the container provider are responsible for the generation of additional classes when the entity bean is deployed. The tools obtain the information that they need for generation of the additional classes by intro-specting the classes and interfaces provided by the entity bean provider and by examining the entity bean's deployment descriptor.

The deployment tools must generate the following classes:

• A class that implements the entity bean's home interface (i.e., the entity EJBHome class)

• A class that implements the entity bean's remote interface (i.e., the entity EJBObject class)

The deployment tools may also generate a class that mixes some container-specific code with the entity bean class. The code may, for example, help the container to manage the entity bean instances at runtime. Tools can use subclassing, delegation, and code generation.

The deployment tools may also allow generation of additional code that wraps the business methods and that is used to customize the business logic for an existing operational environment. For example, a wrapper for a debit function on the Account bean may check that the debited amount does not exceed a certain limit, or perform security checking that is specific to the operational environment.

EJB.9.3.2 Entity EJBHome Class

The entity EJBHome class, which is generated by deployment tools, implements the entity bean's home interface. This class implements the methods of the javax.ejb.EJBHome interface, and the type-specific create and finder methods specific to the entity bean.

The implementation of each create(...) method invokes a matching ejbCreate(...) method, followed by the matching ejbPostCreate(...) method, passing the create(...) parameters to these matching methods.

The implementation of the remove(...) methods defined in the javax.ejb.EJBHome interface must activate an instance (if an instance is not already in the ready state) and invoke the ejbRemove method on the instance.

The implementation of each find<METHOD>(...) method invokes a matching ejbFind<METHOD>(...) method. The implementation of the find<METHOD>(...) method must create an entity object reference for the primary key returned from the ejbFind<METHOD> and return the entity object reference to the client. If the ejbFind<METHOD> method returns a collection of primary keys, the implementation of the find<METHOD>(...) method must create a collection of entity object references for the primary keys and return the collection to the client.

EJB.9.3.3 Entity EJBObject Class

The entity EJBObject class, which is generated by deployment tools, implements the entity bean's remote interface. It implements the methods of the javax.ejb.EJBObject interface and the business methods specific to the entity bean.

The implementation of the remove(...) method (defined in the javax.ejb.EJBObject interface) must activate an instance (if an instance is not already in the ready state) and invoke the ejbRemove method on the instance.

The implementation of each business method must activate an instance (if an instance is not already in the ready state) and invoke the matching business method on the instance.

EJB.9.3.4 Handle Class

The deployment tools are responsible for implementing the handle class for the entity bean. The handle class must be serializable by the Java programming language Serialization protocol.

As the handle class is not entity bean specific, the container may, but is not required to, use a single class for all deployed entity beans.

EJB.9.3.5 Home Handle Class

The deployment tools are responsible for implementing the home handle class for the entity bean. The handle class must be serializable by the Java programming language Serialization protocol.

Because the home handle class is not entity bean specific, the container may, but is not required to, use a single class for the home handles of all deployed entity beans.

EJB.9.3.6 Meta-Data Class

The deployment tools are responsible for implementing the class that provides meta-data information to the client view contract. The class must be a valid RMI-IIOP value type, and must implement the javax.ejb.EJBMetaData interface.

Because the meta-data class is not entity bean specific, the container may, but is not required to, use a single class for all deployed enterprise beans.

EJB.9.3.7 Instance's Reentrance

The container runtime must enforce the rules defined in Section EJB.9.1.12.

EJB.9.3.8 Transaction Scoping, Security, Exceptions

The container runtime must follow the rules on transaction scoping, security checking, and exception handling described in Chapters EJB.11, EJB.15, and EJB.12.

EJB.9.3.9 Implementation of Object References

The container should implement the distribution protocol between the client and the container such that the object references of the home and remote interfaces used by entity bean clients are usable for a long period of time. Ideally, a client should be able to use an object reference across a server crash and restart. An object reference should become invalid only when the entity object has been removed, or after a reconfiguration of the server environment (for example, when the entity bean is moved to a different EJB server or container).

The motivation for this is to simplify the programming model for the entity bean client. While the client code needs to have a recovery handler for the system exceptions thrown from the individual method invocations on the home and remote interface, the client should not be forced to reobtain the object references.