Skip Headers

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

Previous | Next |

# Oracle Containers for J2EE (OC4J)

To integrate a TopLink application with OC4J, you must consider the following:

- CMP Integration

- Migrating OC4J Orion Persistence to OC4J TopLink Persistence

- JTA Integration

In addition to configuring these OC4J specific options, you must also consider the general application server integration issues in "Application Server Integration Concepts".

## CMP Integration

To enable TopLink CMP integration in OC4J, use the following procedure (this procedure assumes you have already installed TopLink):

1. If necessary, migrate your CMP application using the TopLink migration tool (see "Migrating OC4J Orion Persistence to OC4J TopLink Persistence").

2. Evaluate your choice of `UnitOfWork` change policy (see "Unit of Work and Change Policy").

   If you are using EJB 3.0, you can let TopLink configure your persistent classes with the most efficient change policy (see "Attribute Change Tracking Policy") at class loading time using byte code weaving.

3. Ensure that all necessary deployment descriptor files are in place (see "Creating TopLink Files for Deployment" and "Packaging a TopLink Application").

   If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in deployment descriptors. Use deployment descriptors to override annotations or specify options not supported by annotations. For more information on what annotations are currently supported, see Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide.

4. Optionally, consider the EJB customization options that TopLink provides (see "Configuring Miscellaneous EJB Options").

## Migrating OC4J Orion Persistence to OC4J TopLink Persistence

In 10g Release 3 (10.1.3), OC4J is shipped configured to use TopLink as its default persistence manager.

If you upgrade your OC4J to this release, you must migrate persistence configuration from your original `orion-ejb-jar.xml` file to the `toplink-ejb-jar.xml` file.

In this release, Oracle provides a TopLink migration tool that you can use to automate this migration for Release 2 (9.0.4) or later OC4J installations.

After using the TopLink migration tool, you may need to make some additional changes as described in "Post-Migration Changes".

If you encounter problems during migration, see "Troubleshooting Your Migration".

This section explains how to use the TopLink migration tool, including:

- Overview

- Using the TopLink Migration Tool from TopLink Workbench

- Using the TopLink Migration Tool From the Command Line

- Post-Migration Changes

- Troubleshooting Your Migration

### Overview

Before using the TopLink migration tool, review this section to understand how the TopLink migration tool works and to determine what OC4J persistence manager metadata is, and is not, migrated.

Input and Output

The TopLink migration tool takes the following files as input:

- `ejb-jar.xml`

- `orion-ejb-jar.xml`

It migrates as much OC4J-specific persistence configuration as possible to a new `toplink-ejb-jar.xml` file and creates the following new files in a target directory you specify:

- `orion-ejb-jar.xml`

- `toplink-ejb-jar.xml`

- TopLink Workbench project file `TLCmpProject.mwp`

The `ejb-jar.xml` and `orion-ejb-jar.xml` files may be in an EAR, JAR, or just standalone XML files. If you migrate from standalone XML files (rather than an EAR or JAR file), ensure that the domain classes are accessible and included in your classpath.

The TopLink migration tool creates a new `orion-ejb-jar.xml` and `toplink-ejb-jar.xml` file to the target directory you specify in the same format as it reads the original files. For example, if you specify an EAR file as input, then the TopLink migration tool stages and creates a new EAR file that contains both the new `orion-ejb-jar.xml` and the new `toplink-ejb-jar.xml` file, but is otherwise identical to the original.

The TopLink Workbench project file is always created as a separate file.

Note: Oracle recommends that you make a backup copy of your `orion-ejb-jar.xml` file before using the TopLink migration tool.

Migration

As it operates, the TopLink migration tool logs all errors and diagnostic output to a log file named `oc4j_migration.log` in the output directory. If you use the TopLink migration tool from TopLink Workbench, see also the TopLink Workbench log file `oracle.toplink.workbench.log` located in your user home directory (for example, `C:\Documents and Settings\<``user-name``>`).

The TopLink migration tool processes descriptor, mapping, and query information from the input files as follows:

- It builds a TopLink descriptor object for each entity bean and migrates native persistence metadata like mapped tables, primary keys, and mappings for CMP and CMR fields.

- It builds a TopLink mapping object for every CMP and CMR field of an entity bean and migrates native persistence metadata like foreign key references.

- It builds a TopLink query object for each `finder` or `ejbSelect` of an entity bean and migrates persistence metadata like customized query statements.

Table 7-3 lists OC4J `<entity-deployment>` attributes and subelements from the `orion-ejb-jar.xml` file and for each, indicates whether or not the TopLink migration tool:

- Retains it in the new `orion-ejb-jar.xml` file

- Migrates it to the new `toplink-ejb-jar.xml` file

