Skip Headers

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

Previous | Next |

# BEA WebLogic Server

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

- Classpath

- CMP Integration

- Migrating BEA WebLogic Persistence to OC4J TopLink Persistence

- JTA Integration

- Security Manager

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"

## Classpath

To configure TopLink support for BEA WebLogic Server:

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

       <ORACLE_HOME>\toplink\jlib\toplink.jar

2. Ensure that your TopLink application defines an XML parser platform (see "XML Parser Platform Configuration").

## CMP Integration

To enable TopLink CMP integration in BEA WebLogic Server, use the following procedure. This procedure assumes you have already installed TopLink.

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

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

       <ORACLE_HOME>\toplink\jlib\toplink.jar
       <ORACLE_HOME>\lib\xmlparserv2.jar

3. If necessary, migrate your CMP application using the TopLink migration tool ("Migrating BEA WebLogic Persistence to OC4J TopLink Persistence").

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

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

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

## Migrating BEA WebLogic Persistence to OC4J TopLink Persistence

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:

- Overview

- Using the TopLink Migration Tool From TopLink Workbench

- Using the TopLink Migration Tool From the Command Line

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

### Overview

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 your `weblogic-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: `CLOB` or `BLOB` in an Oracle database `LongString` or `SybaseBinary` in a Sybase database | 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").

### Using the TopLink Migration Tool From TopLink Workbench

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

1. From TopLink Workbench, select File > Migrate > From Weblogic Server.

   Figure 7-2 Create Project from WebLogic Dialog Box

   Description of "Figure 7-2 Create Project from WebLogic Dialog Box"

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

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

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

1. Ensure that the following is in your classpath:

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

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

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

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

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

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

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

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

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

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

4. Execute the TopLink migration tool as Example 7-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
--- | ---
`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 BEA WebLogic, use the name `WebLogic`.
`-i <input-directory>` | Fully qualified path to the input directory that contains the BEA WebLogic `weblogic-ejb-jar.xml` and `weblogic-cmp-rdbms-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 BEA WebLogic `weblogic-ejb-jar.xml` and `weblogic-cmp-rdbms-jar.xml` files to migrate.
`-x` | 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.
`-o <output-directory` | 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.

## JTA Integration

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

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

## Security Manager

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";
    };