oracle.toplink.remotecommand
Class RemoteCommandManager

java.lang.Object
oracle.toplink.remotecommand.RemoteCommandManager

All Implemented Interfaces:

CommandManager

public class RemoteCommandManager

extends java.lang.Object

implements CommandManager

Purpose: Provide a CommandManager implementation that will be used by both TopLink and non-TopLink applications.

Description: A RemoteCommandManager (or RCM) instance is the primary component of an RCM service instance. It manages the other components of the service, and directs the overall service operation. Its ServiceId uniquely distinguishes it from other service instances in the cluster.

Each RCM has a logical channel to which it subscribes and publishes. This channel determines which other instances in the cluster the service instance sends and receives remote commands to/from. All RCM's on the same channel should have the same discovery manager settings (be communicating on the same multicast) so that the discovery managers may be able to discover one another. RCM's on different channels may operate on the same or on different multicast groups.

An RCM instance knows about other instances in the cluster through its DiscoveryManager. Its TransportManager is repsonsible for setting up the connections to other instances once they are discovered.

An RCM is instructed to "propagate", or execute on all remote service instances in the cluster that subscribe to the same channel, a remote command by its CommandProcessor. Likewise, when an RCM receives a remote command to be executed then it passes the command off to the CommandProcessor for the processing of the command to occur. CommandProcessors pass commands to the RCM as an Object (in a format that may be specific to the application) and the RCM uses its CommandConverter to convert it to a TopLink Command object before sending the Command off to the cluster. Similarly, when a TopLink Command object is received then the RCM invokes its CommandConverter to convert the object into the application format that will be passed to the CommandProcessor to process the command.

Since:

OracleAS TopLink 10g (9.0.4)

See Also:

CommandManager, Command, CommandProcessor, CommandConverter, CommandTransporter, DiscoveryManager

Field Summary

static boolean	DEFAULT_ASYNCHRONOUS_MODE
static java.lang.String	DEFAULT_CHANNEL
static boolean	DEFAULT_REMOVE_CONNECTION_ON_ERROR_MODE

Constructor Summary

RemoteCommandManager(CommandProcessor commandProcessor)

RemoteCommandManager(CommandProcessor commandProcessor, TransportManager transportManager)

Method Summary

java.lang.String	getChannel() PUBLIC: Return the service channel for this command manager.
CommandConverter	getCommandConverter() PUBLIC: Return the converter instance used to convert between TopLink Command objects and an application command format.
CommandProcessor	getCommandProcessor() PUBLIC: Return the command processor that processes commands received from the cluster.
DiscoveryManager	getDiscoveryManager() PUBLIC: Return the discovery manager that detects the arrival of new cluster members
TransportManager	getTransportManager() PUBLIC: Return the transport manager that manages sending and receiving of remote commands.
java.lang.String	getUrl() PUBLIC: Return the URL for this command manager.
void	initialize() PUBLIC: Initialize the remote command manager.
void	logInfo(java.lang.String message, java.lang.Object[] args)
void	logWarning(java.lang.String message, java.lang.Object[] args)
void	propagateCommand(java.lang.Object command) ADVANCED: Propagate a remote command to all remote RCM services participating in the TopLink cluster.
void	setChannel(java.lang.String channel) ADVANCED: Set the service channel for this command manager.
void	setCommandConverter(CommandConverter newCommandConverter) ADVANCED: Set the converter instance that will be invoked by this CommandProcessor to convert commands from their application command format into TopLink Command objects before being propagated to remote command manager services.
void	setCommandProcessor(CommandProcessor newCommandProcessor) ADVANCED: Set the command processor that will be invoked to process commands.
void	setDiscoveryManager(DiscoveryManager mgr) ADVANCED: Set the discovery manager that detects the arrival of new cluster members.
void	setShouldPropagateAsynchronously(boolean asyncMode) ADVANCED: Set whether this command manager should propagate commands synchronously or asynchronously.
void	setShouldRemoveConnectionOnError(boolean shouldRemoveConnectionOnError) PUBLIC: Set whether connections to remote services should be disconnected when an error occurs.
void	setTransportManager(TransportManager newTransportManager) ADVANCED: Set a specific transport manager to manage sending and receiving of remote commands.
void	setUrl(java.lang.String url) ADVANCED: Set the URL for this command manager.
boolean	shouldPropagateAsynchronously() PUBLIC: Return whether this command manager should propagate commands synchronously or asynchronously.
boolean	shouldRemoveConnectionOnError() PUBLIC: Return whether connections to remote services should be disconnected when an error occurs.
void	shutdown() PUBLIC: Shut down the remote command manager.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_ASYNCHRONOUS_MODE

