|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
 Previous |
 Next |
|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
|
Previous |
Next |
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:
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. This procedure assumes 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 Project from WebLogic 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";
};
