Please note that this documentation is not final and is subject to change.

javax.management.remote
Class JMXConnectorServer

java.lang.Object
  javax.management.NotificationBroadcasterSupport
      javax.management.remote.JMXConnectorServer

All Implemented Interfaces:

MBeanRegistration, NotificationBroadcaster, NotificationEmitter, JMXAddressable, JMXConnectorServerMBean, SendNotification

Direct Known Subclasses:

RMIConnectorServer

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

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 start method is called. A connector server stops listening for client connections when the 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 JMXConnectionNotification is emitted.

Since:

1.5

Field Summary

Modifier and Type	Field and Description
static String	AUTHENTICATOR Name of the attribute that specifies the authenticator for a connector server.
static String	CONTEXT_FORWARDER Name of the attribute that specifies whether this connector server allows clients to communicate a context with each request.
static String	DELEGATE_TO_EVENT_SERVICE Name of the attribute that specifies whether this connector server can delegate notification handling to the Event Service.
static String	EVENT_CLIENT_DELEGATE_FORWARDER Name of the attribute that specifies whether this connector server simulates the existence of the EventClientDelegate MBean.
static String	LOCALIZE_MBEAN_INFO_FORWARDER Name of the attribute that specifies whether this connector server localizes the descriptions in the MBeanInfo object returned by MBeanServer.getMBeanInfo, based on the locale communicated by the client.

Constructor and Description

JMXConnectorServer()
Constructs a connector server that will be registered as an MBean in the MBean server it is attached to.

JMXConnectorServer(MBeanServer mbeanServer)
Constructs a connector server that is attached to the given MBean server.

Method Summary

Modifier and Type	Method and Description
void	closeConnection(String connectionId) Closes a client connection.
protected void	connectionClosed(String connectionId, String message, Object userData) Called by a subclass when a client connection is closed normally.
protected void	connectionFailed(String connectionId, String message, Object userData) Called by a subclass when a client connection fails.
protected void	connectionOpened(String connectionId, String message, Object userData) Called by a subclass when a new client connection is opened.
String[]	getConnectionIds() The list of IDs for currently-open connections to this connector server.
MBeanServer	getMBeanServer() Returns the MBean server that this connector server is attached to, or the first in a chain of user-added MBeanServerForwarders, if any.
MBeanNotificationInfo[]	getNotificationInfo() Returns an array indicating the notifications that this MBean sends.
MBeanServerForwarder	getSystemMBeanServerForwarder() Returns the first item in the chain of system and then user forwarders.
protected void	installStandardForwarders(Map<String,?> env) Install MBeanServerForwarders in the system chain based on the attributes in the given Map.
void	postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
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() Called by an MBean server when this connector server is unregistered from that MBean server.
ObjectName	preRegister(MBeanServer mbs, ObjectName name) Called by an MBean server when this connector server is registered in that MBean server.
void	removeMBeanServerForwarder(MBeanServerForwarder mbsf) Remove a forwarder from the chain of forwarders.
void	setMBeanServerForwarder(MBeanServerForwarder mbsf) Inserts an object that intercepts requests for the MBean server that arrive through this connector server.
boolean	supportsSystemMBeanServerForwarder() Returns true if this connector server supports a system chain of MBeanServerForwarders.
JMXConnector	toJMXConnector(Map<String,?> env) Returns a client stub for this connector server.

Methods inherited from class javax.management.NotificationBroadcasterSupport

addNotificationListener, handleNotification, isListenedTo, removeAllNotificationListeners, removeNotificationListener, removeNotificationListener, sendNotification

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.management.remote.JMXConnectorServerMBean

getAddress, getAttributes, isActive, start, stop

Methods inherited from interface javax.management.remote.JMXAddressable

getAddress

Field Detail

AUTHENTICATOR

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 JMXAuthenticator.

See Also:

Constant Field Values

DELEGATE_TO_EVENT_SERVICE

public static final String DELEGATE_TO_EVENT_SERVICE

Name of the attribute that specifies whether this connector server can delegate notification handling to the Event Service. The value associated with this attribute, if any, is a String, which must be equal, ignoring case, to "true" or "false".

Not all connector servers will understand this attribute, but the standard RMI Connector Server does.

If this attribute is not present, then the system property of the same name ("jmx.remote.delegate.event.service") is consulted. If that is not set either, then the Event Service is used if the connector server supports it.

Since:

1.7

See Also:

Constant Field Values

CONTEXT_FORWARDER

public static final String CONTEXT_FORWARDER

Name of the attribute that specifies whether this connector server allows clients to communicate a context with each request. The value associated with this attribute, if any, must be a string that is equal to "true" or "false", ignoring case. If it is "true", then the connector server will simulate a namespace jmx.context//, as described in ClientContext.newContextForwarder(javax.management.MBeanServer, javax.management.MBeanServer). This namespace is needed for ClientContext.withContext to function correctly.

