2
Mapping Entity Beans

This chapter describes how to map container-managed entity beans using the object mapping features of TopLink for Java. Instructions and hints for using direct and relationship mappings in an EJB context are provided, and differences between beans and regular Java objects are outlined.

For information on direct and relationship mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide. You should read and thoroughly understand those chapters before attempting to map entity beans.

Using TopLink Mapping Workbench

When using TopLink Mapping Workbench with entity beans, the bean classes themselves should be loaded into TopLink Mapping Workbench. The remote, local, home, and local home interfaces and the primary key class do not need to be loaded, nor should mappings be defined using these classes.

Make sure you include any classes referred to by the entity beans on the classpath that is used by the TopLink Mapping Workbench, otherwise errors may occur when the beans are loaded. The remote, local, home, and localhome interfaces should also be avilable on the classpath, as they may be used during EJB validation.

Mappings

TopLink mappings define how an object's attributes are to be represented in the database. Attributes that are to be persistent, or that reference other beans or mapped objects, must be mapped to the database using either direct or relationship mappings.

To enable container-managed persistent storage of entity beans, the attributes on the bean implementation class must be mapped. The implementation class is the one specified in the ejb-class element for the particular bean in the ejb-jar.xml deployment descriptor file. The home and remote interface classes should not be mapped. Primary key classes, if they exist, also should not be mapped.

Creating mappings

You can create mappings by using TopLink Mapping Workbench or by using the Java code-based API. TopLink Mapping Workbench is a visual tool that offers windows and dialogs to set properties and to configure the mappings and TopLink descriptors for any given project. This is the preferred method of creating mappings, and should be used whenever possible.

TopLink Mapping Workbench imposes some limitations that require you to use the code API instead of the tool, but these limitations are few and are mentioned in the TopLink Mapping Workbench documentation.

For more information on the TopLink Mapping Workbench features and usage, and on the limitations mentioned above, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Direct mappings

Direct mappings define how a persistent object refers to objects that do not have TopLink descriptors, such as the JDK classes, primitive types and other non-persistent classes.

Attributes containing state that is a primitive object, or a regular object that is not itself mapped to the database should be mapped using a direct mapping. For example, a String attribute would need a direct to field mapping for the attribute to be stored in a VARCHAR field.

For a complete description of direct mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Entity bean attributes can be mapped using direct mappings without any special considerations.

Note: The entity context attribute (type javax.ejb.EntityContext) should not be mapped.

Relationship mappings

Persistent objects use relationship mappings to store references to instances of other persistent classes. The appropriate mapping type is based primarily upon the cardinality of the relationship (for example, one-to-one compared to one-to-many). For a complete description of relationship mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Entity beans may be related to regular Java objects, other entity beans, or both. The following sections outline the mappings and conditions where special attention must be paid to correctly map beans and execute operations that traverse or modify these relationships.

Mappings between entity beans

The EJB 2.0 specification introduces and defines the concept of relating beans to one another. It also imposes a number of restrictions on CMP relationships that TopLink does not enforce. Developers who wish to write their beans in such a way that they may be more easily migrated to full EJB 2.0 compliance may wish to follow some of the programming restrictions required by EJB 2.0, even if these restrictions are not enforced by TopLink.

TopLink support for the EJB 2.0 specification includes the following concepts:

• Bean relationships are managed automatically by the persistence layer, and do not require any internal use of finder methods.

• One-to-one, one-to-many and many-to-many relationships can be defined between beans.

• Dependent objects (regular Java objects) may be used to model fine-grained objects that are associated with a particular entity.

Some of the restrictions imposed by the EJB 2.0 specification that are not enforced by TopLink include:

• CMP beans must be abstract and have only "virtual" fields.

• Collections of entities used in relationship mappings must not be implemented by the bean developer, and must never be exposed directly to the client.

• Beans that are referenced by other beans must be related through local interfaces.

