B
Configuring OracleAS TopLink for J2EE Containers

This chapter describes how to configure Oracle Application Server TopLink for use with J2EE containers and application servers. It includes sections on:

• Software Requirements

• Non-CMP Configuration

• OracleAS TopLink CMP Configuration

• OracleAS TopLink in a BEA WebLogic Cluster

• For installation information, see "Installing and Configuring OracleAS TopLink," in the Oracle Application Server TopLink Getting Started Guide.

Software Requirements

To run an OracleAS TopLink application within a J2EE container, your system must meet the following software requirements:

• An application server or J2EE container such as:
  • Oracle Application Server Containers for J2EE

  • IBM WebSphere Application Server 4.0

  • BEA WebLogic Application Server 6.1 (Service Pack 4), 7.0 (Service Pack 2) or 8.1.

• 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 (WASD)

  • Sun Java Development Kit (JDK) 1.3.1 or higher

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

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

Non-CMP Configuration

OracleAS TopLink supports several architectures that leverage a J2EE container. To enable OracleAS TopLink in these architectures configure the following:

Class Path

Place the OracleAS TopLink JARs on the application server class path. Class path configuration is container-specific. For more information, see:

• Oracle Application Server Containers for J2EE Support

• IBM WebSphere Application Server 4.0

• IBM WebSphere Application Server 5.0

• BEA WebLogic Application Server (6.1, 7.0 or 8.1)

Datasource

OracleAS TopLink applications that run in a J2EE container often use a J2EE Datasource to access JDBC connections. To leverage a J2EE datasource, configure a datasource with the server's configuration tools, and specify the name of the datasource in the sessions.xml file, as follows:

    <login>
        <datasource>java:comp/env/jdbc/myJTADataSource</datasource>
        <uses-external-connection-pool>true</uses-external-connection-pool>
        ...
    </login> 

JTA integration

The OracleAS TopLink Unit of Work uses the Java Transaction API (JTA) to participate in global transactions. Configure OracleAS TopLink JTA support in the sessions.xml file as follows:

    <login>
        ...
        <uses-external-transaction-controller>true</uses-external-transaction-controller>
    </login>
    <external-transaction-controller-class>oracle.toplink.jts.oracle9i.Oracle9iJTSExternal
TransactionController </external-transaction-controller-class>

OracleAS TopLink support for external transaction controllers requires a J2EE datasource. OracleAS TopLink provides several container-specific external transaction controllers, as well as a generic controller.

For more information, see "J2EE Integration".

Oracle Application Server Containers for J2EE Support

To configure OracleAS TopLink support for Oracle Application Server Containers for J2EE, include the following OracleAS TopLink JARS on the Oracle Application Server Containers for J2EE class path:

<ORACLE_HOME>\toplink\jlib\toplink.jar
<ORACLE_HOME>\toplink\jlib\antlr.jar

For example, add the following code to the Oracle Application Server Containers for J2EE application.xml file:

<library path="/OraHome1/toplink/jlib/toplink.jar" />
<library path="/OraHome1/toplink/jlib/antlr.jar" />

Substitute your <ORACLE_HOME> directory for OraHome1.

IBM WebSphere Application Server 4.0

OracleAS TopLink provides support for IBM WebSphere Application Server 4.0. To configure this support for IBM WebSphere Application Server, copy the following OracleAS TopLink JARs to the application server class path directory:

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

Table B-1 lists the default application class path directories for IBM container components.

Table B-1 Class Path Directories for IBM Container Components

Container	Default Application Class Path
WebSphere Application Server 4.0 (for Windows)	\WebSphere\AppServer\lib\app
WebSphere Studio Application Developer 4.0 (for Windows)	\Program Files\ibm\Application Developer\plugins\com.ibm.etools.websphere.runtime\lib\app

Configuring IBM WebSphere Module Visibility Setting

Because of the way the WebSphere defines its class loader isolation mode, OracleAS TopLink supports only the APPLICATION and MODULE modes for module visibility.

Module Mode

A J2EE application (EAR file) can have multiple EJB modules (EJB JAR files). OracleAS TopLink CMP loads one toplink-ejb-jar.xml per EJB module (EJB JAR). If you do not set the loader isolation mode to MODULE, an EJB module can load the incorrect toplink-ejb-jar.xml from another EJB module.

