Sun Microsystems Inc

An entity EJBObject is an object whose class was generated at deployment time by the Container Provider’s tools. The entity EJBObject class implements the entity bean’s remote interface. A client never references an entity bean instance directly—a client always references an entity EJBObject whose class is generated by the Container Provider’s tools.

An entity EJBHome object provides the life cycle operations (create, remove, find) for its entity objects as well as home business methods, which are business methods that are not specific to an entity bean instance. The class for the entity EJBHome object is generated by the Container Provider’s tools at deployment time. The entity EJBHome object implements the entity bean’s home interface that was defined by the Bean Provider.

9.5.2 Relationships among the classes provided by the bean provider and persistence manager

The entity bean provider is responsible for providing the entity bean class as an abstract class. Any dependent object classes with which the entity bean has container managed relationships are also provided by the entity bean provider as abstract classes.

The persistence manager provider tools are responsible for providing the concrete entity bean class (or dependent object class). The persistence manager provider tools can achieve this by subclassing the abstract entity bean class (or dependent object class) and providing a concrete implementation or by utilizing encapsulation and delegation.

The class or classes provided by the persistence manager tools are responsible for managing the relationships of the entity bean or dependent object class and for managing the access to its persistent state. The persistence manager provider tools are also responsible for providing the implementations of the java.util.Collection classes that are used in maintaining the container managed relationships of the entity bean.

Figure 23 illustrates these relationships.

Sun Microsystems Inc.

Entity Bean Component Contract for Container Managed PersistenceEnterprise JavaBeans 2.0, Public DraftThe entity bean component

Figure 23 Relationships Among the Classes

Sun Microsystems Inc

9.5.2.1 Container-managed fields

An entity bean with container managed persistence relies on the Persistence Manager Provider’s tools to generate methods that perform persistent data access on behalf of the entity bean instances. The generated methods transfer data between an entity bean instance and the underlying resource manager. The generated methods also implement the creation, removal, and lookup of the entity object in the underlying database.

The Bean Provider is responsible for using the cmp-field and cmr-field elements of the deployment descriptor to declare the fields whose persistent state is managed by the Persistence Manager. These “fields” are not defined in the bean class that is provided by the Bean Provider: they are accessed by means of the abstract accessor methods. There is no instance variable corresponding to a cmp-field or cmr-field in the entity bean class.

The Persistence Manager is responsible for implementing the entity bean class by providing the implementation of the accessor methods of the bean’s abstract persistence schema. These are defined by the abstract get and set methods. Likewise, the Persistence Manager is responsible for implementing a dependent object class by providing the implementation of its abstract accessor methods. In order to implement these methods, the Persistence Manager must also manage the mapping between primary keys or handles and EJBObjects.

The Persistence Manager is responsible for transferring data betwen the entity bean and the underlying data source. The data is transferred by the persistence manager as a result of the execution of the entity bean’s methods. Because of the requirement that all data access occur through the accessor methods, the Persistence Manager can implement both eager and lazy loading and storing schemes. Synchronization between the Persistence Manager and the Container is achieved before or after the execution of the ejbCreate<METHOD>, ejbRemove, ejbLoad, and ejbStore methods. These contracts are described in Section 9.6.

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

•The Bean Provider must ensure that the Java types assigned to the container-managed fields of an entity bean and of any of its dependent object classes are restricted to the following: Java primitive types, references to enterprise bean remote or home interfaces, references to con- tainer-managed dependent classes, and Java serializable types.

•The Persistence Manager must be capable of persisting references to enterprise bean remote and home interfaces (for example, by storing their handle or primary key). The Persistence Manager Provider is allowed to use Java Serialization to store the container-managed fields.

9.5.2.2Container-managed relationships

The Persistence Manager maintains the relationships between beans and between beans and dependent classes.

•For a relationship with a bean, it is the responsibility of the Persistence Manager to materialize the remote object for the bean based on the information provided in the deployment descriptor. This eliminates the need for the bean provider to look up and execute a finder method for the related bean.

Sun Microsystems Inc.

Entity Bean Component Contract for Container Managed PersistenceEnterprise JavaBeans 2.0, Public DraftThe entity bean component

•It is the responsibility of the Persistence Manager to maintain the referential integrity of the container managed relationships in accordance with the semantics of the relationship type and its navigability, as specified in the deployment descriptor. A relationship is navigable for a role in a relationship if there is a corresponding cmr-field element contained in the ejb-relationship-role element in the deployment descriptor. In the case of a bidirectional relationship, for example, if a bean is added to a collection corresponding to the container managed relationship field of another bean, the container managed relationship field of the first bean must also be updated by the Persistence Manager in the same transaction context.

•The bean provider may specify bidirectional relationships between entity beans only when both beans are provided by the same bean provider and are both available together during deployment.

•It is the responsibility of the Persistence Manager to detect cycles in maintaining bidirectional relationships.

•It is the responsibility of the Persistence Manager to throw the java.lang.IllegalArgumentException when the argument to a set method in a relationship is a dependent object instance that is inappropriate for the relationship type (see Section 9.4.5.1).

9.5.2.3Container-managed dependent object classes

The Persistence Manager must provide the implementation of the dependent object classes that the bean provider provides as abstract classes.

The create<type> methods that are defined on the entity bean’s class and dependent object classes enable the Bean Provider to create instances of dependent object classes. The create methods, like the accessor methods, are abstract and are implemented by the Persistence Manager. The Bean Provider must define a create method on each entity bean or dependent object class for each dependent object class that can be accessed through a cmr-field directly defined by that entity bean or dependent object class. It is the responsibility of the Persistence Manager to ensure that the values that will be initially returned by the dependent object class instance’s get methods will be the Java language defaults (e.g. 0 for integer, null for pointers), except for collection-valued cmr-fields, which will have the empty collection (or set) as their value.

The deepCopy() methods that are defined on the dependent object classes enable the Bean Provider to create copies of dependent object class instances. The deepCopy methods are abstract and are implemented by the Persistence Manager. The Bean Provider must define a deepCopy method on each dependent object class. It is the responsibility of the Persistence Manager to implement the deepCopy method to create a deep copy of a dependent object class instance, including other dependent object class instances with which it has relationships.

The Persistence Manager must maintain the container-managed relationships between dependent object classes:

•The Persistence Manager must maintain the referential integrity of the container managed relationships. For example, if an instance of a dependent object class is added to a collection corresponding to the container managed relationship field of another dependent object class in a