3
Configuring TopLink Container-Managed Persistence

This chapter describes the configuration and testing of TopLink Container-Managed Persistence. Please refer to Oracle9iAS TopLink Getting Started for installation information.

Software requirements

TopLink Container-Managed Persistence requires:

• BEA WebLogic Server 6.1 (Service Pack 3) or 7.0

• A JDBC driver that is configured to connect with your local database system (see your database administrator)

• A Java development environment that is compatible with the JDBC API, such as:
  • Oracle JDeveloper

  • Sun JDK 1.3 or higher

  • Any other Java environment that is compatible with the Sun JDK 1.3 or higher

• A command-line Java virtual machine (VM) executable (such as java.exe or jre.exe)

Configuring TopLink CMP

This procedure configures TopLink Container-Managed Persistence Foundation Library. This procedure assumes you have already installed TopLink Container-Managed Persistence.

Notes: If you are running under Windows NT, make sure you have administrator privileges. Also, make sure you modify the System Variables, not the User Variables. Java package names are case-sensitive. If you are installing under a 32-bit Windows environment, ensure the case sensitivity is enabled.

The TopLink class library is certified 100% pure Java and can be run on any JDK 1.2 or higher Java VM/platform.

To configure TopLink:

1. Locate the WebLogic persistence directory, which is located above the installation drive and root directory of your BEA WebLogic executable, as follows:

   WebLogic Version	Persistence directory (above <WebLogLogicINSTALL_DIR>)
   6.1 (service Pack 3)	\wlserver6.1\lib\persistence
   7.0	\weblogic700\server\lib\persistence

   Under Windows, if BEA WebLogic Server is already installed, the TopLink installer automatically copies a file called persistence.install to the WebLogic persistence directory.

   If BEA WebLogic Server is not yet installed, or if you are installing TopLink in a non-Windows environment, then you must either:

   • Open the persistence directory using a text editor and add a new line to the persistence.install file referencing TopLink_CMP_Descriptor.xml.

   or

   • Replace your existing persistence.install file with the new persistence.install file found in the <INSTALL_DIR>\wls_cmp folder.

     Note: Refer to <INSTALL_DIR>\Index.html for the most recent installation notes. If you installed to the default directory, <INSTALL_DIR> is C:\{ORACLE_HOME}\toplink.

2. If you are writing your own start script, you must ensure that the CLASSPATH includes all of the following

   <INSTALL_DIR>\core\lib\toplink.jar; <INSTALL_DIR>\core\lib\xerces.jar;
   <INSTALL_DIR>\wls_cmp\lib\tl_wlsx.jar;
   

   where <INSTALL_DIR> is the directory into which you installed TopLink (C:\{ORACLE_HOME}\toplink if you installed to the default directory).

   Note: When editing the CLASSPATH, ensure that weblogic.jar and weblogic_sp.jar are placed before the TopLink JAR files in the CLASSPATH statement.

Testing TopLink Container-Managed Persistence with entity beans

To test TopLink Container-Managed Persistence with entity beans, run the Single Bean example documented in Chapter 9, "The EJB 2.0 Single Bean Example Application". For detailed instructions on how to set up and run this example, see Chapter 9, "The EJB 2.0 Single Bean Example Application".

When the TopLink Mapping Workbench, and the Single Bean example all run successfully, your TopLink installation is complete.

Running the BEA WebLogic Server with TopLink

Start the server as described in the WebLogic documentation. The most reliable way to start a server is to create a startup script. Refer to the BEA WebLogic documentation for more information on class loader and classpath issues. Once the server is running, start the TopLink CMP application.

Note: If you encounter problems running BEA WebLogic Server, contact BEA's WebLogic support.

TopLink Container-Managed Persistence includes a sample domain used to deploy and run the example application. This start script is available in <INSTALL_DIR>\examples\ under

• wls6.1\Server\config\TopLink_Domain for WebLogic 6.1 (service Pack 3)

• wls7.0\Server\config\TopLink_Domain for WebLogic 7.0

If you write your own start script, ensure that the CLASSPATH includes all of the following

<INSTALL_DIR>\core\lib\toplink.jar; <INSTALL_DIR>\core\lib\xerces.jar;
<INSTALL_DIR>\wls_cmp\lib\tl_wlsx.jar; 

where <INSTALL_DIR> is the directory into which you installed TopLink (C:\{ORACLE_HOME}\toplink if you installed to the default directory).

Note: Ensure that weblogic.jar and weblogic_sp.jar are placed before the TopLink JAR files in the CLASSPATH.

If a security manager is used, you must specify a security policy file.

-Djava.security.manager
-Djava.security.policy==c:\weblogic\weblogic.policy

A sample security policy file is supplied with the BEA WebLogic installation procedure.

Note that you will have to edit the weblogic.policy file (normally located in the BEA WebLogic install directory) to grant permission for TopLink to use reflection. To do this, add the following line to the file in the general "grant" section.:

permission java.lang.reflect.ReflectPermission "suppressAccessChecks";

A subset of a "grant" section taken from a weblogic.policy file

grant
// Permission "enableSubstitution" needed to run the WebLogic console
permission java.io.SerializablePermission "enableSubstitution";
// Permission "modifyThreadGroup" required to run the WebLogic Server
permission java.lang.RuntimePermission "modifyThreadGroup";
permission java.lang.RuntimePermission
//... bulk of permissions not shown ...
//required for toplink
   permission java.lang.reflect.ReflectPermission
   suppressAccessChecks";
};

Configuration troubleshooting

If after successfully installing TopLink, you encounter problems running TopLink, one or more of the following suggestions may help resolve the problem:

• Ensure that the persistence.install file in the WebLogic installation contains the required TopLink_CMP_Descriptor.xml entry

• Some database servers (such as DB2) require an extra Windows NT service to be running for JDBC connections. If your server has been rebooted, this service may not have been restarted.

• If the BEA WebLogic Server is installed to a directory other than the default directory, ensure that the weblogic.policy file is edited to reflect this.

See Oracle9iAS TopLink Troubleshooting for more information.