EJB.9.4 Entity Beans with Container-Managed Persistence

The previous sections described the component contract for entity beans with bean-managed persistence. The contract for an entity bean with container-managed persistence is the same as the contract for an entity bean with bean-managed persistence (as described in the previous sections), except for the differences described in this section.

The deployment descriptor for an entity bean indicates whether the entity bean uses bean-managed persistence or container-managed persistence.

EJB.9.4.1 Container-Managed Fields

An entity bean with container-managed persistence relies on the container provider's tools to generate methods that perform data access on behalf of the entity bean instances. The generated methods transfer data between the entity bean instance's variables and the underlying resource manager at the times defined by the EJB specification. The generated methods also implement the creation, removal, and lookup of the entity object in the underlying database.

An entity bean with container-manager persistence must not code explicit data access ”all data access must be deferred to the container.

The bean provider is responsible for using the cmp-field elements of the deployment descriptor to declare the instance's fields that the container must load and store at the defined times. The fields must be defined in the entity bean class as public , and must not be defined as transient .

The container is responsible for transferring data between the entity bean's instance variables and the underlying data source before or after the execution of the ejbCreate , ejbRemove , ejbLoad , and ejbStore methods, as described in the following subsections. The container is also responsible for the implementation of the finder methods.

The following requirements ensure that an entity bean can be deployed in any compliant container.

• The bean provider must ensure that the Java programming language types assigned to the container-managed fields are restricted to the following: Java programming language primitive types, Java programming language serializable types, and references of enterprise beans' remote or home interfaces.

• The container provider may, but is not required to, use Java programming language serialization to store the container-managed fields in the database. If the container chooses a different approach, the effect should be equivalent to that of Java programming language serialization. The container must also be capable of persisting references to enterprise beans' remote and home interfaces (for example, by storing their handle or primary key).

Although the above requirements allow the bean provider to specify almost any arbitrary type for the container-managed fields, we expect that in practice the bean provider will use relatively simple Java programming language types, and that most containers will be able to map these simple Java programming language types to columns in a database schema to externalize the entity state in the database, rather than use Java programming language serialization.

If the bean provider expects that the container-managed fields will be mapped to database fields, he should provide mapping instructions to the deployer. The mapping between the instance's container-managed fields and the schema of the underlying database manager will be then realized by the data access classes generated by the container provider's tools. Because entity beans are typically coarse-grained objects, the content of the container-managed fields may be stored in multiple rows, possibly spread across multiple database tables. These mapping techniques are beyond the scope of the EJB specification, and do not have to be supported by an EJB compliant container. (The container may simply use the Java serialization protocol in all cases.)

Because a compliant EJB container is not required to provide any support for mapping the container-managed fields to a database schema, a bean provider of entity beans that need a particular mapping to an underlying database schema instead should use bean-managed persistence.

The provider of entity beans with container-managed persistence must take into account the following limitations of the container-managed persistence protocol:

• Data aliasing problems. If container-managed fields of multiple entity beans map to the same data item in the underlying database, the entity beans may see an inconsistent view of the data item if the multiple entity beans are invoked in the same transaction. (That is, an update of the data item done through a container-managed field of one entity bean may not be visible to another entity bean in the same transaction if the other entity bean maps to the same data item.)

• Eager loading of state. The container loads the entire entity object state into the container-managed fields before invoking the ejbLoad method. This approach may not be optimal for entity objects with large states if most business methods require access to only parts of the state.

An entity bean designer who runs into the limitations of the container-managed persistence should use bean-managed persistence instead.

EJB.9.4.2 ejbCreate, ejbPostCreate

With bean-managed persistence, the entity bean provider is responsible for writing the code that inserts a record into the database in the ejbCreate(...) methods. However, with container-managed persistence, the container performs the database insert after the ejbCreate(...) method completes.

The container must ensure that the values of the container-managed fields are set to the Java language defaults (e.g., 0 for integer, null for pointers) prior to invoking an ejbCreate(...) method on an instance.

The entity bean provider's responsibility is to initialize the container-managed fields in the ejbCreate(...) methods from the input arguments such that when an ejbCreate(...) method returns, the container can extract the container-managed fields from the instance and insert them into the database.

The ejbCreate(...) methods must be defined to return the primary key class type. The implementation of the ejbCreate(...) methods should be coded to return a null . The returned value is ignored by the container.

Note

The above requirement is to allow the creation of an entity bean with bean-managed persistence by subclassing an entity bean with container-managed persistence. The Java programming language rules for overriding methods in subclasses require the signatures of the ejbCreate(...) methods in the subclass and the superclass to be the same.

The container is responsible for creating the entity object's representation in the underlying database, extracting the primary key fields of the newly created entity object representation in the database, and for creating an entity EJBObject reference for the newly created entity object. The container must establish the primary key before it invokes the ejbPostCreate(...) method. The container may cre-ate the representation of the entity in the database immediately after ejbCreate(...) returns, or it can defer it to a later time (for example, to the time after the matching ejbPostCreate(...) has been called, or to the end of the transaction).

Then container invokes the matching ejbPostCreate(...) method on the instance. The instance can discover the primary key by calling getPrimaryKey() on its entity context object.

