Sun Microsystems Inc

The entity bean provider’s view of persistence Enterprise JavaBeans 2.0, Public Draft Entity Bean Component Contract for Container

9.3.1 Granularity of entity beans

This section provides guidelines to the Bean Provider for the modeling of business objects as entity beans.

In general, an entity bean should represent an independent business object that has an independent identity and lifecycle, and is referenced by multiple enterprise beans and/or clients.

A dependent object should not be implemented as an entity bean. Instead, a dependent object is better implemented as a Java class (or several classes) and included with the entity bean or beans on which it depends.

A dependent object can be characterized as follows. An object D is a dependent object, if D is created by another object, if D can only be accessed through another object (and not remotely), and if D’s existence or removal is dependent on some other object: in other words, if D’s lifecycle is managed by some other object.

For example, whereas a purchase order might be implemented as an entity bean, the individual line items on the purchase order might be implemented as dependent, or “helper”, classes, not as entity beans. An employee record might be implemented as an entity bean, but the employee address and phone number might be implemented as dependent object classes, rather than as entity beans.

The state of an entity object that has dependent objects is often stored in multiple records in multiple database tables.

In addition, the Bean Provider must take the following into consideration when making a decision on the granularity of an entity object:

Every method call to an entity object via the remote and home interface is potentially a remote call. Even if the calling and called entity bean are collocated in the same JVM, the call must go through the container, which must create copies of all the parameters that are passed through the interface by value (i.e. all parameters that do not extend the java.rmi.Remote interface). The container is also required to check security and apply the declarative transaction attribute on the inter-component calls. The overhead of an inter-component call will likely be prohibitive for object interactions that are too fine-grained.

9.4 The entity bean provider’s view of persistence

An entity bean with container managed persistence consists of its class and its related dependent object classes, a remote interface which defines its client view business methods, a home interface which defines its create, remove, home, and finder methods, and an abstract persistence schema.

A client of an entity bean can control the lifecycle of a bean by using the bean’s home interface and can manipulate the bean as a business entity by using the methods defined by its remote interface. The home and remote interfaces of a bean define its client view.

Sun Microsystems Inc.

Entity Bean Component Contract for Container Managed PersistenceEnterprise JavaBeans 2.0, Public Draft The entity bean provider’s

The abstract persistence schema of an entity bean consists of a set of properties (in the JavaBeans sense), where each property corresponds to an aspect of the persistent state of the entity bean (a field or relationship). The abstract persistence schema of an entity bean defines the set of accessor methods for its persistent fields and relationships. The persistent fields and relationships themselves are maintained by the persistence manager.

It is the responsibility of the bean provider to specify the abstract persistence schema of the entity bean and the abstract persistence schemas of any of its related dependent object classes in the deployment descriptor. The deployment descriptor provides details about the entity bean’s persistent fields and relationships. The bean provider’s responsibilities in specifying the abstract persistence schema in the deployment descriptor are discussed further in Section 9.4.12.

9.4.1 The entity bean provider’s programming contract

The bean provider must observe the following programming contract when defining an entity bean class that uses container managed persistence:

•The bean provider must define the bean class as an abstract class.

•The bean provider must define the accessor methods for the container managed persistent fields and container managed relationship fields as get and set methods, as for a Java Bean.

• The container managed persistent fields and container managed relationship fields must not be defined in the bean class. From the perspective of the Bean Provider, the container managed persistent fields and container managed relationship fields are virtual fields only. The implementation of the get and set methods for these virtual fields is supplied by the Persistence Manager, as is the implementation of the container managed persistent fields and container managed relationship fields themselves. The persistence manager provides the implementation class that is used for the bean at runtime.

•The accessor methods must be public or protected, must be abstract, and must bear the name of the container managed persistent field ( cmp-field) or container managed relationship field

(cmr-field) that is specified in the deployment descriptor, prefixed by “ get” or “ set”.

•The accessor methods for container managed relationship fields that reference other enterprise beans must be defined in terms of the remote interfaces of those beans, as described in Section 9.4.2.

•The accessor methods for container managed relationship fields for one-to-many or

many-to-many relationships must utilize one of the following Collection interfaces: java.util.Collection or java.util.Set[6]. The Collection interfaces used by a

bean are specified in the deployment descriptor.

•The accessor methods of the bean must not be exposed in the client interface of the bean except in the cases that are defined in Section 9.4.9. This restriction is to ensure the data independence between the client view of the bean and the persistent state that is managed by the persistence

[6]We expect to include java.util.List and java.util.Map in a later version of this specification.

Sun Microsystems Inc

The entity bean provider’s view of persistence Enterprise JavaBeans 2.0, Public Draft Entity Bean Component Contract for Container

