Skip Headers

Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide 10g (9.0.4) Part Number B10324-01 |
Home | Contents | Index

# 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 )

| Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
Home | Contents | Index