Skip Headers

Oracle® Containers for J2EE Orion CMP Developer's Guide 10g Release 3 (10.1.3) B19177-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Configuring Container-Managed Persistent Fields

Container-managed persistent fields represent simple data types that are persisted to database tables. These fields define the state of an entity bean. These fields are direct attributes of a bean. For more information about persistent fields, see "Container-Managed Persistent Fields".

In entity beans with container-managed persistence, you define the persistent data both in the bean instance and in the deployment descriptor using the following:

- Accessor methods (getter and setter) in the bean instance: For each persistent field, both a getter and a setter method is created. The data type of the parameter returned from the getter and passed into the setter defines the simple data type of the field. The name of the field is designated by the name of the getter and setter methods.

  The following code shows a getter and a setter for the employee name persistent field. A String that is returned from the getter and passed into the setter is a simple data type of the field. If you remove the "get" and "set" from the method names, and then lower the case of the first letter, you have the persistent field name. In the following example, `empName` is the persistent field name:

      public abstract String getEmpName() throws RemoteException;

      public abstract void setEmpName(String empName) throws RemoteException;

- The deployment descriptor declares these fields as persistent. Each field name must be defined in a `<cmp-field><field-name>` element in the deployment descriptor. In the preceding example, three persistent fields are defined in the data accessor methods: `empNumber`, `empName`, and `salary`.

  These fields are defined as persistent fields in the `ejb-jar.xml` deployment descriptor within the `<cmp-field><field-name>` element, as follows:

      <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>empNumber</field-name></cmp-field>
              <cmp-field><field-name>empName</field-name></cmp-field>
              <cmp-field><field-name>salary</field-name></cmp-field>
              <primkey-field>empNumber</primkey-field>
          </entity>
      ...
      </enterprise-beans>

Map these fields to the database as follows:

- Accept the defaults for these fields and avoid more deployment descriptor configuration. See "Configuring Default Mapping of Persistent Fields to the Database" for more information.

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

## Configuring Default Mapping of Persistent Fields to the Database

If you simply define the persistent fields in the `ejb-jar.xml` file, then OC4J provides the following mappings of these fields to the database:

- Database: The default database as set up in your OC4J instance configuration. For the JNDI name, use the`<location>` element for emulated data sources, and `<ejb-location>` element for nonemulated data sources.

  Upon installation, the default database is a locally installed Oracle database that must be listening on port 1521 with a SID of `ORCL`. To customize the default database, change the first configured database to point to your database.

- Table: The container automatically creates a default table where the name of the table is guaranteed to be unique. For all future redeployments, copy the generated `orion-ejb-jar.xml` file with this table name into the same directory as your `ejb-jar.xml` file. 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.

  The table name is constructed with the following names, where each name is separated by an underscore character ( _ ):

  - EJB name defined in `<ejb-name>` in the deployment descriptor.

  - JAR file name, including the `.jar` extension. However, all dash characters ( - ) and periods ( . ) are converted to underscore characters ( _ ) 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 that you define during deployment.

  If the constructed name is greater than thirty characters, the name is truncated at twenty-four characters. Then six characters made up of an alphanumeric hash code are appended to the name.

  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: The columns in the entity bean table each have the same name as the `<cmp-field>` elements in the designated database. The data types for the database, translating Java data types to database data types, are defined in the specific database XML file, such as `oracle.xml`.

## Configuring Explicit Mapping of Persistent Fields to the Database

As "Configuring Default Mapping of Persistent Fields to the Database" discusses, your persistent data can be automatically mapped to a database table by the container. However, if the data represented by your bean is more complex or you do not want to accept the defaults that OC4J provides for you, then you can map the persistent data to an existing database table and its columns within the `orion-ejb-jar.xml` file. Once the fields are mapped, the container provides the persistence storage of the persistent data to the indicated table and rows.

To explicitly map persistent fields to the database, do the following:

1. Deploy your application with only the `ejb-jar.xml` elements configured.

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

2. Modify the `<entity-deployment>` element (see Table A-1, "Attributes of the <entity-deployment> Element") in the `orion-ejb-jar.xml` file to use the database table and columns you specify.

Once you define container-managed persistent fields, each within its own `<cmp-field>` element, you can map each to a specific database table and column. Thus, you can map these persistent fields to existing database tables. The mapping occurs with the `orion-ejb-jar.xml` file (the OC4J-specific deployment descriptor).

The explicit mapping of persistent fields is completed within an `<entity-deployment>` element t (see Table A-1, "Attributes of the <entity-deployment> Element"). This element contains all mapping for an entity bean. The following are the attributes and elements that are specific to persistent field mapping:

    <entity-deployment name="..." location="..." table="..." data-source="...">
        <primkey-mapping>
            <cmp-field-mapping name="..." persistence-name="..." />
        </primkey-mapping>
        <cmp-field-mapping name="..." persistence-name="..." />
    ...
    </entity-deployment>

Table 5-2 Deployment Descriptor's Elements for Mapping Persistent Fields to a Specific Database Table

Element or Attribute Name | Description
--- | ---
`name` | Bean name, which is defined in the `ejb-jar.xml` file in the `<ejb-name>` element.
`location` | JNDI location.
`table` | Database table name.
`data-source` | Data source for the database where the table resides.
`primkey-mapping` | Definition of how the primary key is mapped to the table.
`cmp-field-mapping` | The name attribute specifies the `<cmp-field>` in the deployment descriptor, which is mapped to a table column in the `persistence-name` attribute.

You can configure the following within the `orion-ejb-jar.xml` file:

1. Configure the `<entity-deployment>` element for every entity bean that contains container-managed persistent fields that you will map within it.

2. Configure a `<cmp-field-mapping>` element for every field within the bean that you are mapping. Each `<cmp-field-mapping>` element must contain the name of the field to be persisted, as follows:

   1. Configure the primary key in the `<primkey-mapping>` element contained within its own `<cmp-field-mapping>` element.

   2. Configure simple data types (such as a primitive, simple object, or serializable object) that are mapped to a single field within a single `<cmp-field-mapping>` element. The name and database field are fully defined within the element attributes.

Example 5-5 Mapping Persistent Fields to a Specific Database Table

Example 5-5 demonstrates how to map persistent fields in your bean instance to database tables and columns by mapping the employee persistence fields to the Oracle database table `EMP`:

    <entity-deployment name="EmpBean"
                       location="emp/EmpBean" wrapper="EmpHome_EntityHomeWrapper2"
                       max-tx-retries="3" table="emp" data-source="jdbc/OracleDS">
        <primkey-mapping>
            <cmp-field-mapping name="empNumber" persistence-name="empnumber" />
        </primkey-mapping>
        <cmp-field-mapping name="empName" persistence-name="ename" />
        <cmp-field-mapping name="salary" persistence-name="sal" />
    ...
    </entity-deployment>

After deployment, OC4J maps the element values, as Table 5-3 shows:

Table 5-3 Mapping of the Deployment Descriptor's Element Values by the Container

Bean | Database
--- | ---
`emp/EmpBean` | `EMP` table, located in `jdbc/OracleDS` in the `data-sources.xml` file
`empNumber` | `EMPNUMBER` column as primary key
`empName` | `EMPNAME` column
`salary` | `SALARY` column