4
Entity Relationship Mapping

This chapter discusses how to develop entity-to-entity relationships. As a developer, you can approach entity relationships from either of the following viewpoint:

• EJB development--Use UML diagrams to design the entity beans, and the cardinality and direction of the relationship between each bean, from the perspective of the EJB objects.

• Database development--Use ERD diagrams to design the database tables, complete with the cardinality and direction designated by primary and foreign keys, that support the entity beans. The focus is on how the database maps each entity bean and the relationships between them.

This chapter starts by discussing entity relationships from the EJB development viewpoint. Next, it demonstrates how the deployment descriptor maps to database tables. If you want to design with the database development viewpoint, skip to "Mapping Object Relationship Fields to the Database".

Note: An object-relationship entity bean example (ormapdemo.jar) is available on OTN from the OC4J sample code page on the OTN Web site.

This chapter covers the following topics:

• Transaction Requirements

• Defining Entity-To-Entity Relationships

• Mapping Object Relationship Fields to the Database

• Using a Foreign Key in a Composite Primary Key

• How to Override a Foreign Key Database Constraint

Transaction Requirements

All entity beans with CMP and CMR relationships must be involved in a transaction. As such, you cannot define any entity bean with a transaction attribute of NEVER, SUPPORTS, or NOT_REQUIRED as this would put the entity outside of a transaction.

Defining Entity-To-Entity Relationships

The following sections describe what an entity bean relationship can be and how to define them.

• Choosing Cardinality and Direction

• Requirements in Defining Relationships

Choosing Cardinality and Direction

Cardinality refers to the number of entity objects on each side of the relationship. Thus, you can define the following types of relationship between EJBs:

• one-to-one

• one-to-many or many-to-one (dependent on the direction)

• many-to-many

In addition, each relationship can unidirectional or bidirectional. For example, a unidirectional relationship can be from an employee to an address. With the employee information, you can retrieve an address. However, with an address, you cannot retrieve the employee. An example of a bidirectional relationship is with a employee/projects example. Given a project number, you can retrieve the employees working on the project. Given an employee number, you can retrieve all projects that the employee is working on. Thus, the relationship is valid in both directions.

You can use a unidirectional relationship when you want to reuse the target from multiple entities. For example, both a husband and a wife may work for the same company. Both of their employee records could point to the same home phone number in a unidirectional relationship. You could not have this situation in a bidirectional relationship.

You define the cardinality and direction of the relationship between two beans in the deployment descriptor.

One-To-One Relationship Overview

A one-to-one relationship is the simplest relationship between two beans. One entity bean relates only to one other entity bean. If our company office contains only cubicles, and only a single employee can sit in each cubicle, then you have a one-to-one relationship: one employee in one designated cubicle. You define a unidirectional definition for this relationship as follows:

employee --> cubicle

However, if you have a cubicle number and want to determine who is assigned to it, you can assign a bidirectional relationship. This would enable you to retrieve the employee and find what cubicle he/she sits in. In addition, you could retrieve the cubicle number and determine who sits there. You define this bidirectional one-to-one relationship as follows:

employee <--> cubicle

One-To-Many or Many-To-One Relationship Overview

In a one-to-many relationship, one object can reference several instances of another. A many-to-one relationship is when many objects reference a single object. For example, an employee can have multiple addresses: a home address and an office address. If you define these relationships as unidirectional from the perspective of the employee, then you can look up the employee and see all of his/her addresses, but you cannot look up an address to see who lives there. However, if you define this relationship as bidirectional, then you can look up any address and see who lives there.

Many-To-Many Relationship Overview

A many-to-many relationship is complex. For example, each employee can be working on several projects. And each projects has multiple employees working on it. Thus, you have a many-to-many cardinality. The direction does not matter in this instance. You have the following cardinality:

employees <--> projects

In a many-to-many relationship, many objects can reference many objects. This cardinality is the most difficult to manage.

Requirements in Defining Relationships

Here are the restrictions imposed on defining your relationships:

• You can define relationships only between CMP 2.0 entity beans.

• You must declare both EJBs in the relationship within the same deployment descriptor.

• Each relationship can use only the local interface of the target EJB.

The following are the requirements to define each cardinality type and its direction:

1. Define the abstract accessor methods (get/set methods) for each relationship field. The naming follows the same rules as for the persistence field abstract accessor methods. For example, getAddress and setAddress methods are abstract accessor methods for retrieving and setting an address.

2. Set the relationships in the bean implementation. The primary key must always be set in the ejbCreate method; the foreign key can be set anytime after the ejbCreate method, but not within it.

3. Define each relationship--its cardinality and direction--in the deployment descriptor. The relationship field name is defined in the <cmr-field-name> element. This name must be the same as the abstract accessor methods, without the get/set and the first letter in lower case. For example, the <cmr-field-name> would be address to compliment the getAddress/setAddress abstract accessor methods.

4. If you want cascade delete, then declare the cascade delete option for the one-to-one, one-to-many, and many-to-one relationships. The cascade delete is always specified on the slave side of the relationship, so that when the master entity is deleted, all of the slave entities related to it are subsequently deleted. For example, when an employee has multiple phone numbers, the cascade delete is defined on the phone numbers side. Then, when the employee is deleted, all of the related phone numbers are also deleted.

The following sections provides an example of how to implement each of these requirements:

• Define the Get/Set Methods for Each Relationship Field

• Set the Relationships in the Bean Implementation

• Declare the Relationships in the Deployment Descriptor

• Decide Whether to Use the Cascade Delete Option

Define the Get/Set Methods for Each Relationship Field

Each relationship field must have the abstract accessor methods defined for it. In a relationship that sets or retrieves only a single entity, the object type passed back and forth must be the local interface of the target entity bean. In a relationship that sets or retrieves multiple objects, the object type passed back and forth is a Set or Collection containing local interface objects.

Example 4-1 Definition of Abstract Accessor Methods for the Employee Example

In this example, the employee has an employee number and a single address. You can retrieve the employee number and address only through the employee. This defines one-to-one relationships that is unidirectional from the perspective of the employee. Then the abstract accessor methods for the employee bean are as follows:

public Integer getEmpNo();
public void setEmpNo(Integer empNo);
public AddressLocal getAddress();
public void setAddress(AddressLocal address);

Because the cardinality is one-to-one, the local interface of the address entity bean is the object type that is passed back and forth in the abstract accessor methods.

The cardinality and direction of the relationship are defined in the deployment descriptor.

Example 4-2 Definition of One-To-Many Abstract Accessor Methods

If the employee example included a one-to-many relationship, the abstract accessor methods would pass back and forth a Set or Collection of objects, each of which contains target bean local interface objects. When you have a "many" relationship, multiple records are being passed back and forth.

A department contains many employees. In this one-to-many example, the abstract accessor methods for the department retrieves multiple employees. Thus, the abstract accessor methods pass a Collection or a Set of employees, as follows:

public Collection getDeptEmployees();
public void setDeptEmployees(Collection deptEmpl);

Set the Relationships in the Bean Implementation

Once you have defined the get/set relationship methods, use them in the bean implementation to set up the relationships. All primary key relationships must be set within the ejbCreate method, as shown in "Entity Bean Class". If you use a foreign key, as described in "Using a Foreign Key in a Composite Primary Key", you can set the foreign key as early as the ejbPostCreate method.

When you set the primary key in the ejbCreate, the set methods populate the CMP fields that you define in the deployment descriptor. At the end of the ejbCreate method, these fields are written out to the appropriate database row.

The employee has a primary key of the employee number. The following sets the primary key for the department:

public Integer ejbCreate(Integer empNo) throws CreateException
{
    setEmpNo(empNo);
    return empNo;
}

Declare the Relationships in the Deployment Descriptor

You define the relationships between entity beans in the same deployment descriptor the entity beans are declared. All entity-to-entity relationships are defined within the <relationships> element and you can define multiple relationships within this element. Each specific entity-to-entity relationship is defined within an <ejb-relation> element. The following XML demonstrates two entity-to-entity relationships defined within an application:

<relationships>
      <ejb-relation>
      ...
      </ejb-relation>
      <ejb-relation>
      ...
      </ejb-relation>
</relationships>

The following XML shows the full element structure for relationships:

<relationships>
  <ejb-relation>
    <ejb-relation-name> </ejb-relation-name>
    <ejb-relationship-role>
      <ejb-relationship-role-name> </ejb-relationship-role-name>
      <multiplicity> </multiplicity>
      <relationship-role-source>
         <ejb-name> </ejb-name>
      </relationship-role-source>
      <cmr-field>
        <cmr-field-name> </cmr-field-name>
        <cmr-field-type> </cmr-field-type>
      </cmr-field>
    </ejb-relationship-role>
  </ejb-relation>
</relationships>

Note: An object-relationship entity bean example is available on OTN from the OC4J sample code page on the OTN Web site.

Table 4-1 describes the usage for each of these elements.

Table 4-1 Description of Relationship Elements of the Deployment Descriptor

Deployment Descriptor Element	Description
<ejb-relation>	Each entity-to-entity relationship is described in a single <ejb-relation> element.
<ejb-relation-name>	A user-defined name for the entity-to-entity relationship.
<ejb-relationship-role>	Each entity within the relationship is described within its own <ejb-relationship-role>. Thus, there are always two <ejb-relationship-role> entities within the <ejb-relation>.
<ejb-relationship-role-name>	A user-defined name to describe the role or involvement of the entity bean in the relationship.
<multiplicity>	The declaration of the cardinality for this entity. The value is "one" or "many."
<relationship-role-source><ejb-name>	The name of the entity bean. This must equal an EJB name defined in an <entity><ejb-name> element in the ejb-jar.xml file.
<cmr-field><cmr-field-name>	A user-defined name to represent the target bean reference. This name must match the abstract accessor methods. For example, if the abstract accessor fields are getAddress() and setAddress(), the CMR field must be address.
<cmr-field><cmr-field-type>	Optional. If "many", this type should be a Collection or Set. This is only specified for the "many" side to inform if a Collection or a Set is returned.

These relationships can be one-to-one, one-to-many, or many-to-many. The cardinality is defined within the <multiplicity> element. Each bean defines its cardinality within its own relationship. For example,

• One-to-one: For one employee to have a relationship with one address, the employee bean is declared with a <multiplicity> of one, and the address bean is declared with a <multiplicity> of one.

• One-to-many, many-to-one: For one department to have a relationship with multiple employees, the department bean is declared with a <multiplicity> of one, and the employee bean is declared with a <multiplicity> of many. For many employees to belong to a department, you define the same <multiplicity>.

• Many-to-many: For each employee to have a relationship with multiple projects and each project to have multiple employees working on it, the employee bean is declared with a <multiplicity> of many, and the project is declared with a <multiplicity> of many.

The direction of the relationship is defined by the presence of the <cmr-field> element. The reference to the target entity is defined within the <cmr-field> element. If the relationship is unidirectional, then only one entity within the relationship contains a reference to a target. In this case, the <cmr-field> element is declared in the source entity and contains the target bean reference. If the relationship is bidirectional, both entities should declare a reference to each other's bean within a <cmr-field> element.

The following demonstrates how to declare direction in the one-to-one employee and address example:

• Unidirectional: Define the <cmr-field> element within the employee bean section that references the address bean. Do not define a <cmr-field> element in the address bean section of the relationship.

• Bidirectional: Define a <cmr-field> element in the employee bean section that references the address bean. In addition, define a <cmr-field> element in the address bean section that references the employee bean.

Once you understand how to declare the cardinality and direction of the entity relationships, configuring the EJB deployment descriptor for each relationship is simple.

Example 4-3 One-To-One Relationship Example

The employee example defines a one-to-one unidirectional relationship in which each employee has only one address. This relationship is unidirectional because you can retrieve the address from the employee, but you cannot retrieve the employee from the address. Thus, the employee object has a relationship to the address object.

The ejb-jar.xml file is configured for this example, as follows:

<enterprise-beans>
  <entity>
    ...
    <ejb-name>EmpBean</ejb-name>
    <local-home>employee.EmpHome</local-home>
    <local>employee.Emp</local>
    <ejb-class>employee.EmpBean</ejb-class>
    ...
  </entity>
  <entity>
    ...
    <ejb-name>AddressBean</ejb-name> 
    <local-home>employee.AddressHome</local-home>
    <local>employee.Address</local>
    <ejb-class>employee.AddressBean</ejb-class>
    ...
  </entity>