In Table 7-3, elements are identified with angle brackets. Note that in some cases an attribute is migrated when set to one value, but discarded if set to another value (for example, `exclusive-write-access`).

Table 7-3 OC4J orion-ejb-jar.xml Feature Migration

orion-ejb-jar.xml Feature | Retained in New orion-ejb-jar.xml | Migrated to New toplink-ejb-jar.xml
--- | --- | ---
`<entity-deployment>` |  |
`clustering-schema` |  |
`copy-by-value` |  |
`data-source` |  |
`location` |  |
`max-instances` |  |
`min-instances` |  |
`max-tx-retries` |  |
`disable-wrapper-cache` |  |
`name` |  |
`pool-cache-timeout` |  |
`wrapper` |  |
`local-wrapper` |  |
`call-timeout` |  |
`exclusive-write-access` |  |
`true` |  |
`false` |  |
`do-select-before-insert` |  |
`true` |  |
`false` |  |
`isolation` |  |
`locking-mode` |  |
`pessimistic` |  |
`optimistic` |  |
read-only |  |
`old_pessimistic` |  |
`update-changed-fields-only` |  |
`true` |  |
`false` |  |
`table` |  |
`force-update` |  |
true |  |
false |  |
`data-synchronization-option` |  |
ejbCreate |  |
ejbPostCreate |  |
`batch-size` |  |
Any value greater than 1 |  |
`<ior-security-config>` |  |
`<env-entry-mapping>` |  |
`<resource-ref-mapping>` |  |
`<resource-env-ref-mapping>` |  |
`<primkey-mapping>` |  |
`<cmp-field-mapping>` |  |
`one-to-one-join` |  |
inner |  |
outerFoot 1 |  |
shared |  |
`<finder-method>` |  |
`<persistence-type>`Foot 2 |  |

Footnote 1 TopLink supports both `outer` and `inner` joins at run time.You can manually configure EJB descriptors with these options. For more information, see "Join Reading and Object-Level Read Queries" .

Footnote 2 The `persistence-type` attribute's table column size, if present, is discarded. For more information, see "Recovering persistence-type Table Column Size".

Table 7-4 lists OC4J features and their TopLink equivalents configured by the TopLink migration tool.

Table 7-4 OC4J and TopLink Feature Comparison

Feature | orion-ejb-jar.xml | toplink-ejb-jar.xml
--- | --- | ---
CMP field mapping | Direct Serialized object | Direct-to-field Serialized object
CMR field mapping | One-to-one One-to-many Many-to-many | One-to-one One-to-many Many-to-many
Partial query | Full SQL statement | SQL Call
Finder | Oracle-specific syntax | SQL Call or EJB-QL
Lazy loading (fetch group) | Lazy loading of primary key and CMP fields | Not supported Alternatively, you can manually configure the TopLink equivalent, if appropriate (see "Fetch Groups").
SQL statement caching | Cache static SQL | Not supported at the bean level. TopLink supports parameterized SQL and statement caching at the session and query level (see "Understanding TopLink Queries").
Locking | Optimistic: database-level Pessimistic: bean instance-level | Optimistic: object-level Pessimistic: query lock at database-level
Read-only | Attempt to change throws `Exception` | Attempt to change throws `Exception`
Validity timeout | Read-only bean validity timeout before reloaded. | Cache timeout
Isolation level | Committed Serializable | Committed Serializable Not Committed Not Repeatable
Delay update until commit | Supported | Supported (see "Configuring a Descriptor With EJB Information").
Exclusive write access on bean | Default value is `false` | Assume `true`
Insert without existence check | Supported | Supported
Update changed fields only | Supported | Supported (see "Attribute Change Tracking Policy").
Force update | Invoke bean life cycle `ejbStore` method even though persistent fields have not changed | Supported

### Using the TopLink Migration Tool from TopLink Workbench

To use the TopLink migration tool and create a new, mapped TopLink Workbench project from an OC4J application, use this procedure:

1. From TopLink Workbench, select File > Migrate > From OC4J 9.0.x.

   Figure 7-1 Create Project from OC4J Dialog Box

2. Continue with "Post-Migration Changes".

Use the following information to enter data in each field of the Create Project from OC4J dialog box:

Field | Description
--- | ---
From | Use these fields to specify the location of the existing OC4J files. These files may be included as part of a JAR, EAR, or individual files.
Individual Files | Select to convert from individual `ejb-jar.xml` and `orion-ejb-jar.xml` files in the Input Directory. Click Browse and select the directory location that contains the XML files to convert from.
Archive File | Select to use a specific archive file. Click Browse and select the archive file to convert from..
To | Use these fields to specify the location to which migrated files are written.
Output Directory | Click Browse and select a directory location in which to create the new XML files and TopLink Workbench project.
Classpath | If you are migrating from individual files, ensure that the domain classes are accessible and included in your classpath.
Show Migration Log | Select to have migration log output displayed in a separate window.

