org.rhq.enterprise.communications

Class ServiceContainer

java.lang.Object

org.rhq.enterprise.communications.ServiceContainer

public class ServiceContainer
extends Object

This is the main container that manages the communications services required by the server to accept incoming command requests.

Author:

John Mazzitelli

Field Summary

Fields

Modifier and Type	Field and Description
static String	JMX_DOMAIN The JMX domain where all the services are registered.
static ObjectName	OBJECTNAME_CMDSERVICE_DIRECTORY The default name of the network registry service.
static ObjectName	OBJECTNAME_CONNECTOR The default name of the multicast detector service.
static ObjectName	OBJECTNAME_MULTICAST_DETECTOR The default name of the multicast detector service.
static ObjectName	OBJECTNAME_NETWORK_REGISTRY The default name of the network registry service.
static ObjectName	OBJECTNAME_SSL_SERVERSOCKET_FACTORY The default name of the SSL server socket factory service.

Constructor Summary

Constructors

Constructor and Description
ServiceContainer() Private to prevent external instantiation.

Method Summary

Methods

Modifier and Type	Method and Description
void	addCommandListener(CommandListener listener) Adds the given listener so it can be notified everytime a new command is received.
CommandServiceId	addCommandService(CommandService command_service) Adds the given command service to the service container.
CommandServiceId	addCommandService(String command_service_class_name) Adds the given command service to the service container where the command service classname is specified.
void	addCustomData(String key, Object data) Stores the given custom data to be identified with the given key.
void	addDiscoveryListener(AutoDiscoveryListener listener) Adds the given object as a listener that will receive notifications when new servers coming online have been discovered or old servers were discovered to have gone offline.
void	addInvocationHandler(String subsystem, org.jboss.remoting.ServerInvocationHandler handler) Allows a caller to install their own invocation handler for another subsystem.
Long	addRemoteInputStream(InputStream in) Enables the input stream to receive remote invocations.
Long	addRemoteOutputStream(OutputStream out) Enables the output stream to receive remote invocations.
void	addRemotePojo(Object pojo, String interface_name) Enables the POJO to receive remote invocations.
<T> void	addRemotePojo(T pojo, Class<T> pojo_interface) Similar to addRemotePojo(Object, String) except this method allows you to provide the actual interface class representation, as opposed to its name as a String.
void	addServiceContainerSenderCreationListener(ServiceContainerSenderCreationListener listener) Adds the given listener so it will be notified everytime this service container creates a new sender.
ClientCommandSender	createClientCommandSender(String server_endpoint, ClientCommandSenderConfiguration client_config) A convienence method that takes a client configuration and builds a sender object with it.
ClientCommandSender	createClientCommandSenderWithSecurity(String server_endpoint, ClientCommandSenderConfiguration client_config) A convienence method that takes a client configuration and builds a sender object with it.
ClientCommandSenderConfiguration	getClientConfiguration() Returns the configuration that the server-side services will use when it needs to be a client itself and send commands to a remote server.
ConcurrencyManager	getConcurrencyManager() Returns a manager that can be used by objects that either own, use or have access to this ServiceContainer object.
ServiceContainerConfiguration	getConfiguration() Returns the configuration preferences that were used when the service container was started.
Object	getCustomData(String key) Returns custom data identified with the given key.
MBeanServer	getMBeanServer() Returns the MBeanServer that is housing all the services.
String	getServerEndpoint() Returns a string that identifies the server's socket endpoint.
void	removeCommandListener(CommandListener listener) Removes the given listener so it no longer is notified when a new command is received.
void	removeCommandService(CommandServiceId id) Removes a command service that is identified by the given ID.
void	removeDiscoveryListener(AutoDiscoveryListener listener) Removes the given object as a listener so it will no longer receive discovery notifications.
void	removeInvocationHandler(String subsystem)
boolean	removeRemoteInputStream(Long stream_id) Removes a remoted input stream that has the given ID from the remote framework such that the stream is no longer remotely accessible.
boolean	removeRemoteOutputStream(Long stream_id) Removes a remoted output stream that has the given ID from the remote framework such that the stream is no longer remotely accessible.
void	removeRemotePojo(Class remote_interface) Removes the given remote interface from the remote framework such that the POJO is no longer remoted.
void	removeRemotePojo(String interface_name) Removes the given remote interface from the remote framework such that the POJO is no longer remoted.
void	removeServiceContainerSenderCreationListener(ServiceContainerSenderCreationListener listener) Removes the given listener so it no longer is notified when this service container creates a new sender.
void	setConcurrencyManager(ConcurrencyManager concurrencyManager) Allows the caller to provide a reconfigured concurrency manager.
void	shutdown() This method should be called when the services are no longer needed (for example, when the VM is shutting down).
void	start(Preferences configuration, ClientCommandSenderConfiguration client_configuration) This initializes the container with the given set of configuration preferences and starts the communications services.
void	start(Preferences configuration, ClientCommandSenderConfiguration client_configuration, MBeanServer mbs) This initializes the container with the given set of configuration preferences and starts the communications services using the given MBeanServer to register the services.