public static final boolean DEFAULT_ASYNCHRONOUS_MODE

See Also:

Constant Field Values

DEFAULT_REMOVE_CONNECTION_ON_ERROR_MODE

public static final boolean DEFAULT_REMOVE_CONNECTION_ON_ERROR_MODE

See Also:

Constant Field Values

DEFAULT_CHANNEL

public static final java.lang.String DEFAULT_CHANNEL

See Also:

Constant Field Values

Constructor Detail

RemoteCommandManager

public RemoteCommandManager(CommandProcessor commandProcessor)

RemoteCommandManager

public RemoteCommandManager(CommandProcessor commandProcessor,
                            TransportManager transportManager)

Method Detail

initialize

public void initialize()

PUBLIC: Initialize the remote command manager. This will also trigger the DiscoveryManager to start establishing the TopLink cluster.

Specified by:

initialize in interface CommandManager

shutdown

public void shutdown()

PUBLIC: Shut down the remote command manager. This will also trigger the DiscoveryManager to stop. NOTE: Although this call initiates the shutdown process, no guarantees are made as to when it will actually complete.

Specified by:

shutdown in interface CommandManager

propagateCommand

public void propagateCommand(java.lang.Object command)

ADVANCED: Propagate a remote command to all remote RCM services participating in the TopLink cluster.

Specified by:

propagateCommand in interface CommandManager

Parameters:

command - An object representing a TopLink command

getCommandProcessor

public CommandProcessor getCommandProcessor()

Description copied from interface: CommandManager

PUBLIC: Return the command processor that processes commands received from the cluster.

Specified by:

getCommandProcessor in interface CommandManager

Returns:

An implementation instance of CommandProcessor

setCommandProcessor

public void setCommandProcessor(CommandProcessor newCommandProcessor)

Description copied from interface: CommandManager

ADVANCED: Set the command processor that will be invoked to process commands. Non-TopLink applications can implement this interface in order to receive remote commands from a TopLink cluster.

Specified by:

setCommandProcessor in interface CommandManager

Parameters:

newCommandProcessor - The intended processor of remote commands

getTransportManager

public TransportManager getTransportManager()

Description copied from interface: CommandManager

PUBLIC: Return the transport manager that manages sending and receiving of remote commands.

Specified by:

getTransportManager in interface CommandManager

Returns:

The TransportManager instance being used by this CommandManager

setTransportManager

public void setTransportManager(TransportManager newTransportManager)

Description copied from interface: CommandManager

ADVANCED: Set a specific transport manager to manage sending and receiving of remote commands.

Specified by:

setTransportManager in interface CommandManager

Parameters:

newTransportManager - An instance of the desired transport manager type

setShouldRemoveConnectionOnError

public void setShouldRemoveConnectionOnError(boolean shouldRemoveConnectionOnError)

PUBLIC: Set whether connections to remote services should be disconnected when an error occurs.

Specified by:

setShouldRemoveConnectionOnError in interface CommandManager

Parameters:

shouldRemoveConnectionOnError - True if connections are to be transparently removed by the RCM, false if the exception should be thrown instead.

shouldRemoveConnectionOnError