</enterprise-beans>
...
<relationships>
   <ejb-relation>
         <ejb-relation-name>Emp-Address</ejb-relation-name>
         <ejb-relationship-role>
            <ejb-relationship-role-name>Emp-has-Address
            </ejb-relationship-role-name>
            <multiplicity>One</multiplicity>
            <relationship-role-source><ejb-name>EmpBean</ejb-name>
            </relationship-role-source>
            <cmr-field>
               <cmr-field-name>address</cmr-field-name>
            </cmr-field>
         </ejb-relationship-role>
         <ejb-relationship-role>
            <ejb-relationship-role-name>Address-has-Emp
            </ejb-relationship-role-name>
            <multiplicity>One</multiplicity>
            <relationship-role-source><ejb-name>AddressBean</ejb-name>
            </relationship-role-source>
         </ejb-relationship-role>
      </ejb-relation>
</relationships>

The ejb-jar.xml file has defined the following:

• Configure each <entity> element within the <enterprise-beans> section for each of the entity beans involved in the relationship. For this example, these include an <entity> element for the employee with an <ejb-name> of EmpBean and an <entity> element for the address with an <ejb-name> of AddressBean.

• Configure the <ejb-relationship> element within the <relationships> section for the one-to-one relationship. For this example, it defines the following:
  • An <ejb-relationship-role> element for the employee bean that defines its cardinality as "one" in its <multiplicity> element. The <relationship-role-source> element defines the <ejb-name> as EmpBean, which is the same name in the <entity> element.

  • An <ejb-relationship-role> element for the address bean that defines its cardinality as "one" in its <multiplicity> element. The <relationship-role-source> element defines the <ejb-name> as AddressBean, which is the same name in the <entity> element.

• Configure a <cmr-field> element in the EmpBean relationship that points to the AddressBean. The <cmr-field> element defines address as the AddressBean reference. This element name matches the get and set method names, which are named getAddress and setAddress. These methods identify the local interface of the address entity bean as the data type that is returned from the get method and passed in on the set method.

  Note: An object-relationship entity bean example is available on OTN from the OC4J sample code page on the OTN Web site.

Decide Whether to Use the Cascade Delete Option

When you have relationships between entity beans and the master entity bean is deleted, what happens to the slave beans? If you specify cascade delete, the deletion of a master entity bean automatically deletes all of its slave relationship entity beans. You specify the cascade delete option in the slave relationship definition, which is the object that is deleted automatically.

For example, an employee has a relationship with an address object. The address object specifies cascade delete. When the employee, as master in this relationship, is deleted, the address, the slave, is also deleted.

In some instances, you do not want a cascade delete to occur. If you have a department that has a relationship with multiple employees within the department, you do not want all employees to be deleted when you delete the department.

You can only specify a cascade delete on a relationship if the master entity bean has a <multiplicity> of one. Thus, in a one-to-one, the master is obviously a "one". You can specify a cascade delete in a one-to-many relationship, but not in a many-to-one or many-to-many relationship.

Example 4-4 Cascade Delete Requested in the Employee Example

The following deployment descriptor shows the definition of a one-to-one relationship with the employee and his/her address. When the employee is deleted, the slave entity bean--the address--is automatically deleted. You ensure the deletion by specifying the <cascade-delete/> element in the slave entity bean of the relationship. In this case, specify the <cascade-delete/> element in the AddressBean definition.

<relationships>
   <ejb-relation>
         <ejb-relation-name>Emp-Address</ejb-relation-name>
         <ejb-relationship-role>
            <ejb-relationship-role-name>Emp-has-Address
            </ejb-relationship-role-name>
            <multiplicity>One</multiplicity>
            <relationship-role-source><ejb-name>EmpBean</ejb-name>
            </relationship-role-source>
            <cmr-field>
               <cmr-field-name>address</cmr-field-name>
            </cmr-field>
         </ejb-relationship-role>
         <ejb-relationship-role>
            <ejb-relationship-role-name>Address-has-Emp
            </ejb-relationship-role-name>
            <multiplicity>One</multiplicity>
           <cascade-delete/>
            <relationship-role-source><ejb-name>AddressBean</ejb-name>
            </relationship-role-source>
         </ejb-relationship-role>
      </ejb-relation>
</relationships>

Mapping Object Relationship Fields to the Database

Each entity bean maps to a table in the database. Each of its persistent and relationship fields are saved within a database table in columns. For these fields to be mapped to a database, do one of the following:

• Accept the defaults for these fields and avoid more deployment descriptor configuration. See "Default Mapping of Relationship Fields to the Database" to learn how the default mapping occurs. The tables are automatically created for the bean based on the information in the ejb-jar.xml file.

• Map the fields to columns in a table that already exists in a designated database. The persistent data mapping is configured within the orion-ejb-jar.xml file. See "Explicit Mapping of Relationship Fields to the Database" for more information.

Default Mapping of Relationship Fields to the Database

Note: This section discusses how OC4J maps relationship fields to the database. Chapter 3, "CMP Entity Beans" discusses persistent field mapping.

When you declare relationship fields in the ejb-jar.xml file, OC4J provides default mappings of these fields to the database when it auto-generates the orion-ejb-jar.xml file. The default mapping for relationships is the same as for the persistent fields, as described in "Default Mapping of Persistent Fields to the Database".

Note: For all future redeployments, copy the auto-generated orion-ejb-jar.xml file with this table name into the same directory as your ejb-jar.xml file from the J2EE_HOME/application-deployments directory. Thus, all future redeployments have the same table names as first generated. If you do not copy this file over, different table names may be generated.

In summary, these defaults include:

• Database--The default database as set up in your OC4J instance configuration.

• Default table--Each entity bean in the relationship represents data in its own database table. The name of the entity bean table makes an effort to be unique, and so it is constructed with the following names, where each is separated by an underscore (_):
  • EJB name defined in <ejb-name> in the deployment descriptor.

  • JAR file name, including the .jar extension. However, all dashes (-) and periods (.) are converted to underscores (_) to follow SQL conventions. For example, if the name of your JAR file is employee.jar, then employee_jar is appended to the name.

  • Application name: You define the application name during deployment.

  If the constructed name is greater than thirty characters, the name is truncated at twenty-four characters. An underscore and then five characters made up of an alphanumeric hash code is appended to the name for uniqueness.

  For example, if the EJB name is EmpBean, the JAR file is empl.jar, and the application name is employee, then the default table name is EmpBean_empl_jar_employee.

• Column names in each table--The container generates columns in each table based on the <cmp-field> and <cmr-field> elements defined in the deployment descriptor. A column is created for each <cmp-field> element that relates to the entity bean data. In addition, a column is created for each <cmr-field> element that represents a relationship. In a unidirectional relationship, only a single entity in the relationship defines a <cmr-field> in the deployment descriptor. In a bidirectional relationship, both entities in the relationship define a <cmr-field>.

  For each <cmr-field> element, the container creates a foreign key that points to the primary key of the relevant object, as follows:

  • In the default one-to-one relationship, the foreign key is created in the database table for the source EJB and is directed to the primary key of the target database table. For example, if one employee has one address, then the foreign key is created within the employee table that points to the primary key of the address table. For more information, see "Example of a Default Mapping of the One-To-One Relationship".

  • The default for one-to-many relationships uses a foreign key as described in "Using a Foreign Key with the One-To-Many Relationship".

  • The default for many-to-many relationships creates an association table (a third table). The association table contains two foreign keys, where each points to the primary key of one of the entity tables. For more information, see "Example of a Default Mapping of One-To-Many and Many-To-Many Relationships".

  Since the <cmp-field> and <cmr-field> elements represent Java data types, they may not convert to database types in the manner you believe that they should. See "Converstion of CMP Types to Database Types" for a table of how the conversion occurs. However, you can modify the translation rules for converting Java data types to database data types in the specific database XML files, which are located in j2ee/home/config/database-schemas. This directory includes all database files. The Oracle database conversion file is named oracle.xml.

• Primary key generation--Both entity tables contain a primary key. The primary key can be defined or auto-generated. See "Primary Key" for a full description.
  • Defined primary key: The primary key is generated as designated in the <primkey-field> element as a simple data type or a class. Thus, the column name is the same as the name in the <primkey-field> element.

  • Composite primary key: The primary key is defined within a class, and is made up of several fields. Each field within the composite primary key is represented by a column in the database table, where each is considered part of the primary key in the table.

  • Auto-generated primary key: If you specify a java.lang.Object as the primary key class type in <prim-key-class>, but do not specify the primary key name in <primkey-field>, then the primary key is auto-generated by the container. The column is named AUTOID.

Example of a Default Mapping of the One-To-One Relationship

The one-to-one entity relationship is managed between the entity tables with a foreign key. Figure 4-1 demonstrates the default table mapping of a one-to-one unidirectional relationship between the employee and address bean.

Figure 4-1 One-To-One Employee Relationship Example

Text description of the illustration o_1037.gif

• The container generates the table names based on the entity bean names, the JAR file the beans are archived in, and the application name that they are deployed under. If the JAR filename is empl.jar and the application name is employee, then the table names are EmpBean_empl_jar_employee and AddressBean_empl_jar_employee.

• The container generates columns in each table based on the <cmp-field> and <cmr-field> elements declared in the deployment descriptor.
  • The columns for the EmpBean table are empno, empname, and salary. A foreign key is created called address, from the <cmr-field> declaration, that points to the primary key column of the AddrBean table.

  • The columns for the AddressBean table are an auto-generated long primary key and columns for street, city, state, and zip.

• The primary key for the employee table is designated in the deployment descriptor as empno. The AddressBean is configured for an auto-generated primary key by specifying only <primkey-class> of java.lang.Object.

Example of a Default Mapping of One-To-Many and Many-To-Many Relationships

As described in "One-To-Many or Many-To-One Relationship Overview", one bean, such as a department, can have a relationship to multiple instances of another bean, such as employees. There are several employees in each department. Since this is a bidirectional relationship, you can look up the department from the employee. The relationships between the DeptBean and EmpBean is represented by CMR fields, employees and deptno, as shown in Figure 4-10.

Figure 4-2 One-to-Many Bean Relationship

Text description of the illustration o_1066.gif

How this relationship is mapped to database tables depends on your choices. The default method adds a foreign key to the table that defines the "many" side of the relationship--in this case, the table that represents the EmpBean. The foreign key points back to the department to which each employee belongs.

Figure 4-11 shows the department<-->employee example, where each employee belongs to only one department and each department can contain multiple employees. The department table has a primary key. The employee table has a primary key to identify each employee and a foreign key to point back to the employee's department. If you want to find the department for a single employee, a simple SQL statement retrieves the department information from the foreign key. To find all employees in a department, the container performs a JOIN statement on both the department and employee tables and retrieves all employees with the designated department number.

Figure 4-3 Default Mapping for One-To-Many Bidirectional Relationship Example

Text description of the illustration o_1090.gif

"Using a Foreign Key with the One-To-Many Relationship" details how the deployment descriptors are configured for this behavior to occur. To keep the same defaults for all future redeployments, copy the auto-generated orion-ejb-jar.xml file with the default table name into the same directory as your ejb-jar.xml file from the J2EE_HOME/application-deployments directory. Thus, all future redeployments have the same table names as first generated. If you do not copy this file over, different table names may be generated. To modify the defaults, copy the file over and follow the directions in "Using a Foreign Key with the One-To-Many Relationship".

Explicit Mapping of Relationship Fields to the Database

As "Default Mapping of Relationship Fields to the Database" discusses, your relationship fields can be automatically mapped to the database tables by the container. However, if you do not want to accept the defaults that OC4J provides for you or if you need to map the fields to an existing database table, then you can map the relationships between entity beans to an existing database table and its columns in the orion-ejb-jar.xml file.

"Explicit Mapping of Persistent Fields to the Database" discusses how to explicitly map CMP fields. This section is about mapping CMR fields and so builds on that information to show how the relationship mapping occurs.

