org.rhq.enterprise.communications.command.client
Class JBossRemotingRemoteCommunicator

java.lang.Object
  org.rhq.enterprise.communications.command.client.JBossRemotingRemoteCommunicator

All Implemented Interfaces:

RemoteCommunicator

public class JBossRemotingRemoteCommunicator
extends Object
implements RemoteCommunicator

Provides basic functionality to all command clients that want to use JBoss/Remoting as the remoting framework.

This superclass provides the hooks by which users of the client can select the location of the remote server and the subsystem where the command is to be invoked.

Under the covers, a remoting client is created and maintained by this object. The users of this object may manually connect and disconnect that remoting client. Typically, there will not be a need to connect since it will be done automatically when appropriate; however, it is good practice to tell this object to disconnect its remoting client when this object is no longer needed to issue commands to the remote server.

All subclasses should include a no-arg constructor so they can be built dynamically by the cmdline client.

Author:

John Mazzitelli

Field Summary

static String

DEFAULT_SUBSYSTEM The default subsystem to use when sending messages via the JBoss/Remoting client.

Constructor Summary

JBossRemotingRemoteCommunicator()
Constructor for JBossRemotingRemoteCommunicator that initializes the client with no invoker locator defined.

JBossRemotingRemoteCommunicator(org.jboss.remoting.InvokerLocator locator)
Constructor for JBossRemotingRemoteCommunicator that allows you to specify the invoker locator to use.

JBossRemotingRemoteCommunicator(org.jboss.remoting.InvokerLocator locator, Map<String,String> client_config)
Constructor for JBossRemotingRemoteCommunicator that allows you to specify the invoker locator to use.

JBossRemotingRemoteCommunicator(org.jboss.remoting.InvokerLocator locator, String subsystem)
Constructor for JBossRemotingRemoteCommunicator that allows you to specify the invoker locator to use.

JBossRemotingRemoteCommunicator(org.jboss.remoting.InvokerLocator locator, String subsystem, Map<String,String> client_config)
Constructor for JBossRemotingRemoteCommunicator that allows you to specify the invoker locator to use.

JBossRemotingRemoteCommunicator(String locatorUri)
Constructor for JBossRemotingRemoteCommunicator that allows you to indicate the invoker locator to use by specifying the locator's URI.

JBossRemotingRemoteCommunicator(String locatorUri, Map<String,String> client_config)
Constructor for JBossRemotingRemoteCommunicator that allows you to indicate the invoker locator to use by specifying the locator's URI.

JBossRemotingRemoteCommunicator(String locatorUri, String subsystem)
Constructor for JBossRemotingRemoteCommunicator that allows you to indicate the invoker locator to use by specifying the locator's URI.

JBossRemotingRemoteCommunicator(String locatorUri, String subsystem, Map<String,String> client_config)
Constructor for JBossRemotingRemoteCommunicator that allows you to indicate the invoker locator to use by specifying the locator's URI.

Method Summary

void	connect() Connects this communicator object with the remote endpoint.
void	disconnect() Disconnects this communicator object from the remote endpoint.
Map<String,String>	getClientConfiguration() Returns the map of name/value pairs of client configuration settings used when creating the client.
FailureCallback	getFailureCallback() Returns the failure callback currently configured within this object.
InitializeCallback	getInitializeCallback() Returns the initialize callback currently configured within this object.
org.jboss.remoting.InvokerLocator	getInvokerLocator() Returns the invoker locator that is to be used to find the remote JBoss/Remoting server.
String	getRemoteEndpoint() Returns a string representation of the remote endpoint this communicator is configured to talk to.
protected org.jboss.remoting.Client	getRemotingClient() Returns the remoting client that is to be used to transport the command request to the server.
String	getSubsystem() Returns the value of the subsystem that will be used to target command invocations.
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 RemoteCommunicator.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 RemoteCommunicator.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 RemoteCommunicator.connect().
void	setInvokerLocator(org.jboss.remoting.InvokerLocator locator) Sets the invoker locator that this communicator should use for its subsequent command client invocations.
void	setInvokerLocator(org.jboss.remoting.InvokerLocator locator, Map<String,String> client_config) Sets the invoker locator that this communicator should use for its subsequent command client invocations.
void	setInvokerLocator(String locatorUri) Sets the invoker locator URI and creates a new locator that is to be used to find the remote JBoss/Remoting server for its subsequent command client invocations.
void	setInvokerLocator(String locatorUri, Map<String,String> client_config) Sets the invoker locator URI and creates a new locator that is to be used to find the remote JBoss/Remoting server for its subsequent command client invocations.
void	setRemoteEndpoint(String endpoint) Sets the remote endpoint that this communicator object will send commands to.
void	setSubsystem(String subsystem) Sets the value of the subsystem that will be used to target command invocations.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_SUBSYSTEM

