com.sun.jdmk.comm
Class CommunicatorServer

java.lang.Object
  com.sun.jdmk.comm.CommunicatorServer

All Implemented Interfaces:

CommunicatorServerMBean, Runnable, MBeanRegistration, NotificationBroadcaster

Direct Known Subclasses:

CommunicatorServer, GenericHttpConnectorServer, HtmlAdaptorServer, RmiConnectorServer

public abstract class CommunicatorServer
extends Object
implements Runnable, MBeanRegistration, NotificationBroadcaster, CommunicatorServerMBean

Defines generic behavior for the server part of a connector or an adaptor. Most connectors or adaptors extend CommunicatorServer and inherit this behavior. Connectors or adaptors that do not fit into this model do not extend CommunicatorServer.

A CommunicatorServer is an active object, it listens for client requests and processes them in its own thread. When necessary, a CommunicatorServer creates other threads to process multiple requests concurrently.

A CommunicatorServer object can be stopped by calling the stop method. When it is stopped, the CommunicatorServer no longer listens to client requests and no longer holds any thread or communication resources. It can be started again by calling the start method.

A CommunicatorServer has a State attribute which reflects its activity.

CommunicatorServer	State
stopped	OFFLINE
starting	STARTING
running	ONLINE
stopping	STOPPING

The STARTING state marks the transition from OFFLINE to ONLINE.

The STOPPING state marks the transition from ONLINE to OFFLINE. This occurs when the CommunicatorServer is finishing or interrupting active requests.

When a CommunicatorServer is unregistered from the MBeanServer, it is stopped automatically.

When the value of the State attribute changes the CommunicatorServer sends a AttributeChangeNotification to the registered listeners, if any.

Field Summary

static int	HTML_TYPE Indicates that it is an HTML connector type.
static int	HTTP_TYPE Indicates that it is an HTTP connector type.
static int	HTTPS_TYPE Indicates that it is an HTTPS connector type.
static int	OFFLINE Represents an OFFLINE state.
static int	ONLINE Represents an ONLINE state.
static int	RMI_TYPE Indicates that it is an RMI connector type.
static int	SNMP_TYPE Indicates that it is an SNMP connector type.
static int	STARTING Represents a STARTING state.
static int	STOPPING Represents a STOPPING state.

Constructor Summary

CommunicatorServer(int connectorType)
Instantiates a CommunicatorServer.

Method Summary

void	addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener for the notifications emitted by this CommunicatorServer.
protected abstract void	doBind()
protected abstract void	doError(Exception e)
protected abstract void	doProcess() doProcess() is called after doReceive(): it should process the requests of the incoming client.
protected abstract void	doReceive() doReceive() should block until a client is available.
protected abstract void	doUnbind() doUnbind() is called whenever the connector goes OFFLINE, except if doBind() has thrown an exception.
String	getHost() Gets the host name used by this CommunicatorServer.
MBeanServer	getMBeanServer() Get the MBeanServer object to which incoming requests are sent.
MBeanNotificationInfo[]	getNotificationInfo() Returns an array of MBeanNotificationInfo objects describing the notification types sent by this CommunicatorServer.
int	getPort() Gets the port number used by this CommunicatorServer.
abstract String	getProtocol() Gets the protocol being used by this CommunicatorServer.
int	getState() Gets the state of this CommunicatorServer as an integer.
String	getStateString() Gets the state of this CommunicatorServer as a string.
boolean	isActive() Tests whether the CommunicatorServer is active.
void	postDeregister() Do nothing.
void	postRegister(Boolean registrationDone)
void	preDeregister() Stop the connector.
ObjectName	preRegister(MBeanServer server, ObjectName name) Preregister method of connector.
void	removeNotificationListener(NotificationListener listener) Removes the specified listener from this CommunicatorServer.
void	run() For Java DMK internal use only.
void	setMBeanServer(MBeanServer newMBS) Set the MBeanServer object to which incoming requests are sent.
void	setPort(int port) Sets the port number used by this CommunicatorServer.
void	start() Starts this CommunicatorServer.
void	stop() Stops this CommunicatorServer.
boolean	waitState(int wantedState, long timeout) Waits until either the State attribute of this MBean equals the specified wantedState parameter, or the specified timeout has elapsed.

Methods inherited from class java.lang.Object

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

Field Detail

ONLINE

