| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
This chapter describes how to configure Oracle TopLink for use with J2EE containers and application servers. It includes sections on the following:
For more information, see the following:
TopLink can be used with any J2EE application server.
Table 7-1 lists the application servers for which TopLink provides special EJB and CMP integration.
Table 7-1 TopLink Integration Support by Application Server Type
| Application Server Type | TopLink Integration for Application Server Version | TopLink Integration for EJB Version |
|---|---|---|
|
"Oracle Containers for J2EE (OC4J)" |
|
|
|
|
|
|
|
"IBM WebSphere Application Server" |
|
|
Footnote 1 When using OC4J and Java 1.5, TopLink supports a subset of the persistent features anticipated in the final EJB 3.0 specification. EJB 3.0 feature support is subject to change and dependent upon the contents of the final specification. For more information on EJB 3.0 support, see Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide.
This section describes concepts unique to TopLink application server integration, including the following:
To run a TopLink application within a J2EE container, your system must meet the following software requirements:
An application server or J2EE container (see Table 7-1)
XML parser (see "XML Parser Platform Configuration")
A JDBC driver configured to connect with your local database system (for more information, see your database administrator)
A Java development environment, such as:
Oracle JDeveloper
IBM WebSphere Studio Application Developer (WSAD)
Sun Java Development Kit (JDK) 1.3.1 or later. Oracle recommends using 1.4.2 (or later).
Any other Java environment that is compatible with the Sun JDK 1.3.1 or later
A command-line JVM executable (such as java.exe or jre.exe)
The TopLink run-time environment uses an XML parser to do the following:
Read and write XML configuration files (see "project.xml File" and "sessions.xml File")
Read and write TopLink Workbench project files (see "Understanding TopLink Workbench")
Perform object-to-XML transformations in EIS projects using XML records (see Chapter 53, "Understanding EIS Mappings"
Perform object-to-XML transformations in XML projects (see Chapter 62, "Understanding XML Mappings"
Application servers use an XML parser to read deployment files such as ejb-jar.xml and <J2EE container>-ejb-jar.xml (see "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 "Configuring XML Parser Platform").
You can also create your own XMLPlatform to provide access to an XML parser not currently supported by TopLink (see "Creating an XML Parser Platform").
TopLink provides the XMLPlatform instances shown in Table 7-2.
Table 7-2 Supported XML Platforms
| XMLPlatform... | Provides Access too... | Use With... |
|---|---|---|
|
|
|
Oracle Containers for J2EE (OC4J) |
|
|
|
IBM WebSphere Application Server |
Footnote 1 Default:
|
Note: To use an XML parser not listed in Table 7-2, create your own XMLPlatform (see "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 shows.
Using the oracle.toplink.platform.xml classes included in the public source files shipped with TopLink (see "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 7-2.
After creating your XMLPlatform, configure TopLink to use it (see "Configuring XML Parser Platform").
Crimson (http://xml.apache.org/crimson/) is the XML parser supplied in the Java 2 Platform, Standard Edition (J2SE) 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).
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 "Understanding Security Permissions".
If you run a TopLink-enabled application in a JVM without a nondefault SecurityManager, you do not need to set any permissions.
From the perspective of an application server, TopLink is a persistence manager. You can configure an application server to use TopLink as the default 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 J2EE application to use TopLink as the persistence manager. For more information, see the following:
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 procedure:
Install the toplink.jar file (and include it in the classpath) on each application server in the cluster to which you deploy TopLink applications.
Configure TopLink cache consistency options appropriate for your application.
For more information, see Chapter 87, "Understanding the Cache".
If you are deploying a CMP application, see also "Configuring cache-synchronization Properties".
Configure clustering on each application server.
For more information, see your application server documentation.
To integrate a TopLink application with OC4J, you must consider the following:
In addition to configuring these OC4J specific options, you must also consider the general application server integration issues in "Application Server Integration Concepts".
To enable TopLink CMP integration in OC4J, use the following procedure (this procedure assumes you have already installed TopLink):
If necessary, migrate your CMP application using the TopLink migration tool (see "Migrating OC4J Orion Persistence to OC4J TopLink Persistence").
Evaluate your choice of UnitOfWork change policy (see "Unit of Work and Change Policy").
|
Note: 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. |
Ensure that all necessary deployment descriptor files are in place (see "Creating TopLink Files for Deployment" and "Packaging a TopLink Application").
|
Note: 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. |
Optionally, consider the EJB customization options that TopLink provides (see "Configuring Miscellaneous EJB Options").
In 10g Release 3 (10.1.3.1.0), 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:
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 yourorion-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 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
||
|
Any value greater than 1 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Footnote 1 You can enable force-update after migration. For more information, see "Configuring a Descriptor With EJB 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 "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 "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 Chapter 93, "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 |
Attempt to change throws |
|
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 |
Assume |
|
Insert without existence check |
Supported |
Supported |
|
Update changed fields only |
Supported |
Supported (see "Attribute Change Tracking Policy"). |
|
Force update |
Invoke bean life cycle |
Supported |
To use the TopLink migration tool and create a new, mapped TopLink Workbench project from an OC4J application, use this procedure:
From TopLink Workbench, select File > Migrate > From OC4J 9.0.x.
Figure 7-1 Create Project from OC4J Migration Dialog Box
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. |
To use the TopLink migration tool from the command line, you must perform the following steps:
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
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.
Make a backup copy of your original XML files.
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 |
|---|---|
|
|
The system property used to turn on schema validation if |
|
|
The system property used enable generation of the TopLink Workbench project. The default value is |
|
|
The address of your local HTTP proxy host |
|
|
The port number on which your local HTTP proxy host receives HTTP requests. |
|
|
The name of the native persistence manager from which you are migrating. For OC4J, use the name |
|
|
Fully qualified path to the input directory that contains both the OC4J |
|
|
Fully qualified path to the archive file (either an EAR or JAR) that contains both the OC4J |
|
|
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. |
|
|
Ensure that permissions are set on this directory to allow the TopLink migration tool to create files and subdirectories. |
|
|
Verbose mode. Tells the TopLink migration tool to log errors and diagnostic information to the console. |
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
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:
Perform the migration as described in "Using the TopLink Migration Tool From the Command Line".
Launch the generated TopLink Workbench project file TLCmpProject.mwp.
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:
Determine the largest key value generated prior to migration.
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.
You can customize the following components of your project:
For an EJB 3.0 persistent 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 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.
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".
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:
This section describes solutions for problems you may encounter during migration, including the following:
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 |
The Verify that the |
|
There is not an |
The Verify that the |
|
|
A Remove the |
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.
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".
To integrate a TopLink application with BEA WebLogic Server, you must consider the following:
In addition to configuring these BEA WebLogic Server-specific options, you must also consider the general application server integration issues in "Application Server Integration Concepts".
To configure TopLink support for BEA WebLogic Server, do the following:
Add the following JAR files to the application server classpath:
<ORACLE_HOME>\toplink\jlib\toplink.jar
Ensure that your TopLink application defines an XML parser platform (see "XML Parser Platform Configuration").
To enable TopLink CMP integration in BEA WebLogic Server, use the following procedure (assuming you have already installed TopLink):
Locate the persistence directory, located above the installation drive and root directory of your BEA WebLogic Server executable, as follows:
| Version | Persistence Directory (above the <WebLogic_INSTALL_DIR>) |
|---|---|
| 6.1 (Service Pack 4) | \wlserver6.1\lib\persistence |
| 7.0 (Service Pack 2) | \weblogic700\server\lib\persistence |
| 8.1 | \weblogic81\server\lib\persistence |
Do one of the following:
Use a text editor to open the persistence.install file in the BEA WebLogic Server persistence directory, and add a new line that references the TopLink_CMP_Descriptor.xml file.
Replace the WebLogic persistence.install file with the TopLink persistence.install file found in the <ORACLE_HOME>\toplink\config directory.
Add the following JAR files to the application server classpath:
<ORACLE_HOME>\toplink\jlib\toplink.jar <ORACLE_HOME>\lib\xmlparserv2.jar
If necessary, migrate your CMP application using the TopLink migration tool ("Migrating BEA WebLogic Persistence to OC4J TopLink Persistence").
Ensure that all necessary deployment descriptor files are in place (see "Creating TopLink Files for Deployment" and "Packaging a TopLink Application").
Optionally, consider the EJB customization options that TopLink provides ("Configuring Miscellaneous EJB Options").
Start the container, and then start the TopLink application. Where supported, use a startup script to start the server. If you write your own startup script, ensure that the classpath includes the files listed in Step 2.
You can migrate a BEA WebLogic application that uses the default BEA WebLogic persistence manager to an Oracle Containers for J2EE (OC4J) application that uses TopLink as the persistence manager. In this release, Oracle provides a TopLink migration tool that you can use to automate this migration.
This section includes the following:
If you encounter problems during migration, see "Troubleshooting Your Migration".
After using the TopLink migration tool, you may need to make some additional changes as described in "Post-Migration Changes".
Before using the TopLink migration tool, review this section to understand how the TopLink migration tool works and to determine what BEA WebLogic persistence manager metadata is, and is not, migrated.
Input and Output
The TopLink migration tool takes the following files as input:
weblogic-ejb-jar.xml
weblogic-cmp-rdbms-jar.xml
It migrates as much BEA WebLogic-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 input BEA WebLogic 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 yourweblogic-ejb-jar.xml, weblogic-cmp-rdbms-jar.xml, and toplink-ejb-jar.xml files before using the TopLink migration tool. |
For information on configuring the weblogic-ejb-jar.xml file, see "Configuring the weblogic-ejb-jar.xml File for BEA WebLogic Server".
Migration
As it operates, the TopLink migration tool logs all errors and diagnostic output to a log file named wls_migration.log in the output directory. If you use the TopLink migration tool from TopLink Workbench, see also 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. It performs the following:
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-7 lists BEA WebLogic features and their TopLink equivalents configured by the TopLink migration tool.
Table 7-7 BEA WebLogic and TopLink Feature Comparison
| Feature | weblogic-cmp-rdbms-jar.xml | toplink-ejb-jar.xml |
|---|---|---|
|
Direct mapping |
Field mapping Table mapping |
Direct-to-field |
|
Relational mapping |
WebLogic-RDBMS relation |
One-to-one One-to-many Many-to-many |
|
Multiple tables |
Table mapping |
Supported |
|
Read-only |
Read-only: concurrency strategy |
Supported |
|
Pessimistic locking |
Enforce pessimistic concurrency on a per-bean basis |
Supported |
|
Large Objects (LOB) support |
Map the current field to one of the following:
|
Supported for Oracle BLOB only |
|
Optimistic locking |
Optimistic: concurrency strategy Verify columns: optimistic concurrency strategy |
Version Timestamp |
|
Cascade delete |
Database cascade delete |
Privately owned |
|
Sorting database dependency |
Order database operations |
unit of work |
|
Lazy loading (fetch group) |
Field group |
Not supported. Alternatively, you can manually configure the TopLink equivalent, if appropriate (see "Fetch Groups"). |
To use the TopLink migration tool and create a new, mapped TopLink Workbench project from a BEA WebLogic application, use this procedure:
From TopLink Workbench, select File > Migrate > From Weblogic Server.
Figure 7-2 Create Projects from WebLogic Server Migration Dialog Box
Continue with "Post-Migration Changes".
Use the following information to enter data in each field on the Create Project from WebLogic dialog box:
| Field | Description |
|---|---|
| From | Use these fields to specify the location of the existing BEA WebLogic files. These files may be included as part of a JAR, EAR, or individual files. |
| Individual Files | Select to convert from individual weblogic-ejb-jar.xml and weblogic-cmp-rdbms-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 this field 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. |
To use the TopLink migration tool from the command line, you must do the following:
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
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.
Make a backup copy of your original XML files.
Execute the TopLink migration tool as Example 7-4 illustrates using the appropriate arguments listed in Table 7-8.
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-4 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 -sWebLogic -iC:/mywork/in -aEmployee.ear -oC:/mywork/out -v
Table 7-8 TopLink Migration Tool Arguments
| Argument | Description |
|---|---|
|
|
The system property used to turn on schema validation if |
|
|
The system property used enable generation of the TopLink Workbench project. The default value is |
|
|
The address of your local HTTP proxy host |
|
|
The port number on which your local HTTP proxy host receives HTTP requests. |
|
|
The name of the native persistence manager from which you are migrating. For BEA WebLogic, use the name |
|
|
Fully qualified path to the input directory that contains the BEA WebLogic |
|
|
Fully qualified path to the archive file (either an EAR or JAR) that contains both the BEA WebLogic |
|
|
Tells the TopLink migration tool that the BEA WebLogic 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. |
|
|
The path to the directory into which the TopLink migration tool writes the new Ensure that permissions are set on this directory to allow the TopLink migration tool to create files and subdirectories. |
|
|
Verbose mode. Tells the TopLink migration tool to log errors and diagnostic information to the console. |
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".
If you use a security manager, specify a security policy file in the weblogic.policy file (normally located in the BEA WebLogic install directory), as follows:
-Djava.security.manager -Djava.security.policy==c:\weblogic\weblogic.policy
The BEA WebLogic 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 7-5 A Subset of a "Grant" Section from a BEA 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";
};
To integrate a TopLink application with IBM WebSphere Application Server, you must consider the following:
In addition to configuring these IBM WebSphere application server-specific options, you must also consider the general application server integration issues in "Application Server Integration Concepts".
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 4.0
Configuring Classpath for IBM WebSphere Application Server 5.0 and Later
TopLink provides CMP support for IBM WebSphere application server 4.0. To configure the classpath for this version, do the following:
Add the following JAR files to the application server classpath directory (see Table 7-9):
<ORACLE_HOME>\toplink\jlib\toplink.jar
Ensure that your TopLink application defines an XML parser platform (see "XML Parser Platform Configuration").
Table 7-9 lists the default application classpath directories for IBM container components in IBM WebSphere application server 4.0.
Table 7-9 Classpath Directories for IBM WebSphere 4.0 Container Components
| Container | Default Application Classpath |
|---|---|
|
WebSphere Application Server 4.0 (for Windows) |
|
|
WebSphere Studio Application Developer 4.0 (for Windows) |
|
TopLink provides JTA and general integration support for IBM WebSphere application server 5.0 and later. To configure the classpath for this version, do the following:
Create a shared library that contains the following Toplink JAR files and associate the shared library with the application:
<ORACLE_HOME>\toplink\jlib\toplink.jar
Ensure that your TopLink application defines an XML parser platform (see "XML Parser Platform Configuration").
To enable TopLink CMP integration in IBM WebSphere application server, use the following procedure (assuming you have already installed TopLink):
Ensure that all necessary deployment descriptor files are in place (see "Creating TopLink Files for Deployment" and "Packaging a TopLink Application").
Optionally, consider the EJB customization options that TopLink provides ("Configuring Miscellaneous EJB Options").
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".
For more information on integrating a TopLink application with an application server cluster, see "Clustering".
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 "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 "Disabling doPrivileged Operation"). In this case, you must grant TopLink all required permissions (see "Permissions Required by TopLink Features" and "Permissions Required When doPrivileged is Disabled").
|
Note: While enabling the use ofdoPriviledged 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.
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:
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 7-6 shows.
Most TopLink-enabled applications read in project.xml and sessions.xml files directly. Grant permissions to the specific files or file locations as Example 7-7 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 7-7 Permissions for Loading Deployment XML Files
permission java.io.FilePermission "${deployment.xml.home}/*.xml", "read";
For information on FilePermission settings for J2EE applications, see "J2EE Application Deployment".
If your application uses cache coordination (see "Understanding Cache Coordination"), then grant accept, connect, listen, and resolve permissions to the specific sockets used by your coordinated cache as Example 7-8 shows. This example assumes that the coordinated cache multicast port (see "Configuring a Multicast Port") is 1024.
If your TopLink-enabled application accesses a data source using a socket, then grant connect and resolve permissions for that socket as Example 7-9 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 7-9 Permissions for non-J2EE Data Source Connections
permission java.net.SocketPermission "${remote.data.source.host}:1025-", "connect, resolve";
For J2EE applications, data source socket permissions are usually handled by the application server.
If you configure your TopLink-enabled application to use java.util.logging package (see "Configuring Logging"), then grant your application control permissions as Example 7-10 shows.
If you are deploying a TopLink-enabled J2EE application, you must grant permissions for:
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"
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 "Permissions Required by TopLink Features".
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.
TopLink provides system properties that you can use to customize the following EJB options:
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 totrue 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 the EJB 2.1 specification, section 10.3.6.
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 now provides run-time support for such deferred primary key type specification.
For more information, see the EJB 2.1 specification, section 10.8.3.
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 the EJB 2.1 specification, section 10.5.6.1.