public static final String DEFAULT_SUBSYSTEM

The default subsystem to use when sending messages via the JBoss/Remoting client.

See Also:

Constant Field Values

Constructor Detail

JBossRemotingRemoteCommunicator

public JBossRemotingRemoteCommunicator()

Constructor for JBossRemotingRemoteCommunicator that initializes the client with no invoker locator defined. It must later be specified through setInvokerLocator(InvokerLocator) before any client commands can be issued. In addition, the getSubsystem() will be set to the DEFAULT_SUBSYSTEM.

Note that all subclasses are strongly urged to include this no-arg constructor so it can plug into the cmdline client seamlessly.

JBossRemotingRemoteCommunicator

public JBossRemotingRemoteCommunicator(String locatorUri)
                                throws MalformedURLException

Constructor for JBossRemotingRemoteCommunicator that allows you to indicate the invoker locator to use by specifying the locator's URI. The subsystem will be set to the DEFAULT_SUBSYSTEM.

Parameters:

locatorUri - the locator's URI (must not be null)

Throws:

MalformedURLException - if failed to create the locator (see InvokerLocator.InvokerLocator(String))

JBossRemotingRemoteCommunicator

public JBossRemotingRemoteCommunicator(String locatorUri,
                                       Map<String,String> client_config)
                                throws MalformedURLException

Constructor for JBossRemotingRemoteCommunicator that allows you to indicate the invoker locator to use by specifying the locator's URI. The subsystem will be set to the DEFAULT_SUBSYSTEM. The given Map should contain Client configuration attributes.

Parameters:

locatorUri - the locator's URI (must not be null)

client_config - the client configuration (may be null or empty)

Throws:

MalformedURLException - if failed to create the locator (see InvokerLocator.InvokerLocator(String))

JBossRemotingRemoteCommunicator

public JBossRemotingRemoteCommunicator(org.jboss.remoting.InvokerLocator locator)

Constructor for JBossRemotingRemoteCommunicator that allows you to specify the invoker locator to use. locator may be null, in which case, it must later be specified through setInvokerLocator(InvokerLocator) before any client commands can be issued. The subsystem will be set to the DEFAULT_SUBSYSTEM.

Parameters:

locator - the locator to use (may be null)

JBossRemotingRemoteCommunicator

public JBossRemotingRemoteCommunicator(org.jboss.remoting.InvokerLocator locator,
                                       Map<String,String> client_config)

Constructor for JBossRemotingRemoteCommunicator that allows you to specify the invoker locator to use. locator may be null, in which case, it must later be specified through setInvokerLocator(InvokerLocator) before any client commands can be issued.The subsystem will be set to the DEFAULT_SUBSYSTEM. The given Map should contain Client configuration attributes.

Parameters:

locator - the locator to use (may be null)

client_config - the client configuration (may be null or empty)

JBossRemotingRemoteCommunicator

public JBossRemotingRemoteCommunicator(org.jboss.remoting.InvokerLocator locator,
                                       String subsystem)

Constructor for JBossRemotingRemoteCommunicator that allows you to specify the invoker locator to use. locator may be null, in which case, it must later be specified through setInvokerLocator(InvokerLocator) before any client commands can be issued.

Parameters:

locator - the locator to use (may be null)

subsystem - the subsystem (or command domain) in which commands will be invoked (may be null)

JBossRemotingRemoteCommunicator

public JBossRemotingRemoteCommunicator(org.jboss.remoting.InvokerLocator locator,
                                       String subsystem,
                                       Map<String,String> client_config)

Constructor for JBossRemotingRemoteCommunicator that allows you to specify the invoker locator to use. locator may be null, in which case, it must later be specified through setInvokerLocator(InvokerLocator) before any client commands can be issued.

Parameters:

locator - the locator to use (may be null)

subsystem - the subsystem (or command domain) in which commands will be invoked (may be null)

client_config - the client configuration (may be null or empty)

JBossRemotingRemoteCommunicator

