Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Configuring a Descriptor With EJB Information

If your project uses EJB (see "Configuring Persistence Type"), you can use descriptors to describe the characteristics of CMP and BMP entity beans.

Table 28-18 summarizes which descriptors support EJB information.

Table 28-18 Descriptor Support for EJB Information

Descriptor | Using TopLink Workbench | Using Java
--- | --- | ---
Relational DescriptorsFoot 1 |  |
Object-Relational Descriptors |  |
EIS DescriptorsFoot 2 |  |
XML Descriptors |  |

Footnote 1 Relational class descriptors only (see "Relational Class Descriptors").

Footnote 2 EIS root descriptors only (see "EIS Root Descriptors").

When mapping EJB, you create a descriptor for the bean class; you do not create a descriptor for the local interface, remote interface, home class, or primary key class.

When using TopLink Workbench, you must define the project with the correct EJB type (such as CMP or BMP) and import the `ejb-jar.xml` file for the beans into the TopLink Workbench project.

For CMP 2.0 projects, the `ejb-jar.xml` file defines the bean's attributes to be mapped. A CMP bean descriptor contains a CMP policy used to configure CMP-specific options.

For more information, see "Descriptors and EJB".

## Using TopLink Workbench

To configure a descriptor with EJB information, use this procedure:

1. In the Navigator, select a relational descriptor.

2. Click EJB Descriptor on the mapping toolbar.

   An EJB Info tab is added to the descriptor.

   To remove the EJB information for the selected descriptor, click EJB Descriptor again.

   The EJB Info tab is removed from the descriptor.

3. Click the EJB Info tab in the Editor

   Figure 28-30 EJB Info Tab

   Description of "Figure 28-30 EJB Info Tab"

Use the following information to enter data in each field on the tab:

Field | Description
--- | ---
EJB Name | Enter the bean's base name. When using EJB 2.0, this is specified in the `<ejb-name>` element of the `ejb-jar.xml` file and is for display only.
Primary Key Class | Enter the primary key. When using EJB 2.0, this is specified in the `<prim-key-class>` element of the `ejb-jar.xml` file and is for display only.
Unknown Primary Key Class | Check this option if you choose not to specify the primary key class or the primary key fields for an entity bean with container managed persistence. For example, select this field if the entity bean does not have a natural primary key or you want the deployer to select the primary key fields at deployment time. For more information, see "Unknown Primary Key Class Support".
Local Interface | Enter the local interface. When using EJB 2.0, this is specified in the `<local>` element of the `ejb-jar.xml` file and is for display only.
Local Home Interface | Enter the local home interface. When using EJB 2.0, this is specified in the `<local-home>` element of the `ejb-jar.xml` file and is for display only.
Remote Interface | Enter the remote interface. When using EJB 2.0, this is specified in the `<remote>` element of the `ejb-jar.xml` file and is for display only.
Remote Home Interface | Enter the remote interface. When using EJB 2.0, this is specified in the `<home>` element of the `ejb-jar.xml` file and is for display only.
Change Deferral | Use these options to specify how TopLink updates the database for this EJB descriptor.
Defer All Changes | Specify not to send changes to the database until the JTA transaction is committed. This is the default TopLink behavior. This is the most efficient option that results in the least amount of data source interaction.
Defer Updates Only | Specify to send changes to the database immediately after any insert or delete operation, but do not send changes to the data source for update operations until the JTA transaction is committed. Select this option for backwards compatibility with some CMP containers, such as OC4J. For more information, see "Nondeferred Changes"). Use this option with caution as it will require the data source transaction and locks to be held longer and may cause referential integrity issues.
Defer None | Specify to send all changes to the database immediately. This is the least efficient option that generates the greatest amount of data source interaction. Select this option for backwards compatibility with some CMP containers, such as OC4J. For more information, see "Nondeferred Changes").
Insert New Objects After | Specify to send new object insert changes to the database after bean life cycle method `ejbCreate` (default) or `ejbPostCreate`. This is only relevant when not deferring changes (see "Configuring Change Policy"). If non-null foreign key constraints cannot be satisfied when the insert is performed after `ejbCreate`, you may consider configuring TopLink CMP to do the insert after `ejbPostCreate`, if supported by your container. For more information, see "Creating a New Entity Bean and ejbCreate / ejbPostCreate Methods".

## Using Java

Using Java code, you can use descriptors to describe the characteristics of CMP (see "Configuring CMP Information") and BMP (see "Configuring BMP Information") entity beans.

### Configuring CMP Information

To configure EJB CMP specific information on a descriptor, define a `CMPPolicy`:

    descriptor.setCMPPolicy(new CMPPolicy());

You can use the following `CMPPolicy` API to configure optional EJB behavior:

Note: Most of these options are provided for compatibility with other EJB CMP implementations. Use caution when using them as they will affect application performance.

- `setDeferModificationsUntilCommit`–By default TopLink defers all changes to the database until the transaction is committed. Use this method to configure TopLink to update the database after each EJB operation for the specified deferral level:

  - `CMPPolicy.NONE`–default behavior

  - `CMPPolicy.UPDATE_MODIFICATIONS`–update the database after each EJB operation for update modifications only

  - `CMPPolicy.ALL_MODIFICATIONS`–update the database after each EJB operation for all modifications

- `setNonDeferredCreateTime`–when using non-deferred writes (see setDeferModificationsUntilCommit), use this method to configure TopLink to insert a new EJB before (`CMPPolicy.AFTER_EJBCREATE`) or after (`CMPPolicy.AFTER_EJBPOSTCREATE`) the `ejbPostCreate` method.

- `setForceUpdate`–use this method to make TopLink write all EJB that have been accessed to the database regardless if they changed or not. Normally, this is set during migration if the `orion-ejb-jar.xml` file has force update enabled. For more information, see "Migrating OC4J Orion Persistence to OC4J TopLink Persistence"

- `setUpdateAllFields`–use this method to configure TopLink to force all the fields of the bean to be updated instead of only the changed fields.

- `setPessimisticLockingPolicy`–use this method to configure EJB-level pessimistic locking.

### Configuring BMP Information

EJB BMP descriptors must be configured with a `BMPWrapperPolicy`. TopLink Workbench does not currently support defining the `BMPWrapperPolicy` so you must define this through Java code.

For more information, see "Configuring Wrapper Policy".