3 Understanding Orion CMP Support in OC4J

This chapter describes the two varieties of persistence managers that OC4J can use, and provides detailed instructions for migrating from one persistent manager (Orion) to another (TopLink).

This chapter includes information on the following topics:

• EJB 2.0 Support

• Persistence Manager

EJB 2.0 Support

The OC4J EJB container provides complete support for EJB 2.0, which includes the full support of the following:

• session beans

• entity beans

• message-driven beans

• BMP

• CMP

• object-relational mapping

OC4J provides CMP implementation for entity beans supporting object-relational mapping. OC4J supports one-to-one, one-to-many, many-to-one and many-to-many object-relational mappings (see "Container-Managed Relationships"), including simple object-relational mapping for simple, primitive, and serializable objects, as well as complex object-relational mapping for compound objects, entity references, and collections.

You can use OC4J to persist EJB 2.0 entity beans using the Orion persistence manager (see "Orion Persistence Manager").

Note: The key difference between the Orion persistence manager (see "Orion Persistence Manager") and the TopLink persistence manager (see "TopLink Persistence Manager") is that the former is limited to the support of EJB 2.0 entity beans, whereas the latter supports EJB 2.1 entity beans and EJB 3.0 entities.

Persistence Manager

An EJB container uses the services of a persistent manager to persist data from entity beans to a database. The following is the list of responsibilities of the persistence manager:

• handle the process of persisting an entity bean with container-managed persistence automatically at run time;

• map an entity bean to the database based on a contract (abstract schema) between the bean and the persistence manager;

• implement and execute finder and select methods using EJB QL.

This section elaborates on the following topics:

• Orion Persistence Manager

• TopLink Persistence Manager

• Migrating to the TopLink Persistence Manager

Orion Persistence Manager

The main difference between the Orion persistence manager and the TopLink persistence manager (see "TopLink Persistence Manager") is that the former only supports EJB 2.0 entity beans, whereas the latter supports EJB 2.1 entity beans, as well as EJB 3.0 entities.

The Orion persistence manager is deprecated and will not be supported in future releases. Oracle recommends that you use OC4J and the TopLink persistence manager for new development. Using the migration tool (see "Migrating to the TopLink Persistence Manager"), you can easily migrate an existing OC4J application that uses EJB 2.0 entity beans with the Orion persistence manager to use EJB 2.0 entity beans with the TopLink persistence manager (see "TopLink Persistence Manager").

TopLink Persistence Manager

Oracle TopLink is an advanced, object-persistence and object-transformation framework. TopLink provides development tools and run-time capabilities that reduce development and maintenance efforts, as well as increase enterprise application functionality.

TopLink lets you build high-performance applications that store persistent object-oriented data in a relational database. It successfully transforms object-oriented data into either relational data or XML elements. Using TopLink, you can integrate persistence and object-transformation into your application, while staying focused on your primary domain problem by taking advantage of an efficient, flexible, and field-proven solution. The extensive suite of development tools that TopLink provides, including Oracle TopLink Workbench, lets you quickly capture and define object-to-data source and object-to-data representation mappings in a flexible, efficient metadata format. The TopLink runtime lets your application exploit this mapping metadata with a simple session facade that provides in-depth support for data access, queries, transactions, and caching.

The following are some of the key features of TopLink:

• Nonintrusive, flexible, metadata-based architecture

• Comprehensive visual TopLink Workbench

• Advanced mapping support and flexibility (relational, object-relational, EIS, and XML)

• Object caching support

• Query flexibility

• Just-in-time reading

• Caching

• Object-level transaction support and integration

• Locking

• Multiple performance tuning options

• Architectural flexibility

For additional information about TopLink, see the TopLink page on Oracle Technology Network at http://www.oracle.com/technology/products/ias/toplink/index.html

Note: Currently, TopLink persistence manager is the default persistence manager for OC4J. It has support for EJB 2.1 and EJB 3.0 Persistence API.

The following are some of the advantages of using OC4J with the TopLink persistence manager:

• They permit concurrent access to database tables and enable the avoidance of the database resource contention (see "Avoiding Database Resource Contention").

• You can express selection criteria for an EJB 3.0 query or EJB 2.1 finder or select method using the TopLink query and expressions framework.

• You can take advantage of predefined and default finder and select methods.

• The TopLink persistence manager takes the query syntax you specify ("Understanding Query Syntax") and generates SQL native to your underlying relational database.

Migrating to the TopLink Persistence Manager

Using the TopLink migration tool, you can easily migrate an existing OC4J application that uses EJB 2.0 entity beans with the Orion persistence manager to use EJB 2.0 entity beans with the TopLink persistence manager.

You can configure OC4J to use TopLink as the default persistence manager. In 10g Release 3 (10.1.3.1), OC4J is shipped configured to use TopLink as its default persistence manager.

Note: You can only use one persistence manager for all the CMP EJB in a JAR file.

TopLink provides automated support for migrating an existing J2EE application to use TopLink as the persistence manager. In 10.1.3 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. If you upgrade your OC4J to this new release, you must migrate persistence configuration from your original orion-ejb-jar.xml file to the toplink-ejb-jar.xml file.

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 the following:

• Key Features of the TopLink Migration Tool

• Using the TopLink Migration Tool From the Command Line

• Post-Migration Changes

• Troubleshooting Your Migration

Key Features of the TopLink Migration Tool

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.

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 container-managed persistent and relationship fields.

• It builds a TopLink mapping object for every container-managed persistent and relationship field of an entity bean and migrates native persistence metadata, such as foreign key references.

• It builds a TopLink query object for each ejbFind or ejbSelect of an entity bean and migrates persistence metadata, such as customized query statements.

Table 3-1 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 does the following:

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

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

In Table 3-1, elements are identified with angle brackets See Table A-1, "Attributes of the <entity-deployment> Element" for more information.

Table 3-1 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.

^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 3-2 lists OC4J features and their TopLink equivalents configured by the TopLink migration tool.

Table 3-2 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.
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.
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
Exclusive write access on bean	Default value is false	Assume true
Insert without existence check	Supported	Supported
Update changed fields only	Supported	Supported
Force update	Invoke bean life cycle ejbStore method even though persistent fields have not changed	Supported

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

     
     

     Note: Depending on your specific installation, the ejb.jar file could be located in <ORACLE_HOME>/j2ee/home/lib/ directory instead.

     
     

   • <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 3-1 illustrates, using the appropriate arguments listed in Table 3-3.

   The usage information for the TopLink migration tool is as follows:

   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 3-1 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 3-3 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. Current working directory is the default.
-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 3-2.

Example 3-2 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.

Updating the Unknown Primary Key Class Mapping Sequence Table

TopLink supports the use of an unknown primary key class. Naturally, 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:

• Persistence Manager Property

• Session Event Listener

Persistence Manager Property After migrating your application, you may wish to customize the persistence manager 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.

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

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.

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 3-4 lists these problems and suggests possible solutions.

Table 3-4 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 no 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.