Methods inherited from class java.lang.Object

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

Field Detail

JMX_DOMAIN

public static final String JMX_DOMAIN

The JMX domain where all the services are registered.

See Also:

Constant Field Values

OBJECTNAME_CMDSERVICE_DIRECTORY

public static final ObjectName OBJECTNAME_CMDSERVICE_DIRECTORY

The default name of the network registry service.

OBJECTNAME_NETWORK_REGISTRY

public static final ObjectName OBJECTNAME_NETWORK_REGISTRY

The default name of the network registry service.

OBJECTNAME_MULTICAST_DETECTOR

public static final ObjectName OBJECTNAME_MULTICAST_DETECTOR

The default name of the multicast detector service.

OBJECTNAME_CONNECTOR

public static final ObjectName OBJECTNAME_CONNECTOR

The default name of the multicast detector service.

OBJECTNAME_SSL_SERVERSOCKET_FACTORY

public static final ObjectName OBJECTNAME_SSL_SERVERSOCKET_FACTORY

The default name of the SSL server socket factory service.

Constructor Detail

ServiceContainer

public ServiceContainer()

Private to prevent external instantiation.

Method Detail

getCustomData

public Object getCustomData(String key)

Returns custom data identified with the given key. If no data exists that is identified by that key, null is returned.

Parameters:

key - identifies the custom data to return - if null, this method returns null

Returns:

the custom data or null if there is no custom data associated with the given key

addCustomData

public void addCustomData(String key,
                 Object data)

Stores the given custom data to be identified with the given key. You can retrieve this data via getCustomData(String).

Parameters:

key - identifies the custom data to store - if null, this method does nothing and returns.

data - custom data to add - it will be associated with the given key.

getConfiguration

public ServiceContainerConfiguration getConfiguration()

Returns the configuration preferences that were used when the service container was started.

If this container is not started (e.g. it has been shutdown()), this will return null.

Returns:

configuration properties

getMBeanServer

public MBeanServer getMBeanServer()

Returns the MBeanServer that is housing all the services.

If this container is not initialized (e.g. it has been shutdown()), this will return null.

Returns:

mbs

getServerEndpoint

public String getServerEndpoint()

Returns a string that identifies the server's socket endpoint.

Returns:

server endpoint

getClientConfiguration

public ClientCommandSenderConfiguration getClientConfiguration()

Returns the configuration that the server-side services will use when it needs to be a client itself and send commands to a remote server. The returned client configuration is a copy - changes made to it will not affect this container's clients.

Returns:

configuration of the clients that are created by this container

getConcurrencyManager

public ConcurrencyManager getConcurrencyManager()

