Remote Command Manager

The Remote Command Manager (RCM) enables OracleAS TopLink to send synchronization messages across the network to non-OracleAS TopLink applications. This feature is separate from the standard cache synchronization feature.

When you build a distributed system that includes both OracleAS TopLink and non-OracleAS TopLink applications, use the RCM in place of regular cache synchronization. Do not use RCM and regular OracleAS TopLink cache synchronization concurrently.

This section discusses the RCM, and offers information on:

RCM Implementation Requirements
RCM Structure
RCM Channels
Configuring the RCM
Error Handling
Guidelines for Using RCM
Custom Remote Commands

RCM Implementation Requirements

To enable RCM in a distributed system, enable RCM for all OracleAS TopLink sessions in the system. In addition, non-OracleAS TopLink applications must meet the following criteria to participate in cache synchronization through the RCM:

The application must be a Java application or include a Java component.
It must have access to a local JNDI service that supports remote access.
The toplink.jar must be included in the application classpath.
You must configure the RCM in Java code for the application, and include the appropriate converter and processor components.

RCM Structure

The RCM is both modular and pluggable. Figure 8-2 illustrates the components of the RCM.

Figure 8-2 Remote Command Manager Components

Description of the illustration rcm.gif

The RCM components comprise:

CommandManager: The CommandManager is the central point of control for the system.
DiscoveryManager: The DiscoveryManager dynamically maintains the membership of the OracleAS TopLink cluster.
TransportManager: The TransportManager manages the transport level of the message exchange.
CommandProcessor: The CommandProcessor interface sits between the RCM and the application. It is the main integration point for non-OracleAS TopLink applications.
CommandConverter: An implementation of the CommandConverter translates commands between OracleAS TopLink and non-OracleAS TopLink applications. Regular OracleAS TopLink sessions do not require a CommandConverter implementation, because they do not require conversion.

Transmitting Commands From OracleAS TopLink with RCM

The process of initiating and transmitting commands from an OracleAS TopLink application is as follows:

Invoke the getCommandManager() accessor on the session to obtain a CommandManager interface.
Invoke the CommandManager.propagateCommand(command) method to initiate commands from the OracleAS TopLink session. Pass the command to be remotely executed as the command argument.
The TransportManager transmits the command to other members of the cluster.
If the receiving application is:
- An OracleAS TopLink application, then the OracleAS TopLink session executes the command
- A non-OracleAS TopLink application (or an application that does not use an OracleAS TopLink session), then the application must provide implementation classes for the CommandProcessor and CommandConverter interfaces

Using Commands on a Non-OracleAS TopLink Application

To send remote commands to the cluster, non-OracleAS TopLink applications invoke the CommandManager.propagateCommand(command) method. The application must provide a CommandConverter interface to convert the application-specific command format to an OracleAS TopLink Command object.

Likewise, when a non-OracleAS TopLink application receives an OracleAS TopLink command, it must implement a converter to translate the command for the CommandManager. To execute the command, a non-OracleAS TopLink application invokes the processCommand(command) method.

RCM Channels

The RCM passes remote commands along virtual channels. The RCM assigns each subscribing service a channel on which to send and receive commands, and all services assigned to a particular channel send (or publish) commands to that channel. Services also act as subscribers to their assigned channel, receiving all the commands published to that channel by other services.

You can assign any number of channels in the system without performance penalty, but any given service may publish and subscribe only to a single channel. You cannot reassign channels dynamically or while discovery is active.

If you do not set a channel name, RCM assigns a default channel when you add services to the cluster. For example, if you do not set a channel name for any service instance you add to the system, all services subscribe to the same default channel.

Configuring the RCM

Use the RCM API to configure the RCM. For OracleAS TopLink applications create the cluster as part of the session initialization (for example, use a session PreLogin event when the session is initialized from the sessions.xml file). Note that neither the OracleAS TopLink Sessions Editor nor the sessions.xml file directly support RCM configuration.

The logical OracleAS TopLink cluster includes any number of OracleAS TopLink session-based applications, and non-OracleAS TopLink applications. Bind non-OracleAS TopLink applications in with OracleAS TopLink code to enable them to access the OracleAS TopLink commands.

Configuring the RCM for OracleAS TopLink Applications

To configure applications that use OracleAS TopLink sessions for RCM:

Create a Remote Command Manager implementation instance for the CommandManager interface. Pass the session as the CommandProcessor argument.

For example:
```
CommandManager rcm = new RemoteCommandManager(session);
```
To enable change set propagation between sessions, set the propagating option to true:
```
session.setShouldPropagateChanges(true);
```
Set the URL that other RCM servers use to look up JNDI names in this Java virtual Machine (JVM). For example, for OC4J, the URL can appear as follows:
```
rcm.setUrl(Òormi://myHostname:23791/myDeployedApplicationÓ);
```
For a WebLogic Server, the URL can appear as follows:
```
rcm.setUrl(Òt3://myHostname:7001Ó);
```
If you use OC4J, set a valid user and password. This enables the RCM services to look up remote names in JNDI. The user and password combination must be valid on all servers that participate in RCM.

For example:
```
rcm.getTransportManager().setUserName("admin");
rcm.getTransportManager().setPassword("password");
```

If you are using WebLogic Server, leave the remote context properties empty.

For example:

rcm.getTransportManager().setRemoteContextProperties(    new java.util.Hashtable());