The container must invoke ejbCreate , perform the database insert operation, and invoke ejbPostCreate in the transaction context determined by the transaction attribute of the matching create(...) method, as described in Section EJB.11.6.2.

The container throws the DuplicateKeyException if the newly created entity object would have the same primary key as one of the existing entity objects within the same home.

EJB.9.4.3 ejbRemove

The container invokes the ejbRemove() method on an entity bean instance with container-managed persistence in response to a client-invoked remove operation on the entity bean's home or remote interface.

The entity bean provider can use the ejbRemove method to implement any actions that must be done before the entity object's representation is removed from the database.

The container synchronizes the instance's state before it invokes the ejbRemove method. This means that the state of the instance variables at the beginning of the ejbRemove method is the same as it would be at the beginning of a business method.

After ejbRemove returns, the container removes the entity object's representation from the database.

The container must perform ejbRemove and the database delete operation in the transaction context determined by the transaction attribute of the invoked remove method, as described in Section EJB.11.6.2.

EJB.9.4.4 ejbLoad

When the container needs to synchronize the state of an enterprise bean instance with the entity object's state in the database, the container reads the entity object's state from the database into the container-managed fields and then it invokes the ejbLoad() method on the instance.

The entity bean provider can rely on the container's having loaded the container-managed fields from the database just before the container invokes the ejbLoad() method. The entity bean can use the ejbLoad() method, for instance, to perform some computation on the values of the fields that were read by the container (for example, uncompressing text fields).

EJB.9.4.5 ejbStore

When the container needs to synchronize the state of the entity object in the database with the state of the enterprise bean instance, the container first calls the ejbStore() method on the instance, and then it extracts the container-managed fields and writes them to the database.

The entity bean provider should use the ejbStore() method to set up the values of the container-managed fields just before the container writes them to the database. For example, the ejbStore() method may perform compression of text before the text is stored in the database.

EJB.9.4.6 Finder Methods

The entity bean provider does not write the finder ( ejbFind<METHOD>(...) ) methods.

The finder methods are generated at the entity bean deployment time using the container provider's tools. The tools can, for example, create a subclass of the entity bean class that implements the ejbFind<METHOD>() methods, or the tools can generate the implementation of the finder methods directly in the class that implements the entity bean's home interface.

Note that the ejbFind<METHOD> names and parameter signatures do not provide the container tools with sufficient information for automatically generating the implementation of the finder methods for methods other than ejbFindByPrimaryKey . Therefore, the bean provider is responsible for providing a description of each finder method. The entity bean deployer uses container tools to generate the implementation of the finder methods based in the description supplied by the bean provider. The Enterprise JavaBeans architecture does not specify the format of the finder method description.

EJB.9.4.7 Primary Key Type

The container must be able to manipulate the primary key type. Therefore, the primary key type for an entity bean with container-managed persistence must follow the rules in this subsection, in addition to those specified in Section EJB.9.2.9.

There are two ways to specify a primary key class for an entity bean with container-managed persistence:

• Primary key that maps to a single field in the entity bean class.

• Primary key that maps to multiple fields in the entity bean class.

The second method is necessary for implementing compound keys, and the first method is convenient for single-field keys. Without the first method, simple types such as string would have to be wrapped in a user -defined class.

EJB.9.4.7.1 Primary Key that Maps to a Single Field in the Entity Bean Class

The bean provider uses the primkey-field element of the deployment descriptor to specify the container-managed field of the entity bean class that contains the primary key. The field's type must be the primary key type.

EJB.9.4.7.2 Primary Key that Maps to Multiple Fields in the Entity Bean Class

The primary key class must be public , and must have a public constructor with no parameters.

All fields in the primary key class must be declared as public.

The names of the fields in the primary key class must be a subset of the names of the container-managed fields. (This allows the container to extract the primary key fields from an instance's container-managed fields, and vice versa.)

EJB.9.4.7.3 Special Case: Unknown Primary Key Class

In special situations, the entity bean provider may choose not to specify the primary key class for an entity bean with container-managed persistence. This case usually happens when the entity bean does not have a natural primary key, and the bean provider wants to allow the deployer to select the primary key fields at deployment time. The entity bean's primary key type will usually be derived from the primary key type used by the underlying database system that stores the entity objects. The primary key used by the database system may not be known to the bean provider.

When defining the primary key for the enterprise bean, the deployer may sometimes need to subclass the entity bean class to add additional container-managed fields (this typically happens for entity beans that do not have a natural primary key, and the primary keys are system-generated by the underlying database system that stores the entity objects).

In this special case, the type of the argument of the findByPrimaryKey method must be declared as java.lang.Object , and the return value of ejbCreate() must be declared as java.lang.Object. The bean provider must specify the primary key class in the deployment descriptor as of the type java.lang.Object.

The primary key class is specified at deployment time in the situations when the bean provider develops an entity bean that is intended to be used with multiple back-ends that provide persistence, and when these multiple back-ends require different primary key structures.

Use of entity beans with a deferred primary key type specification limits the client application programming model, because the clients written prior to deployment of the entity bean may not use, in general, the methods that rely on the knowledge of the primary key type.

The implementation of the enterprise bean class methods must be done carefully . For example, the methods should not depend on the type of the object returned from EntityContext.getPrimaryKey() , because the return type is determined by the deployer after the EJB class has been written.