Important: You modify elements and attributes of the <entity-deployment> element in the orion-ejb-jar.xml file to explicitly map relationship fields. JDeveloper was created to manage the complex mapping between the entity beans and the database tables. Thus, JDeveloper validates the deployment descriptors and prevents inconsistencies. You are allowed to modify the orion-ejb-jar.xml file on your own; however, we suggest that you use JDeveloper for modifying container-managed relationships. CMR configuration is complex and can be difficult to understand. You can download JDeveloper at the following site: http://otn.oracle.com/software/products/jdev/content.html

This chapter provides two levels of information about the orion-ejb-jar.xml elements:

• A quick, direct guide for identifying the fields in which you would modify if you mapped to an existing database. See "Quick Cookbook for Matching an Existing Database to the Bean Mappings".

• An education on all elements used in the CMR mapping and directions on modifying them. See "Steps for Modifying CMR Mapping Elements".

Quick Cookbook for Matching an Existing Database to the Bean Mappings

If you want to know how to modify the orion-ejb-jar.xml file without understanding what each of the elements are for in this XML file and you do not want to use JDeveloper, then do the following:

1. Deploy your bean with the autocreate-tables element set to false in the orion-application.xml file.

2. Copy the orion-ejb-jar.xml file from the application-deployments/ directory to your development directory.

3. Modify the data-source element to be the correct data source. Note that all beans that are associated with each other must use the same data source.

4. Modify the table attribute to be the correct table. Make sure that it is the correct table for the bean that is defined in the <entity-deployments> element.

5. Modify the persistence-name attributes to the correct column for each bean persistence type, whether a CMP or CMR field.

6. Set the autocreate-tables element in orion-application.xml file to true.

7. Rearchive your application and redeploy.

   Note: An object-relationship entity bean example is available on OTN from the OC4J sample code page on the OTN Web site.

Steps for Modifying CMR Mapping Elements

If JDeveloper does not provide the mapping that you need or if you wish to manage the XML on your own, then you should perform the following steps:

1. Deploy your bean with the autocreate-tables element set to false in the orion-application.xml file and the ejb-jar.xml elements configured.

   OC4J creates an orion-ejb-jar.xml file for you, with the default mappings in it. It is easier to modify these fields than to create them from scratch.

2. Copy the container-created orion-ejb-jar.xml file from the $J2EE_HOME/application-deployments directory to your development environment.

3. Modify the <entity-deployment> element in the orion-ejb-jar.xml file to use the database table and columns you specify, based on the relationship type. See "Hand-Editing the orion-ejb-jar.xml File to Map Bean Relationships to Database Tables" for an overview.

   Each of the following sections describes how the CMR mapping occurs for each relationship type:

   • One-To-One Relationship Explicit Mapping

   • Table Mapping For Primary Keys That Use AutoId

   • Using a Foreign Key with the One-To-Many Relationship

   • Association Table Explicit Mapping for Relationships Overview

   • Using an Association Table with a One-to-Many Bidirectional Relationship

   • Using an Association Table in a One-to-Many Unidirectional Relationship

   • Using an Association Table in Many-to-Many Relationships

4. Set the autocreate-tables element in orion-application.xml file to true.

5. Rearchive your application and redeploy.

   Note: If you deployed without setting autocreate-tables to false, then OC4J automatically created the default tables. You must drop all of these tables before redeploying the application. If you use an association table, this must be dropped also.

Hand-Editing the orion-ejb-jar.xml File to Map Bean Relationships to Database Tables

The relationship between the beans is defined in the <relationships> element in the ejb-jar.xml file; the mapping between the bean and the database table and columns is specified in the <entity-deployment> element in the orion-ejb-jar.xml file.

The orion-ejb-jar.xml file maps the bean entity relationships to database table and columns within a <cmp-field-mapping> element. The following is the XML structure of the <entity-deployment> and <cmp-field-mapping> elements for a simple one-to-one relationship:

<entity-deployment name="SourceBeanName" location="JNDIlocation"

table="TableName" data-source="DataSourceJNDIName">

...
<cmp-field-mapping name="CMRfield_name">
    <entity-ref home="targetBeanName">
      <cmp-field-mapping name="CMRfield_name"

	persistence-name="targetBean_PKcolumn" />
    </entity-ref>
</cmp-field-mapping>

Within this element, you can define the bean name (the source of the relationship that indicates the direction), the JNDI location, the database table to which the information is persisted, and map each of the CMP and CMR fields defined in the ejb-jar.xml file to the underlying persistence storage--the database.

Note: This document refers to beans as the source or target of a relationship. If an employee owns many phones in a unidirectional relationship, then the employee is the source bean and it points to the phones, which are the target.

The attributes of the <entity-deployment> element define the following for the bean:

• The name attribute identifies the EJB name of the bean, which was defined in the <ejb-name> element in the ejb-jar.xml file. This name attribute connects the ejb-jar.xml file definition for the bean to its mapping to the database.

• The location attribute identities the JNDI name of the bean.

• The table attribute identifies the database table to which this entity bean is mapped.

• The data-source attribute identifies the database in which the table resides. The data source must be the same for all beans that interact with each other or are associated with each other. This includes beans that are in the same application, part of the same transaction, or beans that are in a parent-child relationship.

The <cmp-field-mapping> element in the orion-ejb-jar.xml file maps the following fields to database columns.

• The <cmp-field> element in the ejb-jar.xml file defines a CMP field.

• The <cmr-field> element in the ejb-jar.xml file defines a CMR field.

Figure 4-8 displays how the <cmr-field> element in the ejb-jar.xml file maps to the <cmp-field-mapping> element in the orion-ejb-jar.xml file. The name attribute in the <cmp-field-mapping> provides the link between the two XML files. You must not modify any name attributes.

Figure 4-4 Demonstration of Mapping for a One-To-One Relationship

Text description of the illustration o_1061.gif

To fully identify and map CMR fields, nested <cmp-field-mapping> elements are used. The format of the nesting depends on the type of relationship. The database column that is the primary key of the target bean is defined in the persistence-name attribute of the internal <cmp-field-mapping> element. If you have an existing database, you would be modifying the persistence-name attributes for each <cmp-field-mapping> element to match your column names.

The following sections talk about each relationship type and how the mapping occurs:

• One-To-One Relationship Explicit Mapping

• Table Mapping For Primary Keys That Use AutoId

• Using a Foreign Key with the One-To-Many Relationship

• Association Table Explicit Mapping for Relationships Overview

• Using an Association Table with a One-to-Many Bidirectional Relationship

• Using an Association Table in a One-to-Many Unidirectional Relationship

• Using an Association Table in Many-to-Many Relationships

One-To-One Relationship Explicit Mapping

Figure 4-5 demonstrates a one-to-one unidirectional relationship between a single employee and his/her address. The EmpBean points to the AddressBean that is the employee's address using the CMR field, address.

Figure 4-5 One-to-One Bean Relationship

Text description of the illustration o_1062.gif

Figure 4-6 shows the database tables, EMP and ADDRESS, to which these beans will map. The EMP table has a foreign key, named address, which points to the primary key of the ADDRESS table, AddressPK.

Figure 4-6 One-To-One Employee Relationship Example

Text description of the illustration o_1091.gif

The beans and their relationships are specified in both of the deployment descriptors. As Figure 4-7 shows, in the ejb-jar.xml file, the one-to-one relationship between the EmpBean and AddressBean is defined within a <relationships> element. The direction is designated by one or two <cmr-field> elements.

The mapping of the beans to their database persistent storage is defined in the orion-ejb-jar.xml file. The one-to-one relationship--whether bidirectional or unidirectional--is mapped on both sides with an <entity-ref> element inside a <cmp-field-mapping> element. The <entity-ref> describes the target entity bean of the relationship.

Figure 4-7 Demonstration of Mapping for a One-To-One Relationship

Text description of the illustration o_1064.gif

To map your bean fields to an existing database, you need to understand the fields within the <cmp-field-mapping> element in the orion-ejb-jar.xml file. This element has the following structure:

<cmp-field-mapping name="CMRfield_name">
    <entity-ref home="targetBeanName">
      <cmp-field-mapping name="CMRfield_name"

	persistence-name="targetBean_PKcolumn" />
    </entity-ref>
</cmp-field-mapping>

• The name attribute of the <cmp-field-mapping> element is the same as the <cmp-field> element in the ejb-jar.xml file. Do not modify the name attribute in the <cmp-field-mapping> element.

• The target bean name is specified in the home attribute of the <entity-ref> element.

• The database column that is the primary key of the target bean is defined in the persistence-name attribute of the internal <cmp-field-mapping> element. If you have an existing database, modify the persistence-name attributes for each <cmp-field-mapping> element to match your column names.

Example 4-5 The XML Configuration for One-to-One Unidirectional

The ejb-jar.xml file configuration defines a one-to-one unidirectional relationship between the EmpBean and AddressBean.

<enterprise-beans>
  <entity>
    ...
    <ejb-name>EmpBean</ejb-name>
    <local-home>employee.EmpHome</local-home>
    <local>employee.Emp</local>
    <ejb-class>employee.EmpBean</ejb-class>
    ...
    <cmp-field><field-name>empNo</field-name></cmp-field>
    <cmp-field><field-name>empName</field-name></cmp-field>
    <cmp-field><field-name>salary</field-name></cmp-field>
    <primkey-field>empNo</primkey-field>
    <prim-key-class>java.lang.Integer</prim-key-class>
    ...
  </entity>
  <entity>
    ...
    <ejb-name>AddressBean</ejb-name> 
    <local-home>employee.AddressHome</local-home>
    <local>employee.Address</local>
    <ejb-class>employee.AddressBean</ejb-class>
    ...
    <cmp-field><field-name>addressPK</field-name></cmp-field>
    <cmp-field><field-name>addressDescription</field-name></cmp-field>
    <primkey-field>addressPK</primkey-field>
    <prim-key-class>java.lang.Integer</prim-key-class>
    ...
  </entity>
</enterprise-beans>
<relationships>
   <ejb-relation>
         <ejb-relation-name>Emp-Address</ejb-relation-name>
         <ejb-relationship-role>
            <ejb-relationship-role-name>Emp-has-Address
            </ejb-relationship-role-name>
            <multiplicity>One</multiplicity>
            <relationship-role-source><ejb-name>EmpBean</ejb-name>
            </relationship-role-source>
            <cmr-field>
               <cmr-field-name>address</cmr-field-name>
            </cmr-field>
         </ejb-relationship-role>
         <ejb-relationship-role>
            <ejb-relationship-role-name>Address-has-Emp
            </ejb-relationship-role-name>
            <multiplicity>One</multiplicity>
            <relationship-role-source><ejb-name>AddressBean</ejb-name>
            </relationship-role-source>
       </ejb-relationship-role>
      </ejb-relation>
</relationships>

The EmpBean defines a <cmr-field> for the direction of the relationship showing that each employee has one address. The EMP table that supports EmpBean requires a foreign key to point to the table that supports the AddressBean.

The foreign key from the EMP table to the ADDRESS table is identified as address within the <cmr-field-name> element, which is required on the name attribute of the <cmp-field-mapping> element in the orion-ejb-jar.xml file. Thus, address is the identifier that links the relationship defined in the ejb-jar.xml file to the persistence storage mapping specified in the orion-ejb-jar.xml file.

The following is the orion-ejb-jar.xml file with the elements modified to map to the existing database tables:

<entity-deployment name="EmpBean" location="emp/EmpBean" ...

table="EMP" data-source="jdbc/OracleDS" ...>

       <primkey-mapping>
             <cmp-field-mapping name="empNo" persistence-name="EMPNO" />
       </primkey-mapping>
       <cmp-field-mapping name="empName" persistence-name="ENAME" />
       <cmp-field-mapping name="salary" persistence-name="SAL" />
       <cmp-field-mapping name="address">
           <entity-ref home="AddressBean">
              <cmp-field-mapping name="address"
                                 persistence-name="addressPK" />
            </entity-ref>
       </cmp-field-mapping>
       ...
