Previously known as Aggregate Entity

Mapping an object model to an Enterprise JavaBeans^TM (EJB^TM) object model is a common design problem in Java^TM 2 Platform, Enterprise Edition (J2EE^TM) applications. Given a network of inter-related objects, you must choose whether each object should be implemented as an entity EJB or a plain old Java object, and manage the relationships between the objects. Remote entity beans are best suited for modeling coarse-grained business entities. Modeling fine-grained entities as remote entity beans creates problems performance problems such as excessive remote communication. Choosing to use Bean Managed persistence means:

Dependent objects, which are objects whose data are meaningful only in the context of a relationship to another object, are especially prone to these problems. For example, in many applications, an Account object is meaningless outside of its relationship to its associated parent Customer object.

The Composite Entity design pattern offers a solution to modeling a networks of interrelated business entities. The composite entity's interface is coarse-grained, and it manages interactions between fine-grained objects internally. This design pattern is especially useful for efficiently managing relationships to dependent objects.

Before the EJB 2.0 specification, entity beans were always heavyweight and remote. The local, lightweight entity beans introduced with EJB 2.0 are intended for efficient modeling of fine-grained business entities and dependent objects. Efficient local access eliminates many of the problems listed above.

See the Core J2EE Patterns

It is important to note that this pattern is still viable with EJB 2.0 and Local Entity Beans. In both a local and a distributed environment there are drawbacks to using remote entity beans to model fine-grained or dependent business objects, so the composite entity pattern is applicable in both cases. Before EJB 2.0 existed, a common strategy for composite entity implementations was to use a Remote Entity Bean for the parent and use Java objects instead of remote entity beans for the dependent objects in a parent-child relationship. This also meant that the parent usually used Bean-managed persistence so it had to write the code to manage the relationships to the other objects also. But with the introduction of local entity beans in EJB 2.0, the strategy of using local entity beans to model fine-grained entities and dependent objects is recommended. An additional benefit of this strategy is that since all the objects in this strategy are Entity beans, you can efficiently use container-managed persistence and avoid writing code to manage the relationships. The following example from the Java Pet Store sample application illustrates this recommended strategy.

The following interfaces greatly simplifies implementing a composite entity, as shown by the following example.Enterprise bean local interfaces eliminate most of the performance costs associated with remote interfaces, making them practical for modeling fine-grained business entities and dependent objects.

The sample application models the application Customer class and several related objects as a composite entity. It uses local entity bean interfaces to model fine-grained objects that are dependent on the Customer object. Figure 1 below shows the Customer entity and its associated dependent objects: Profile, Account, ContactInfo, CreditCard, and Address.

Figure 1. The Customer composite entity and its dependent objects

The diagram in Figure 1 shows the entities involved in the composite entity Customer. Several classes represent the enterprise beans used to implement these entities. The classes written by the developer appear in Table 1 below.

Table 1. Classes implementing composite entity Customer
Entity EJB Class Component Interface Home Interface Customer CustomerEJB CustomerLocal CustomerLocalHome Profile ProfileEJB ProfileLocal ProfileLocalHome Account AccountEJB AccountLocal AccountLocalHome CreditCard CreditCardEJB CreditCardLocal CreditCardLocalHome ContactInfo ContactInfoEJB ContactInfoLocal ContactInfoLocalHome Address AddressEJB AddressLocal AddressLocalHome

The parent Customer composite entity provides access to the children dependent entities, as shown by the following excerpt from the CustomerLocal interface:

        
public interface CustomerLocal extends javax.ejb.EJBLocalObject {
    public String getUserId();
    public AccountLocal getAccount();
    public ProfileLocal getProfile();
}
      

Using a local entity bean instead of a plain old Java object to implement the dependent objects in a composite entity improves a design in several ways:

• Improved performance. Local interfaces improve performance because they eliminate the parameter and return value serialization and data transmission costs incurred by remote method calls. In addition, local interfaces are designed to allow the EJB container to optimize state representation, method calls, and relationships to other local beans.


• Cleaner programming model. Remote interfaces must usually be coarse to be practical. Local interfaces allow a designer to choose a granularity that is most appropriate for the application. Local interfaces also minimize the number of utility classes, such as data access objects, session facades, and transfer objects that are used to facilitate a distributed environment and remote interfaces.


• Automatic relationship and integrity control. Using container-managed relationships (CMR) with local interfaces simplifies implementation and reduces maintenance problems. With CMR, the container manages relationships between local entities, and enforces integrity constraints defined by the developer or deployer. The following code segment shows the definition of the relationship between the Customer and Profile entities in the sample application's EJB deployment descriptor:

              
  
  <ejb-relation>
    ...
    <ejb-relationship-role>
      <ejb-relationship-role-name>ProfileEJB</ejb-relationship-role-name>
      <multiplicity>One</multiplicity>
      <cascade-delete/>
      <relationship-role-source>
        <ejb-name>ProfileEJB</ejb-name>
      </relationship-role-source>
    </ejb-relationship-role>
  </ejb-relation>
  
  
            

  The application deployer or developer defines a multiplicity of One to the relationship between a Customer and a Profile. At runtime, the container ensures that exactly one Profile is associated with each Customer. In addition, the developer need not even write the code that manages the relationship, because it is automatically implemented by the container.



• Cascading deletes. The element <cascade-delete/> in the code sample above indicates that when a Customer instance is deleted, the container always automatically deletes the associated Profile instance, as well. Again, no code need be written or maintained to manage such deletions: the container handles it automatically.

Finally, a note about modeling. All of the entity beans that Customer uses to form a composite entity are dependent objects, meaning that they have little meaning in the application apart from the Customer object that "owns" them. In the parent-child relationship between the customer and its dependent objects means that the dependent objects such as Profile, Address, etc. can not exist if the parent Customer does not exist. In addition to dependent objects, entities accessed in a fine-grained manner may also be accesses by a composite entity, whether or not they are dependent on the composite entity. For example, adding a customer purchase history function to the customer entity might require fine-grained access to the product catalog. In such a case, catalog-related entities could be aggregated with the Customer composite entity, even though the catalog is not dependent on the Customer. Customer