Returns a manager that can be used by objects that either own, use or have access to this ServiceContainer object. It can be used, for example, by command services to restrict concurrent access. Callers must not cache this object for more than a single permit/release cycle or otherwise assume they know the specific concurrency manager instance that is being used, in case a new manager has been installed with different configuration (see setConcurrencyManager(ConcurrencyManager)).

Returns:

concurrency manager object

setConcurrencyManager

public void setConcurrencyManager(ConcurrencyManager concurrencyManager)

Allows the caller to provide a reconfigured concurrency manager. This is useful if new concurrency limits should be imposed on users of this manager. It is assumed clients are not caching the object returned by getConcurrencyManager(), otherwise, they will not pick up the changes in any new managers that are installed by calls to this setter.

We can't easily reconfigure existing concurrency manager objects due to the nature of the counting semaphore objects and not being able to nicely resize them to a specific value - hence we ask clients to get getConcurrencyManager() when they need to get a permit.

Parameters:

concurrencyManager - the new concurrency manager object that is being installed

createClientCommandSenderWithSecurity

public ClientCommandSender createClientCommandSenderWithSecurity(String server_endpoint,
                                                        ClientCommandSenderConfiguration client_config)

A convienence method that takes a client configuration and builds a sender object with it. Note that regardless of the transport specified in server_endpoint, this method will always place security configuration into the underlying remote communicator.

Parameters:

server_endpoint - a string that represents the remote endpoint to which the sender will connect and send commands

client_config - the client configuration which with to configure the sender

Returns:

a sender with the client configuration as defined in this container

Throws:

RuntimeException - if failed to create the sender

createClientCommandSender

public ClientCommandSender createClientCommandSender(String server_endpoint,
                                            ClientCommandSenderConfiguration client_config)

A convienence method that takes a client configuration and builds a sender object with it. Note that this method will examine the transport specified in server_endpoint, and if (and only if) that transport requires security, the underlying remote communicator will get configured with security information found in the given client configuration. This is different than createClientCommandSenderWithSecurity(String, ClientCommandSenderConfiguration).

Note that the given client_config may have its values modified by any registered sender creation listeners, so callers should pass in a copy of their config object if they do not want it altered.

Parameters:

server_endpoint - a string that represents the remote endpoint to which the sender will connect and send commands

client_config - the client configuration which with to configure the sender

Returns:

a sender with the client configuration as defined in this container

Throws:

RuntimeException - if failed to create the sender

start

public void start(Preferences configuration,
         ClientCommandSenderConfiguration client_configuration)
           throws Exception

This initializes the container with the given set of configuration preferences and starts the communications services. The configuration preferences are used to configure the internal services. Note that if ServiceContainerConfigurationConstants.DISABLE_COMMUNICATIONS is true, this method does nothing - all communications services will not be started.

The client_configuration is used in case any of the server-side services need to act as a client and send commands out to another external server (as is the case when input streams are being remoted).

Parameters:

configuration - set of configuration preferences used to configure the internal server-side services

client_configuration - set of configuration preferences used to configure the internal client-side services

Throws:

Exception - if failed to initialize all of the services successfully

See Also:

start(Preferences, ClientCommandSenderConfiguration, MBeanServer)

start

public void start(Preferences configuration,
         ClientCommandSenderConfiguration client_configuration,
         MBeanServer mbs)
           throws Exception

This initializes the container with the given set of configuration preferences and starts the communications services using the given MBeanServer to register the services. The configuration preferences are used to configure the internal services. Note that if ServiceContainerConfigurationConstants.DISABLE_COMMUNICATIONS is true, this method does nothing - all communications services will not be started.

The client_configuration is used in case any of the server-side services need to act as a client and send commands out to another external server (as is the case when input streams are being remoted).

