org.rhq.enterprise.communications.command.client

Interface CommandClient

All Known Implementing Classes:

AbstractCommandClient, EchoCommandClient, GenericCommandClient

public interface CommandClient

Interface to all clients of commands. This interface defines the operations one can make as a client to a remote command server.

Author:

John Mazzitelli

Method Summary

Methods

Modifier and Type	Method and Description
void	connectRemoteCommunicator() Provides a mechanism by which users can notify this object that the user is about to issue commands and that a remoting communicator should be created and should connect to the remote server.
Command	createNewCommand(Map<String,Object> params) Creates a new Command object that can be used by this client.
void	disconnectRemoteCommunicator() Provides a mechanism by which users can notify this object that the user is no longer interested in issuing commands to the remote server.
RemoteCommunicator	getRemoteCommunicator() Gets the object that encapsulates the underlying remote framework implementation.
CommandResponse	invoke(Command command) Invokes the actual command by utilizing the remoting communicator to transport the command to the server.
CommandResponse	invoke(Map<String,Object> params) Invokes the actual command by utilizing the remoting communicator to transport the command to the server.
void	setRemoteCommunicator(RemoteCommunicator remoteCommunicator) Sets the object that encapsulates the underlying remote framework implementation.

Method Detail

getRemoteCommunicator

RemoteCommunicator getRemoteCommunicator()

Gets the object that encapsulates the underlying remote framework implementation. This is the object that performs the actual sending of commands and receiving of command responses over the underlying remote framework transport.

Returns:

the remote communicator object that is specific to a particular underlying remote framework.

setRemoteCommunicator

void setRemoteCommunicator(RemoteCommunicator remoteCommunicator)

Sets the object that encapsulates the underlying remote framework implementation. This is the object that performs the actual sending of commands and receiving of command responses over the underlying remote framework transport.

Parameters:

remoteCommunicator - the remote communicator object that is specific to a particular underlying remote framework.

connectRemoteCommunicator

void connectRemoteCommunicator()
                               throws Exception

Provides a mechanism by which users can notify this object that the user is about to issue commands and that a remoting communicator should be created and should connect to the remote server.

Throws:

Exception - if failed to connect to the remote server for any reason

See Also:

disconnectRemoteCommunicator()

disconnectRemoteCommunicator

void disconnectRemoteCommunicator()

Provides a mechanism by which users can notify this object that the user is no longer interested in issuing commands to the remote server. The effect of this is the remoting communicator will now disconnect from the remote server.

Note that the user may later on change its mind and reconnect simply by calling connectRemoteCommunicator(). Calling that method will reconnect the remoting communicator.

invoke

CommandResponse invoke(Map<String,Object> params)
                       throws Throwable

Invokes the actual command by utilizing the remoting communicator to transport the command to the server. This is the method in which subclasses make the command-specific client calls necessary to invoke the command on the remote server.

This method is typically used in conjunction with CmdlineClient to invoke commands that are unknown at compile-time. In this case, params typically contain values of type String - these are text-based parameters that were entered via a script or cmdline. That text-based data will be converted to meaningful Java types in order to be able to build the proper Command objects.

Parameters:

params - a set of command parameters that are to be used to execute the proper command (may be null)

Returns:

the command response

Throws:

Throwable - on any error (either during the sending or execution of the command)

See Also:

createNewCommand(Map)

invoke

CommandResponse invoke(Command command)
                       throws Throwable

Invokes the actual command by utilizing the remoting communicator to transport the command to the server. This is the method in which subclasses make the command-specific client calls necessary to invoke the command on the remote server.

This is the prefered method for clients to call when it needs to invoke commands since each Command is strongly typed and provides compile-time error checking. However, in order to be able to invoke this method on subclasses, concrete implementations must be used and hence the actual command that is to be issued must be known at compile time. Should a dynamic runtime client be needed to invoke commands unknown at compile time (see CmdlineClient), the use of invoke(Map) will be required.

Parameters:

command - encapsulates the command that is to be executed (must not be null)

Returns:

the command response

Throws:

Throwable - on any error (either during the sending or execution of the command)

createNewCommand

Command createNewCommand(Map<String,Object> params)

Creates a new Command object that can be used by this client. The client can take this new command instance, fill it in with parameter values and execute it. The given map of parameters is optional; if non- null, all parameters found in the map will be added to the command.

Parameters:

params - contains parameter values keyed on the parameter names (may be null)

Returns:

a new Command instance