</entity-deployment>
<entity-deployment name="AddressBean" location="emp/AddressBean" ...

	table="ADDRESS" data-source="jdbc/OracleDS"... >
		<primkey-mapping>
			<cmp-field-mapping name="addressPK" 

				persistence-name="addressPK" />
		</primkey-mapping>
		<cmp-field-mapping name="street" persistence-name="street" />
		<cmp-field-mapping name="city" persistence-name="city" />
		<cmp-field-mapping name="state" persistence-name="state" />
		<cmp-field-mapping name="zip" persistence-name="zip" />
		<cmp-field-mapping name="EmpBean_address">
			<entity-ref home="EmpBean">
				<cmp-field-mapping name="EmpBean_address" 

								persistence-name="EMPNO" />
			</entity-ref>
		</cmp-field-mapping>
...
</entity-deployment>

Note: This section describes in detail how logical names defined in the ejb-jar.xml file relate to those in the orion-ejb-jar.xml file. And it describes how the logical variables defined in the orion-ejb-jar.xml file relate to the database table and column names. This chapter specifically chooses different names for closely aligned elements in the ejb-jar.xml and orion-ejb-jar.xml files in order that you can understand which names where the mappings occur. However, for efficiency and ease, you can make all related names the same. For example, instead of identifying address and addressPK for identifying the CMR field name and database column name, you could use one name, address, for all of them. Your configuration is easier if all these names are the same.

The <entity-deployment> mapping for the EmpBean specifies:

• The <entity-deployment> attributes define the following:
  • name attribute: The name of the source bean is EmpBean.

  • location attribute: The JNDI location is emp/EmpBean.

  • table attribute: The database table in which the persistent data for this entity bean is stored is emp.

  • data-source attribute: The database in which this table resides is defined by the data source jdbc/OracleDS.

• The <cmp-field-mapping> elements identify the table columns and the persistent data to be stored in each: The columns in this table are empno, ename, sal, and address.
  • The empno column contains the primary key, as defined in the EmpBean as empNo.

  • The empName and salary CMP data are saved in the ename and sal columns.

  • The address column is a foreign key in the EmpBean table, EMP, that points to the primary key of the AddressBean table.

• The <cmp-field-mapping> element for the foreign key defines the following:
  • Both of the name attributes identify the <cmr-field> that was defined in the ejb-jar.xml file. This name is address.

  • The <entity-ref> home attribute identifies the <ejb-name> of the target bean. The target in this example is the AddressBean.

  • The persistence-name attribute identifies the primary key column name of the target bean. In this example, the primary key of the AddressBean table, ADDRESS, is the addressPK column.

Figure 4-8 displays the relationship mapping of the EmpBean address foreign key to the AddressBean addressPK primary key.

Figure 4-8 Demonstration of Explicit Mapping for a One-To-One Relationship

Text description of the illustration o_1040.gif

In summary, an address column in the EMP table is a foreign key that points to the primary key, addressPK, in the ADDRESS table. For the example in which the AddressBean has an auto-generated primary key, an address column in the EMP table is a foreign key that points to the primary key, autoid, in the ADDRESS table.

Table Mapping For Primary Keys That Use AutoId

As described in "Defining an Auto-Generated Primary Key", you can define that a table use an automatic identifier as the primary key. This results in the following XML configuration in the orion-ejb-jar.xml file for the bean:

<primkey-mapping>
  <cmp-field-mapping name="auto_id" 
                                      persistence-name="autoid"/>
</primkey-mapping>

In our employee/address example, if the AddressBean had a primary key undefined, so that it defaulted to an autoid, then the table mapping would be as follows:

Figure 4-9 One-To-One Employee Relationship Example With Auto-ID

Text description of the illustration o_1065.gif

Using a Foreign Key with the One-To-Many Relationship

As described in "One-To-Many or Many-To-One Relationship Overview", one bean, such as a department, can have a relationship to multiple instances of another bean, such as employees. There are several employees in each department. Since this is a bidirectional relationship, you can look up the department from the employee. The relationships between the DeptBean and EmpBean is represented by CMR fields, employees and deptno, as shown in Figure 4-10.

Figure 4-10 One-to-Many Bean Relationship

Text description of the illustration o_1066.gif

How this relationship is mapped to database tables depends on your choices. The default method is add a foreign key to the table that defines the "many" side of the relationship--in this case, the table that represents the EmpBean. The foreign key points back to the department to which each employee belongs.

Figure 4-11 shows the department<-->employee example, where each employee belongs to only one department and each department can contain multiple employees. The department table has a primary key. The employee table has a primary key to identify each employee and a foreign key to point back to the employee's department. If you want to find the department for a single employee, a simple SQL statement retrieves the department information from the foreign key. To find all employees in a department, the container performs a JOIN statement on both the department and employee tables and retrieves all employees with the designated department number.

Figure 4-11 Explicit Mapping for One-To-Many Bidirectional Relationship Example

Text description of the illustration o_1043.gif

This is the default behavior. If you need to change the mappings to other database tables, then you use either JDeveloper or hand-edit the orion-ejb-jar.xml file to manipulate the <collection-mapping> or <set-mapping> element.

Important: You modify elements and attributes of the <entity-deployment> element in the orion-ejb-jar.xml file to explicitly map relationship fields. JDeveloper was created to manage the complex mapping between the entity beans and the database tables. Thus, JDeveloper validates the deployment descriptors and prevents inconsistencies. You are allowed to modify the orion-ejb-jar.xml file on your own; however, we suggest that you use JDeveloper for modifying container-managed relationships. CMR configuration is complex and can be difficult to understand. You can download JDeveloper at the following site: http://otn.oracle.com/software/products/jdev/content.html

Example 4-6 shows the table mapping for the bidirectional relationship of one department with many employees. The "one" side of the relationship is the department; the "many" side of the relationship is the employee. Figure 4-11 shows the table design. This demonstrates how to hand-edit the orion-ejb-jar.xml file for this relationship to use a foreign key.

Example 4-6 One-To-Many Relationship Using a Foreign Key

The ejb-jar.xml <relationships> section defines the department-employee bidirectional example, as follows:

<relationships>
	<ejb-relation>
		<ejb-relation-name>Dept-Emps</ejb-relation-name>
		<ejb-relationship-role>
			<ejb-relationship-role-name>Dept-has-Emps

			</ejb-relationship-role-name>
			<multiplicity>One</multiplicity>
			<relationship-role-source>
				<ejb-name>DeptBean</ejb-name>
			</relationship-role-source>
			<cmr-field>
				<cmr-field-name>employees</cmr-field-name>
				<cmr-field-type>java.util.Set</cmr-field-type>
			</cmr-field>
		</ejb-relationship-role>
		<ejb-relationship-role>
			<ejb-relationship-role-name>Emps-have-Dept

			</ejb-relationship-role-name>
			<multiplicity>Many</multiplicity>
			<cascade-delete/>
			<relationship-role-source>
				<ejb-name>EmpBean</ejb-name>
			</relationship-role-source>
			<cmr-field><cmr-field-name>dept</cmr-field-name></cmr-field>
		</ejb-relationship-role>
	</ejb-relation>
</relationships>

The orion-ejb-jar.xml file maps this definition in the following XML. If the table identified in the <collection-mapping> or <set-mapping> element of the "one" relationship (the department) is the name of the target bean's table (the employee bean table), then the one-to-many relationship is defined with a foreign key. For example, the table attribute in the department definition is EMP.

<?xml version = '1.0' encoding = 'windows-1252'?>
<!DOCTYPE orion-ejb-jar PUBLIC "-//Evermind//DTD Enterprise JavaBeans 2.0 
runtime//EN" "
http://xmlns.oracle.com/ias/dtds/orion-ejb-jar.dtd">
<orion-ejb-jar>
  <enterprise-beans>
    <entity-deployment name="DeptBean" data-source="jdbc/scottDS" table="DEPT">
      <primkey-mapping>
        <cmp-field-mapping name="deptno" persistence-name="DEPTNO" />  /*PK*/
      </primkey-mapping>
       <cmp-field-mapping name="dname" persistence-name="DNAME" />
      <cmp-field-mapping name="employees">
        /*points from DEPTNO column in EMP to DEPTNO in DEPT*/
1.     <collection-mapping table="EMP"> /*table where FK lives*/ 
          <primkey-mapping>
           <cmp-field-mapping name="DeptBean_deptno"> /*CMR field name*/
              <entity-ref home="DeptBean"> /*points to DeptBean*/
2.                    <cmp-field-mapping name="DeptBean_deptno"

                     persistence-name="EDEPTNO"/>
              </entity-ref>
            </cmp-field-mapping>
          </primkey-mapping>
          <value-mapping type="mypackage1.EmpLocal">
            <cmp-field-mapping name="EmpBean_empno">
              <entity-ref home="EmpBean">
                  <cmp-field-mapping name="EmpBean_empno"

			persistence-name="EMPNO"/>
              </entity-ref>
            </cmp-field-mapping>
          </value-mapping>
        </collection-mapping>
      </cmp-field-mapping>
    </entity-deployment>
    <entity-deployment name="EmpBean" data-source="jdbc/scottDS" table="EMP">
      <primkey-mapping>
        <cmp-field-mapping name="empNo" persistence-name="EMPNO"/>
      </primkey-mapping>
      <cmp-field-mapping name="empName" persistence-name="ENAME" />
	<cmp-field-mapping name="salary" persistence-name="SAL" />
      <cmp-field-mapping name="dept"> /*foreign key*/
        <entity-ref home="DeptBean">
2.	<cmp-field-mapping name="dept" persistence-name="EDEPTNO" />
        </entity-ref>
      </cmp-field-mapping>
    </entity-deployment>
  </enterprise-beans>
  <assembly-descriptor>
    <default-method-access>
      <security-role-mapping impliesAll="true" 
	name="&lt;default-ejb-caller-role>"/>
    </default-method-access>
  </assembly-descriptor>
</orion-ejb-jar>

The foreign key is defined in the database table of the "many" relationship. In our example, the EDEPTNO foreign key column exists in the EMP database table. This is defined in a persistence-name attribute of the <cmp-field-mapping> element in the EmpBean configuration.

Thus, to manipulate the <collection-mapping> or <set-mapping> element in the orion-ejb-jar.xml file, modify the <entity-deployment> element for the "one" entity bean, which contains the Collection, as follows:

1. Modify the table in the <collection-mapping> or <set-mapping> table attribute in the "one" relationship to be the database table of the "many" relationship. In this example, you would modify this attribute to be the EMP table.

2. Modify the foreign key that points to the "one" relationship within the "many" relationship configuration. In this example, modify the <cmp-field-mapping> element to specify the EDEPTNO foreign key in the persistence-name attribute.

These steps are delineated in the code example in Example 4-6.

Unidirectional One-to-Many Relationship Using a Foreign Key

An example of a unidirectional one-to-many relationship is the employee/phones example. An employee can own one or more phone numbers; however, you cannot look up an employee given a phone number. Figure 4-12 demonstrates the bean relationship.

Figure 4-12 One-to-Many Bean Relationship

Text description of the illustration o_1067.gif

Figure 4-11 shows the employee-->phone numbers example, where each employee can have multiple phone numbers. The employee table has a primary key. The phone numbers table has a auto-id for the primary key, the phone number, and a foreign key to point back to the employee. If you want to find all phone numbers for a single employee, the container performs a JOIN statement on both the employee and phone number tables and retrieves all phone numbers with the designated employee number.

Figure 4-13 Explicit Mapping for One-To-Many Bidirectional Relationship Example

Text description of the illustration o_1089.gif

Example 4-7 One-to-Many Unidirectional Example With Foreign Key

The ejb-jar.xml <relationships> section defines the employee-phone numbers unidirectional example, as follows:

<entity>
	<ejb-name>EmpBean</ejb-name>
	...
	<cmp-field><field-name>empNo</field-name></cmp-field>
	<cmp-field><field-name>empName</field-name></cmp-field>
	<cmp-field><field-name>salary</field-name></cmp-field>
	<primkey-field>empNo</primkey-field>
	<prim-key-class>java.lang.Integer</prim-key-class>
</entity>
<entity>
	<ejb-name>PhoneBean</ejb-name>
	...
	<cmp-field><field-name>phoneNo</field-name></cmp-field>
	<prim-key-class>java.lang.Object</prim-key-class>