manager, and to allow flexibility to the Persistence Manager in loading and maintaining the persistent state of the bean.

9.4.2 The entity bean provider’s view of persistent relationships

The bean developer navigates or manipulates logical relationships by using the accessor methods for the container managed relationship fields. The name of an accessor method for a container managed relationship field corresponds to the cmr-field-name element defined in the deployment descriptor, prefixed by “ get” or “ set”.

A bean may have relationships both with other beans and with dependent object classes.

Relationships may be one-to-one, one-to-many, or many-to-many relationships.

Relationships may be either bidirectional or unidirectional. The directionality of a relationship characterizes its navigability. If a relationship is bidirectional, it can be navigated in both directions, whereas a unidirectional relationship can be navigated in one direction only. Bidirectional container managed relationships can exist (either directly or indirectly) only among beans and dependent objects whose abstract persistence schemas are defined in the same ejb-jar file and thus are managed by the same Persistence Manager. A bean or dependent object class may have a unidirectional relationship with a target entity bean that is “remote” (i.e., whose abstract persistence schema is not defined in the same ejb-jar file). This includes entity beans with bean managed persistence, EJB 1.1 entity beans with container managed persistence, and entity beans that are defined in another ejb-jar file.

The bean provider must consider the type and cardinality of the relationships when the beans and dependent classes are programmed. In particular:

• In a relationship between beans, the get method must return either the remote interface of the related bean or a collection (more precisely, either java.util.Collection or java.util.Set[7]), in which the members of the collection must be the remote interfaces of the related beans. Similarly, the set method for the relationship must take as an argument the remote interface of the related bean or a collection whose members are the remote interfaces of the related beans.

•In a relationship between a bean and dependent object class, the get method that accesses the bean from the dependent object class must return the remote interface of the related bean (or a collection whose members must be the remote interfaces of the related beans), and the set method defined on the dependent object class must take as an argument the remote interface of the related bean (or a collection whose members must be the remote interfaces of the related beans). The get method that accesses the dependent object class from the bean must return the dependent class type (or a collection whose members must be of the dependent class type), and the set method defined on the bean must take as an argument the dependent object class type (or a collection of the same).

[7]We expect to include java.util.List and java.util.Map in a later version of this specification.

Sun Microsystems Inc.

Entity Bean Component Contract for Container Managed PersistenceEnterprise JavaBeans 2.0, Public Draft The entity bean provider’s

•In a relationship between dependent object classes, the formal types of the arguments and results of the get and set methods must be the respective dependent object classes (or collections of the same).

In EJB 1.1, the bean provider had to supply the code to explicitly locate related beans through the JNDI lookup of their home interfaces and the execution of their finder methods. In EJB 2.0 container managed persistence, the bean provider accesses related beans by means of container managed relationships defined in terms of the remote interfaces of the related beans. The responsibility to locate the homes of the related beans and to execute their finder methods is shifted to the persistence manager, which automatically provides the related objects (beans or dependent objects) at runtime.

9.4.3 The view of dependent classes

Two types of dependent classes must be distinguished: dependent object classes and dependent value classes. This chapter has up to now considered only dependent object classes.

A dependent object class is defined in much the same way as an entity bean class: as an abstract class, with an abstract persistence schema that defines its relationships with entity beans and other dependent object classes. A dependent object class can participate in both unidirectional and bidirectional container managed relationships. A dependent object class instance (or a collection of dependent object class instances) can be the value of a cmr-field; a dependent object class instance cannot be the value of a cmp-field. A dependent object class must not be serializable.

A dependent value class is a concrete class. A dependent value class can be the value of a cmp-field, but it cannot be the value of a cmr-field or participate in container managed relationships. A dependent value class may be a legacy class that the bean provider wishes to utilize within an entity bean with container managed persistence and/or to expose through the remote interface of the entity bean. A dependent value class must be serializable. The internal structure of a dependent value class is not described in the EJB deployment descriptor.

9.4.4 The entity bean provider’s programming contract for dependent object classes

The bean provider must observe the following programming contract when defining a dependent object class:

•The bean provider must define the dependent object class as an abstract class.

•The bean provider must define the accessor methods for the container managed persistent fields and container managed relationship fields as get and set methods, as for a Java Bean.

• The container managed persistent fields and container managed relationship fields must not be defined in the dependent object class. From the perspective of the Bean Provider, the container managed persistent fields and container managed relationship fields are virtual fields only. The implementation of the get and set methods is supplied by the Persistence Manager, as is the implementation of the container managed persistent fields and container managed relationship fields themselves. The Persistence Manager provides the implementation class for the dependent object class that is used at runtime.