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:

IBM WebSphere 4.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
- IBM WebSphere Studio Application Developer (WASD)
- Sun JDK 1.2 or higher (note that TopLink ships with JDK 1.3 JAR files that are compatible with the JDK 1.2)
- IBM VisualAge for Java
- 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)

A note about the WebSphere Module Visibility setting

TopLink only supports the WebSphere APPLICATION mode and MODULE mode for module visibility. This is because of the way WebSphere Application Server defines its class loader isolation mode for each setting.

A J2EE application (EAR file) can have multiple EJB modules (EJB JAR files). TopLink Container-Managed Persistence is designed to load one toplink-ejb-jar.xml per EJB module (EJB JAR). If the module visibility mode is not set to MODULE, an EJB module could load the wrong toplink-ejb-jar.xml from the other EJB module. TopLink CMP also supports the application with the restriction that each application can only have one EJB JAR file. Again, this is due to how class loader is designed for this mode. For more information about module visibility in WebSphere, consult the WebSphere documentation.

WebSphere 4.0 document from the link above indicates, "Portable J2EE applications should be written with Module-level visibility." Developer should keep this in mind when developing application.

Table 3-1 TopLink support of server-installable applications on server vs. module visibility mode

Installable Applications on Server	Module Visibility Mode
Installable Applications on Server	Application	Module	Compatibility	Server
Multiple applications in which each application can have multiple TopLink EJB modules	No	Yes	No	No
Multiple applications in which each application has single TopLink EJB module	Yes	Yes	No	No
Single application has multiple TopLink EJB modules	No	Yes	No	No
Single application has Single TopLink EJB module	Yes	Yes	Yes	Yes

Configuring TopLink CMP

The following procedures configure 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 steps required for preparing a system for TopLink depends on the type of system you are running:

To prepare a Windows-based system, you must copy some JARs from the TopLink installation to your WebSphere installation (see ""Installing TopLink JARs to a WebSphere Server", next) and then modify your PATH and CLASSPATH (see "To Modify the PATH and CLASSPATH for running the Deploy tool").
To prepare a non-Windows environment, you must modify your PATH and CLASSPATH.

Installing TopLink JARs to a WebSphere Server

Create a directory structure in the WebSphere installation directory as follows:

<WEBSPHERE_INSTALL_DIR>\lib\app

If you are using WebSphere, (the default installation directory is C:\WebSphere\AppServer) ; if you are using WSAD, the default directory is C:\Program Files\ibm\Application Developer\plugins\com.ibm.etools.websphere.runtime.
Copy the following JAR files to the directory you created:
- <INSTALL_DIR>\core\lib\toplink.jar
- <INSTALL_DIR>\core\lib\xerces.jar
- <INSTALL_DIR>\core\lib\tl_wasx.jar
- <INSTALL_DIR>\hsql\lib\hsql_ds.jar
- <INSTALL_DIR>\hsql\lib\hsqldb.jar
where <INSTALL_DIR> is the directory into which you installed TopLink (C:\{ORACLE_HOME}\toplink if you installed to the default directory).
Check the PATH and, if necessary, modify it to include <JAVADIR>\bin where <JAVADIR> is the installation drive and directory for your Java Virtual Machine (VM) executable. This path must be the first one listed in the PATH environment variable, before any other paths.
Check and if necessary, modify the CLASSPATH environment variable.

Note:
The CLASS and CLASSPATH commands must appear in your autoexec.bat file. If either of them is missing, you must add them manually.

To Modify the PATH and CLASSPATH for running the Deploy tool

If you have not already done so, edit your PATH to include <JAVADIR>\bin\; as the first entry in the PATH list.
Edit the CLASSPATH to include all of the following:
```
<INSTALL_DIR>\core\lib\toplink.jar;<INSTALL_DIR>\core\lib\xerces.jar;
<INSTALL_DIR>\was_cmp\lib\tl_wasx.jar;<INSTALL_DIR>\hsql\lib\hsqlds.jar;
<INSTALL_DIR>\hsql\lib\hsqldb.jar
```
where <INSTALL_DIR> is the directory into which you installed TopLink (C:\{ORACLE_HOME}\toplink if you installed to the default directory).

Testing your TopLink installation

Compile and execute the JDBCConnectTest class in the oracle.toplink.tutorials.gettingstarted package.

To test the installation, do one of the following:

Run the JDBCConnectTest class from the command line, passing appropriate database login information as parameters as follows:
```
java oracle.toplink.tutorials.gettingstarted.JDBCConnectTest <username>
<password> <database url> <jdbc driver class>
```
or

Modify the main() method to contain appropriate database login information as parameters, then recompile and execute the class. For example:

public static void main(String[] args) {
   JDBCConnectTest test = new
   JDBCConnectTest();
   if (args.length > 0) {
      test.connect(args[0], args[1], args[2], args[3]);
   }
   // Add your login information below
   else {
      /*This test uses the WebSphere sql server driver. Any compliant jdbc
      driver can be used. Do not use WebSphere pool devices for this test.*/
      test.connect("<user>","<password>",
      "WebSphere.jdbc.mssqlserver4.Driver",
      "jdbc:WebSphere:mssqlserver4:myserver:1433");
   }
}

If the code does not run successfully, check the error message and ensure that all of your settings are correct. You may also need to consult Oracle9iAS TopLink Troubleshooting.

Testing TopLink deployment tool

With the Java VM PATH and CLASSPATH properly configured, run the following classes to test the deployment tool:

java oracle.toplink.ejb.cmp.was.deploy.Deploy

java oracle.toplink.ejb.cmp.was.deploy.EJBDeployFrame(GUI tool)

Other ways to test the installation:

Run the deploy tool by clicking Start > Programs > Oracle9iAS TopLink > Tools > Deploy Tool for WebSphere Server.
Execute the script deployTool.cmd or deployTool.sh to invoke the GUI tool:
- <INSTALL_DIR>\was_cmp\deployTool.cmd (for Windows)
- <INSTALL_DIR>/was_cmp/deployTool.sh (for Unix)

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 8, "The Single Bean Example Application". .

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

Running the Server with TopLink

Start the server as described in the WebSphere documentation. Refer to the WebSphere 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 WebSphere, contact IBM support.

See Oracle9iAS TopLink Troubleshooting for more information.