</entity>

<relationships>
	<ejb-relation>
		<ejb-relation-name>Emp-Phone</ejb-relation-name>
		<ejb-relationship-role>
			<ejb-relationship-role-name>Emp-has-Phones

			</ejb-relationship-role-name>
			<multiplicity>One</multiplicity>
			<relationship-role-source>
				<ejb-name>EmpBean</ejb-name>
			</relationship-role-source>
			<cmr-field>
				<cmr-field-name>phones</cmr-field-name>
			</cmr-field>
		</ejb-relationship-role>
		<ejb-relationship-role>
			<ejb-relationship-role-name>Phones-have-Emp

			</ejb-relationship-role-name>
			<multiplicity>Many</multiplicity>
			<cascade-delete/>
			<relationship-role-source>
				<ejb-name>PhoneBean</ejb-name>
			</relationship-role-source>
		</ejb-relationship-role>
	</ejb-relation>
</relationships>

The orion-ejb-jar.xml file maps this definition in the following XML. If the table identified in the <collection-mapping> or <set-mapping> element of the "one" relationship (the employee) is the name of the target bean's table (the phone bean table), then the container defines the one-to-many relationship with a foreign key. In this example, the target bean's table is the PHONE database table.

<entity-deployment name="EmpBean"  table="EMP">
	<primkey-mapping>
		<cmp-field-mapping name="empNo" persistence-name="EMPNO" />
	</primkey-mapping>
	<cmp-field-mapping name="empName" persistence-name="ENAME" />
	<cmp-field-mapping name="salary" persistence-name="SAL" />
	<cmp-field-mapping name="phones">
1.		<collection-mapping table="PHONE">
			<primkey-mapping>
				<cmp-field-mapping name="EmpBean_empno">
					<entity-ref home="EmpBean">
2.						<cmp-field-mapping name="EmpBean_empNo"

							persistence-name="EMPNO"/>
					</entity-ref>
				</cmp-field-mapping>
			</primkey-mapping>
			<value-mapping type="hr.PhoneLocal">
				<cmp-field-mapping name="autoid">
					<entity-ref home="PhoneBean">
						<cmp-field-mapping name="autoid"

							persistence-name="AUTOID"/>
					</entity-ref>
				</cmp-field-mapping>
			</value-mapping>
		</collection-mapping>
	</cmp-field-mapping>
</entity-deployment>
<entity-deployment name="PhoneBean"  table="PHONE">
	<primkey-mapping>
		<cmp-field-mapping name="autoid" persistence-name="AUTOID"/>
	</primkey-mapping>
	<cmp-field-mapping name="phoneNo" persistence-name="PHONE_NO" />
	<cmp-field-mapping name="EmpBean_phones">
		<entity-ref home="EmpBean">
2.			<cmp-field-mapping name="EmpBean_phones" persistence-name="EMPNO" />
		</entity-ref>

	</cmp-field-mapping>
</entity-deployment>

The foreign key is defined in the database table of the "many" relationship. In our example, the EMPNO foreign key column exists in the PHONE database table. This is defined in a persistence-name attribute of the <cmp-field-mapping> element in the PhoneBean configuration.

Thus, to manipulate the <collection-mapping> or <set-mapping> element in the orion-ejb-jar.xml file, modify the <entity-deployment> element for the "one" entity bean, which contains the Collection, as follows:

1. Modify the table in the <collection-mapping> or <set-mapping> table attribute in the "one" relationship to be the database table for the "many" relationship. In this example, you would modify this attribute to be the PHONE table.

2. Modify the foreign key that points to the "one" relationship within the "many" relationship configuration. In this example, modify the <cmp-field-mapping> element to specify the EMPNO foreign key in the persistence-name attribute.

These steps are delineated in the code example in Example 4-7.

Association Table Explicit Mapping for Relationships Overview

As described in "One-To-Many or Many-To-One Relationship Overview", one bean, such as a department, can have a relationship to multiple instances of another bean, such as employees. There are several employees in each department. Since this is a bidirectional relationship, you can look up the department from the employee. The relationships between the DeptBean and EmpBean is represented by CMR fields, employees and deptno, as shown in Figure 4-14.

Figure 4-14 One-to-Many Bidirectional Bean Relationship

Text description of the illustration o_1066.gif

How this relationship is mapped to database tables depends on your choices. You could choose to use a separate table, known as an association table, which maps the two tables together appropriately with two foreign keys, where each foreign key points to each of the entity tables in the relationship.

Note: If you have a composite primary key in either or both tables, the foreign key will be a composite foreign key; thus, the association table will have the appropriate number of columns for each part of the composite foreign key.

This is not the default behavior. To have this type of relationship, do one or both of the following:

• Specify -DassociateUsingThirdTable=true on the OC4J startup options before deployment. Restart the OC4J instance. This generates the association table for all applications deployed after the restart.

• You can modify the mappings either through JDeveloper or by hand-editing the orion-ejb-jar.xml file.

  Important: You modify elements and attributes of the <entity-deployment> element in the orion-ejb-jar.xml file to explicitly map relationship fields. JDeveloper was created to manage the complex mapping between the entity beans and the database tables. Thus, JDeveloper validates the deployment descriptors and prevents inconsistencies. You are allowed to modify the orion-ejb-jar.xml file on your own; however, we suggest that you use JDeveloper for modifying container-managed relationships. CMR configuration is complex and can be difficult to understand. You can download JDeveloper at the following site: http://otn.oracle.com/software/products/jdev/content.html

Figure 4-15 shows the tables that are created for the employee/project relationship.

Figure 4-15 Many-To-Many Employee Relationship Example

Text description of the illustration o_1092.gif

Each project can have multiple employees, and each employee can belong to several projects. Thus, the employee and project relationship is a many-to-many relationship. The container creates three tables to manage this relationship: the employee table, the project table, and the association table for both of these tables.

The association table for this example contains two foreign key columns: one that points to the employee table and one that points to the project table. The column names of the association table are a concatenation of the entity bean name in <ejb-name> element of the ejb-jar.xml file and its primary key name. If the primary key for the bean is auto-generated, then "autoid" is appended as the primary key name. For example, the following are the names for the foreign keys of our employee/project example:

• The foreign key that points to the employee table is the bean name of EmpBean, followed by the primary key name of empno, which results in the column name EmpBean_empno.

• The foreign key that points to the address table is the bean name of ProjectBean concatenated with autoid, because the primary key is auto-generated, which results in the column name ProjectBean_autoid.

The following is a demonstration of the association table for the employee/projects relationship. Employee 1 is assigned to projects a, b, and c. Project a involves employees 1, 2, and 3. The association table contains the following:

EmpBean_empno	ProjectBean_autoid
1	a
1	b
1	c
2	a
3	a

The association table details all relationships between the two entity beans.

Example 4-8 Deployment Descriptor for a Many-To-Many Relationship

The deployment descriptors for the employee/project many-to-many relationship contains an <ejb-relation> element in which each bean defines its <multiplicity> as many and defines a <cmr-field> to the other bean of type Collection or Set.

<enterprise-beans>
  <entity>
    ...
    <ejb-name>EmpBean</ejb-name>
    <local-home>employee.EmpHome</local-home>
    <local>employee.Emp</local>
    ...
    <cmp-field><field-name>empNo</field-name></cmp-field>
    <cmp-field><field-name>empName</field-name></cmp-field>
    <cmp-field><field-name>salary</field-name></cmp-field>
    <primkey-field>empNo</primkey-field>
    <prim-key-class>java.lang.Integer</prim-key-class>
    ...
  </entity>
  <entity>
    ...
    <ejb-name>ProjectBean</ejb-name>
    <local-home>employee.ProjectHome</local-home>
    <local>employee.Project</local> 
    ...
    <cmp-field><field-name>projectName</field-name></cmp-field>
    <prim-key-class>java.lang.Object</prim-key-class>
    ...
  </entity>
</enterprise-beans>
<relationships>
  <ejb-relation>
    <ejb-relation-name>Emps-Projects</ejb-relation-name>
    <ejb-relationship-role>
      <ejb-relationship-role-name>Project-has-Emps</ejb-relationship-role-name>
      <multiplicity>Many</multiplicity>
      <relationship-role-source>
        <ejb-name>ProjectBean</ejb-name>
      </relationship-role-source>
      <cmr-field>
        <cmr-field-name>employees</cmr-field-name>
        <cmr-field-type>java.util.Collection</cmr-field-type>
      </cmr-field>
    </ejb-relationship-role> 
    <ejb-relationship-role>
      <ejb-relationship-role-name>Emp-has-Projects</ejb-relationship-role-name>
      <multiplicity>Many</multiplicity>
      <relationship-role-source>
        <ejb-name>EmpBean</ejb-name>
      </relationship-role-source>
      <cmr-field>
        <cmr-field-name>projects</cmr-field-name>
        <cmr-field-type>java.util.Collection</cmr-field-type>
      </cmr-field>
    </ejb-relationship-role>
  </ejb-relation>
</relationships>

The container maps this definition to the following:

• The container generates the entity tables based on the entity bean names, the JAR file that the beans are archived in, and the application name that they are deployed under. If the JAR filename is empl.jar and the application name is employee, then the table names are EmpBean_empl_jar_employee and ProjectBean_empl_jar_employee.

• The container generates columns in each entity table based on the <cmp-field> elements declared in the deployment descriptor.
  • The columns for the EmpBean table are empno, empname, and salary. The primary key is designated as the empno field.

  • The columns for the ProjectBean table are autoid for an auto-generated primary key and a projectName column. The primary key is auto-generated because the <prim-key-class> is defined as java.lang.Object, and no <primkey-field> element is defined.

• The container generates an association table in the same manner as the entity table.
  • The association table name is created to include the two <cmr-field> element definitions for each of the entity beans in the relationship. The format for the association table name consists of the following, separated by underscores: first bean name, its <cmr-field> to the second bean, second bean name, its <cmr-field> to the first bean, JAR file name, and application name. The rule of thirty characters also applies to this table name, as to the entity tables. Thus, the association table name for the employee/projects relationship is ProjectBean_employees_EmpBean_projects_empl_jar_employee. Because this name is over thirty characters, it is truncated to twenty-four characters, and then an underscore plus five characters of a hash code are added. Thus, the official association table would be something like ProjectBean_employees_Em_fj49g

  • Two foreign keys in the association table are created. In this example, each foreign key is defined in a column, where the name is a concatenation of the bean name and the primary key (or autoid if auto-generated). In our example, the column names would be EmpBean_empno and ProjectBean_autoid. These columns are foreign keys to the entity tables that are involved in the relationship. The EmpBean_empno foreign key points to the employee table; the ProjectBean_autoid foreign key points to the projects table.

Example 4-9 Deployment Descriptor for One-To-Many Unidirectional Relationship

Figure 4-16 shows the default database tables for the employee/phone numbers example.

Figure 4-16 One-To-Many Relationship Employee Example

Text description of the illustration o_1039.gif

Each employee can have multiple phone numbers. The employee entity bean, EmpBean, defines a <cmr-field> element designating a Collection of phoneNumbers within the PhoneBean. The deployment descriptors for this exmple are as follows:

<relationships>
  <ejb-relation>
   <ejb-relation-name>Emp-Phone</ejb-relation-name>
   <ejb-relationship-role>
     <ejb-relationship-role-name>Emp-PhoneNumbers</ejb-relationship-role-name>
     <multiplicity>One</multiplicity>
     <relationship-role-source>
        <ejb-name>EmpBean</ejb-name>
     </relationship-role-source>
     <cmr-field>
        <cmr-field-name>phoneNumbers</cmr-field-name>
        <cmr-field-type>java.util.Collection</cmr-field-type>
     </cmr-field>
   </ejb-relationship-role>
   <ejb-relationship-role>
     <ejb-relationship-role-name>Phone-has-Emp</ejb-relationship-role-name>
     <multiplicity>Many</multiplicity>
     <relationship-role-source>
        <ejb-name>PhoneBean</ejb-name>
     </relationship-role-source>
    </ejb-relationship-role>
  </ejb-relation>
</relationships>

Note: An object-relationship entity bean example is available on OTN from the OC4J sample code page on the OTN Web site.