### Using the TopLink Migration Tool From the Command Line

To use the TopLink migration tool from the command line, you must perform the following steps:

1. Ensure that the following is in your classpath:

   - `<``TOPLINK_HOME``>/jlib/antlr.jar`

   - `<``TOPLINK_HOME``>/jlib/ejb.jar`

   - `<``TOPLINK_HOME``>/jlib/toplink.jar`

   - `<``TOPLINK_HOME``>/jlib/cmpmigrator.jar`

   - `<``TOPLINK_HOME``>/jlib/toplinkmw.jar`

   - `<``TOPLINK_HOME``>/jlib/tlmwcore.jar`

   - `<``TOPLINK_HOME``>/config`

   - `<``ORACLE_HOME``>/lib/xmlparserv2.jar`

2. If you intend to migrate from plain XML files (rather than an EAR or JAR file), ensure that the domain classes are accessible and included in your classpath.

3. Make a backup copy of your original XML files.

4. Execute the TopLink migration tool as Example 7-2 illustrates using the appropriate arguments listed in Table 7-5.

   The usage information for the TopLink migration tool is:

       java -Dtoplink.ejbjar.schemavalidation=<true|false> -Dtoplink.migrationtool.generateWorkbenchProject=<true|false> -Dhttp.proxyHost=<proxyHost> -Dhttp.proxyPort=<proxyPort> oracle.toplink.tools.migration.TopLinkCMPMigrator -s<nativePM> -i<inputDir> -a<ear>|<jar> -x -o<outputDir> -v

   To identify the input files, you must specify one of `-a` or `-x`.

   For troubleshooting information, see "Troubleshooting Your Migration".

Example 7-2 Using the TopLink Migration Tool from the Command Line

    java -Dhttp.proxyHost=www-proxy.us.oracle.com -Dhttp.proxyPort=80 oracle.toplink.tools.migration.TopLinkCMPMigrator -sOc4j-native -iC:/mywork/in -aEmployee.ear -oC:/mywork/out -v

Table 7-5 TopLink Migration Tool Arguments

Argument | Description
--- | ---
`toplink.ejbjar.schemavalidation` | The system property used to turn on schema validation if `ejb-jar.xml` uses XML Schema (XSD) instead of DTD. The default value is `false`.
`toplink.migrationtool.generateWorkbenchProject` | The system property used enable generation of the TopLink Workbench project. The default value is `true`.
`<``proxyHost``>` | The address of your local HTTP proxy host
`<``proxyHost``>` | The port number on which your local HTTP proxy host receives HTTP requests.
`-s <source>` | The name of the native persistence manager from which you are migrating. For OC4J, use the name `Oc4j-native`.
`-i <input-directory>` | Fully qualified path to the input directory that contains both the OC4J `ejb-jar.xml` and `orion-ejb-jar.xml` files to migrate. Default: current working directory.
`-a <EAR-or-JAR>` | Fully qualified path to the archive file (either an EAR or JAR) that contains both the OC4J `ejb-jar.xml` and `orion-ejb-jar.xml` files to migrate.
`-x` | Tells the TopLink migration tool that the OC4J files in the input directory to migrate from are plain XML files (not in an archive file). If you use this option, ensure that the domain classes are accessible and included in your classpath.
`-o <output-directory` | `<targetDir>` is the path to the directory into which the TopLink migration tool writes the new `orion-ejb-jar.xml`, `toplink-ejb-jar.xml`, and log files. The path may be absolute or relative to the current working directory. You must specify this argument value. Ensure that permissions are set on this directory to allow the TopLink migration tool to create files and subdirectories.
`-v` | Verbose mode. Tells the TopLink migration tool to log errors and diagnostic information to the console.

### Post-Migration Changes

After you migrate the `orion-ejb-jar.xml` file persistence configuration to your `toplink-ejb-jar.xml` file, consider the following post-migration changes:

- Recovering persistence-type Table Column Size

- Updating the Unknown Primary Key Class Mapping Sequence Table

- Project Customization

Recovering persistence-type Table Column Size

In the `orion-ejb-jar.xml` file, you can specify this mapping, `cmp-field-mapping`, with a `persistence-type` attribute that provides both the type and column size as shown in Example 7-3.

Example 7-3 A cmp-field-mapping with persistence-type Specifying a Column Size

    <cmp-field-mapping ejb-reference-home="MyOtherEntity" name="myField" persistence-name="myField" persistence-type="VARCHAR2(30)">

The TopLink migration tool migrates the persistence type but not the column size because a TopLink project does not normally contain this size information.

To recover the `persistence-type` column size, do the following:

1. Perform the migration as described in "Using the TopLink Migration Tool From the Command Line".

