Configuring a Primary Key for an EJB 2.1 Entity Bean With Container-Managed Persistence

Every EJB 2.1 entity bean with container-managed persistence must have a primary key field.

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

For more information, see "What is a Primary Key of an Entity Bean With Container-Managed Persistence?"

Typically, you rely on OC4J to assign primary key values automatically. To configure how OC4J assigns primary key values, you use TopLink persistence API. For more information, see the following:

• "Customizing the TopLink EJB 2.1 Persistence Manager"

• "Understanding Sequencing in Relational Projects" in the Oracle TopLink Developer's Guide

Configuring a Primary Key Field for an EJB 2.1 Entity Bean With Container-Managed Persistence

For a simple EJB 2.1 entity bean with container-managed persistence, 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 With Container-Managed Persistence")

• 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. The container manages the instantiation of primary keys of this type and initializes your entity bean primary key field accordingly.

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 for EJB 2.1 Entity Bean With Container-Managed Persistence

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

Configuring a Composite Primary Key Class for an EJB 2.1 Entity Bean With Container-Managed Persistence

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 entity bean, you must do the following:

• Code your bean's ejbCreate method to return the primary key class type (see "Implementing an EJB 2.1 Entity Bean With Container-Managed Persistence")

• 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. The container manages the instantiation of primary keys of this type and initializes your entity bean primary key field accordingly.

Using Java

Example 14-2 shows an example primary key class.

Example 14-2 Primary Key Class Implementation for an EJB 2.1 Entity Bean With Container-Managed Persistence

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-3 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-3 ejb-jar.xml for Primary Key Class and Its Instance Variables for an EJB 2.1 Entity Bean With Container-Managed Persistence

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