Not all connector servers will understand this attribute, but the standard RMI Connector Server does. For a connector server that understands this attribute, the default value is "true".

Since:

1.7

See Also:

Constant Field Values

LOCALIZE_MBEAN_INFO_FORWARDER

public static final String LOCALIZE_MBEAN_INFO_FORWARDER

Name of the attribute that specifies whether this connector server localizes the descriptions in the MBeanInfo object returned by MBeanServer.getMBeanInfo, based on the locale communicated by the client.

The value associated with this attribute, if any, must be a string that is equal to "true" or "false", ignoring case. If it is "true", then the connector server will localize MBeanInfo descriptions as specified in ClientContext.newLocalizeMBeanInfoForwarder(javax.management.MBeanServer).

Not all connector servers will understand this attribute, but the standard RMI Connector Server does. For a connector server that understands this attribute, the default value is "false".

Because localization requires the client to be able to communicate its locale, it does not make sense to specify this attribute as "true" if CONTEXT_FORWARDER is not also "true". For a connector server that understands these attributes, specifying this inconsistent combination will result in an IllegalArgumentException.

Since:

1.7

See Also:

Constant Field Values

EVENT_CLIENT_DELEGATE_FORWARDER

public static final String EVENT_CLIENT_DELEGATE_FORWARDER

Name of the attribute that specifies whether this connector server simulates the existence of the EventClientDelegate MBean. The value associated with this attribute, if any, must be a string that is equal to "true" or "false", ignoring case. If it is "true", then the connector server will simulate an EventClientDelegate MBean, as described in EventClientDelegate.newForwarder(javax.management.MBeanServer, javax.management.MBeanServer). This MBean is needed for EventClient to function correctly.

Not all connector servers will understand this attribute, but the standard RMI Connector Server does. For a connector server that understands this attribute, the default value is "true".

Since:

1.7

See Also:

Constant Field Values

Constructor Detail

JMXConnectorServer

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.

JMXConnectorServer

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, or not registered in any MBean server.

Parameters:

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.

Method Detail

getMBeanServer

public MBeanServer getMBeanServer()

Returns the MBean server that this connector server is attached to, or the first in a chain of user-added MBeanServerForwarders, if any.

Returns:

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

See Also:

setMBeanServerForwarder(javax.management.remote.MBeanServerForwarder), getSystemMBeanServerForwarder()

setMBeanServerForwarder

public void setMBeanServerForwarder(MBeanServerForwarder mbsf)

Description copied from interface: JMXConnectorServerMBean

Inserts an object that intercepts requests for the MBean server that arrive through this connector server. This object will be supplied as the MBeanServer for any new connection created by this connector server. Existing connections are unaffected.

This method can be called more than once with different MBeanServerForwarder objects. The result is a chain of forwarders. The last forwarder added is the first in the chain. In more detail:

• If this connector server is already associated with an MBeanServer object, then that object is given to mbsf.setMBeanServer. If doing so produces an exception, this method throws the same exception without any other effect.

• If this connector is not already associated with an MBeanServer object, or if the mbsf.setMBeanServer call just mentioned succeeds, then mbsf becomes this connector server's MBeanServer.

A connector server may support two chains of forwarders, a system chain and a user chain. See getSystemMBeanServerForwarder() for details.

Specified by:

setMBeanServerForwarder in interface JMXConnectorServerMBean

Parameters:

mbsf - the new MBeanServerForwarder.

See Also:

getSystemMBeanServerForwarder()

removeMBeanServerForwarder

public void removeMBeanServerForwarder(MBeanServerForwarder mbsf)

Remove a forwarder from the chain of forwarders. The forwarder can be in the system chain or the user chain. On successful return from this method, the first occurrence in the chain of an object that is equal to mbsf will have been removed.

Parameters:

mbsf - the forwarder to remove

Throws:

NoSuchElementException - if there is no occurrence of mbsf in the chain.

IllegalArgumentException - if mbsf is null or is the system forwarder.

Since:

1.7

getSystemMBeanServerForwarder

public MBeanServerForwarder getSystemMBeanServerForwarder()

Returns the first item in the chain of system and then user forwarders. There is a chain of MBeanServerForwarders between a JMXConnectorServer and its MBeanServer. This chain consists of two sub-chains: first the system chain and then the user chain. Incoming requests are given to the first forwarder in the system chain. Each forwarder can handle a request itself, or more usually forward it to the next forwarder, perhaps with some extra behavior such as logging or security checking before or after the forwarding. The last forwarder in the system chain is followed by the first forwarder in the user chain.

The object returned by this method is the first forwarder in the system chain. For a given JMXConnectorServer, this method always returns the same object, which simply forwards every request to the next object in the chain.

