How to Define and Use Primary Keys for Your Entity Bean

Each entity bean instance has a primary key that uniquely identifies it from other instances. You must declare the primary key (or the fields contained within a complex primary key) as a container-managed persistent field in the deployment descriptor. All fields within the primary key are restricted to either primitive, serializable, or types that can be mapped to SQL types. You can define your primary key in one of two ways:

• Define the type of the primary key to be a well-known type. The type is defined in the <prim-key-class> in the deployment descriptor. The data field that is identified as the persistent primary key is identified in the <primkey-field> element in the deployment descriptor. The primary key variable that is declared within the bean class must be declared as public.

• Define the type of the primary key as a serializable object within a <name>PK class that is serializable. This class is declared in the <prim-key-class> element in the deployment descriptor. This is an advanced method for defining a primary key and is discussed in "Defining the Entity Bean Primary Key in a Class".

• Specify an 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. See Defining an Auto-Generated Primary Key for Your Entity Bean for more information.

For a simple CMP, you can define your primary key to be a well-known type by defining the data type of the primary key within the deployment descriptor.

The employee example defines its primary key as a java.lang.Integer and uses the employee number (empNo) as its primary key.

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

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

Note: The entire CMP entity bean example (cmpapp.jar) is available on OTN from the OC4J sample code page at http://www.oracle.com/technology/tech/java/oc4j/demos/ on the OTN Web site.

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. In the following orion-ejb-jar.xml fragment, 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.

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

Defining the Entity Bean Primary Key in a Class

If your primary key is more complex than a simple data type, your primary key must be a class that is serializable of the name <name>PK. You define the primary key class within the <prim-key-class> element in the deployment descriptor.

The primary key variables must adhere to the following:

• Be defined within a <cmp-field><field-name> element in the deployment descriptor. This enables the container to manage the primary key fields.

• Be declared within the bean class as public and restricted to be either primitive, serializable, or types that can be mapped to SQL types.

• The names of the variables that make up the primary key must be the same in both the <cmp-field><field-name> elements and in the primary key class.

Within the primary key class, you implement a constructor for creating a primary key instance. Once the primary key class is defined in this manner, the container manages the class.

The following example places the employee number within a primary key class.

package employee;

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

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

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

The primary key class is declared within the <prim-key-class> element, and each of its variables are declared within a <cmp-field><field-name> element in the XML deployment descriptor, as follows:

<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 creates a column 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 "How to Define and Use Primary Keys for Your Entity Bean". With a complex primary key, the mapping contains more than a single field; thus, the <cmp-field-mapping> element of the <primkey-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 shown below.

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

Special mapping needs to happen if you have a complex primary key that contains a foreign key. See "Using a Foreign Key in a Composite Primary Key" for directions.

Defining an Auto-Generated Primary Key for Your Entity Bean

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 employee example defines its primary key as a java.lang.Object. Thus, the container auto-generates the primary key.

<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 called autoid 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 follows:

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