(Optional) Set the DiscoveryManager parameters to custom multicast socket settings for your environment.

For example:

rcm.getDiscoveryManager().setMulticastGroupAddress(Ò226.1.2.3Ó);
rcm.getDiscoveryManager().setMulticastPort(3122);

(Optional) Set the logical channel to assign a channel for the service.

For example:
```
rcm.setChannel("MyChannel");
```

(Optional) Set other RCM properties to customize the application.

For example:

rcm.setShouldPropagateAsynchronously(false);
rcm.setShouldRemoveConnectionOnError(true);

Example 8-10 Enabling RCM on OC4J

CommandManager rcm = new RemoteCommandManager(session);
rcm.setUrl(Òormi://ferengi:23791/orderEntryAppÓ);
rcm.getTransportManager().setUserName("admin");
rcm.getTransportManager().setPassword("password");
session.setShouldPropagateChanges(true);

Example 8-11 Enabling RCM on the BEA WebLogic Server

CommandManager rcm = new RemoteCommandManager(session);
rcm.setUrl(Òt3://ferengi:7001Ó);
rcm.getTransportManager().setRemoteContextProperties(new java.util.Hashtable());
session.setShouldPropagateChanges(true);

Configuring RCM for Non-OracleAS TopLink Applications

To configure RCM on applications that do not use the OracleAS TopLink sessions:

Create an application class to implement the CommandProcessor interface.

For example:
```
CommandProcessor processor = new ApplicationCommandProcessor();
```
Create a Remote Command Manager implementation instance for the CommandManager interface. Pass the session as the CommandProcessor argument:
```
CommandManager rcm = new RemoteCommandManager(processor);
```
Create an application class to implement the CommandConverter interface and set an instance of the implementation class on the CommandManager.

For example:
```
CommandConverter converter = new ApplicationCommandConverter();
rcm.setCommandConverter(converter);
```

If you are using a WebLogic Server, leave the remote context properties empty.

For example:

rcm.getTransportManager().setRemoteContextProperties(    new java.util.Hashtable());

(Optional) Set the DiscoveryManager parameters to custom multicast socket settings for your environment.

For example:

rcm.getDiscoveryManager().setMulticastGroupAddress(Ò226.1.2.3Ó);
rcm.getDiscoveryManager().setMulticastPort(3122);

(Optional) Set the logical channel to assign a channel for the service.

For example:
```
rcm.setChannel("MyChannel");
```

(Optional) Set other RCM properties to customize the application.

For example:

rcm.setShouldPropagateAsynchronously(false);
rcm.setShouldRemoveConnectionOnError(true);

Start the RCM service:
```
rcm.initialize();
```

Example 8-12 Enabling RCM for a Non-OracleAS TopLink Application Using JNDI on OC4J

CommandManager rcm = new RemoteCommandManager(
    new ApplicationCommandProcessor()
);
rcm.setCommandConverter(new ApplicationCommandConverter());
rcm.setUrl(Òormi://ferengi:23791/orderEntryAppÓ);
rcm.getTransportManager().setUserName("admin");
rcm.getTransportManager().setPassword("password");rcm.initialize();

Example 8-13 Enabling RCM for a Non-OracleAS TopLink Application Using JNDI on WebLogic Server

CommandManager rcm = new RemoteCommandManager(
    new ApplicationCommandProcessor());
rcm.setCommandConverter(    new ApplicationCommandConverter());
rcm.setUrl(Òt3://ferengi:7001Ó);
rcm.getTransportManager().setRemoteContextProperties(
    new java.util.Hashtable());
rcm.initialize();

Error Handling

Propagated commands often execute on multiple subscribing services. The subscribing services return results to the publishing server only if the command fails. The propagation mode affects error handling when a subscribing node reports a failure:

In synchronous mode, the first remote command execution that fails raises a RemoteCommandException on the publishing service. The publishing service stops command propagation.
In asynchronous mode, every server that fails raises a RemoteCommandException on the publishing service. Because the threads are asynchronous to the publishing server thread, the exceptions are not raised within the context of the calling thread.

You can choose to catch and handle exceptions explicitly. The CommandProcessor interface includes the handleException() method for this purpose. Implement this method to catch exceptions thrown from a remote command service. For OracleAS TopLink applications, you can specify an exception handler on the session to handle the exception.

Raised exceptions are either:

CommunicationException: Thrown when a transport-level communications error occurs
RemoteCommandException: Thrown when any other problem occurs.

Guidelines for Using RCM

When you use RCM, note the following:

When you run OC4J, include the -userThreads command line option when you start the server. This enables the DiscoveryManager to initialize as a separate thread.
When you deploy a single archive (for example, an EAR file) to multiple servers, implement one of the following on the host-specific Java code that configures the URL:
- Use the java.net.InetAddress methods.
- Define a system property on the command line to pass in the hostname or URL used by the RCM service.
No transaction context is associated with remote command execution. The CommandProcessor interface must initiate its own transactions, and provide clean-up functionality in the case of failure.
OracleAS TopLink applications must hook a server session as the CommandProcessor interface to an RCM. Do not use other types of sessions.

Custom Remote Commands

To create additional custom commands, extend the oracle.toplink.remotecommand.Command class, and implement the executeWithSession(Session) method. If the CommandProcessor interface is an OracleAS TopLink session, this method executes when the service executes.

You can pass instances of these commands to the propagateCommand() method, and publish them for execution on the remote services.