2. Launch the generated TopLink Workbench project file `TLCmpProject.mwp`.

3. Log in to your database (see "Logging In and Out of a Database").

   TopLink Workbench retrieves all column sizes.

Updating the Unknown Primary Key Class Mapping Sequence Table

TopLink supports the use of an unknown primary key class (see "Unknown Primary Key Class Support") and so the TopLink migration tool also supports this feature.

OC4J uses a native run-time key generator to generate unique keys for auto-id key fields. In contrast, TopLink uses a sequencing table.

If your OC4J persistence configuration includes the use of an unknown primary key class, then the TopLink migration tool will create a sequencing table for this purpose.

Before deploying your application after migration, you must do the following:

1. Determine the largest key value generated prior to migration.

2. Manually update the counter of the TopLink migration tool-generated sequence table to a number that must be one larger than the largest key value generated prior to migration.

Project Customization

You can customize the following components of your project:

- EJB 3.0 Persistence Manager Customization

- EJB 2.1 Persistence Manager Customization

- Session Event Listener

#### EJB 3.0 Persistence Manager Customization

TopLinkFor an EJB 3.0 CMP application deployed to OC4J, you customize the TopLink persistence manager by creating a TopLink project XML file named `toplink-ejb-jar.xml` and a TopLink session XMl file named `ejb3-toplink-sessions.xml` and packaging them in the META-INF directory of the EJB-JAR that contains your EJB 3.0 entities. For more information, see "Customizing the TopLink Persistence Manager in an EJB 3.0 Application" in the Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide.

#### EJB 2.1 Persistence Manager Customization

For an EJB 2.1 CMP application deployed to OC4J, you customize the TopLink persistence manager by configuring properties in the `orion-ejb-jar.xml` file. These properties are used to configure the TopLink session that the TopLink runtime uses internally for CMP projects. For more information, see "Configuring persistence-manager Entries".

#### Session Event Listener

After you applied the default settings to your project at deployment time, you may wish to customize the TopLink session by configuring the session event listener. The pre-login event that the session raises is particularly useful. It lets you define the custom (nondefault) specifics for the session just before the session initializes and acquires connections.

For more information, see the following:

- "Session Customization"

- "Managing Session Events With the Session Event Manager"

- "Configuring Session Event Listeners"

### Troubleshooting Your Migration

This section describes solutions for problems you may encounter during migration, including the following:

- Log Messages

- Unexpected Relational Multiplicity

Log Messages

As it operates, the TopLink migration tool logs all errors and diagnostic output to a log file named `oc4j_migration.log` in the output directory. If you use the TopLink migration tool from TopLink Workbench, see also the TopLink Workbench log file `oracle.toplink.workbench.log` located in your user home directory (for example, `C:\Documents and Settings\<``user-name``>`)

In addition to these warnings, the TopLink migration tool logs an error if it encounters a problem that prevents it from completing the migration. Table 7-6 lists these problems and suggests possible solutions.

Table 7-6 TopLink Migration Tool Error Messages

Error Message | Description
--- | ---
There is no `ejb-jar.xml` in the input file. You must provide the `ejb-jar.xml` in order for the migration process to work. | The `ejb-jar.xml` file is missing. The TopLink migration tool stops and copies the original input files into the target directory. Verify that the `ejb-jar.xml` file is present in the specified EAR, JAR, or as a plain XML file. Empty the target directory and execute the TopLink migration tool again.
There is not an `orion-ejb-jar.xml` with native persistent metadata defined, no migration needed. | The `orion-ejb-jar.xml` file is missing. The TopLink migration tool stops and copies the original input files into the target directory. Verify that the `orion-ejb-jar.xml` file is present in the specified EAR, JAR, or as a plain XML file. Empty the target directory and execute the TopLink migration tool again.
`toplink-ejb-jar.xml` is already defined in the archive, no migration needed. | A `toplink-ejb-jar.xml` file is already present in the target directory. The TopLink migration tool stops and copies the original input files into the target directory. Remove the `toplink-ejb-jar.xml` file from the target directory. Empty the target directory and execute the TopLink migration tool again.

Unexpected Relational Multiplicity

The TopLink migration tool retrieves relationship multiplicity from the `orion-ejb-jar.xml` file and not from the OC4J `ejb-jar.xml` file.

Thus, even though the OC4J `ejb-jar.xml` file defines a relationship to be one-to-many, if the `orion-ejb-jar.xml` file defines the same relationship as many-to-many, then the TopLink migration tool will migrate the relationship as many-to-many.

## JTA Integration

For applications that require JTA integration, specify the external transaction controller when you configure the server platform in your session (see "Configuring the Server Platform").

For more information, see "Integrating the Unit of Work With an External Transaction Service".