Not all connector servers support a system chain of forwarders, although the standard RMI connector server does. For those that do not, this method will throw UnsupportedOperationException. All connector servers do support a user chain of forwarders.

The system chain is usually defined by a connector server based on the environment Map; see JMXConnectorServerFactory.newJMXConnectorServer. Allowing the connector server to define its forwarders in this way ensures that they are in the correct order - some forwarders need to be inserted before others for correct behavior. It is possible to modify the system chain, for example using connectorServer.getSystemMBeanServerForwarder().setMBeanServer(mbsf) or removeMBeanServerForwarder, but in that case the system chain is no longer guaranteed to be correct.

The user chain is defined by calling setMBeanServerForwarder to insert forwarders at the head of the user chain.

This code illustrates how the chains can be traversed:

 JMXConnectorServer cs;
 System.out.println("system chain:");
 MBeanServer mbs = cs.getSystemMBeanServerForwarder();
 while (true) {
     if (mbs == cs.getMBeanServer())
         System.out.println("user chain:");
     if (!(mbs instanceof MBeanServerForwarder))
         break;
     MBeanServerForwarder mbsf = (MBeanServerForwarder) mbs;
     System.out.println("--forwarder: " + mbsf);
     mbs = mbsf.getMBeanServer();
 }
 System.out.println("--MBean Server");
 

Note for connector server implementors

Existing connector server implementations can be updated to support a system chain of forwarders as follows:

• Override the supportsSystemMBeanServerForwarder() method so that it returns true.

• Call installStandardForwarders(java.util.Map) from the constructor of the connector server.

• Direct incoming requests to the result of getSystemMBeanServerForwarder() instead of the result of getMBeanServer().

Returns:

the first item in the system chain of forwarders.

Throws:

UnsupportedOperationException - if supportsSystemMBeanServerForwarder() returns false.

Since:

1.7

See Also:

supportsSystemMBeanServerForwarder(), setMBeanServerForwarder(javax.management.remote.MBeanServerForwarder)

supportsSystemMBeanServerForwarder

public boolean supportsSystemMBeanServerForwarder()

Returns true if this connector server supports a system chain of MBeanServerForwarders. The default implementation of this method returns false. Connector servers that do support the system chain must override this method to return true.

Returns:

true if this connector server supports the system chain of forwarders.

Since:

1.7

closeConnection

public void closeConnection(String connectionId)
                     throws IOException

Closes a client connection. If the connection is successfully closed, the method connectionClosed(java.lang.String, java.lang.String, java.lang.Object) is called to notify interested parties.

Not all connector servers support this method. For those that do, it should be possible to cause a new client connection to fail before it can be used, by calling this method from within a NotificationListener when it receives a JMXConnectionNotification.OPENED notification. This allows the owner of a connector server to deny certain connections, typically based on the information in the connection id.

The implementation of this method in JMXConnectorServer throws UnsupportedOperationException. Subclasses can override this method to support closing a specified client connection.

Parameters:

connectionId - the id of the client connection to be closed.

Throws:

IllegalStateException - if the server is not started or is closed.

IllegalArgumentException - if connectionId is null or is not the id of any open connection.

IOException - if an I/O error appears when closing the connection.

Since:

1.7

installStandardForwarders

protected void installStandardForwarders(Map<String,?> env)

Install MBeanServerForwarders in the system chain based on the attributes in the given Map. A connector server that supports a system chain of MBeanServerForwarders can call this method to add forwarders to that chain based on the contents of env. In order:

• If EVENT_CLIENT_DELEGATE_FORWARDER is absent, or is present with the value "true", then a forwarder equivalent to EventClientDelegate.newForwarder(sysMBSF.getMBeanServer(), sysMBSF) is inserted at the start of the system chain, where sysMBSF is the object returned by getSystemMBeanServerForwarder().
• If LOCALIZE_MBEAN_INFO_FORWARDER is present with the value "true", then a forwarder equivalent to ClientContext.newLocalizeMBeanInfoForwarder(sysMBSF.getMBeanServer()) is inserted at the start of the system chain.
• If CONTEXT_FORWARDER is absent, or is present with the value "true", then a forwarder equivalent to ClientContext.newContextForwarder(sysMSBF.getMBeanServer(), sysMBSF) is inserted at the tart of the system chain.

For EVENT_CLIENT_DELEGATE_FORWARDER and CONTEXT_FORWARDER, if the attribute is absent from the Map and a system property of the same name is defined, then the value of the system property is used as if it were in the Map.

Since each forwarder is inserted at the start of the chain, the final order of the forwarders is the reverse of the order above. This is important, because the LOCALIZE_MBEAN_INFO_FORWARDER can only work if the CONTEXT_FORWARDER has already installed the remote client's locale in the context of the current thread.

Attributes in env that are not listed above are ignored by this method.

Throws:

UnsupportedOperationException - if supportsSystemMBeanServerForwarder() is false.

