public abstract class

CommunicatorServer

extends Object
implements CommunicatorServerMBean Runnable MBeanRegistration NotificationBroadcaster
java.lang.Object
   ↳ com.sun.jmx.snmp.daemon.CommunicatorServer
Known Direct Subclasses

Class Overview

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.

This API is a Sun Microsystems internal API and is subject to change without notice.

Summary

Constants
int OFFLINE Represents an OFFLINE state.
int ONLINE Represents an ONLINE state.
int SNMP_TYPE Indicates that it is an SNMP connector type.
int STARTING Represents a STARTING state.
int STOPPING Represents a STOPPING state.
Public Constructors
CommunicatorServer(int connectorType)
Instantiates a CommunicatorServer.
Public Methods
void addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)
Adds a listener for the notifications emitted by this CommunicatorServer.
String getHost()
Gets the host name used by this CommunicatorServer.
synchronized 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)
Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
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 SNMP Runtime internal use only.
synchronized 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 start(long timeout)
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.

Protected Methods
Thread createMainThread()
abstract void doBind()
abstract void doError(Exception e)
abstract void doProcess()
doProcess() is called after doReceive(): it should process the requests of the incoming client.
abstract void doReceive()
doReceive() should block until a client is available.
abstract void doUnbind()
doUnbind() is called whenever the connector goes OFFLINE, except if doBind() has thrown an exception.
long getBindSleepTime()
The delay, in ms, during which the communicator server will sleep before attempting to bind again.
int getBindTries()
The number of times the communicator server will attempt to bind before giving up.
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.sun.jmx.snmp.daemon.CommunicatorServerMBean
From interface java.lang.Runnable
From interface javax.management.MBeanRegistration
From interface javax.management.NotificationBroadcaster

Constants

public static final int OFFLINE

Represents an OFFLINE state.

Constant Value: 1 (0x00000001)

public static final int ONLINE

Represents an ONLINE state.

Constant Value: 0 (0x00000000)

public static final int SNMP_TYPE

Indicates that it is an SNMP connector type.

Constant Value: 4 (0x00000004)

public static final int STARTING

Represents a STARTING state.

Constant Value: 3 (0x00000003)

public static final int STOPPING

Represents a STOPPING state.

Constant Value: 2 (0x00000002)

Public Constructors

public CommunicatorServer (int connectorType)

Instantiates a CommunicatorServer.

Parameters
connectorType Indicates the connector type. Possible values are: SNMP_TYPE.
Throws
This connector type is not correct.
IllegalArgumentException

Public Methods

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

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.

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.

public String getHost ()

Gets the host name used by this CommunicatorServer.

Returns
  • The host name used by this CommunicatorServer.

public synchronized 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.

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.

Returns
  • the array of possible notifications.

public int getPort ()

Gets the port number used by this CommunicatorServer.

Returns
  • The port number used by this CommunicatorServer.

public abstract String getProtocol ()

Gets the protocol being used by this CommunicatorServer.

Returns
  • The protocol as a string.

public int getState ()

Gets the state of this CommunicatorServer as an integer.

Returns
  • ONLINE, OFFLINE, STARTING or STOPPING.

public String getStateString ()

Gets the state of this CommunicatorServer as a string.

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

public boolean isActive ()

Tests whether the CommunicatorServer is active.

Returns
  • True if connector is ONLINE; false otherwise.

public void postDeregister ()

Do nothing.

public void postRegister (Boolean registrationDone)

Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

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.

public void preDeregister ()

Stop the connector.

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

public ObjectName preRegister (MBeanServer server, ObjectName name)

Preregister method of connector.

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
This exception should be caught by the MBeanServer and re-thrown as an MBeanRegistrationException.
Exception

public void removeNotificationListener (NotificationListener listener)

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.

Parameters
listener The listener object to be removed.
Throws
ListenerNotFoundException The listener is not registered.

public void run ()

For SNMP Runtime internal use only.

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

public synchronized void setMBeanServer (MBeanServer newMBS)

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.

public void setPort (int port)

Sets the port number used by this CommunicatorServer.

Parameters
port The port number used by this CommunicatorServer.
Throws
IllegalStateException This method has been invoked while the communicator was ONLINE or STARTING.

public void start ()

Starts this CommunicatorServer.

Has no effect if this CommunicatorServer is ONLINE or STOPPING.

public void start (long timeout)

Starts this CommunicatorServer.

Has no effect if this CommunicatorServer is ONLINE or STOPPING.

Parameters
timeout Time in ms to wait for the connector to start. If timeout is positive, wait for at most the specified time. An infinite timeout can be specified by passing a timeout value equals Long.MAX_VALUE. In that case the method will wait until the connector starts or fails to start. If timeout is negative or zero, returns as soon as possible without waiting.
Throws
CommunicationException if the connectors fails to start.
InterruptedException if the thread is interrupted or the timeout expires.

public void stop ()

Stops this CommunicatorServer.

Has no effect if this CommunicatorServer is OFFLINE or STOPPING.

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

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.

Protected Methods

protected Thread createMainThread ()

protected abstract void doBind ()

Throws
CommunicationException
InterruptedException

protected abstract void doError (Exception e)

Throws
CommunicationException

protected abstract void doProcess ()

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

protected abstract void doReceive ()

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

protected abstract void doUnbind ()

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

Throws
CommunicationException
InterruptedException

protected long getBindSleepTime ()

The delay, in ms, during which the communicator server will sleep before attempting to bind again.

protected int getBindTries ()

The number of times the communicator server will attempt to bind before giving up.