XML Structure for One-to-Many Relationship Mapping

The relationship that is defined in the ejb-jar.xml file is mapped in the orion-ejb-jar.xml file within a <cmp-field-mapping> element. The <cmp-field-mapping> element contains either a <collection-mapping> or <set-mapping> element. Our example contains a department has many employees. The department describes its "many" relationship to employees with a <collection-mapping> element.

Note: The "many" side of the relationship is defined by the <collection-mapping> or <set-mapping> element. The "one" side of the relationship is defined by the <entity-ref> element. Thus, for a one-to-many relationship, a single <collection-mapping> element is used to describe the "many" side.

The XML structure for defining a one-to-many relationship includes the following:

<cmp-field-mapping name="CMRfield">
    <collection-mapping table="association_table">
      <primkey-mapping>
         <cmp-field-mapping name="CMRfield"

	persistence-name="first_column_name_assoc_table" />
      </primkey-mapping>
      <value-mapping type="target_bean_local_home_interface">
        <cmp-field-mapping>
          <entity-ref home="target_bean_EJBname">
            <cmp-field-mapping name="CMRfield"

            persistence-name="second_column_name_assoc_table"/>
          </entity-ref>
        </cmp-field-mapping>
      </value-mapping>
    </collection-mapping>
</cmp-field-mapping>

Element or Attribute	Description
<cmp-field-mapping>	This element maps a persistent field or a relationship field. For relationship fields, it will contain either an <entity-ref> for a one-to-one mapping or a <collection-mapping> for a one-to-many, many-to-one, or many-to-many relationship. The name attribute identifies the <cmp-field> or <cmr-field> that is to be mapped. Do not change this name. The persistence-name attribute identifies the database column. You can modify this name to match your database column name.
<entity-ref>	This element identifies the target bean and its primary key to which the foreign key points. The home attribute is not the home interface, but identifies the EJB name of the target bean. This is the logical name of the bean defined in <ejb-name> in the ejb-jar.xml file. The <cmp-field-mapping> within this element identifies the foreign key column name.
<collection-mapping>	This element explicitly maps the "many" side of a relationship. The table attribute identifies the association table. You can modify this name to match your own association table name. This element defines two elements, one for each column in the association table: <primkey-mapping> identifies the first foreign key in the association table. <value-mapping> identifies the second foreign key in the association table.
<primkey-mapping>	Within the <collection-mapping>, use this element to identify the first foreign key. You can modify the persistence-name attribute in this element to match the column name in your own association table.
<value-mapping>	Use this element to specify the second foreign key. The type attribute identifies the local interface for the target bean. You can modify the persistence-name attribute in this element to match the column name in your own association table.

Using an Association Table with a One-to-Many Bidirectional Relationship

The following example shows how a one-to-many bidirectional relationship is configured to use an association table. In the ejb-jar.xml file, the department defines itself as the "one" side of the relationship and shows that it expects to receive back "many" employees through the definition of a Collection in the <cmr-field> element. The employee defines itself as the "many" side of the relationship.

<relationships>
	<ejb-relation>
		<ejb-relation-name>Dept-Emps</ejb-relation-name>
		<ejb-relationship-role>
			<ejb-relationship-role-name>Dept-has-Emps

			</ejb-relationship-role-name>
			<multiplicity>One</multiplicity>
			<relationship-role-source>

				<ejb-name>DeptBean</ejb-name>

			</relationship-role-source>
			<cmr-field>
				<cmr-field-name>employees</cmr-field-name>
				<cmr-field-type>java.util.Collection</cmr-field-type>
			</cmr-field>
		</ejb-relationship-role>
		<ejb-relationship-role>
			<ejb-relationship-role-name>Emp-has-Dept

			</ejb-relationship-role-name>
			<multiplicity>Many</multiplicity>
			<relationship-role-source>

				<ejb-name>EmpBean</ejb-name>

			</relationship-role-source>
			<cmr-field>

				<cmr-field-name>dept</cmr-field-name>

			</cmr-field>
		</ejb-relationship-role>
	</ejb-relation>
</relationships>

In the orion-ejb-jar.xml file, the mapping of this relationship to an association table is described in a <collection-mapping> element. Since this is a one-to-many relationship, the "one" entity bean, the department, has the <collection-mapping> element as it receives back a Collection or Set of the target, the employees.

In the orion-ejb-jar.xml file, the DeptBean <entity-deployment> element defines the <collection-mapping> element to designate a Collection of employees. The <collection-mapping> element defines the association table.

<entity-deployment name="DeptBean" location="DeptBean" 
	table="DEPT" data-source="jdbc/OracleDS" ... >
	<primkey-mapping>
		<cmp-field-mapping name="deptNo" persistence-name="deptNo" />
	</primkey-mapping>
	<cmp-field-mapping name="deptName" persistence-name="deptName" />
	<cmp-field-mapping name="employees">
		<collection-mapping table="DEPT_EMP">
			<primkey-mapping>
				<cmp-field-mapping name="DeptBean_deptno">
					<entity-ref home="DeptBean">
						<cmp-field-mapping name="DeptBean_deptno"

							persistence-name="DEPARTMENT" />
					</entity-ref>
				</cmp-field-mapping>
			</primkey-mapping>
			<value-mapping type="hr.EmpLocal">
				<cmp-field-mapping name="EmpBean_empNo">
					<entity-ref home="EmpBean">
						<cmp-field-mapping name="EmpBean_empNo" 

							persistence-name="EMPLOYEE" />
					</entity-ref>
				</cmp-field-mapping>
			</value-mapping>
		</collection-mapping>
	</cmp-field-mapping>
...
</entity-deployment>
<entity-deployment name="EmpBean" location="EmpBean" 

	table="EMP" data-source="jdbc/OracleDS" ... >
	<primkey-mapping>
		<cmp-field-mapping name="empNo" persistence-name="EMPNO" />
	</primkey-mapping>
	<cmp-field-mapping name="empName" persistence-name="ENAME" />
	<cmp-field-mapping name="salary" persistence-name="SAL" />
	<cmp-field-mapping name="dept">
		<entity-ref home="DeptBean">
			<cmp-field-mapping name="dept" persistence-name="DEPARTMENT" />
		</entity-ref>
	</cmp-field-mapping>
...
</entity-deployment>

The following describes how the DeptBean is configured in the orion-ejb-jar.xml file:

• The relationship from the department to the employee bean is defined in the employees field, which is mapped in the <collection-mapping> element.

• The association table name is specified in the table attribute, which currently defines the association table name as DEPT_EMP.

• The foreign keys of the association table are defined as follows:
  • The <primkey-mapping> element defines the column name for the foreign key of the current entity bean in the persistence-name attribute, which is DEPARTMENT.

  • The <value-mapping> element defines the column name for the foreign key of the target bean in the persistence-name attribute, which is EMPLOYEE.

• The <value-mapping> element specifies the target entity bean.
  • The type attribute of the <value-mapping> element defines the local interface of the target bean that is returned to the source entity bean.

  • The <ejb-name> of the target entity bean is defined in the <entity-ref> home attribute.

The following describes how the EmpBean is configured in the orion-ejb-jar.xml file:

• The relationship from the employee to the department bean is defined in the dept field, which is mapped in the <cmp-field-mapping><entity-ref> element. The persistence-name attribute contains the foreign key in the association table that points to the department bean.

Using an Association Table in a One-to-Many Unidirectional Relationship

As described in "One-To-Many or Many-To-One Relationship Overview", one bean, such as an employee, can have a relationship to multiple instances of another bean, such as phone numbers. For each employee, you can have one or more phone numbers. However, this is a unidirectional relationship. You cannot look up an employee given a phone number.

The relationships between the EmpBean and PhoneBean is represented by a CMR field, phones, as shown in Figure 4-17.

Figure 4-17 One-to-Many Unidirectional Bean Relationship

Text description of the illustration o_1067.gif

The relationship is mapped to database tables using an association table, which maps the two tables together appropriately. The association table consists of two foreign keys.

Note: If you have a composite primary key in either or both tables, the foreign key will be a composite foreign key; thus, the association table will have the appropriate number of columns for each part of the composite foreign key.

For a full description of how an association table works, see "Example of a Default Mapping of One-To-Many and Many-To-Many Relationships". This section shows how to change the XML configuration for this mapping.

Note: If you do not want to use an association table, see "Using a Foreign Key with the One-To-Many Relationship" for directions on how to use a foreign key in the "one" side of the relationship.

Figure 4-18 shows the employee-->phone numbers example, where each employee can have multiple phone numbers. Both the employee and phone tables have a primary key. A separate table, the association table, contains two foreign keys. One foreign key points to the employee; the other foreign key points to the phone number. Every relationship has its own row denoting the relationship. Thus, for every phone number, a row is created where the first foreign key points to the employee to which the phone number belongs and the second foreign key points to the phone number record. Figure 4-18 shows an association table, EMP_PHONE, where the foreign keys are named EMPLOYEE and PHONEBEAN_AUTOID.

Figure 4-18 Explicit Mapping for One-To-Many Unidirectional Relationship Example

Text description of the illustration o_1071.gif

To change the mappings to other database tables, then you use either JDeveloper or hand-edit the orion-ejb-jar.xml file to manipulate the <collection-mapping> or <set-mapping> element.

Important: You modify elements and attributes of the <entity-deployment> element in the orion-ejb-jar.xml file to explicitly map relationship fields. JDeveloper was created to manage the complex mapping between the entity beans and the database tables. Thus, JDeveloper validates the deployment descriptors and prevents inconsistencies. You are allowed to modify the orion-ejb-jar.xml file on your own; however, we suggest that you use JDeveloper for modifying container-managed relationships. CMR configuration is complex and can be difficult to understand. You can download JDeveloper at the following site: http://otn.oracle.com/software/products/jdev/content.html

Specifying the One-to-Many Unidirectional Relationship in the XML Deployment Descriptors

In the ejb-jar.xml file, the cardinality is defined in the <relationships> element. The following is the ejb-jar.xml file configuration of the one-to-many unidirectional example of the employee and his/her phone numbers.

• The primary key field of the EmpBean is empNo, as defined in the <primkey-field> element.

• The primary key of the PhoneBean is not defined, as defined by the absence of the <primkey-field> element and the existence of the <prim-key-class> element. Thus, the primary key is auto-generated and represented by AUTOID. For more information on auto-generated primary keys, see "Defining an Auto-Generated Primary Key".

• The CMR field (<cmr-field> element) defining the "many" side of the relationship is a Collection that is identified as phones.

  <entity>
  	<ejb-name>EmpBean</ejb-name>
  	...
  	<cmp-field><field-name>empNo</field-name></cmp-field>
  	<cmp-field><field-name>empName</field-name></cmp-field>
  	<cmp-field><field-name>salary</field-name></cmp-field>
  	...
  	<primkey-field>empNo</primkey-field>
  	<prim-key-class>java.lang.Integer</prim-key-class>
  	...
  </entity>
  <entity>
  	...
  	<ejb-name>PhoneBean</ejb-name>
  	...
  	<cmp-field><field-name>phoneNo</field-name></cmp-field>
  	<cmp-field><field-name>phoneType</field-name></cmp-field>
  	<prim-key-class>java.lang.Object</prim-key-class>
  	...
  </entity>
  <relationships>
    <ejb-relation>
     <ejb-relation-name>Emp-Phone</ejb-relation-name>
     <ejb-relationship-role>
       <ejb-relationship-role-name>Emp-PhoneNumbers</ejb-relationship-role-name>
       <multiplicity>One</multiplicity>
       <relationship-role-source>
          <ejb-name>EmpBean</ejb-name>
       </relationship-role-source>
       <cmr-field>
          <cmr-field-name>phones</cmr-field-name>
          <cmr-field-type>java.util.Collection</cmr-field-type>
       </cmr-field>
     </ejb-relationship-role>
     <ejb-relationship-role>
       <ejb-relationship-role-name>Phone-has-Emp</ejb-relationship-role-name>
       <multiplicity>Many</multiplicity>
       <relationship-role-source>
          <ejb-name>PhoneBean</ejb-name>
       </relationship-role-source>
      </ejb-relationship-role>
    </ejb-relation>
  </relationships>
  
  

