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
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, through either user transactions or 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 subelements:

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