public static final int ONLINE

Represents an ONLINE state.

See Also:

Constant Field Values

OFFLINE

public static final int OFFLINE

Represents an OFFLINE state.

See Also:

Constant Field Values

STOPPING

public static final int STOPPING

Represents a STOPPING state.

See Also:

Constant Field Values

STARTING

public static final int STARTING

Represents a STARTING state.

See Also:

Constant Field Values

RMI_TYPE

public static final int RMI_TYPE

Indicates that it is an RMI connector type.

See Also:

Constant Field Values

HTTP_TYPE

public static final int HTTP_TYPE

Indicates that it is an HTTP connector type.

See Also:

Constant Field Values

HTML_TYPE

public static final int HTML_TYPE

Indicates that it is an HTML connector type.

See Also:

Constant Field Values

SNMP_TYPE

public static final int SNMP_TYPE

Indicates that it is an SNMP connector type.

See Also:

Constant Field Values

HTTPS_TYPE

public static final int HTTPS_TYPE

Indicates that it is an HTTPS connector type.

See Also:

Constant Field Values

Constructor Detail

CommunicatorServer

public CommunicatorServer(int connectorType)
                   throws IllegalArgumentException

Instantiates a CommunicatorServer.

Parameters:

connectorType - Indicates the connector type. Possible values are: RMI_TYPE, HTTP_TYPE, HTML_TYPE, SNMP_TYPE, HTTPS_TYPE.

Throws:

java.lang.IllegalArgumentException - This connector type is not correct.

IllegalArgumentException

Method Detail

start

public void start()

Starts this CommunicatorServer.

Has no effect if this CommunicatorServer is ONLINE or STOPPING.

Specified by:

start in interface CommunicatorServerMBean

stop

public void stop()

Stops this CommunicatorServer.

Has no effect if this CommunicatorServer is OFFLINE or STOPPING.

Specified by:

stop in interface CommunicatorServerMBean

isActive

public boolean isActive()

Tests whether the CommunicatorServer is active.

Specified by:

isActive in interface CommunicatorServerMBean

Returns:

True if connector is ONLINE; false otherwise.

waitState

public boolean waitState(int wantedState,
                         long timeout)

Waits until either the State attribute of this MBean equals the specified wantedState parameter, or the specified timeout has elapsed. The method waitState returns with a boolean value indicating whether the specified wantedState parameter equals the value of this MBean's State attribute at the time the method terminates.

Two special cases for the timeout parameter value are:

• if timeout is negative then waitState returns immediately (i.e. does not wait at all),
• if timeout equals zero then waitState waits until the value of this MBean's State attribute is the same as the wantedState parameter (i.e. will wait indefinitely if this condition is never met).

Specified by:

waitState in interface CommunicatorServerMBean

Parameters:

wantedState - The value of this MBean's State attribute to wait for. wantedState can be one of: CommunicatorServer.OFFLINE, CommunicatorServer.ONLINE, CommunicatorServer.STARTING, CommunicatorServer.STOPPING.

timeout - The maximum time to wait for, in milliseconds, if positive. Infinite time out if 0, or no waiting at all if negative.

Returns:

true if the value of this MBean's State attribute is the same as the wantedState parameter; false otherwise.

getState

public int getState()

Gets the state of this CommunicatorServer as an integer.

Specified by:

getState in interface CommunicatorServerMBean

Returns:

ONLINE, OFFLINE, STARTING or STOPPING.

getStateString

public String getStateString()

Gets the state of this CommunicatorServer as a string.

Specified by:

getStateString in interface CommunicatorServerMBean

Returns:

One of the strings "ONLINE", "OFFLINE", "STARTING" or "STOPPING".

getHost

public String getHost()

Gets the host name used by this CommunicatorServer.

Specified by:

getHost in interface CommunicatorServerMBean

Returns:

The host name used by this CommunicatorServer.

getPort

public int getPort()

Gets the port number used by this CommunicatorServer.

Specified by:

getPort in interface CommunicatorServerMBean

Returns:

The port number used by this CommunicatorServer.

setPort

public void setPort(int port)
             throws IllegalStateException

Sets the port number used by this CommunicatorServer.

Specified by:

setPort in interface CommunicatorServerMBean

Parameters:

port - The port number used by this CommunicatorServer.

Throws:

IllegalStateException - This method has been invoked while the communicator was ONLINE or STARTING.