public boolean shouldRemoveConnectionOnError()

PUBLIC: Return whether connections to remote services should be disconnected when an error occurs.

Specified by:

shouldRemoveConnectionOnError in interface CommandManager

Returns:

Return true if connections will be transparently removed by the RCM, or false if the exception will be thrown instead.

shouldPropagateAsynchronously

public boolean shouldPropagateAsynchronously()

PUBLIC: Return whether this command manager should propagate commands synchronously or asynchronously. If set to synchronous propagation then propagateCommand() will not return to the caller until the command has been executed on all of the services in the cluster. In asynchronous mode the command manager will create a separate thread for each of the remote service executions, and then promptly return to the caller.

Specified by:

shouldPropagateAsynchronously in interface CommandManager

Returns:

True if asynchronous mode enabled, false if synchronous propagation will occur (default is true)

setShouldPropagateAsynchronously

public void setShouldPropagateAsynchronously(boolean asyncMode)

ADVANCED: Set whether this command manager should propagate commands synchronously or asynchronously. If set to synchronous propagation then propagateCommand() will not return to the caller until the command has been executed on all of the services in the cluster. In asynchronous mode the command manager will create a separate thread for each of the remote service executions, and then promptly return to the caller.

Specified by:

setShouldPropagateAsynchronously in interface CommandManager

Parameters:

asyncMode - True if asynchronous mode enabled, false if synchronous propagation will occur (default is true)

getDiscoveryManager

public DiscoveryManager getDiscoveryManager()

PUBLIC: Return the discovery manager that detects the arrival of new cluster members

Specified by:

getDiscoveryManager in interface CommandManager

Returns:

The DiscoveryManager instance being used by this CommandManager

setDiscoveryManager

public void setDiscoveryManager(DiscoveryManager mgr)

ADVANCED: Set the discovery manager that detects the arrival of new cluster members. Note: This should only be used in rare cases or special customized systems. Under normal circumstances the discovery manager should not need to be set.

getCommandConverter

public CommandConverter getCommandConverter()

PUBLIC: Return the converter instance used to convert between TopLink Command objects and an application command format.

Specified by:

getCommandConverter in interface CommandManager

Returns:

The converter being used by this CommandManager

setCommandConverter

public void setCommandConverter(CommandConverter newCommandConverter)

ADVANCED: Set the converter instance that will be invoked by this CommandProcessor to convert commands from their application command format into TopLink Command objects before being propagated to remote command manager services. The converter will also be invoked to convert TopLink Command objects into application format before being sent to the CommandProcessor for execution.

Specified by:

setCommandConverter in interface CommandManager

Parameters:

newCommandConverter - The converter to be used by this CommandManager

logInfo

public void logInfo(java.lang.String message,
                    java.lang.Object[] args)

logWarning

public void logWarning(java.lang.String message,
                       java.lang.Object[] args)

getChannel

public java.lang.String getChannel()

PUBLIC: Return the service channel for this command manager. All command managers with the same service channel will send and receive commands from each other. Commands sent on other service channels will not be exchanged with this command manager.

Specified by:

getChannel in interface CommandManager

Returns:

The service channel String subscribed to by this CommandManager

setChannel

public void setChannel(java.lang.String channel)

ADVANCED: Set the service channel for this command manager. All command managers with the same service channel will send and receive commands from each other. Commands sent on other service channels will not be exchanged with this command manager.

Specified by:

setChannel in interface CommandManager

Parameters:

channel - The service channel subscribed to by this CommandManager

getUrl

public java.lang.String getUrl()

PUBLIC: Return the URL for this command manager.

Specified by:

getUrl in interface CommandManager

Returns:

The URL String for this CommandManager

setUrl

public void setUrl(java.lang.String url)

ADVANCED: Set the URL for this command manager.

Specified by:

setUrl in interface CommandManager

Parameters:

url - The URL String for this CommandManager