Application Mode

OracleAS TopLink supports class loader isolation APPLICATION mode. However, each application must have only one EJB JAR file.

For more information about the module visibility in IBM WebSphere, see the IBM WebSphere documentation.

Table B-2 lists the application and module modes OracleAS TopLink supports.

Table B-2 OracleAS TopLink Support of Server-Installable Applications on Server Versus Module Visibility Mode

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

IBM WebSphere Application Server 5.0

To enable OracleAS TopLink support for IBM WebSphere Application Server 5.0, configure the following four elements for WebSphere at the Enterprise Application level:

Creating a Shared Library

Create a shared library that contains the following Toplink JARS and associate the shared library with the application:

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

Classloader Mode

Set the application Classloader Mode to PARENT_LAST. Note that you can also configure the Classloader at the Server level.

For more information, see the IBM WebSphere 5.0 documentation.

Application Classloader Policy

Set the Application Classloader Policy on the application server to Multiple.

For more information, see the IBM WebSphere 5.0 documentation.

A WAS 5.0 JTA Integration Class

For applications that require JTA integration, specify the external transaction controller in the OracleAS TopLink sessions.xml file. To enable the WebSphere 5.0 external transaction controller, add the following line to the sessions.xml file:

<external-transaction-controller-class>oracle.toplink.jts.was.
JTSExternalTransactionController_5_0</external-transaction-controller-class>

For more information, see "External Transaction Controllers".

BEA WebLogic Application Server (6.1, 7.0 or 8.1)

OracleAS TopLink provides support for BEA WebLogic Application Server 6.1, 7.0 and 8.1. This support requires manual configuration, and includes a sample domain and the ability to use a security manager with BEA WebLogic.

To configure OracleAS TopLink support for BEA WebLogic Server, add the following JAR files to the application server class path:

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

Note: When you add the toplink.jar and xmlparserv2.jar files in the application server class path, ensure they are placed before the weblogic.jar file.

Using a Security Manager with BEA WebLogic Server

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 OracleAS TopLink to use reflection.

Example B-1 A Subset of a "Grant" Section from a BEA WebLogic.policy File

This example illustrates only the permissions that OracleAS TopLink requires, but most weblogic.policy files contain more permissions than are shown in this example.

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 OracleAS TopLink to use reflection
    permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
};

OracleAS TopLink CMP Configuration

OracleAS TopLink provides a CMP integration for:

• IBM WebSphere Application Server 4.0

• BEA WebLogic Application Server (6.1, 7.0 and 8.1)

IBM WebSphere Application Server 4.0

To enable the OracleAS TopLink CMP integration for IBM WebSphere 4.0, configure OracleAS TopLink J2EE support for WebSphere as described in "IBM WebSphere Application Server 4.0".

BEA WebLogic Application Server (6.1, 7.0 and 8.1)

To enable the OracleAS TopLink CMP integration for BEA WebLogic Server 6.1, 7.0 and 8.1, use the following procedures. These procedures assume you have already installed OracleAS TopLink.

To configure OracleAS TopLink support for WebLogic:

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 <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 TopLink_CMP_Descriptor.xml.

   • Replace the WebLogic persistence.install file with the OracleAS TopLink persistence.install file found in the <ORACLE_HOME>\toplink\config directory.

2. Add the following JAR files to the application server class path:

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

   Note: When you add the toplink.jar and xmlparserv2.jar files in the application server class path, ensure they are placed before the weblogic.jar file.

3. Start the container, and then start the OracleAS TopLink application. Where supported, use a startup script to start the server. If you write your own startup script, ensure that the class path includes the files listed in Step 2.

OracleAS TopLink in a BEA WebLogic Cluster

BEA WebLogic includes a clustering service that you can leverage with your OracleAS TopLink application. To leverage a cluster, make the OracleAS TopLink runtime JAR available to all servers to which you deploy OracleAS TopLink CMP beans. This section discusses the following cluster-related issues:

• Collocation

• Static Partitioning

• Pinning

• Pinning with Session Beans

• Cache Synchronization and the Cluster

Collocation

Although the BEA WebLogic cluster enables you to build an application across several servers, related components in the application must still be localized to a server. When you store several beans on the same server, the beans are said to be collocated.

