org.rhq.enterprise.communications.command.client
Interface RemoteCommunicator

All Known Implementing Classes:

JBossRemotingRemoteCommunicator

public interface RemoteCommunicator

Interface defining the generic contract that is used to locate a remote endpoint and communicate with that remote endpoint via any remoting framework.

Author:

John Mazzitelli

Method Summary

void	connect() Connects this communicator object with the remote endpoint.
void	disconnect() Disconnects this communicator object from the remote endpoint.
FailureCallback	getFailureCallback() Returns the failure callback currently configured within this object.
InitializeCallback	getInitializeCallback() Returns the initialize callback currently configured within this object.
String	getRemoteEndpoint() Returns a string representation of the remote endpoint this communicator is configured to talk to.
boolean	isConnected() Returns true if this object has established a live connection with the remote endpoint.
CommandResponse	send(Command command) Sends the given command to the remote endpoint by utilizing a remoting framework supported by the specific communicator implementation.
CommandResponse	sendWithoutCallbacks(Command command) This is the same as send(Command) except, on error, this method will not attempt to call the failure callback, if one was set.
CommandResponse	sendWithoutInitializeCallback(Command command) This is the same as send(Command) except this method will not attempt to call the initialize callback, thus allowing this method to be called from the initialize callback itself.
void	setFailureCallback(FailureCallback callback) Sets the given failure callback as the one that will be notified when this object sees a comm failure.
void	setInitializeCallback(InitializeCallback callback) Sets the given initialize callback as the one that will be notified when this object attempts to send its very first message after a connect().
void	setRemoteEndpoint(String endpoint) Sets the remote endpoint that this communicator object will send commands to.

Method Detail

connect

void connect()
             throws Exception

Connects this communicator object with the remote endpoint. Once connected, this communicator may send commands and receive command responses from the remote endpoint.

Throws:

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

See Also:

disconnect()

disconnect

void disconnect()

Disconnects this communicator object from the remote endpoint. Once disconnected, this communicator will not be able to send commands to the remote endpoint.

Note that the user may later on change its mind and reconnect simply by calling connect().

isConnected

boolean isConnected()

Returns true if this object has established a live connection with the remote endpoint.

Returns:

true if connected to a remote endpoint; false otherise

send

CommandResponse send(Command command)
                     throws Throwable

Sends the given command to the remote endpoint by utilizing a remoting framework supported by the specific communicator implementation. This will transport the command to the remote endpoint. This is the method in which subclasses make the command-specific client calls necessary to invoke the command on the remote endpoint. If an error is detected by this method, and a failure callback is defined, this method will notify that callback of the problem and ask it if it should retry.

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)

sendWithoutCallbacks

CommandResponse sendWithoutCallbacks(Command command)
                                     throws Throwable

This is the same as send(Command) except, on error, this method will not attempt to call the failure callback, if one was set. This is useful when the caller wants to explicitly handle any failure that might occur without any interference with a failure callback. This method will also not attempt to call the initialize callback, thus allowing this method to be called from the initialize callback itself.

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)

sendWithoutInitializeCallback

CommandResponse sendWithoutInitializeCallback(Command command)
                                              throws Throwable

This is the same as send(Command) except this method will not attempt to call the initialize callback, thus allowing this method to be called from the initialize callback itself.

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)

getFailureCallback

FailureCallback getFailureCallback()

Returns the failure callback currently configured within this object.

Returns:

the callback (may be null)

setFailureCallback

void setFailureCallback(FailureCallback callback)

Sets the given failure callback as the one that will be notified when this object sees a comm failure. You can pass in null if you don't need this object to notify anything when a failure is detected. The callback can be used to reconfigure this communicator and retry the failed message (useful to implement failover algorithms).

Parameters:

callback - the object that listens to failures and may trigger retries (may be null)

getInitializeCallback

InitializeCallback getInitializeCallback()

Returns the initialize callback currently configured within this object.

Returns:

the callback (may be null)

setInitializeCallback

void setInitializeCallback(InitializeCallback callback)

Sets the given initialize callback as the one that will be notified when this object attempts to send its very first message after a connect(). This allows the callback to perform additional initialization procedures prior to the first message getting sent to the remote endpoint. The callback is free to send its own messages via sendWithoutCallbacks(Command) or sendWithoutInitializeCallback(Command).

Parameters:

callback -

getRemoteEndpoint

String getRemoteEndpoint()

Returns a string representation of the remote endpoint this communicator is configured to talk to.

Returns:

remote endpoint string

setRemoteEndpoint

void setRemoteEndpoint(String endpoint)
                       throws Exception

Sets the remote endpoint that this communicator object will send commands to.

Parameters:

endpoint - the new remote endpoint

Throws:

Exception - if the communicator could not point to the new remote endpoint