FileDocCategorySizeDatePackage
JMXConnectorServer.javaAPI DocJava SE 6 API13824Tue Jun 10 00:26:18 BST 2008javax.management.remote

JMXConnectorServer

public abstract class JMXConnectorServer extends NotificationBroadcasterSupport implements JMXAddressable, JMXConnectorServerMBean, MBeanRegistration

Superclass of every connector server. A connector server is attached to an MBean server. It listens for client connection requests and creates a connection for each one.

A connector server is associated with an MBean server either by registering it in that MBean server, or by passing the MBean server to its constructor.

A connector server is inactive when created. It only starts listening for client connections when the {@link #start() start} method is called. A connector server stops listening for client connections when the {@link #stop() stop} method is called or when the connector server is unregistered from its MBean server.

Stopping a connector server does not unregister it from its MBean server. A connector server once stopped cannot be restarted.

Each time a client connection is made or broken, a notification of class {@link JMXConnectionNotification} is emitted.

since
1.5
since.unbundled
1.0

Fields Summary
public static final String
AUTHENTICATOR

Name of the attribute that specifies the authenticator for a connector server. The value associated with this attribute, if any, must be an object that implements the interface {@link JMXAuthenticator}.

private MBeanServer
mbeanServer
The MBeanServer used by this server to execute a client request.
private ObjectName
myName
The name used to registered this server in an MBeanServer. It is null if the this server is not registered or has been unregistered.
private final int[]
lock
private List
connectionIds
private static final int[]
sequenceNumberLock
private static long
sequenceNumber
Constructors Summary
public JMXConnectorServer()

Constructs a connector server that will be registered as an MBean in the MBean server it is attached to. This constructor is typically called by one of the createMBean methods when creating, within an MBean server, a connector server that makes it available remotely.


                                                      
      
	this(null);
    
public JMXConnectorServer(MBeanServer mbeanServer)

Constructs a connector server that is attached to the given MBean server. A connector server that is created in this way can be registered in a different MBean server.

param
mbeanServer the MBean server that this connector server is attached to. Null if this connector server will be attached to an MBean server by being registered in it.

	this.mbeanServer = mbeanServer;
    
Methods Summary
protected voidconnectionClosed(java.lang.String connectionId, java.lang.String message, java.lang.Object userData)

Called by a subclass when a client connection is closed normally. Removes connectionId from the list returned by {@link #getConnectionIds()}, then emits a {@link JMXConnectionNotification} with type {@link JMXConnectionNotification#CLOSED}.

param
connectionId the ID of the closed connection.
param
message the message for the emitted {@link JMXConnectionNotification}. Can be null. See {@link Notification#getMessage()}.
param
userData the userData for the emitted {@link JMXConnectionNotification}. Can be null. See {@link Notification#getUserData()}.
exception
NullPointerException if connectionId is null.


	if (connectionId == null)
	    throw new NullPointerException("Illegal null argument");

	synchronized (connectionIds) {
	    connectionIds.remove(connectionId);
	}

	sendNotification(JMXConnectionNotification.CLOSED, connectionId,
			 message, userData);
    
protected voidconnectionFailed(java.lang.String connectionId, java.lang.String message, java.lang.Object userData)

Called by a subclass when a client connection fails. Removes connectionId from the list returned by {@link #getConnectionIds()}, then emits a {@link JMXConnectionNotification} with type {@link JMXConnectionNotification#FAILED}.

param
connectionId the ID of the failed connection.
param
message the message for the emitted {@link JMXConnectionNotification}. Can be null. See {@link Notification#getMessage()}.
param
userData the userData for the emitted {@link JMXConnectionNotification}. Can be null. See {@link Notification#getUserData()}.
exception
NullPointerException if connectionId is null.


	if (connectionId == null)
	    throw new NullPointerException("Illegal null argument");

	synchronized (connectionIds) {
	    connectionIds.remove(connectionId);
	}

	sendNotification(JMXConnectionNotification.FAILED, connectionId,
			 message, userData);
    
protected voidconnectionOpened(java.lang.String connectionId, java.lang.String message, java.lang.Object userData)

Called by a subclass when a new client connection is opened. Adds connectionId to the list returned by {@link #getConnectionIds()}, then emits a {@link JMXConnectionNotification} with type {@link JMXConnectionNotification#OPENED}.

param
connectionId the ID of the new connection. This must be different from the ID of any connection previously opened by this connector server.
param
message the message for the emitted {@link JMXConnectionNotification}. Can be null. See {@link Notification#getMessage()}.
param
userData the userData for the emitted {@link JMXConnectionNotification}. Can be null. See {@link Notification#getUserData()}.
exception
NullPointerException if connectionId is null.


	if (connectionId == null)
	    throw new NullPointerException("Illegal null argument");

	synchronized (connectionIds) {
	    connectionIds.add(connectionId);
	}

	sendNotification(JMXConnectionNotification.OPENED, connectionId,
			 message, userData);
    
public java.lang.String[]getConnectionIds()

	synchronized (connectionIds) {
	    return (String[])
		connectionIds.toArray(new String[connectionIds.size()]);
	}
    
public synchronized javax.management.MBeanServergetMBeanServer()

Returns the MBean server that this connector server is attached to.

return
the MBean server that this connector server is attached to, or null if it is not yet attached to an MBean server.

	return mbeanServer;
    
public javax.management.MBeanNotificationInfo[]getNotificationInfo()

Returns an array indicating the notifications that this MBean sends. The implementation in JMXConnectorServer returns an array with one element, indicating that it can emit notifications of class {@link JMXConnectionNotification} with the types defined in that class. A subclass that can emit other notifications should return an array that contains this element plus descriptions of the other notifications.

return
the array of possible notifications.

	final String[] types = {
	    JMXConnectionNotification.OPENED,
	    JMXConnectionNotification.CLOSED,
	    JMXConnectionNotification.FAILED,
	};
	final String className = JMXConnectionNotification.class.getName();
	final String description =
	    "A client connection has been opened or closed";
	return new MBeanNotificationInfo[] {
	    new MBeanNotificationInfo(types, className, description),
	};
    
private synchronized java.lang.ObjectgetNotificationSource()

	if (myName != null)
	    return myName;
	else
	    return this;
    
private static longnextSequenceNumber()

	synchronized (sequenceNumberLock) {
	    return sequenceNumber++;
	}
    
public voidpostDeregister()

	myName = null;
    
public voidpostRegister(java.lang.Boolean registrationDone)

	// do nothing
    
public synchronized voidpreDeregister()

Called by an MBean server when this connector server is unregistered from that MBean server. If this connector server was attached to that MBean server by being registered in it, and if the connector server is still active, then unregistering it will call the {@link #stop stop} method. If the stop method throws an exception, the unregistration attempt will fail. It is recommended to call the stop method explicitly before unregistering the MBean.

exception
IOException if thrown by the {@link #stop stop} method.

	if (myName != null && isActive()) {
	    stop();
	    myName = null; // just in case stop is buggy and doesn't stop
	}
    
public synchronized javax.management.ObjectNamepreRegister(javax.management.MBeanServer mbs, javax.management.ObjectName name)

Called by an MBean server when this connector server is registered in that MBean server. This connector server becomes attached to the MBean server and its {@link #getMBeanServer()} method will return mbs.

If this connector server is already attached to an MBean server, this method has no effect. The MBean server it is attached to is not necessarily the one it is being registered in.

param
mbs the MBean server in which this connection server is being registered.
param
name The object name of the MBean.
return
The name under which the MBean is to be registered.
exception
NullPointerException if mbs or name is null.

	if (mbs == null || name == null)
	    throw new NullPointerException("Null MBeanServer or ObjectName");
	if (mbeanServer == null) {
	    mbeanServer = mbs;
	    myName = name;
	}
	return name;
    
private voidsendNotification(java.lang.String type, java.lang.String connectionId, java.lang.String message, java.lang.Object userData)

	Notification notif =
	    new JMXConnectionNotification(type,
					  getNotificationSource(),
					  connectionId,
					  nextSequenceNumber(),
					  message,
					  userData);
	sendNotification(notif);
    
public synchronized voidsetMBeanServerForwarder(javax.management.remote.MBeanServerForwarder mbsf)

	if (mbsf == null) 
	    throw new IllegalArgumentException("Invalid null argument: mbsf");

        if (mbeanServer !=  null) mbsf.setMBeanServer(mbeanServer);
        mbeanServer = mbsf;
    
public javax.management.remote.JMXConnectortoJMXConnector(java.util.Map env)

Returns a client stub for this connector server. A client stub is a serializable object whose {@link JMXConnector#connect(Map) connect} method can be used to make one new connection to this connector server.

A given connector need not support the generation of client stubs. However, the connectors specified by the JMX Remote API do (JMXMP Connector and RMI Connector).

The default implementation of this method uses {@link #getAddress} and {@link JMXConnectorFactory} to generate the stub, with code equivalent to the following:

JMXServiceURL addr = {@link #getAddress() getAddress()};
return {@link JMXConnectorFactory#newJMXConnector(JMXServiceURL, Map)
JMXConnectorFactory.newJMXConnector(addr, env)};

A connector server for which this is inappropriate must override this method so that it either implements the appropriate logic or throws {@link UnsupportedOperationException}.

param
env client connection parameters of the same sort that could be provided to {@link JMXConnector#connect(Map) JMXConnector.connect(Map)}. Can be null, which is equivalent to an empty map.
return
a client stub that can be used to make a new connection to this connector server.
exception
UnsupportedOperationException if this connector server does not support the generation of client stubs.
exception
IllegalStateException if the JMXConnectorServer is not started (see {@link JMXConnectorServerMBean#isActive()}).
exception
IOException if a communications problem means that a stub cannot be created.

	if (!isActive()) throw new 
	    IllegalStateException("Connector is not active");
	JMXServiceURL addr = getAddress();
	return JMXConnectorFactory.newJMXConnector(addr, env);