org.eclipse.persistence.sessions.coordination.CommandManager Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of eclipselink Show documentation
Show all versions of eclipselink Show documentation
EclipseLink build based upon Git transaction f2b9fc5
/*
* Copyright (c) 1998, 2019 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0,
* or the Eclipse Distribution License v. 1.0 which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
*/
// Contributors:
// Oracle - initial API and implementation from Oracle TopLink
package org.eclipse.persistence.sessions.coordination;
/**
*
* Purpose: Provide an interface that clients can use to invoke remote
* commands on other EclipseLink instances, or on other applications that may want
* to receive and process EclipseLink commands.
*
* Description: This is the main interface that is used to send and receive
* remote commands in a EclipseLink cluster. The sequence of remote command execution
* is as follows:
*
*
* - CommandProcessor creates a command and gives it to its local CommandManager
* to send to remote services.
*
- CommandManager uses its CommandConverter to convert the command into a
* TopLink Command object
*
- CommandManager then uses its TransportManager to send the Command to all
* other known cluster members that are subscribing to the same channel
*
- Each remote TransportManager receives the Command and passes it off to the
* CommandManager
*
- Each CommandManager uses its local CommandConverter to convert the command
* into a format appropriate to its application (CommandProcessor)
*
- Each CommandManager invokes its local CommandProcessor and passes it the
* command (formatted the way that the application-specified converter left it in)
* to be executed. If the CommandProcessor is a EclipseLink session then the
* executeWithSession method will be invoked on the command.
*
*
* Responsibilities:
*
* - Invoke the DiscoveryManager to establish the EclipseLink cluster
*
- Propagate remote command to EclipseLink cluster
*
- Delegate processing command to its CommandProssesor
*
- Convert command to appropriate format for sending to EclipseLink cluster
* or its command processor
*
* @see Command
* @see CommandProcessor
* @author Steven Vo
* @since OracleAS TopLink 10g (9.0.4)
*/
public interface CommandManager {
/**
* PUBLIC:
* Initialize the remote command manager. This will also trigger the
* DiscoveryManager to start establishing the EclipseLink cluster.
*/
void initialize();
/**
* 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.
*/
void shutdown();
/**
* PUBLIC:
* Return the URL for this command manager.
*
* @return The URL String for this CommandManager
*/
String getUrl();
/**
* ADVANCED:
* Set the URL for this command manager.
*
* @param url The URL String for this CommandManager
*/
void setUrl(String url);
/**
* 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.
*
* @return The service channel String subscribed to by this CommandManager
*/
String getChannel();
/**
* 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.
*
* @param channel The service channel subscribed to by this CommandManager
*/
void setChannel(String channel);
/**
* ADVANCED:
* Propagate a remote command to all remote RCM services participating
* in the EclipseLink cluster.
*
* @param command An object representing a TopLink command
*/
void propagateCommand(Object command);
/**
* PUBLIC:
* Return the command processor that processes commands received from the cluster.
*
* @return An implementation instance of CommandProcessor
*/
CommandProcessor getCommandProcessor();
/**
* ADVANCED:
* Set the command processor that will be invoked to process commands. EclipseLink
* applications can implement this interface in order to receive remote commands
* from a EclipseLink cluster.
*
* @param commandProcessor The intended processor of remote commands
*/
void setCommandProcessor(CommandProcessor commandProcessor);
/**
* ADVANCED:
* Set a specific transport manager to manage sending and receiving of remote commands.
*
* @param newTransportManager An instance of the desired transport manager type
*/
void setTransportManager(TransportManager newTransportManager);
/**
* PUBLIC:
* Return the transport manager that manages sending and receiving of remote commands.
*
* @return The TransportManager instance being used by this CommandManager
*/
TransportManager getTransportManager();
/**
* PUBLIC:
* Return the discovery manager that manages membership in the EclipseLink cluster.
*
* @return The DiscoveryManager instance being used by this CommandManager
*/
DiscoveryManager getDiscoveryManager();
/**
* PUBLIC:
* Return the converter instance used to convert between TopLink Command
* objects and an application command format.
*
* @return The converter being used by this CommandManager
*/
CommandConverter getCommandConverter();
/**
* ADVANCED:
* Set the converter instance that will be invoked by this CommandProcessor
* to convert commands from their application command format into EclipseLink
* Command objects before being propagated to remote command manager services.
* The converter will also be invoked to convert EclipseLink Command objects into
* application format before being sent to the CommandProcessor for execution.
*
* @param commandConverter The converter to be used by this CommandManager
*/
void setCommandConverter(CommandConverter commandConverter);
/**
* 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.
*/
boolean shouldPropagateAsynchronously();
/**
* 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.
*/
void setShouldPropagateAsynchronously(boolean asyncMode);
/**
* ADVANCE:
* Return whether this commandProcessor is a EclipseLink session or not.
*/
boolean isCommandProcessorASession();
}