public JBossRemotingRemoteCommunicator(String locatorUri,
                                       String subsystem)
                                throws MalformedURLException

Constructor for JBossRemotingRemoteCommunicator that allows you to indicate the invoker locator to use by specifying the locator's URI.

Parameters:

locatorUri - the locator's URI (must not be null)

subsystem - the subsystem (or command domain) in which commands will be invoked (may be null)

Throws:

MalformedURLException - if failed to create the locator (see InvokerLocator.InvokerLocator(String))

JBossRemotingRemoteCommunicator

public JBossRemotingRemoteCommunicator(String locatorUri,
                                       String subsystem,
                                       Map<String,String> client_config)
                                throws MalformedURLException

Constructor for JBossRemotingRemoteCommunicator that allows you to indicate the invoker locator to use by specifying the locator's URI. The given Map should contain Client configuration attributes.

Parameters:

locatorUri - the locator's URI (must not be null)

subsystem - the subsystem (or command domain) in which commands will be invoked (may be null)

client_config - the client configuration (may be null or empty)

Throws:

MalformedURLException - if failed to create the locator (see InvokerLocator.InvokerLocator(String))

Method Detail

getInvokerLocator

public org.jboss.remoting.InvokerLocator getInvokerLocator()

Returns the invoker locator that is to be used to find the remote JBoss/Remoting server. If null is returned, this communicator will not be able to issue commands.

Returns:

invoker locator used by this client to issue commands

setInvokerLocator

public void setInvokerLocator(String locatorUri)
                       throws MalformedURLException

Sets the invoker locator URI and creates a new locator that is to be used to find the remote JBoss/Remoting server for its subsequent command client invocations. Any existing remoting client is automatically disconnected. The client configuration properties will, however, remain the same as before - so the new clients that are created will have the same configuration attributes. See setInvokerLocator(String, Map) if you want to reconfigure the client with different properties that are more appropriate for the new locator.

Parameters:

locatorUri - the new invoker locator's URI to use for future command client invocations (must not be null)

Throws:

MalformedURLException - if failed to create the locator (see InvokerLocator.InvokerLocator(String))

See Also:

setInvokerLocator(InvokerLocator)

setInvokerLocator

public void setInvokerLocator(String locatorUri,
                              Map<String,String> client_config)
                       throws MalformedURLException

Sets the invoker locator URI and creates a new locator that is to be used to find the remote JBoss/Remoting server for its subsequent command client invocations. Any existing remoting client is automatically disconnected. New remoting clients will also be configured with the new set of configuration properties - thus allowing you to configure the client to be able to handle the new locator.

Parameters:

locatorUri - the new invoker locator's URI to use for future command client invocations (must not be null)

client_config - the client configuration for any new remoting clients that are created (may be null or empty)

Throws:

MalformedURLException - if failed to create the locator (see InvokerLocator.InvokerLocator(String))

See Also:

setInvokerLocator(InvokerLocator)

setInvokerLocator

public void setInvokerLocator(org.jboss.remoting.InvokerLocator locator)

Sets the invoker locator that this communicator should use for its subsequent command client invocations. Any existing remoting client is automatically disconnected.The client configuration properties will, however, remain the same as before - so the new clients that are created will have the same configuration attributes. See setInvokerLocator(InvokerLocator, Map) if you want to reconfigure the client with different properties that are more appropriate for the new locator.

Parameters:

locator - the new invoker locator to use for future command client invocations (must not be null)

Throws:

IllegalArgumentException - if locator is null

setInvokerLocator

public void setInvokerLocator(org.jboss.remoting.InvokerLocator locator,
                              Map<String,String> client_config)

Sets the invoker locator that this communicator should use for its subsequent command client invocations. Any existing remoting client is automatically disconnected. New remoting clients will also be configured with the new set of configuration properties - thus allowing you to configure the client to be able to handle the new locator.

Parameters:

locator - the new invoker locator to use for future command client invocations (must not be null)

client_config - the client configuration for any new remoting clients that are created (may be null or empty)

Throws:

IllegalArgumentException - if locator is null

getSubsystem

public String getSubsystem()

Returns the value of the subsystem that will be used to target command invocations. The subsystem is defined by the JBoss/Remoting API and can be used by the Command Framework to organize command processors into different domains.

Returns:

subsystem (may be null)

setSubsystem

public void setSubsystem(String subsystem)

