8 Integrating TopLink with an Application Server

This chapter describes how to configure Oracle TopLink for use with Java EE containers and application servers. Although you can use Oracle TopLink with any Java EE container or application server (by using the TopLink API), TopLink provides specific integration and support for the application servers listed in this chapter.

This chapter includes the following sections:

• Introduction to the Application Server Support

• Integrating TopLink with an Application Server

• Integrating TopLink with Oracle WebLogic Server

• Integrating TopLink with Oracle Containers for Java EE (OC4J)

• Integrating TopLink with IBM WebSphere Application Server

• Integrating TopLink with Sun Application Server

• Integrating TopLink with JBoss Application Server

• Defining Security Permissions

• Configuring Miscellaneous EJB CMP Options

For more information, see the following:

• Chapter 9, "Creating TopLink Files for Deployment"

• Chapter 10, "Packaging a TopLink Application"

• Chapter 11, "Deploying a TopLink Application"

8.1 Introduction to the Application Server Support

You can use TopLink with any Java EE application server (by using the TopLink API) that meets the requirements shown in "What Are the Software Requirements".

Table 8-1 lists the application servers for which TopLink provides specific JPA, CMP 2.n, and session EJB/BMP integration.

Table 8-1 TopLink Integration Support by Application Server Type

Application Server Type	Application Server Version	JPA	CMP 2.n	(Session BeanFoot 1  and BMP
Oracle WebLogic Server	10.3
Oracle WebLogic Server	9.n
OC4J	10.1.3.n
OC4J	10.1.3
OC4J	9.0.4
OC4J	9.0.3
IBM WebSphere	6.1
SunAS	9
JBoss	4.2.0

^Footnote 1 This applies to EJB 1.n, 2.n and 3.0 session beans.

For more information, see the following:

• Section 8.3, "Integrating TopLink with Oracle WebLogic Server"

• Section 8.4, "Integrating TopLink with Oracle Containers for Java EE (OC4J)"

• Section 8.5, "Integrating TopLink with IBM WebSphere Application Server"

• Section 8.6, "Integrating TopLink with Sun Application Server"

• Section 8.7, "Integrating TopLink with JBoss Application Server"

8.2 Integrating TopLink with an Application Server

This section describes concepts unique to TopLink application server integration, including the following:

• What Are the Software Requirements

• How to Configure the XML Parser Platform

• How to Set Security Permissions

• How to Migrate the Persistence Manager

• How to Integrate Clustering

8.2.1 What Are the Software Requirements

To run a TopLink application within a Java EE container, your system must meet the following software requirements:

• An application server or Java EE container (see Table 8-1);

• XML parser (see Section 8.2.2, "How to Configure the XML Parser Platform");

• A JDBC driver configured to connect with your local database system (for more information, see your database administrator);

• A Java development environment, such as the following:

  • Oracle JDeveloper;

  • IBM WebSphere Studio Application Developer (WSAD);

  • Sun Java Development Kit (JDK) 1.5 or later;

• Any other Java environment that is compatible with the Sun JDK 1.5 or later;

• A command-line JVM executable (such as java.exe or jre.exe).

8.2.2 How to Configure the XML Parser Platform

The TopLink run-time environment uses an XML parser to do the following:

• Read and write XML configuration files (see Section 9.1.1, "project.xml File" and Section 9.1.2, "sessions.xml File");

• Read and write TopLink Workbench project files (see Section 5.1, "Introduction to TopLink Workbench");

• Perform object-to-XML transformations in EIS projects using XML records (see Chapter 77, "Introduction to EIS Mappings");

• Perform object-to-XML transformations in XML projects (see Chapter 53, "Introduction to XML Mappings");

Application servers use an XML parser to read deployment files, such as ejb-jar.xml and <Java EE container>-ejb-jar.xml files (see Chapter 9, "Creating TopLink Files for Deployment").

To avoid XML parser conflicts, you must configure your TopLink application to use the same XML parser as that used by the application server on which you deploy your application.

Internally, TopLink accesses its XML parser using an instance of oracle.toplink.platform.xml.XMLPlatform class.

You can configure TopLink to use any XML parser for which an XMLPlatform class exists (see Section 8.2.2.1, "Configuring XML Parser Platform").

You can also create your own XMLPlatform to provide access to an XML parser not currently supported by TopLink (see Section 8.2.2.2, "Creating an XML Parser Platform").

8.2.2.1 Configuring XML Parser Platform

TopLink provides the XMLPlatform instances shown in Table 8-2.

Table 8-2 Supported XML Platforms

XMLPlatform...	Provides Access to...	Use with...
oracle.toplink.platform.xml.xdk.XDKPlatformFoot 1	XDKParser: this class provides access to the Oracle XML Developer's Kit (XDK) XML parser (see http://www.oracle.com/technology/tech/xml/xdkhome.html).	See Section 8.4, "Integrating TopLink with Oracle Containers for Java EE (OC4J)"
oracle.toplink.platform.xml.jaxp.JAXPPlatform	JAXPParser: this class provides access to the Java SDK XML parser in the javax.xml.parsers package (see http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPIntro2.html).	See the following: Section 8.3, "Integrating TopLink with Oracle WebLogic Server" Section 8.5, "Integrating TopLink with IBM WebSphere Application Server"

^Footnote 1 Default.

Note:

To use an XML parser not listed in Table 8-2, create your own XMLPlatform (see Section 8.2.2.2, "Creating an XML Parser Platform").

To configure your TopLink application to use a particular instance of the XMLPlatform class, set system property toplink.xml.platform to the fully qualified name of your XMLPlatform class, as Example 8-1 shows.

Example 8-1 Configuring XML Platform

toplink.xml.platform=oracle.toplink.platform.xml.jaxp.JAXPPlatform

8.2.2.2 Creating an XML Parser Platform

Using the oracle.toplink.platform.xml classes included in the public source files shipped with TopLink (see Section 13.3, "Using Public Source"), you can create your own instance of the oracle.toplink.platform.xml.XMLPlatform class to specify an XML parser not listed in Table 8-2.

After creating your XMLPlatform, configure TopLink to use it (see Section 8.2.2.1, "Configuring XML Parser Platform").

8.2.2.3 XML Parser Limitations

Crimson (http://xml.apache.org/crimson/) is the XML parser supplied in the Java Platform, Standard Edition (Java SE) and in some JAXP reference implementations.

If you use Crimson with the JAXP API to parse XML files whose system identifier is not a fully qualified URL, then XML parsing will fail with a not valid URL exception.

Other XML parsers defer validation of the system identifier URL until it is specifically referenced.

If you are experiencing this problem, consider one of the following alternatives:

• Ensure that your XML files use a fully qualified system identifier URL.

• Use another XML parser (such as the OracleAS XML Parser for Java v2).

8.2.3 How to Set Security Permissions

By default, when you run a TopLink-enabled application in a JVM configured with a nondefault java.lang.SecurityManager, the TopLink run-time environment executes certain internal functions by executing a PrivilegedAction with java.security.AccessController method doPrivileged. This ensures that you do not need to grant many permissions to TopLink for it to perform its most common operations. You need only grant certain permissions depending on the types of optional TopLink features you use.

For more information, see Section 8.8, "Defining Security Permissions".

If you run a TopLink-enabled application in a JVM without a nondefault SecurityManager, you do not need to set any permissions.

8.2.4 How to Migrate the Persistence Manager

You can configure an application server to use TopLink as the persistence manager.

You can only use one persistence manager for all the entity beans with container-managed persistence in a JAR file.

TopLink provides automated support for migrating an existing Java EE application to use TopLink as the persistence manager. For more information, see Section 8.4.2, "How to Migrate OC4J Orion CMP Persistence to OC4J TopLink Persistence".

8.2.5 How to Integrate Clustering

Most application servers include a clustering service that you can use with your TopLink application.

To use TopLink with an application server cluster, use this general procedure:

1. Install the toplink.jar file (and include it in the classpath) on each application server in the cluster to which you deploy TopLink applications.

2. Configure TopLink cache consistency options appropriate for your application.

   For more information, see Chapter 102, "Introduction to Cache".

   If you are deploying a CMP application, see also Section 9.9.1.2, "Configuring cache-synchronization Properties".

3. Configure TopLink coordinated cache support for your application server, if available.

4. Configure clustering on each application server.

   For more information, see your application server documentation.

8.3 Integrating TopLink with Oracle WebLogic Server

To integrate a TopLink application with Oracle WebLogic Server, you must consider the following:

• How to Configure Classpath

• How to Integrate JTA

• How to Integrate JMX

• How to Integrate the Security Manager

In addition to configuring these Oracle WebLogic Server-specific options, you must also consider the general application server integration issues in Section 8.2, "Integrating TopLink with an Application Server".

8.3.1 How to Configure Classpath

There is no need for the application server classpath modifications, as TopLink works out of the box in Oracle WebLogic Server.

Note that both the TopLink library in the form of the com.oracle.toplink_*.jar file, and the EclipseLink library in the form of the org.eclipse.persistence_*.jar file, reside in the following location on the server:

<BEA_HOME>/modules/

where <BEA_HOME> is the directory in which the standalone Oracle WebLogic Server is installed.

Note:

Although not suitable for the production environment, during development time you might consider different configurations of the library files. These configuration options depend on the desired location of the libraries in your classpath tree, as well as on whether or not you want to run two different server versions. For more information, see http://wiki.eclipse.org/EclipseLink/Examples/JPA/WebLogic_Web_Tutorial#EclipseLink_JAR_location

8.3.2 How to Integrate JTA

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

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

8.3.3 How to Integrate JMX

By default, when you deploy a TopLink application to Oracle WebLogic Server, the TopLink runtime uses the EclipseLink persistence provider to deploy the following Java Management Extensions (JMX) MBean to the Oracle WebLogic Server JMX service for each session:

• org.eclipse.persistence.services.DevelopmentServices

• org.eclipse.persistence.services.RuntimeServices

For more information, see "How to Integrate JMS" section of the EclipseLink Developer's Guide at http://wiki.eclipse.org/Integrating_EclipseLink_with_an_Application_Server_%28ELUG%29#How_to_Integrate_JMX

For information on Oracle WebLogic Server JMX support, see the following documentation:

• Oracle Fusion Middleware Developing Manageable Applications With JMX for Oracle WebLogic Server

• Oracle Fusion Middleware Developing Manageable Applications With JMX for Oracle WebLogic Server

For information on JMX in general, see http://java.sun.com/docs/books/tutorial/jmx/index.html.

8.3.4 How to Integrate the Security Manager

If you use a security manager, specify a security policy file in the weblogic.policy file (usually located in the Oracle WebLogic Server install directory), as follows:

-Djava.security.manager
-Djava.security.policy==<BEA_HOME>\wlsserver_10.3\weblogic.policy

The Oracle WebLogic Server installation procedure includes a sample security policy file. You need to edit the weblogic.policy file to grant permission for TopLink to use reflection.

The following example illustrates only the permissions that TopLink requires, but most weblogic.policy files contain more permissions than are shown in this example.

Example 8-2 A Subset of a "Grant" Section from a weblogic.policy File

grant {
// "enableSubstitution" required to run the WebLogic console
permission java.io.SerializablePermission "enableSubstitution";
// "modifyThreadGroup" required to run the WebLogic server
permission java.lang.RuntimePermission "modifyThreadGroup";
// grant permission for TopLink to use reflection
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};

8.4 Integrating TopLink with Oracle Containers for Java EE (OC4J)

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

• How to Integrate CMP

• How to Migrate OC4J Orion CMP Persistence to OC4J TopLink Persistence

• How to Integrate JTA

• How to Integrate with Oracle Application Server Manageability and Diagnosability

In addition to configuring these OC4J-specific options, you must also consider the general application server integration issues in Section 8.2, "Integrating TopLink with an Application Server".

8.4.1 How to Integrate CMP

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 Section 8.4.2, "How to Migrate OC4J Orion CMP Persistence to OC4J TopLink Persistence").

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

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

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

8.4.2 How to Migrate OC4J Orion CMP Persistence to OC4J TopLink Persistence

If you upgrade OC4J 9.0.4 or earlier to 11g Release 1 (11.1.1), you must migrate persistence configuration from your original orion-ejb-jar.xml file to the toplink-ejb-jar.xml file.

In 11g Release 1 (11.1.1), 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 Section 8.4.2.4, "Performing Post-Migration Changes".

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

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

• What You May Need to Know About Migrating OC4J Orion Persistence to OC4J TopLink Persistence

• Using the TopLink Migration Tool from TopLink Workbench

• Using the TopLink Migration Tool from the Command Line

• Performing Post-Migration Changes

• Troubleshooting Your Migration

Note:

You can also use the TopLink migration tool from Oracle JDeveloper.

8.4.2.1 What You May Need to Know About Migrating OC4J Orion Persistence to OC4J TopLink Persistence

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 8-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 8-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 8-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
trueFoot 1
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 2
shared
<finder-method>
<persistence-type>Foot 3

^Footnote 1  You can enable force-update after migration. For more information, see Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information".

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

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

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

Table 8-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 Section 16.2.4, "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 Chapter 108, "Introduction to 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 Section 119.18, "Configuring a Descriptor with EJB CMP and BMP 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 Section 113.2.3.3, "Attribute Change Tracking Policy").
Force update	Invoke bean life cycle ejbStore method even though persistent fields have not changed	Supported

8.4.2.2 Using the TopLink Migration Tool from TopLink Workbench

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

   Figure 8-1 Create TopLink Workbench Projects from OC4J Migration Dialog Box

   
   Description of "Figure 8-1 Create TopLink Workbench Projects from OC4J Migration Dialog Box"
   
   

Use the following information to enter data in each field of the Create TopLink Workbench Projects from OC4J Migration 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.

8.4.2.3 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>/modules/oracle.toplink_11.1.1/jlib/antlr.jar

   • <TOPLINK_HOME>/jlib/toplink.jar

   • <TOPLINK_HOME>/utils/workbench/jlib/cmpmigrator.jar

   • <TOPLINK_HOME>/utils/workbench/jlib/toplinkmw.jar

   • <TOPLINK_HOME>/utils/workbench/jlib/tlmwcore.jar

   • <TOPLINK_HOME>/jlib

   • <TOPLINK_HOME>/modules/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 8-3 illustrates, using the appropriate arguments listed in Table 8-5.

   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 Section 8.4.2.5, "Troubleshooting Your Migration".

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

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

• Customizing a Project

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 8-4.

Example 8-4 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 Section 8.4.2.3, "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 Section 5.5.1.1, "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 Section 8.9.2, "How to Configure EJB CMP 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.

Customizing a Project

You can customize the following components of your project:

• EJB 2.1 Persistence Manager Customization

• Session Event Listener

8.4.2.4.1 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 Section 9.9.1, "How to Configure persistence-manager Entries".

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

• Section 87.2.3, "Session Customization"

• Section 87.2.5, "Managing Session Events with the Session Event Manager"

• Section 89.10, "Configuring Session Event Listeners"

8.4.2.5 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 8-6 lists these problems and suggests possible solutions.

Table 8-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.
The entity (ENTITY_NAME) in orion-ejb-jar.xml is not mapped as no table is specified. You need to provide the completely mapped orion-ejb-jar.xml to the migration tool. You can obtain the completely mapped orion-ejb-jar.xml from the application-deployment directory after deploying the application.	An entity is not mapped to database table. Before migration, confirm that you map all CMP entities in your application to one or more database tables in the ejb-jar.xml file, the orion-ejb-jar.xml file, or a combination of both.

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.

8.4.3 How to Integrate JTA

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

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

8.4.4 How to Integrate with Oracle Application Server Manageability and Diagnosability

Oracle recommends that you consider TopLink support for Oracle Application Server Manageability and Diagnosability to simplify application management and problem diagnosis.

For more information, see Section A.1, "TopLink Support for Oracle Application Server Manageability and Diagnosability".

8.5 Integrating TopLink with IBM WebSphere Application Server

To integrate a TopLink application with IBM WebSphere Application Server, you must consider the following:

• How to Configure Classpath

• How to Configure Class Loader Order

• How to Integrate JTA

In addition to configuring these IBM WebSphere application server-specific options, you must also consider the general application server integration issues in Section 8.2, "Integrating TopLink with an Application Server".

8.5.1 How to Configure Classpath

You configure the IBM WebSphere application server classpath differently depending on what version of this server you are using:

• Configuring Classpath for IBM WebSphere Application Server 6.1 and Later

8.5.1.1 Configuring Classpath for IBM WebSphere Application Server 6.1 and Later

TopLink provides JTA and general integration support for IBM WebSphere application server 6.1 and later. To configure the classpath for this version, do the following:

1. Create a shared library that contains the following Toplink JAR files and associate the shared library with the application:

   <TOPLINK_HOME>\jlib\toplink.jar
   

2. Ensure that your TopLink application defines an XML parser platform (see Section 8.2.2, "How to Configure the XML Parser Platform").

8.5.2 How to Configure Class Loader Order

If you are deploying a TopLink enabled application that uses TopLink sessions.xml or XML project deployment, you must use the WebSphere Application Server Administrative Console to set Class loader order to Class loaded with application class loader first.

8.5.3 How to Integrate JTA

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

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

8.5.4 How to Configure Clustering on IBM WebSphere Application Server

For information on integrating a TopLink application with an application server cluster, see Section 8.2.5, "How to Integrate Clustering".

8.6 Integrating TopLink with Sun Application Server

To integrate a TopLink application with Sun Application Server (SunAS), you must consider the following:

• How to Configure Classpath

• How to Integrate JTA

In addition to configuring these SunAS-specific options, you must also consider the general application server integration issues in Section 8.2, "Integrating TopLink with an Application Server".

8.6.1 How to Configure Classpath

To configure TopLink support for SunAS, do the following:

1. Add the following JAR files to the application server classpath:

   <TOPLINK_HOME>\jlib\toplink.jar
   

2. Ensure that your TopLink application defines an XML parser platform (see Section 8.2.2, "How to Configure the XML Parser Platform").

8.6.2 How to Integrate JTA

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

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

8.7 Integrating TopLink with JBoss Application Server

To integrate a TopLink application with JBoss Application Server, you must consider the following:

• How to Configure Classpath

• How to Integrate JTA

In addition to configuring these JBoss-specific options, you must also consider the general application server integration issues in Section 8.2, "Integrating TopLink with an Application Server".

8.7.1 How to Configure Classpath

To configure TopLink support for JBoss, do the following:

1. Add the following JAR files to the application server classpath:

   <TOPLINK_HOME>\jlib\toplink.jar
   

2. Ensure that your TopLink application defines an XML parser platform (see Section 8.2.2, "How to Configure the XML Parser Platform").

8.7.2 How to Integrate JTA

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

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

8.7.3 How to Configure JPA Application Deployment to JBoss 4.2 Application Server

For JPA applications, to enable the container to manage entities, statically weave the entities and reference JBoss as the target server in the persistence.xml file.Perform the following deployment changes:

1. If weaving is required, statically weave the entities before EAR packaging. Use either the command-line weaver or the weaving Ant task (see "How to Configure Static Weaving for JPA Entities" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Configure_Static_Weaving_for_JPA_Entities).

2. Ensure that the eclipselink.target-server property (see "Using EclipseLink JPA Extensions for Session, Target Database and Target Application Server" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#Using_EclipseLink_JPA_Extensions_for_Session.2C_Target_Database_and_Target_Application_Server) is set in the persistence.xml file of all persistence units deployed to the JBoss container:

   <property name="eclipselink.target-server" value="JBoss"/>
   

   Otherwise, even though the container-managed entities are predeployed, they will not be managed at run time.

For more information, see "How to Deploy an Application to Generic Java EE 5 Application Servers" section of EclipseLink Developer's Guide at http://wiki.eclipse.org/Packaging_and_Deploying_EclipseLink_JPA_Applications_%28ELUG%29#How_to_Deploy_an_Application_to_Generic_Java_EE_5_Application_Servers.

8.8 Defining Security Permissions

By default, when you run a TopLink-enabled application in a JVM configured with a nondefault java.lang.SecurityManager, the TopLink run time executes certain internal functions by executing a PrivilegedAction with java.security.AccessController method doPrivileged. This ensures that you do not need to grant many permissions to TopLink for it to perform its most common operations. You need only grant certain permissions depending on the types of optional TopLink features you use (see Section 8.8.1, "How to Define Permissions Required by TopLink Features").

While using doPrivileged method provides enhanced security, it will severely impact overall performance. Alternatively, you can configure TopLink to disable the use of doPrivileged method even when a nondefault SecurityManager is present (see Section 8.8.3, "How to Disable doPrivileged Operation"). In this case, you must grant TopLink all required permissions (see Section 8.8.1, "How to Define Permissions Required by TopLink Features" and Section 8.8.2, "How to Define Permissions Required when doPrivileged Is Disabled").

Note:

While enabling the use of doPriviledged method enhances TopLink application security, it does not guarantee that secure code cannot be called by application code in ways that the system did not intend. You must consider the use of doPriviledged method within the context of your overall application security strategy. For more information, see http://java.sun.com/security/index.jsp.

If you run a TopLink-enabled application in a JVM without a nondefault SecurityManager, you do not need to grant any permissions.

8.8.1 How to Define Permissions Required by TopLink Features

When you run a TopLink-enabled application in a JVM configured with a nondefault java.lang.SecurityManager and doPrivileged operation is enabled, you may need to grant additional permissions if your application requires any of the following:

• Defining System Properties

• Loading project.xml or sessions.xml Files

• Defining Cache Coordination

• Accessing a Data Source by Port

• Logging with java.util.logging

• Granting Permissions for Java EE Application Deployment

8.8.1.1 Defining System Properties

By default, a TopLink-enabled application requires access to the system properties granted in the default <JAVA_HOME>/lib/security/java.policy file. If your application requires access to other platform-specific, environment, or custom properties, then grant further PropertyPermission permissions, as Example 8-5 shows.

Example 8-5 Permissions for System Properties

permission java.util.PropertyPermission "my.property", "read";

8.8.1.2 Loading project.xml or sessions.xml Files

Most TopLink-enabled applications read in project.xml and sessions.xml files directly. Grant permissions to the specific files or file locations, as Example 8-6 shows. This example assumes that both project.xml and sessions.xml files are located in the same directory (given by application-specific system property deployment.xml.home). Alternatively, you can specify a separate FilePermission for each file.

Example 8-6 Permissions for Loading Deployment XML Files

permission java.io.FilePermission "${deployment.xml.home}/*.xml", "read";

For information on FilePermission settings for Java EE applications, see Section 8.8.1.6, "Granting Permissions for Java EE Application Deployment".

8.8.1.3 Defining Cache Coordination

If your application uses cache coordination (see Section 102.3, "Cache Coordination"), then grant accept, connect, listen, and resolve permissions to the specific sockets used by your coordinated cache, as Example 8-7 shows. This example assumes that the coordinated cache multicast port (see Section 103.5, "Configuring a Multicast Port") is 1024.

Example 8-7 Permissions for Cache Coordination

permission java.net.SocketPermission "localhost:1024-", "accept, connect, listen, resolve";

8.8.1.4 Accessing a Data Source by Port

If your TopLink-enabled application accesses a data source using a socket, then grant connect and resolve permissions for that socket, as Example 8-8 shows. This example assumes that the host name (or IP address) of the remote host that provides the data source (such as a relational database server host) is given by application-specific system property remote.data.source.host and that this host accepts data source connections on port 1025.

Example 8-8 Permissions for non-Java EE Data Source Connections

permission java.net.SocketPermission "${remote.data.source.host}:1025-", "connect, resolve";

For Java EE applications, data source socket permissions are usually handled by the application server.

8.8.1.5 Logging with java.util.logging

If you configure your TopLink-enabled application to use java.util.logging package (see Section 89.4, "Configuring Logging"), then grant your application control permissions, as Example 8-9 shows.

Example 8-9 Permissions for java.util.logging

permission java.util.logging.LoggingPermission "control"

8.8.1.6 Granting Permissions for Java EE Application Deployment

If you are deploying a TopLink-enabled Java EE application, you must grant permissions for the following:

• The toplink.jar file. For example:

  grant codeBase "file:<TOPLINK_HOME>/jlib/toplink.jar" {
      permission java.security.AllPermission;
  };
  

If you are using an XML platform, you must also grant the following permissions:

• The toplink.xml.platform system property. For Example:

  permission java.util.PropertyPermission "toplink.xml.platform", "read"
  

8.8.2 How to Define Permissions Required when doPrivileged Is Disabled

If you disable doPrivileged operation when you run a TopLink-enabled application in a JVM configured with a nondefault java.lang.SecurityManager, you must grant the following permissions:

• java.lang.reflect.RelectPermission "suppressAccessChecks"

• java.lang.RuntimePermission "accessDeclaredMembers"

• java.lang.RuntimePermission "getClassLoader"

You may also have to grant additional permissions depending on the TopLink features your application uses. For more information, see Section 8.8.1, "How to Define Permissions Required by TopLink Features".

8.8.3 How to Disable doPrivileged Operation

To disable doPrivileged operation when you run a TopLink-enabled application in a JVM configured with a nondefault java.lang.SecurityManager, set system property oracle.j2ee.toplink.security.usedoprivileged to false. If you are using OC4J, set system property oracle.j2ee.security.usedoprivileged to false.

To enable doPrivileged operation, set these system properties to true.

8.9 Configuring Miscellaneous EJB CMP Options

TopLink provides system properties that you can use to customize the following EJB CMP options:

• Setter Parameter Type Checking (see Section 8.9.1, "How to Configure EJB CMP Setter Parameter Type Checking")

• Unknown Primary Key Class Support (see Section 8.9.2, "How to Configure EJB CMP Unknown Primary Key Class Support")

• Single-Object Finder Return Type Checking (see Section 8.9.3, "How to Configure EJB CMP Single-Object Finder Return Type Checking")

8.9.1 How to Configure EJB CMP Setter Parameter Type Checking

To make TopLink verify that the parameters to one-to-one and one-to-many relationship setters are of the same type as the corresponding CMR field, set system property toplink.cts.collection.checkParameters to a value of true (not case sensitive). If the setters are not the same type, then TopLink throws a java.lang.IllegalArgumentException.

Note:

Setting this property to true will affect performance. Use this setting only if necessary.

If you set the property to false (the default value), TopLink does not make this verification. In this case, it is up to your application to make sure the parameters are of the correct type.

For more information, see Section 10.3.6 of the EJB 2.1 specification.

8.9.2 How to Configure EJB CMP Unknown Primary Key Class Support

In special situations, you may choose not to specify the primary key class or the primary key fields for an entity bean with container-managed persistence. For example, 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, you may choose to defer primary key type specification.

If this is the case, you must declare the type of the argument of the findByPrimaryKey method as java.lang.Object and you must also specify the primary key class (prim-key-class) in the deployment descriptor (ejb-jar.xml) as java.lang.Object.

TopLink provides run-time support for such deferred primary key type specification.

For more information, see Section 10.8.3 of the EJB 2.1 specification.

8.9.3 How to Configure EJB CMP Single-Object Finder Return Type Checking

By setting system property toplink.cts.checkMultipleRows to true, you can configure TopLink to throw a javax.ejb.FinderException if multiple beans are returned from a single-object finder method.For more information, see Section 10.5.6.1 of the EJB 2.1 specification.