Additional restrictions to the mapping and run-time behavior of EJB 2.0 CMP beans are described in the EJB 2.0 specification (http://java.sun.com/products/ejb).

A bean that has a relationship to another bean acts as a "client" of that bean; that is, it does not access the actual bean directly but acts through the local interface of the bean. For example, if an OrderBean is related to a CustomerBean, it has an instance variable of type Customer (the local interface of the CustomerBean) and only accesses those methods defined on the Customer interface.

Note: Although beans must refer to each other through their local interface, all TopLink descriptors and projects refer to the bean class. For example, if you are mapping beans using the TopLink Mapping Workbench and defining relationships between them, you need to load only the bean classes and not the local, remote, or home interfaces. When defining a relationship mapping in both the TopLink Mapping Workbench and code API, the "reference class" is always the bean class.

Importing relationship metadata in the Mapping Workbench

In accordance with the EJB 2.0 specification, the Mapping Workbench can obtain relationship metadata from the ejb-jar.xml file. For more information on how to update TopLink relationships in the Mapping Workbench from the ejb-jar.xml deployment descriptor, see "Working with project properties" in the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Mappings between entity beans and Java objects

The EJB 2.0 specification notes that entity beans should represent "independent business objects" and that dependent objects are "better implemented as a Java class (or several classes) and included as part of the entity bean on which it depends."

The following relationship mappings may exist between an entity bean and regular Java objects:

• One-to-one, privately-owned mappings (bean is source, Java object is target)

• One-to-many, privately-owned mappings (bean is source, Java object(s) is target)

• Aggregate mappings (bean is source, Java object is target)

• Direct collection mappings (bean is source, Java object is target and is a "base" datatype, such as String, or Date)

Relationships from entity beans to regular Java objects should be dependent and relationships between entity beans should be independent.

If dependent objects are exposed to the client, these objects must be serializable.

One-to-one mappings

One-to-one mappings represent simple pointer references between two objects. For a complete description of one-to-one mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

One-to-one mappings are valid between entity beans, or between an entity bean and a regular Java object where the entity bean is the source and the regular Java object is the target of the relationship.

To maintain EJB compliance, the object attribute that points to the target of the relationship must be of the correct type if the target is a bean. This must be the local interface type and not the bean class.

There are a number of advanced variations on one-to-one mappings, that allow for more complex relationships to be defined -- in particular variable one-to-one mappings allow for polymorphic target objects to be specified. These variations are not available for entity beans, but are valid for dependent Java objects. For more information on these kinds of mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

One-to-many mappings

One-to-many mappings are used to represent the relationship between a single source object and a collection of target objects. For more information on one-to-many mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

One-to-many mappings are valid between entity beans or between an entity bean and a collection of privately-owned regular Java objects.

As described in the Oracle9iAS TopLink Mapping Workbench Reference Guide, a one-to-one mapping should also be created from the target object back to the source. The object attribute that contains a pointer to the bean must be of the correct type (the local interface type) and not the bean class.

TopLink automatically maintains back-pointers as bi-directional relationships between beans are created or updated. See "Maintaining bi-directional relationships".

Many-to-many mappings

Many-to-many mappings represent the relationships between a collection of source objects and a collection of target objects. They require the creation of an intermediate table for managing the associations between the source and target records. For more information on many-to-many mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

When using container-managed persistence, many-to-many mappings are valid only between entity beans and cannot be privately owned. The exception is when a many-to-many mapping is used to implement a logical one-to-many mapping with a relation table.

TopLink automatically maintains back-pointers as bi-directional relationships are created or updated. See "Maintaining bi-directional relationships".

Aggregate object mappings

Two objects are related by aggregation if there is a strict one-to-one relationship between the objects and all the attributes of the second object can be retrieved from the same table(s) as the owning object. This means that if the target (child) object exists, then the source (parent) object must also exist. The child (owned object) cannot exist without its parent.

For a complete description of aggregate object mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Aggregate mappings can be used with entity beans when the source of the mapping is an entity bean and the target is a regular Java object. It is not valid to make an entity bean the target of an aggregate object mapping. As a consequence, it follows that aggregate mappings between entity beans are likewise invalid.

Note: Aggregate objects are privately owned and should not be shared or referenced by other objects.

Aggregate collection mappings

Aggregate collection mappings are used to represent aggregate relationships between a single source object and collection of target objects. Unlike normal one-to many mappings, there is no one-to-one back reference required. Unlike the normal aggregate mappings, a target table is required for the target objects.

For a complete description of Aggregate collection mappings, see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Aggregate collection mappings can be used with entity beans if the source of the relationship is an entity or Java object, and the targets of the mapping are regular Java objects. It is not possible to define an aggregate collection mapping with entity beans as the targets.

Aggregate collections are most appropriate when the target collections are expected to be moderate in size and a one-to-one mapping from target to source would be difficult. In addition, great care should be taken to ensure the identity of the Aggregate object, when referencing objects from an Aggregate within an Aggregate Collection.

Caution: Although aggregate collection mappings appear similar to one-to-many mappings, aggregate collections should not be used in place of one-to-many mappings. One-to-many mappings are more robust and scalable, and offer better performance. In addition, aggregate collections are privately owned by the source of the relationship and should not be shared or referenced by other objects.

Sequencing with Entity Beans

Sequencing is a mechanism which can be used to populate the primary key attribute of new objects/entity beans before inserting them into the database. Refer to the Oracle9iAS TopLink Mapping Workbench Reference Guide for details on the different kinds of TopLink sequencing: table and native.

The configuration of sequencing is similar for both Java objects and entity beans. However, with entity beans a create() method exists on the bean home interface, and ejbCreate() and ejbPostCreate() methods are implemented on the bean implementation class.

Because the primary key is automatically generated, no primary key is passed into the create() method on the home interface when the bean is created. If you are using table-based sequencing or native sequencing for databases that support pre-allocation of sequence numbers, the bean's primary key is available in the ejbPostCreate() method.

Inheritance

Although inheritance is a standard tool in object-oriented modeling, no implementation guidelines are outlined in the EJB specification. The EJB 1.0 specification does not address the issue, and the 1.1 and 2.0 specifications discuss it only in general terms. As a result, any use of inheritance should be approached cautiously.

Some restrictions apply to entity beans when using inheritance:

• The home interfaces cannot inherit. The findByPrimaryKey method must be overloaded in order to have the correct return type, but this is not allowed. As a result, inheritance is not applicable to the home interfaces.

• The primary key of the subclass must be the same as that of the parent class.

The advanced example application illustrates inheritance. For more information, see the ReadMe.html file in the root directory of the advanced example application. This application is located in

• <INSTALL_DIR>\examples\wls70\examples\ejb\cmp20\advanced\ (WebLogic 7.0 and CMP 2.0)

• <INSTALL_DIR>\examples\wls70\examples\ejb\
cmp1.1\advanced\ (WebLogic 7.0 and CMP 1.1)

• <INSTALL_DIR>\examples\wls61\examples\ejb\cmp20\advanced\ (WebLogic 6.1 and CMP 2.0)

• <INSTALL_DIR>\examples\wls61\examples\ejb\cmp20\advanced\ (WebLogic 6.1 and CMP 1.1)

Indirection

TopLink provides several mechanisms for just-in-time reading of relationships (also referred to as "lazy-loading" and "indirection"). There are three techniques that are available:

• use of indirection objects

• transparent indirection

• proxy indirection

While these indirection mechanisms are described in the Oracle9iAS TopLink Mapping Workbench Reference Guide, there are a number of issues that entity bean developers should be aware of when using indirection. In general these issues arise due to the migration of objects between client and server.

Issues include:

• Un-instantiated ValueHolders (indirection objects) do not survive serialization. If a ValueHolder is sent from the server to the client, it will no longer function unless it has been previously triggered.

• ValueHolders can be used in bean-bean relationships, and bean-object relationships, but should be avoided in relationships whose source is likely to be serialized to the client.

• Collections that use transparent indirection should not be serialized to the client application before they are instantiated. These collections will not function if they are serialized.

• Proxy indirection (available in JDK 1.3) cannot be used for relationships whose target is an entity bean. The proxies used for this kind of indirection will interfere with the RMI stubs and skeletons generated for the entity. Proxies should be instantiated before being serialized to the client.

• ValueHolders should generally be used for bean-bean relationships, and for bean-object relationships. Transparent indirection can be used for collections that are not exposed to the client application.

Under the EJB 2.0 specification, the indirection policies for CMP fields must be one of the following:

• Transparent indirection for 1-Many or Many-Many relationships

• Value holder indirection for 1-1 relationships

Because of the code-generated subclasses, all indirection is hidden from the user.

For more information about these and other important issues, consult "Run-time Considerations".