Sets the value of the subsystem that will be used to target command invocations. The subsystem is defined by the JBoss/Remoting API and can be used by the Command Framework to organize command processors into different domains.

If a remoting client already exists, its subsystem will be changed to the given subsystem.

Parameters:

subsystem - the new value of subsystem (may be null)

getFailureCallback

public FailureCallback getFailureCallback()

Description copied from interface: RemoteCommunicator

Returns the failure callback currently configured within this object.

Specified by:

getFailureCallback in interface RemoteCommunicator

Returns:

the callback (may be null)

setFailureCallback

public void setFailureCallback(FailureCallback callback)

Description copied from interface: RemoteCommunicator

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).

Specified by:

setFailureCallback in interface RemoteCommunicator

Parameters:

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

getInitializeCallback

public InitializeCallback getInitializeCallback()

Description copied from interface: RemoteCommunicator

Returns the initialize callback currently configured within this object.

Specified by:

getInitializeCallback in interface RemoteCommunicator

Returns:

the callback (may be null)

setInitializeCallback

public void setInitializeCallback(InitializeCallback callback)

Description copied from interface: RemoteCommunicator

Sets the given initialize callback as the one that will be notified when this object attempts to send its very first message after a RemoteCommunicator.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 RemoteCommunicator.sendWithoutCallbacks(Command) or RemoteCommunicator.sendWithoutInitializeCallback(Command).

Specified by:

setInitializeCallback in interface RemoteCommunicator

getRemoteEndpoint

public String getRemoteEndpoint()

Description copied from interface: RemoteCommunicator

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

Specified by:

getRemoteEndpoint in interface RemoteCommunicator

Returns:

remote endpoint string

setRemoteEndpoint

public void setRemoteEndpoint(String endpoint)
                       throws Exception

Description copied from interface: RemoteCommunicator

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

Specified by:

setRemoteEndpoint in interface RemoteCommunicator

Parameters:

endpoint - the new remote endpoint

Throws:

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

getClientConfiguration

public Map<String,String> getClientConfiguration()

Returns the map of name/value pairs of client configuration settings used when creating the client. The returned map is a copy - changing its contents has no effect on the clients that already have been or will be created by this object. Use setInvokerLocator(InvokerLocator, Map) or setInvokerLocator(String, Map) to change the map contents.

Returns:

copy of the configuration that will be used when creating clients (may be null or empty)

connect

public void connect()
             throws Exception

Description copied from interface: RemoteCommunicator

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

Specified by:

connect in interface RemoteCommunicator

Throws:

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

See Also:

RemoteCommunicator.disconnect()

disconnect

public void disconnect()

Description copied from interface: RemoteCommunicator

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 RemoteCommunicator.connect().

Specified by:

disconnect in interface RemoteCommunicator

isConnected

public boolean isConnected()

Description copied from interface: RemoteCommunicator

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

Specified by:

isConnected in interface RemoteCommunicator

Returns:

true if connected to a remote endpoint; false otherise

sendWithoutCallbacks

public CommandResponse sendWithoutCallbacks(Command command)
                                     throws Throwable

Description copied from interface: RemoteCommunicator

This is the same as RemoteCommunicator.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.

Specified by:

sendWithoutCallbacks in interface RemoteCommunicator

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

public CommandResponse sendWithoutInitializeCallback(Command command)
                                              throws Throwable

Description copied from interface: RemoteCommunicator

This is the same as RemoteCommunicator.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.

Specified by:

sendWithoutInitializeCallback in interface RemoteCommunicator

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)

send

public CommandResponse send(Command command)
                     throws Throwable

Description copied from interface: RemoteCommunicator

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.

Specified by:

send in interface RemoteCommunicator

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)

toString

public String toString()

Overrides:

toString in class Object

getRemotingClient

protected org.jboss.remoting.Client getRemotingClient()
                                               throws Exception

Returns the remoting client that is to be used to transport the command request to the server. If for any reason the client cannot be created, an exception is thrown. This will happen if the invoker locator has not been specified (see setInvokerLocator(InvokerLocator)).

This method will cache the client and connect to the server automatically. Note that the client will be disconnected whenever the invoker is reset via setInvokerLocator(InvokerLocator). Therefore, callers should never cache the returned object themselves - always call this method to obtain a reference to the client.

Returns:

the client to be used to transport the command request to the server

Throws:

Exception - if failed to create the client for whatever reason