Collocation in a BEA WebLogic cluster imposes the following restrictions:

• When you deploy beans on a single server, you can invoke those beans only on that server. This localizes the beans on a given server, and provides a statically-defined means of collocation.

• You must cluster bean Home interfaces, but not instances. When you instantiate a bean, you pin it to the server on which it was instantiated.

  For more information, see "Pinning".

• JTA user transactions must execute completely on a single server, and cannot span servers.

You must collocate all related beans and objects on a single server to support relationships between beans. To simplify the application, also retrieve source and target objects on the same server.

Static Partitioning

Static partitioning refers to strategically deploying all related beans on a single server. A server can contain several groups of related beans, but collocation dictates that a group of beans cannot span several servers.

Static partitioning eliminates cache inconsistency issues, because the application loads beans only on the server on which the beans are deployed. BEA provides limited failover, and bean activity determines how the application load balances across servers.

Pinning

When you create or instantiate a bean, the bean instance is associated with, or pinned to, the server on which it is instantiated. To localize transactions to a particular server, BEA WebLogic Server pins all instantiated beans in a given transaction to the server on which you run the transaction. If beans are pinned to other servers, you cannot localize the transaction.

You can pin beans to a given server dynamically, either through user transactions or through session beans.

Pinning with User Transactions

To maintain bean localization, access beans through a transaction. If you deploy beans on multiple servers, you can initiate the transaction on any server that holds a bean in the transaction. BEA WebLogic attempts to pin all accessed beans to that server for the duration of the transaction.

Example B-2 illustrates the use of a user transaction to collocate related beans.

Example B-2 Using a Transaction to Collocate Beans

UserTransaction transaction = lookupUserTransaction()
// Enclose all construction of relationships in the same transaction
transaction.begin();
/* Look up the home interface and the bean even if they have already been looked up 
previously */
Employee emp = lookupEmployeeHome().findByPrimaryKey(new EmployeePK(EMP_ID));
Address address = new Address(EMP_ID, "99 Bank", "Ottawa", "Ontario", "Canada","K2P 4A1");
emp.setAddress(address);
Project project = lookupProjectHome().findByPrimaryKey(new ProjectPK(PROJ_ID));
emp.addProject(project);
transaction.commit();

Pinning with Session Beans

If you access entity beans through a session bean, the application instantiates the entity beans on the same server as the session bean. By moving the application logic from the client to a session bean, you enable all bean code to run on the same JVM. The client invokes a method in the session bean, and the session bean executes all required logic on the server on which it resides.

You can use session beans to manage scalability and failover.

Cache Synchronization and the Cluster

Cache synchronization propagates changes from one OracleAS TopLink cache to all other server caches. This eliminates the need for manual refresh, and provides a consistent view of cached data across the cluster.

Cache synchronization is a project-level option. If you implement cache synchronization, OracleAS TopLink propagates changes to all objects in the project.

Configuring Cache Synchronization

To configure cache synchronization in the toplink-ejb-jar.xml deployment descriptor, implement the following elements and sub-elements:

• cache-synchronization: Include this tag to enable cache synchronization. To configure synchronization, use the is-asynchronous and should-remove-connection-on-error tags.

• is-asynchronous (optional): Sets the synchronization mode. Set to True to enable asynchronous propagation, or False to force synchronous updates. The default value is True.

  For more information about synchronous and asynchronous updates, see "Synchronous and Asynchronous Propagation".

• should-remove-connection-on-error (optional): Enables error handling at the connection. Set to True to enable this behavior, or False to disable it. The default value is True.

  For more information about this error handling feature, see "Error Handling".

Example B-3 Specifying Cache Synchronization in the toplink-ejb-jar.xml File

<toplink-ejb-jar>
   <session>
      <name>ejb20_AccountDemo</name>
      <project-class>oracle.toplink.demos.ejb20.cmp.account.AccountProject</project-class>
      <login>
         <connection-pool>ejbPool</connection-pool>
      </login>
      <cache-synchronization>
         <is-asynchronous>True</is-asynchronous>
         <should-remove-connection-on-error>True</should-remove-connection-on-error>
      </cache-synchronization>
   </session>
</toplink-ejb-jar>

For more information about the toplink-ejb-jar.xml file, see "Configuring the toplink-ejb-jar.xml File with the BEA WebLogic Server".