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 project classpath that is used by the TopLink Mapping Workbench project, 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 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 1.1 specification does not specify how one entity bean should store an object reference to another entity bean. TopLink for IBM WebSphere goes beyond what is available in the specification and allows the creation of inter-bean relationships.

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 remote interface of the bean. For example, if an OrderBean is related to a CustomerBean, it has an instance variable of type Customer (the remote interface of the CustomerBean) and only accesses those methods defined on the Customer interface.

Note: Although beans must refer to each other through their remote 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 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.

Mappings between entity beans and Java objects

The EJB 1.1 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 remote 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.

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.

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 (which is the only native sequencing available for some CMP implementations).

Adding sequencing outside of the TopLink Mapping Workbench

WebSphere does not support auto-incrementing identity fields such as those found in DB2, Sybase and SQL Server databases when using TopLink for WebSphere Foundation Library. Use a sequence table or Oracle sequence object to implement sequencing with the TopLink for WebSphere Foundation Library.

In order for TopLink to correctly assign the sequence number to a newly created bean the following line must be added to the ejbCreate method in the bean class:

oracle.toplink.ejb.cmp.was.SessionLookupHelper.
getHelper().getSession(this).getActiveUnitofWork().assignSequenceNumber(this);

This line looks up the correct session and uses it to assign a sequence number to the bean. For more information on setting up sequencing see the Oracle9iAS TopLink Mapping Workbench Reference Guide.

Note: TopLink defers database access to the commit stage of the transaction. Clients that use client-initiated UserTransactions should not reference the primary key of newly created objects because they are not yet properly initialized before commit-time.

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 specification discusses 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 {ORACLE_HOME}\TopLink\examples\was\examples\ejb\cmp11\advanced.

Indirection

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

• use of indirection objects

• transparent 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.

• 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.

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