In the orion-ejb-jar.xml file, the mapping of this relationship to an association table is described in a <collection-mapping> element. The "one" side of the relationship, the employee, owns the "many" entities, the phone numbers; thus, the employee defines the <collection-mapping> element that describes the relationship with the phone numbers. In all one-to-many relationships, the entity bean that is represents the "one" side of the relationship defines the <collection-mapping> element as it receives back a Collection or Set of the target entity bean. The entity bean on the "many" side of the relationship defines a <cmp-field-mapping> <entity-ref> element that shows the relationship back to the entity bean that is the "one" side of the relationship. So, the employee defines the <collection-mapping> element to define its relationship with the phone numbers: the phone numbers uses an <entity-ref> element to define its relationship with the employee.

In the orion-ejb-jar.xml file for the employee/phone numbers example, the EmpBean <entity-deployment> element defines the <collection-mapping> element to designate a Collection of phone numbers. The <collection-mapping> element specifies the association table.

<entity-deployment name="EmpBean"  table="EMP">
	<primkey-mapping>
		<cmp-field-mapping name="empNo" persistence-name="EMPLOYEENO" />
	</primkey-mapping>
	<cmp-field-mapping name="empName" persistence-name="EMPLOYEENAME" />
	<cmp-field-mapping name="salary" persistence-name="SAL" />
	<cmp-field-mapping name="phones">
		<collection-mapping table="EMP_PHONE">
			<primkey-mapping>
				<cmp-field-mapping name="EmpBean_empNo">
					<entity-ref home="EmpBean">
						<cmp-field-mapping name="EmpBean_empNo" 
							persistence-name="EMPLOYEENO"/>
					</entity-ref>
				</cmp-field-mapping>
			</primkey-mapping>
			<value-mapping type="hr.PhoneLocal">
				<cmp-field-mapping name="PhoneBean_autoid">
					<entity-ref home="PhoneBean">
						<cmp-field-mapping name="PhoneBean_autoid" 
							persistence-name="AUTOID"/>
					</entity-ref>
				</cmp-field-mapping>
			</value-mapping>
		</collection-mapping>
...
</entity-deployment>
<entity-deployment name="PhoneBean"  table="PHONE">
	<primkey-mapping>
		<cmp-field-mapping name="autoid" persistence-name="AUTOID"/>
	</primkey-mapping>
	<cmp-field-mapping name="phoneNo" persistence-name="PHONE_NO" />
	<cmp-field-mapping name="phoneType" persistence-name="PHONE_TYPE" />
	<cmp-field-mapping name="EmpBean_phones">
		<entity-ref home="EmpBean">
			<cmp-field-mapping name="EmpBean_phones" 

				persistence-name="EMPLOYEENO" />
		</entity-ref>
	</cmp-field-mapping>	
</entity-deployment>

The following describes how the EmpBean is defined in the ejb-jar.xml and orion-ejb-jar.xml files. See Figure 4-19 for a graphic of this mapping.

• The <cmr-field> element in the ejb-jar.xml file defines a name for the relationship with the phone numbers as phones.

• The phones <cmr-field> element maps to the association table in the orion-ejb-jar.xml file. In the orion-ejb-jar.xml file, the <cmp-field-mapping> for phones contains a <collection-mapping> element. This <collection-mapping> element defines the association table name in the table attribute as EMP_PHONE.

• The association table has two foreign keys. In this example, the foreign keys are simple. However, if the primary keys are composite, then these foreign keys would be composite as well.

  Both foreign keys for the association table are defined as follows:

  • The persistence-name attribute in the <primkey-mapping> element defines the association table foreign key column name of the current entity bean, which is EMPLOYEENO.

  • The persistence-name attribute in the <value-mapping> element defines the association table foreign key column name of the target bean, which is PhoneBean_AUTOID.

• The <value-mapping> element specifies the target entity bean.
  • The type attribute of the <value-mapping> element defines the local interface of the target bean that is returned to the source entity bean. This example defines the local home interface of the phone bean as hr.PhoneLocal.

  • The <ejb-name> of the target entity bean is defined in the <entity-ref> home attribute, which in this example is PhoneBean.

The phone bean configuration in the orion-ejb-jar.xml file defines an <entity-ref> for a relationship to the employee bean.

• The <ejb-name> of the target entity bean is defined in the <entity-ref> home attribute, which in this example is EmpBean.

• The persistence-name attribute in the <cmp-field-mapping> element defines the association table foreign key of the current entity bean, which is EMPLOYEENO.

Figure 4-19 shows the following:

• How the CMR field name maps to the <cmp-field-mapping> elements in the orion-ejb-jar.xml file.

• How the association table is defined by the <collection-mapping> element in the employee bean definition.

Figure 4-19 Explicit Mapping for a One-To-Many Relationship

Text description of the illustration o_1072.gif

Using an Association Table in Many-to-Many Relationships

As described in "Many-To-Many Relationship Overview", many beans, such as employees, can have a relationship to multiple instances of another bean, such as projects. There are several employees in each project; each employee can be assigned to multiple projects. Since this is a bidirectional relationship, you can look up the project from the employee. The relationships between the ProjectBean and EmpBean is represented by CMR fields, employees and projects, as shown in Figure 4-20.

Figure 4-20 Many-to-Many Bidirectional Bean Relationship

Text description of the illustration o_1073.gif

This relationship is mapped to database tables using as an association table. The association table consists of two foreign keys.

Note: If you have a composite primary key in either or both tables, the foreign key will be a composite foreign key; thus, the association table will have the appropriate number of columns for each part of the composite foreign key.

For a full description of how an association table works, see "Example of a Default Mapping of One-To-Many and Many-To-Many Relationships". This section shows how to change the XML configuration for this mapping.

Figure 4-21 shows the projects<-->employee example, where each employee belongs to one or more projects and each project can contain multiple employees. Both the project and employee tables have a primary key. A separate table, the association table, contains two foreign keys. One foreign key points to the project; the other foreign key points to the employee. Every relationship has its own row denoting the relationship. Thus, for every employee, a row is created where the first foreign key points to the project the employee belongs to and the second foreign key points to the employee record. The association table in Figure 4-21 shows an association table, PROJECT_EMP, where the foreign keys are named PROJECT_NO and EMPLOYEE_NO.

Figure 4-21 Explicit Mapping for One-To-Many Bidirectional Relationship Example

Text description of the illustration o_1093.gif

If you need to change the mappings to other database tables, then you use either JDeveloper or hand-edit the orion-ejb-jar.xml file to manipulate the <collection-mapping> or <set-mapping> element.

Important: You modify elements and attributes of the <entity-deployment> element in the orion-ejb-jar.xml file to explicitly map relationship fields. JDeveloper was created to manage the complex mapping between the entity beans and the database tables. Thus, JDeveloper validates the deployment descriptors and prevents inconsistencies. You are allowed to modify the orion-ejb-jar.xml file on your own; however, we suggest that you use JDeveloper for modifying container-managed relationships. CMR configuration is complex and can be difficult to understand. You can download JDeveloper at the following site: http://otn.oracle.com/software/products/jdev/content.html

Example 4-10 XML Structure for Many-to-Many Relationship Mapping

The relationship that is defined in the ejb-jar.xml file is mapped in the orion-ejb-jar.xml file within a <cmp-field-mapping> element. The <cmp-field-mapping> element contains either a <collection-mapping> or <set-mapping> element. The project/employee example describes both sides of the "many" relationship with a <collection-mapping> element; thus, both sides use a <collection-mapping> to describe their side of the relationship, even though the information is the same on both sides.

In the ejb-jar.xml file, both sides are define a "many" relationship to each other; thus, both sides declare the <multiplicity> element as Many and define a relationship to each other in a CMR field. The project bean defines the CMR field as employees; the employee bean defines the CMR field as projects. These CMR fields are used in the orion-ejb-jar.xml file to map these relationships in the database tables.

<entity>
	...
	<relationships>
		<ejb-relation>
			<ejb-relation-name>Emps-Projects</ejb-relation-name>
			<ejb-relationship-role>
				<ejb-relationship-role-name>Projects-have-Emps

				</ejb-relationship-role-name>
				<multiplicity>Many</multiplicity>
				<relationship-role-source>
					<ejb-name>ProjectBean</ejb-name>
				</relationship-role-source>
				<cmr-field>
					<cmr-field-name>employees</cmr-field-name>
					<cmr-field-type>java.util.Collection</cmr-field-type>
				</cmr-field>
			</ejb-relationship-role>
			<ejb-relationship-role>
				<ejb-relationship-role-name>Emps-have-Projects

				</ejb-relationship-role-name>
				<multiplicity>Many</multiplicity>
				<relationship-role-source>
					<ejb-name>EmpBean</ejb-name>
				</relationship-role-source>
				<cmr-field>
					<cmr-field-name>projects</cmr-field-name>
					<cmr-field-type>java.util.Collection</cmr-field-type>
				</cmr-field>
			</ejb-relationship-role>
		</ejb-relation>

	</relationships>
...
</entity>

Then in the orion-ejb-jar.xml file, both sides define the relationship with each other in a <collection-mapping> element. This element defines the association table. An association table is created that contains two foreign keys, where each foreign key points to the primary key of the source and target tables. Thus, explicit mapping of this relationship requires modifying the association table name and its foreign key names. You must modify both <collection-mapping> elements with the same information, because both <collection-mapping> elements contain the same information about the association table. The only difference is that the information is switched in the <primary-key> and <value-mapping> elements in each bean definition. What is defined in the <primary-key> element in the project bean definition will be defined in the <value-mapping> element in the employee bean definition.

<entity-deployment name="EmpBean" location="EmpBean" 

	table="EmpBean_ormap_ormap_ejb" data-source="jdbc/OracleDS" >
...
<entity-deployment name="EmpBean"  table="EMP">
	<primkey-mapping>
		<cmp-field-mapping name="empNo" persistence-name="EMPNO" />
	</primkey-mapping>
	<cmp-field-mapping name="empName" persistence-name="ENAME" />
	<cmp-field-mapping name="salary" persistence-name="SAL" />
	<cmp-field-mapping name="projects">
	<collection-mapping table="PROJECT_EMP">
	<primkey-mapping>
		<cmp-field-mapping name="EmpBean_empNo">
				<entity-ref home="EmpBean">
				<cmp-field-mapping name="EmpBean_empNo" 

					persistence-name="EMPLOYEE_NO" />
			</entity-ref>
		</cmp-field-mapping>
	</primkey-mapping>
	<value-mapping type="hr.ProjectLocal">
		<cmp-field-mapping name="ProjectBean_projectNo">
			<entity-ref home="ProjectBean">
				<cmp-field-mapping name="ProjectBean_projectNo" 	

					persistence-name="PROJECT_NO" />
			</entity-ref>
		</cmp-field-mapping>
	</value-mapping>
	</collection-mapping>
	</cmp-field-mapping>
...
</entity-deployment>
...
<entity-deployment name="ProjectBean" location="ProjectBean" 

	table="ProjectBean_ormap_ormap_ejb" data-source="jdbc/OracleDS" >
	<primkey-mapping>
		<cmp-field-mapping name="projectNo" persistence-name="PROJECTNO" />
	</primkey-mapping>
	<cmp-field-mapping name="projectName" persistence-name="PNAME" />
	<cmp-field-mapping name="employees">
		<collection-mapping table="PROJECT_EMP">
			<primkey-mapping>
				<cmp-field-mapping name="ProjectBean_projectNo">
					<entity-ref home="ProjectBean">
						<cmp-field-mapping name="ProjectBean_projectNo" 

							persistence-name="PROJECT_NO" />
					</entity-ref>
				</cmp-field-mapping>
			</primkey-mapping>
			<value-mapping type="hr.EmpLocal">
				<cmp-field-mapping name="EmpBean_empNo">
					<entity-ref home="EmpBean">
						<cmp-field-mapping name="EmpBean_empNo" 

							persistence-name="EMPLOYEE_NO" />
					</entity-ref>
				</cmp-field-mapping>
			</value-mapping>
		</collection-mapping>
</cmp-field-mapping>

The following describes the fields in the orion-ejb-jar.xml file:

