Configuring an EJB 2.1 CMP Entity Bean Primary Key

Every EJB 2.1 CMP entity bean must have a primary key field.

You can configure the primary key as a well-known Java type (see "Configuring an EJB 2.1 CMP Entity Bean Primary Key Field") or as a special type that you create (see "Configuring an EJB 2.1 CMP Entity Bean Composite Primary Key Class").

You can either assign primary key values yourself, or, more typically, you can associate a primary key field with a primary key value generator (see "Configuring EJB 2.1 CMP Entity Bean Automatic Primary Key Generation").

Configuring an EJB 2.1 CMP Entity Bean Primary Key Field

For a simple EJB 2.1 CMP entity bean, you can define your primary key to be a well-known Java type as follows:

Code your bean's ejbCreate method to return the primary key class type (see "Implementing an EJB 2.1 Entity Bean")
Configure your deployment XML to use it (see "Using Deployment XML")

Once defined, the container may create a column or columns in the entity bean table for the primary key and maps the primary key defined in the deployment descriptor to this column.

Once this configuration is complete, the container manages the instantiation of primary keys of this type and initializes your entity bean primary key field accordingly.

If you specify your primary key type as java.lang.Object, you can rely on the container to automatically handle the allocation of primary key values (see "Configuring EJB 2.1 CMP Entity Bean Automatic Primary Key Generation").

Using Deployment XML

Example 14-1 shows the ejb-jar.xml file entity element attributes prim-key-class and primkey-field configured to specify a primary key as well-known Java type Integer.

Example 14-1 ejb-jar.xml for Primary Key Field with Type Integer

<enterprise-beans>
  <entity> 
    <display-name>Employee</display-name>
    <ejb-name>EmployeeBean</ejb-name>
    <local-home>employee.EmployeeLocalHome</local-home>
    <local>employee.EmployeeLocal</local>
    <ejb-class>employee.EmployeeBean</ejb-class>
    <persistence-type>Container</persistence-type>
    <prim-key-class>java.lang.Integer</prim-key-class>
    <reentrant>False</reentrant>
    <cmp-version>2.x</cmp-version>
    <abstract-schema-name>Employee</abstract-schema-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>
    </entity>
...
</enterprise-beans>

Within the orion-ejb-jar.xml file, the primary key is mapped to the underlying database persistence storage by mapping the CMP field or primary key field defined in the ejb-jar.xml file to the database column name. Example 14-2 shows the EmpBean persistence storage is defined as the EMP table in the database that is defined in the jdbc/OracleDS data source. Following the <entity-deployment> element definition, the primary key, empNo, is mapped to the EMPNO column in the Emp table, and the empName and salary CMP fields are mapped to EMPNAME and SALARY columns respectively in the EMP table.

Example 14-2 orion-ejb-jar.xml for Primary Key Field

<entity-deployment name="EmployeeBean" ...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="EMPNAME" />
  <cmp-field-mapping name="salary" persistence-name="SALARY" />
...

Configuring an EJB 2.1 CMP Entity Bean Composite Primary Key Class

If your primary key is more complex than a well-known Java data type, then you can define your own primary key class.

Your primary key class must have the following characteristics:

be named <name>PK
be public and serializable
provide a constructor for creating a primary key instance

Your class may contain any number of instance variables used to form the primary key. Instance variables must have the following characteristics:

be public
use data types that are either primitive or serializable, or types that can be mapped to SQL types

Once the primary key class is defined (see "Using Java"), to use it in an EJB, you must:

Code your bean's ejbCreate method to return the primary key class type (see "Implementing an EJB 2.1 Entity Bean")
Configure your deployment XML to use it (see "Using Deployment XML")

Once this configuration is complete, the container manages the instantiation of primary keys of this type and initializes your entity bean primary key field accordingly.

Using Java

Example 14-3 shows an example primary key class.

Example 14-3 EJB 2.1 CMP Entity Bean Primary Key Class Implementation

package employee;

import java.io.*;
import java.io.Serializable;
...

public class EmployeePK implements java.io.Serializable
{
  public Integer empNo;

  public EmployeePK()
  {
    this.empNo = null;
  }

  public EmployeePK(Integer empNo)
  {
    this.empNo = empNo;
  }
}

Using Deployment XML

As Example 14-4 shows, you define the primary key class within the ejb-jar.xml file <prim-key-class> element. You define each primary key class instance variable in a <cmp-field><field-name> element using the same variable name as that used in the primary key class.

Example 14-4 ejb-jar.xml For a Primary Key Class and Its Instance Variables

<enterprise-beans>
  <entity>
    <description>no description</description>
    <display-name>EmployeeBean</display-name>
         <ejb-name>EmployeeBean</ejb-name>
         <local-home>employee.LocalEmployeeHome</home>
         <local>employee.LocalEmployee</remote>
         <ejb-class>employee.EmployeeBean</ejb-class>
         <persistence-type>Container</persistence-type>
        <prim-key-class>employee.EmployeePK</prim-key-class>
         <reentrant>False</reentrant>
         <cmp-version>2.x</cmp-version>
         <abstract-schema-name>Employee</abstract-schema-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>
      </entity>
</enterprise-beans>

Once defined, the container may create a column or columns in the entity bean table for the primary key and maps the primary key class defined in the deployment descriptor to this column.

The CMP fields are mapped in the orion-ejb-jar.xml in the same manner as described in "Configuring an EJB 2.1 CMP Entity Bean Primary Key Field". However, with a complex primary key, the mapping contains more than a single field; thus, the <primkey-mapping><cmp-field-mapping> element contains another subelement: the <fields> element. All of the fields of a primary key are each defined in a separate <cmp-field-mapping> element within the <fields> element, as Example 14-5 shows.

Example 14-5 orion-ejb-jar.xml for Primary Key Field

<primkey-mapping>
  <cmp-field-mapping>
    <fields>
      <cmp-field-mapping name="empNo" persistence-name="EMPNO" />
    </fields>
  </cmp-field-mapping>
</primkey-mapping>

Configuring EJB 2.1 CMP Entity Bean Automatic Primary Key Generation

If you specify the type of your primary key field (see "Configuring an EJB 2.1 CMP Entity Bean Primary Key Field") as java.lang.Object but do not specify the primary key name, then the primary key is auto-generated by the container (see "Using Deployment XML").

Using Deployment XML

Example 14-6 shows the ejb-jar.xml for an unnamed primary key field of type Object.

Example 14-6 ejb-jar.xml for Primary Key Field with Type Object

<enterprise-beans>
      <entity> 
         <display-name>Employee</display-name>
         <ejb-name>EmployeeBean</ejb-name>
         <local-home>employee.EmployeeLocalHome</local-home>
         <local>employee.EmployeeLocal</local>
         <ejb-class>employee.EmployeeBean</ejb-class>
         <persistence-type>Container</persistence-type>
         <prim-key-class>java.lang.Object</prim-key-class>
         <reentrant>False</reentrant>
         <cmp-version>2.x</cmp-version>
         <abstract-schema-name>Employee</abstract-schema-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>
      </entity>
...
</enterprise-beans>

Once defined, the container creates a column in the entity bean table for the primary key of type LONG. The container uses random numbers for the primary key values. This is generated in the orion-ejb-jar.xml for the bean as Example 14-7. In this case, the container will create a column named autoid.

Example 14-7 orion-ejb-jar.xml for Automatically Generated Primary Key Field

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