IllegalArgumentException - if the relevant attributes in env are inconsistent, for example if LOCALIZE_MBEAN_INFO_FORWARDER is "true" but CONTEXT_FORWARDER is "false"; or if one of the attributes has an illegal value.

Since:

1.7

getConnectionIds

public String[] getConnectionIds()

Description copied from interface: JMXConnectorServerMBean

The list of IDs for currently-open connections to this connector server.

Specified by:

getConnectionIds in interface JMXConnectorServerMBean

Returns:

a new string array containing the list of IDs. If there are no currently-open connections, this array will be empty.

toJMXConnector

public JMXConnector toJMXConnector(Map<String,?> env)
                            throws IOException

Returns a client stub for this connector server. A client stub is a serializable object whose 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 JMXConnectorServerMBean.getAddress() and JMXConnectorFactory to generate the stub, with code equivalent to the following:

 JMXServiceURL addr = getAddress();
 return 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 UnsupportedOperationException.

Specified by:

toJMXConnector in interface JMXConnectorServerMBean

Parameters:

env - client connection parameters of the same sort that could be provided to JMXConnector.connect(Map). Can be null, which is equivalent to an empty map.

Returns:

a client stub that can be used to make a new connection to this connector server.

Throws:

UnsupportedOperationException - if this connector server does not support the generation of client stubs.

IllegalStateException - if the JMXConnectorServer is not started (see JMXConnectorServerMBean.isActive()).

IOException - if a communications problem means that a stub cannot be created.

getNotificationInfo

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

Specified by:

getNotificationInfo in interface NotificationBroadcaster

Overrides:

getNotificationInfo in class NotificationBroadcasterSupport

Returns:

the array of possible notifications.

connectionOpened

protected void connectionOpened(String connectionId,
                                String message,
                                Object userData)

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

Parameters:

connectionId - the ID of the new connection. This must be different from the ID of any connection previously opened by this connector server.

message - the message for the emitted JMXConnectionNotification. Can be null. See Notification.getMessage().

userData - the userData for the emitted JMXConnectionNotification. Can be null. See Notification.getUserData().

Throws:

NullPointerException - if connectionId is null.

connectionClosed

protected void connectionClosed(String connectionId,
                                String message,
                                Object userData)

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

Parameters:

connectionId - the ID of the closed connection.

message - the message for the emitted JMXConnectionNotification. Can be null. See Notification.getMessage().

userData - the userData for the emitted JMXConnectionNotification. Can be null. See Notification.getUserData().

Throws:

NullPointerException - if connectionId is null.

connectionFailed

protected void connectionFailed(String connectionId,
                                String message,
                                Object userData)

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

Parameters:

connectionId - the ID of the failed connection.

message - the message for the emitted JMXConnectionNotification. Can be null. See Notification.getMessage().

userData - the userData for the emitted JMXConnectionNotification. Can be null. See Notification.getUserData().

Throws:

NullPointerException - if connectionId is null.

preRegister

public ObjectName preRegister(MBeanServer mbs,
                              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 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.

Specified by:

preRegister in interface MBeanRegistration

Parameters:

mbs - the MBean server in which this connection server is being registered.

name - The object name of the MBean.

Returns:

The name under which the MBean is to be registered.

Throws:

NullPointerException - if mbs or name is null.

postRegister

public void postRegister(Boolean registrationDone)

Description copied from interface: MBeanRegistration

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

If the implementation of this method throws a RuntimeException or an Error, the MBean Server will rethrow those inside a RuntimeMBeanException or RuntimeErrorException, respectively. However, throwing an exception in postRegister will not change the state of the MBean: if the MBean was already registered (registrationDone is true), the MBean will remain registered.

This might be confusing for the code calling createMBean() or registerMBean(), as such code might assume that MBean registration has failed when such an exception is raised. Therefore it is recommended that implementations of postRegister do not throw Runtime Exceptions or Errors if it can be avoided.

Specified by:

postRegister in interface MBeanRegistration

Parameters:

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

preDeregister

public void preDeregister()
                   throws Exception

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

Specified by:

preDeregister in interface MBeanRegistration

Throws:

IOException - if thrown by the stop method.

Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()

Description copied from interface: MBeanRegistration

Allows the MBean to perform any operations needed after having been unregistered in the MBean server.

If the implementation of this method throws a RuntimeException or an Error, the MBean Server will rethrow those inside a RuntimeMBeanException or RuntimeErrorException, respectively. However, throwing an excepption in postDeregister will not change the state of the MBean: the MBean was already successfully deregistered and will remain so.

This might be confusing for the code calling unregisterMBean(), as it might assume that MBean deregistration has failed. Therefore it is recommended that implementations of postDeregister do not throw Runtime Exceptions or Errors if it can be avoided.

Specified by:

postDeregister in interface MBeanRegistration