• The project bean defines a <cmr-field> element in the ejb-jar.xml file defines a name for the relationship with employees as employees; the employees <cmr-field> element defines a name for the relationship with projects as projects.

• Both of the projects and employees <cmr-field> elements map to the association table in the orion-ejb-jar.xml file. In this file, each of the <cmp-field-mapping> elements for projects and employees contain a <collection-mapping> element. This <collection-mapping> element defines the association table name in the table attribute as PROJECT_EMP.

• The association has two foreign keys. In this example, the foreign keys are simple. However, if the primary keys are composite, then these foreign keys would be composite as well.

  Both foreign keys in the EmpBean for the association table are defined as follows:

  • The persistence-name attribute in the <primkey-mapping> element defines the association table foreign key of the current entity bean, which is EMPLOYEE_NO.

  • The persistence-name attribute in the <value-mapping> element defines the association table foreign key of the target bean, which is PROJECT_NO.

• The <value-mapping> element in EmpBean specifies the target entity bean.
  • The type attribute of the <value-mapping> element defines the local interface of the target bean that is returned to the source entity bean. This example defines the local home interface of the phone bean as hr.ProjectLocal.

  • The <ejb-name> of the target entity bean is defined in the <entity-ref> home attribute, which in this example is ProjectBean.

Using a Foreign Key in a Composite Primary Key

In the EJB specification, the primary key for an entity bean must be initialized within the ejbCreate method; any relationship that this bean has to another bean cannot be set in the ejbCreate method. The earliest that this relationship can be set in a foreign key is in the ejbPostCreate method.

However, if you have a foreign key within a composite primary key, you have the following problem:

• You must set all fields within the composite primary key in the ejbCreate method.

• You cannot set the foreign key in the ejbCreate method.

This section uses the following example to describe the way around this problem:

An order for a company can contain one or more items. The order bean has many items in it. Each item belongs to an order. The primary key for the item is a composite primary key consisting of the item identifier and the order identifier. The order identifier is a foreign key that points to the order.

You will have to modify the deployment descriptors and bean implementation to add a placeholder CMP field that mimics the actual foreign key field. This field is set during the ejbCreate method. However, both the placeholder CMP field and the foreign key point to the same database column. The actual foreign key is updated during the ejbPostCreate method.

The following example demonstrates how to modify both deployment descriptors and the bean implementation.

Note: You modify the ejb-jar.xml file with the placeholder CMP field and the foreign key. We recommend that you deploy the application with autocreate-tables element in the orion-application.xml file set to false to auto-generate the orion-ejb-jar.xml file, without creating any tables. Then modify the orion-ejb-jar.xml file to point to the correct database columns, set autocreate-tables element to true, and redeploy.

Example 4-11 A Foreign Key That Exists in a Primary Key

Each order contains one or more items. Thus, two beans are created, where the OrderBean represents the order and the OrderItemBean represents the items in the order. Each item has a primary key that consists of the item number and the order number to which it belongs. Thus, the primary key for the item contains a foreign key that points to an order bean.

To adjust for a composite primary key, do the following in the ejb-jar.xml file:

1. Define a CMP field in the primary key as a placeholder for the foreign key. This placeholder should be used in the composite primary key class definition.

   In this example, an orderId CMP field is defined in a <cmp-field> element. The orderId and itemId CMP fields are used to identify the composite primary key in the OrderItemPK.java.

2. Define the foreign key outside of the primary key definition in its own <cmr-field> element in the <relationships> section.

   In this example, the belongToOrder foreign key is defined in a <cmr-field> element for the OrderItemBean, defining the relationship from the item to the order.

   <entity>
   	<ejb-name>OrderItemBean</ejb-name>
   	<local-home>OrderItemLocalHome</local-home>
   	<local>OrderItemLocal</local>
   	<ejb-class>OrderItemBean</ejb-class>
   	...
   	<cmp-field><field-name>itemId</field-name></cmp-field>
   	<cmp-field><field-name>orderId</field-name></cmp-field>
   	<cmp-field><field-name>price</field-name></cmp-field>
   	<prim-key-class>OrderItemPK</prim-key-class>
   	...
   </entity>
   <relationships>
   	<ejb-relation>
   		<ejb-relation-name>Order-OrderItem</ejb-relation-name>
   		<ejb-relationship-role>
   			<ejb-relationship-role-name>Order-Has-OrderItems
   
   			</ejb-relationship-role-name>
   			<multiplicity>One</multiplicity>
   			<relationship-role-source>
   				<ejb-name>OrderBean</ejb-name>
   			</relationship-role-source>
   			<cmr-field>
   				<cmr-field-name>items</cmr-field-name>
   				<cmr-field-type>java.util.Collection</cmr-field-type>
   			</cmr-field>
   		</ejb-relationship-role>
   		<ejb-relationship-role>
   			<ejb-relationship-role-name>OrderItems-form-Order
   
   			</ejb-relationship-role-name>
   			<multiplicity>Many</multiplicity>
   			<cascade-delete/>
   			<relationship-role-source>
   				<ejb-name>OrderItemBean</ejb-name>
   			</relationship-role-source>
   			<cmr-field>
   				<cmr-field-name>belongToOrder</cmr-field-name>
   			</cmr-field>
   		</ejb-relationship-role>
   	</ejb-relation>
   </relationships>
   
   

The OrderItemPK.java class defines what is in the complex primary key, as follows:

public class OrderItemPK implements java.io.Serializable
{
  public Integer itemId;
  public Integer orderId;

  public OrderItemPK()
  {
    this.itemId = null;
    this.orderId = null;
  }
        
  public OrderItemPK(Integer itemId, Integer orderId)
  {
    this.itemId = itemId;
    this.orderId = orderId;
  }
}

public boolean equals(Object o) 
  {
      if (o instanceof OrderItemPK) {
          OrderItemPK pk = (OrderItemPK) o;
          if (pk.itemId.intValue() == itemId.intValue() &&
              pk.orderId.intValue() == orderId.intValue())
              return true;
      }
      return false;
  }

  public int hashCode() 
  {
      return itemId.hashCode() * orderId.hashCode();
  }
}

If the auto-created database tables are sufficient for you, you do not need to modify the orion-ejb-jar.xml file. However, if you need to map to existing database tables, then you modify the orion-ejb-jar.xml file to point to these tables.

After you allow the orion-ejb-jar.xml file to auto-generate, copy it into your development directory. The database column names are defined in the persistence-name attributes in each of the CMP and CMR field name mappings. Ensure that the persistence-name attributes for both the placeholder CMP field and foreign key are the same.

The following is the orion-ejb-jar.xml file for the order/order item example. In the <entity-deployment> section for the OrderItemBean,

• The table is defined in the table attribute, which is ORDER_ITEM in this example.

• The column name for the itemId is defined in the persistence-name attribute as Item_ID.

• The column name for the placeholder CMP field, orderId, is defined in the persistence-name attribute as Order_ID.

• The foreign key, belongToOrder, is mapped to the database column, Order_ID, which is the same column as the placeholder CMP field, orderId.

Both the foreign key, belongToOrder, and the placeholder CMP field, orderId, must point to the same database column.

<entity-deployment name="OrderItemBean"  table="ORDER_ITEM">
	<primkey-mapping>
		<cmp-field-mapping name="itemId" persistence-name="Item_ID" />
		<cmp-field-mapping name="orderId" persistence-name="Order_ID" />
	</primkey-mapping>
	<cmp-field-mapping name="price" persistence-name="Price" />
	<cmp-field-mapping name="belongToOrder">
		<entity-ref home="OrderBean">
			<cmp-field-mapping name="belongToOrder" 

				persistence-name="Order_ID" />
		</entity-ref>
	</cmp-field-mapping>
</entity-deployment>

<entity-deployment name="OrderBean"  table="ORDER">
	<primkey-mapping>
		<cmp-field-mapping name="orderId" persistence-name="Order_ID" />
	</primkey-mapping>
	<cmp-field-mapping name="orderDesc"

		persistence-name="Order_Description" />
	<cmp-field-mapping name="items">
		<collection-mapping table="ORDER_ITEM">
		<primkey-mapping>
			<cmp-field-mapping name="OrderBean_orderId">
				<entity-ref home="OrderBean">
					<cmp-field-mapping name="OrderBean_orderId"

						persistence-name="Order_ID"/>
				</entity-ref>
			</cmp-field-mapping>
		</primkey-mapping>
		<value-mapping type="OrderItemLocal">
			<cmp-field-mapping name="OrderItemBean_itemId">
				<entity-ref home="OrderItemBean">
					<cmp-field-mapping name="OrderItemBean_itemId">

						<fields>
							<cmp-field-mapping name="OrderItemBean_itemId" 

								persistence-name="Item_ID"/>

							<cmp-field-mapping name="OrderItemBean_orderId" 

								persistence-name="Order_ID"/>
						</fields>
					</cmp-field-mapping>
				</entity-ref>
			</cmp-field-mapping>
		</value-mapping>
		</collection-mapping>
	</cmp-field-mapping>
</entity-deployment>

Finally, you must update the bean implementation to work with both the placeholder CMP field and the foreign key.

1. In the ejbCreate method, do the following:
   1. Create the placeholder CMP field that takes the place of the foreign key field.

   2. Set a value in the placeholder CMP field in the ejbCreate method. This value is written out to the foreign key field in the database table.

2. In the ejbPostCreate method, set the foreign key to the value in the duplicate CMP field.

   Note: Since the foreign key is part of a primary key, it can only be set once.

In our example, the CMP field, orderId, is set in the ejbCreate method and the relationship field, belongToOrder, is set in the ejbPostCreate method.

public OrderItemPK ejbCreate(OrderItem orderItem) throws CreateException
{
	setItemId(orderItem.getItemId());
	setOrderId(orderItem.getOrderId());
	setPrice(orderItem.getPrice());
	return new OrderItemPK(orderItem.getItemId(),orderItem.getOrderId()) ;
}

public void ejbPostCreate(OrderItem orderItem) throws CreateException
{
	// when just after bean created
	try {
		Context ctx = new InitialContext();
		OrderLocalHome orderHome = 	

			(OrderLocalHome)ctx.lookup("java:comp/env/OrderBean");
		OrderLocal order = orderHome.findByPrimaryKey(orderItem.getOrderId());

		setBelongToOrder(order);
	}
	catch(Exception e) {
		e.printStackTrace();
		throw new EJBException(e);
	}
} 

The OrderItem object that is passed into the ejbCreate and ejbPostCreate methods is as follows:

public class OrderItem implements java.io.Serializable
{

    private Integer itemId;
    private Integer orderId;
    private Double price;

    public OrderItem(Integer itemId, Integer orderId, Double price)
    {
        this.itemId = itemId;
        this.orderId = orderId;
        this.price = price;
    }

    public Integer getItemId() {
        return itemId;
    }

    public void setItemId(Integer itemId) {
        this.itemId = itemId;
    }

    public Integer getOrderId() {
        return orderId;
    }

    public void setOrderId(Integer orderId) {
        this.orderId = orderId;
    }

    public Double getPrice() {
        return price;
    }
    public void setPrice(Double price) {
        this.price = price;
    }

    public boolean equals(Object other)
    {
        if(other instanceof OrderItem) {
            OrderItem orderItem = (OrderItem)other;
            if (itemId.equals(orderItem.getItemId()) &&
                orderId.equals(orderItem.getOrderId()) &&
                price.equals(orderItem.getPrice()) ) {
                return true;
            }
        }
        return false;
    }
}

How to Override a Foreign Key Database Constraint

If you have defined your database columns with a constraint, such as NOT NULL, you may encounter an error after the ejbCreate method. An INSERT is performed after the ejbCreate method; thus, if any field in the database row was left null, the constraint raises a database table constraint violation. This occurs mostly with foreign keys as they cannot be assigned until the ejbPostCreate method. In order to avoid this problem, you must relax the constraint on the field in question.

You can relax the database constraints by redefining the offending column to DEFERRABLE. If you relax the constraint, you will have time to set the database field before the transaction commits and avoid the database constraint violation.

The following shows how to create a deferrable constraint for the TEST table:

create table test (test varchar2(10) not null INITIALLY DEFERRED DEFERRABLE )