If mbs is null, one will be provided. First, if ServiceContainerConfiguration.getMBeanServerName() returns null (meaning, it is not configured), then the built-in JVM platform MBeanServer will be used. If the configured MBeanServer name is non-null, a scan of all registered MBeanServers will be performed to see if an MBeanServer is registered with a default domain name equal to that configured MBeanServer name. If one exists, it will be used. If one does not yet exist, one will be created.

Parameters:

configuration - configuration preferences used to configure the internal server-side services

client_configuration - configuration preferences used to configure the internal client-side services

mbs - the MBeanServer where the services will be registered (may be null)

Throws:

Exception - if failed to initialize all of the services successfully

shutdown

public void shutdown()

This method should be called when the services are no longer needed (for example, when the VM is shutting down). All started services will be stopped.

addDiscoveryListener

public void addDiscoveryListener(AutoDiscoveryListener listener)

Adds the given object as a listener that will receive notifications when new servers coming online have been discovered or old servers were discovered to have gone offline. You can add listeners at any time; regardless of whether this object is started or stopped.

Parameters:

listener - the object that will receive the notifications

removeDiscoveryListener

public void removeDiscoveryListener(AutoDiscoveryListener listener)

Removes the given object as a listener so it will no longer receive discovery notifications. You can remove listeners at any time; regardless of whether this object is started or stopped.

Parameters:

listener - the object that will no longer receive the notifications

addCommandListener

public void addCommandListener(CommandListener listener)

Adds the given listener so it can be notified everytime a new command is received. If the comm services are not already started, this listener will be added once the services are started.

Parameters:

listener -

removeCommandListener

public void removeCommandListener(CommandListener listener)

Removes the given listener so it no longer is notified when a new command is received.

Parameters:

listener -

addServiceContainerSenderCreationListener

public void addServiceContainerSenderCreationListener(ServiceContainerSenderCreationListener listener)

Adds the given listener so it will be notified everytime this service container creates a new sender.

Parameters:

listener -

removeServiceContainerSenderCreationListener

public void removeServiceContainerSenderCreationListener(ServiceContainerSenderCreationListener listener)

Removes the given listener so it no longer is notified when this service container creates a new sender.

Parameters:

listener -

addCommandService

public CommandServiceId addCommandService(CommandService command_service)
                                   throws Exception

Adds the given command service to the service container. Once added, the command service will be able to handle incoming requests for those commands it supports.

Parameters:

command_service - the new command service to add

Returns:

an ID that can be used by this object to later find the service again

Throws:

Exception - if failed to add the command service - it will not be able to process commands

addCommandService

public CommandServiceId addCommandService(String command_service_class_name)
                                   throws Exception

Adds the given command service to the service container where the command service classname is specified. Once added, the command service will be able to handle incoming requests for those commands it supports.

Parameters:

command_service_class_name - the class name of the new command service to add

Returns:

an ID that can be used by this object to later find the service again

Throws:

Exception - if failed to instantiate and add the command service - it will not be able to process commands

See Also:

addCommandService(CommandService)

removeCommandService

public void removeCommandService(CommandServiceId id)

Removes a command service that is identified by the given ID.

Parameters:

id - identifies the command service to remove

addRemotePojo

public void addRemotePojo(Object pojo,
                 String interface_name)
                   throws Exception

Enables the POJO to receive remote invocations. This method will add the appropriate command service if one is needed. Once this method returns, the given POJO can be remotely invoked via a ClientRemotePojoFactory generated proxy object.

Note that only one POJO of the given interface can be remoted.

Parameters:

pojo - the object to make remotely accessible

interface_name - the name of one of the pojo's interfaces that is to be exposed as its remote interface

Throws:

Exception - if failed to instantiate and add the command service - it will not be able to process remote invocation requests to the POJO

See Also:

ClientRemotePojoFactory.getRemotePojo(Class)

addRemotePojo

public <T> void addRemotePojo(T pojo,
                     Class<T> pojo_interface)
                   throws Exception

Similar to addRemotePojo(Object, String) except this method allows you to provide the actual interface class representation, as opposed to its name as a String.