getProtocol

public abstract String getProtocol()

Gets the protocol being used by this CommunicatorServer.

Specified by:

getProtocol in interface CommunicatorServerMBean

Returns:

The protocol as a string.

run

public void run()

For Java DMK internal use only.

The run method executed by this connector's main thread.

Specified by:

run in interface Runnable

doError

protected abstract void doError(Exception e)
                         throws CommunicationException

Throws:

CommunicationException

doBind

protected abstract void doBind()
                        throws CommunicationException,
                               InterruptedException

Throws:

CommunicationException

InterruptedException

doReceive

protected abstract void doReceive()
                           throws CommunicationException,
                                  InterruptedException

doReceive() should block until a client is available. If this method throws an exception, doProcess() is not called but doUnbind() is called then run() stops.

Throws:

CommunicationException

InterruptedException

doProcess

protected abstract void doProcess()
                           throws CommunicationException,
                                  InterruptedException

doProcess() is called after doReceive(): it should process the requests of the incoming client. If it throws an exception, doUnbind() is called and run() stops.

Throws:

CommunicationException

InterruptedException

doUnbind

protected abstract void doUnbind()
                          throws CommunicationException,
                                 InterruptedException

doUnbind() is called whenever the connector goes OFFLINE, except if doBind() has thrown an exception.

Throws:

CommunicationException

InterruptedException

getMBeanServer

public MBeanServer getMBeanServer()

Get the MBeanServer object to which incoming requests are sent. This is either the MBean server in which this connector is registered, or an MBeanServerForwarder leading to that server.

setMBeanServer

public void setMBeanServer(MBeanServer newMBS)
                    throws IllegalArgumentException,
                           IllegalStateException

Set the MBeanServer object to which incoming requests are sent. This must be either the MBean server in which this connector is registered, or an MBeanServerForwarder leading to that server. An MBeanServerForwarder mbsf leads to an MBean server mbs if mbsf.getMBeanServer() is either mbs or an MBeanServerForwarder leading to mbs.

Throws:

IllegalArgumentException - if newMBS is neither the MBean server in which this connector is registered nor an MBeanServerForwarder leading to that server.

IllegalStateException - This method has been invoked while the communicator was ONLINE or STARTING.

addNotificationListener

public void addNotificationListener(NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
                             throws IllegalArgumentException

Adds a listener for the notifications emitted by this CommunicatorServer. There is only one type of notifications sent by the CommunicatorServer: they are AttributeChangeNotification, sent when the State attribute of this CommunicatorServer changes.

Specified by:

addNotificationListener in interface NotificationBroadcaster

Parameters:

listener - The listener object which will handle the emitted notifications.

filter - The filter object. If filter is null, no filtering will be performed before handling notifications.

handback - An object which will be sent back unchanged to the listener when a notification is emitted.

Throws:

IllegalArgumentException - Listener parameter is null.

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException

Removes the specified listener from this CommunicatorServer. Note that if the listener has been registered with different handback objects or notification filters, all entries corresponding to the listener will be removed.

Specified by:

removeNotificationListener in interface NotificationBroadcaster

Parameters:

listener - The listener object to be removed.

Throws:

ListenerNotFoundException - The listener is not registered.

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()

Returns an array of MBeanNotificationInfo objects describing the notification types sent by this CommunicatorServer. There is only one type of notifications sent by the CommunicatorServer: it is AttributeChangeNotification, sent when the State attribute of this CommunicatorServer changes.

Specified by:

getNotificationInfo in interface NotificationBroadcaster

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

Preregister method of connector.

Specified by:

preRegister in interface MBeanRegistration

Parameters:

server - The MBeanServer in which the MBean will be registered.

name - The object name of the MBean.

Returns:

The name of the MBean registered.

Throws:

Exception - This exception should be caught by the MBeanServer and re-thrown as an MBeanRegistrationException.

postRegister

public void postRegister(Boolean registrationDone)

Specified by:

postRegister in interface MBeanRegistration

Parameters:

registrationDone - Indicates whether or not the MBean has been successfully registered in the MBeanServer. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception

Stop the connector.

Specified by:

preDeregister in interface MBeanRegistration

Throws:

Exception - This exception should be caught by the MBeanServer and re-thrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()

Do nothing.

Specified by:

postDeregister in interface MBeanRegistration