com.sun.management.comm
Class CommunicatorServer

java.lang.Object
  extended by com.sun.jdmk.comm.CommunicatorServer
      extended by com.sun.management.comm.CommunicatorServer
All Implemented Interfaces:
CommunicatorServerMBean, Runnable, MBeanRegistration, NotificationBroadcaster
Direct Known Subclasses:
SnmpAdaptorServer

public abstract class CommunicatorServer
extends CommunicatorServer
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.

Since:
Java DMK 5.1

Field Summary
 
Fields inherited from class com.sun.jdmk.comm.CommunicatorServer
HTML_TYPE, HTTP_TYPE, HTTPS_TYPE, OFFLINE, ONLINE, RMI_TYPE, SNMP_TYPE, STARTING, STOPPING
 
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
 

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
Overrides:
start in class CommunicatorServer

stop

public void stop()
Stops this CommunicatorServer.

Has no effect if this CommunicatorServer is OFFLINE or STOPPING.

Specified by:
stop in interface CommunicatorServerMBean
Overrides:
stop in class CommunicatorServer

isActive

public boolean isActive()
Tests whether the CommunicatorServer is active.

Specified by:
isActive in interface CommunicatorServerMBean
Overrides:
isActive in class CommunicatorServer
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:

Specified by:
waitState in interface CommunicatorServerMBean
Overrides:
waitState in class CommunicatorServer
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
Overrides:
getState in class CommunicatorServer
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
Overrides:
getStateString in class CommunicatorServer
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
Overrides:
getHost in class CommunicatorServer
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
Overrides:
getPort in class CommunicatorServer
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
Overrides:
setPort in class CommunicatorServer
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
Specified by:
getProtocol in class CommunicatorServer
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
Overrides:
run in class CommunicatorServer

doError

protected abstract void doError(Exception e)
                         throws CommunicationException
Specified by:
doError in class CommunicatorServer
Throws:
CommunicationException

doBind

protected abstract void doBind()
                        throws CommunicationException,
                               InterruptedException
Specified by:
doBind in class CommunicatorServer
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.

Specified by:
doReceive in class CommunicatorServer
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.

Specified by:
doProcess in class CommunicatorServer
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.

Specified by:
doUnbind in class CommunicatorServer
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.

Overrides:
getMBeanServer in class CommunicatorServer

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.

Overrides:
setMBeanServer in class CommunicatorServer
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
Overrides:
addNotificationListener in class CommunicatorServer
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
Overrides:
removeNotificationListener in class CommunicatorServer
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
Overrides:
getNotificationInfo in class CommunicatorServer

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception
Preregister method of connector.

Specified by:
preRegister in interface MBeanRegistration
Overrides:
preRegister in class CommunicatorServer
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
Overrides:
postRegister in class CommunicatorServer
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
Overrides:
preDeregister in class CommunicatorServer
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
Overrides:
postDeregister in class CommunicatorServer

Open Source build 02
opendmk-1.0-b02 2007.10.01_19:17:46_MEST

Copyright 1998-2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.