Parameters:

pojo - the object to make remotely accessible

pojo_interface - the interface that is to be exposed as its remote interface

Throws:

Exception - if failed to instantiate and add the command service - it will not be able to process remote invocation requests to the POJO

removeRemotePojo

public void removeRemotePojo(String interface_name)

Removes the given remote interface from the remote framework such that the POJO is no longer remoted. Once this method returns, the POJO that was servicing requests for that interface is no longer remotely accessible.

Parameters:

interface_name - the name of the interface that was exposed remotely and is to be removed

removeRemotePojo

public void removeRemotePojo(Class remote_interface)

Removes the given remote interface from the remote framework such that the POJO is no longer remoted. Once this method returns, the POJO that was servicing requests for that interface is no longer remotely accessible.

Parameters:

remote_interface - the interface that was exposed remotely and is to be removed

addRemoteInputStream

public Long addRemoteInputStream(InputStream in)
                          throws Exception

Enables the input stream to receive remote invocations. This method will add the appropriate command service if one is needed. Once this method returns, the given stream can be remotely invoked via a RemoteInputStream proxy object.

Parameters:

in - the input stream to expose to remote clients

Returns:

an identification object that is to be used as the stream ID and can also be used to remove the input stream service.

Throws:

Exception - if failed to instantiate and add the command service - it will not be able to process remote invocation requests to access input streams

See Also:

RemoteInputStreamCommandService.addInputStream(InputStream)

addRemoteOutputStream

public Long addRemoteOutputStream(OutputStream out)
                           throws Exception

Enables the output stream to receive remote invocations. This method will add the appropriate command service if one is needed. Once this method returns, the given stream can be remotely invoked via a RemoteOutputStream proxy object.

Parameters:

out - the output stream to expose to remote clients

Returns:

an identification object that is to be used as the stream ID and can also be used to remove the output stream service.

Throws:

Exception - if failed to instantiate and add the command service - it will not be able to process remote invocation requests to access output streams

See Also:

RemoteOutputStreamCommandService.addOutputStream(OutputStream)

removeRemoteInputStream

public boolean removeRemoteInputStream(Long stream_id)

Removes a remoted input stream that has the given ID from the remote framework such that the stream is no longer remotely accessible.

Parameters:

stream_id - the ID of the stream that was exposed remotely and is to be removed

Returns:

true if the stream ID was valid and a stream was removed; false if the ID referred to a non-existent stream (which could mean either the stream was never registered at all or it was registered but has already been removed)

See Also:

RemoteInputStreamCommandService.removeInputStream(Long)

removeRemoteOutputStream

public boolean removeRemoteOutputStream(Long stream_id)

Removes a remoted output stream that has the given ID from the remote framework such that the stream is no longer remotely accessible.

Parameters:

stream_id - the ID of the stream that was exposed remotely and is to be removed

Returns:

true if the stream ID was valid and a stream was removed; false if the ID referred to a non-existent stream (which could mean either the stream was never registered at all or it was registered but has already been removed)

See Also:

RemoteOutputStreamCommandService.removeOutputStream(Long)

addInvocationHandler

public void addInvocationHandler(String subsystem,
                        org.jboss.remoting.ServerInvocationHandler handler)
                          throws Exception

Allows a caller to install their own invocation handler for another subsystem. This allows the caller to use this ServiceContainer to set up all the infrastructure so the caller doesn't have to do it all. All the caller needs is an invocation handler to handle their own remote messages. To stop the handler from processing messages, call removeInvocationHandler(String).

Parameters:

subsystem - the new subsystem whose messages will be handled by the given handler

handler - used to handle incoming messages for the given subsystem

Throws:

Exception - if the remote connector hasn't been created/started or the handler failed to get added for some reason

removeInvocationHandler

public void removeInvocationHandler(String subsystem)
                             throws Exception

Throws:

Exception