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

javax.management.namespace
Class JMXRemoteNamespace

java.lang.Object
  javax.management.namespace.JMXNamespace
      javax.management.namespace.JMXRemoteNamespace

All Implemented Interfaces:

MBeanRegistration, JMXNamespaceMBean, JMXRemoteNamespaceMBean, NotificationBroadcaster, NotificationEmitter

public class JMXRemoteNamespace
extends JMXNamespace
implements JMXRemoteNamespaceMBean, NotificationEmitter

A JMXNamespace that will connect to a remote MBeanServer by creating a JMXConnector from a JMXServiceURL.

You can call connect() and close() several times. This MBean will emit an AttributeChangeNotification when the value of its Connected attribute changes.

The JMX Remote Namespace MBean is not connected until connect() is explicitly called. The usual sequence of code to create a JMX Remote Namespace is thus:

     final String namespace = "mynamespace";
     final ObjectName name = JMXNamespaces.getNamespaceObjectName(namespace);
     final JMXServiceURL remoteServerURL = .... ;
     final Map optionsMap = .... ;
     final MBeanServer masterMBeanServer = .... ;
     final JMXRemoteNamespace namespaceMBean = JMXRemoteNamespace.newJMXRemoteNamespace(remoteServerURL, optionsMap);
     masterMBeanServer.registerMBean(namespaceMBean, name);
     namespaceMBean.connect();
     // or: masterMBeanServer.invoke(name, "connect", null, null);
 

The JMX Remote Namespace MBean will register for JMX Connection Notifications with its underlying JMXConnector. When a JMX Connection Notification indicates that the underlying connection has failed, the JMX Remote Namespace MBean closes its underlying connector and switches its Connected attribute to false, emitting an AttributeChangeNotification.

At this point, a managing application (or an administrator connected through a management console) can attempt to reconnect the JMX Remote Namespace MBean by calling its connect() method again.

Note that when the connection with the remote namespace fails, or when close(javax.management.remote.JMXConnector) is called, then any notification subscription to MBeans registered in that namespace will be lost - unless a custom event service supporting connection-less mode was used.

Since:

1.7

Field Summary

Modifier and Type	Field and Description

Fields inherited from class javax.management.namespace.JMXNamespace

TYPE, TYPE_ASSIGNMENT

Constructor Summary

Modifier	Constructor and Description
protected	JMXRemoteNamespace(JMXServiceURL sourceURL, Map<String,?> optionsMap) Creates a new instance of JMXRemoteNamespace.

Method Summary

Modifier and Type	Method and Description
void	addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to this MBean.
void	close() Closes the connection with the remote source name space.
void	connect() Connects to the underlying remote source name space, if not already connected.
JMXServiceURL	getAddress() In this class, this method never returns null, and the address returned is the JMXServiceURL that is used by this object to connect(javax.management.remote.JMXServiceURL, java.util.Map) to the remote name space.
String	getDefaultDomain() This method returns the result of calling getDefaultDomain() on the remote namespace.
String[]	getDomains() This method returns the result of calling getDomains() on the remote namespace.
JMXServiceURL	getJMXServiceURL() Returns the JMXServiceURL that is (or will be) used to connect to the remote name space.
Integer	getMBeanCount() This method calls getMBeanCount() on the remote namespace.
protected MBeanServerConnection	getMBeanServerConnection(JMXConnector jmxc) Called when a new connection is established using connect(javax.management.remote.JMXServiceURL, java.util.Map) so that subclasses can customize the connection.
MBeanNotificationInfo[]	getNotificationInfo() A subclass that needs to send its own notifications must override this method in order to return an MBeanNotificationInfo[] array containing both its own notification infos and the notification infos of its super class.
boolean	isConnected() Tells whether the connection to the remote source name space is opened.
protected JMXConnector	newJMXConnector(JMXServiceURL url, Map<String,?> optionsMap) Creates a new JMXConnector with the specified url and env options map.
static JMXRemoteNamespace	newJMXRemoteNamespace(JMXServiceURL sourceURL, Map<String,?> optionsMap) Creates a new instance of JMXRemoteNamespace.
void	preDeregister() This name space handler will automatically close(javax.management.remote.JMXConnector) its connection with the remote source in preDeregister.
void	removeNotificationListener(NotificationListener listener) Removes a listener from this MBean.
void	removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from this MBean.
protected void	sendNotification(Notification n) Sends a notification to registered listeners.

Methods inherited from class javax.management.namespace.JMXNamespace

getMBeanServer, getObjectName, getSourceServer, getUUID, postDeregister, postRegister, preRegister

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.management.namespace.JMXNamespaceMBean

getUUID

Constructor Detail

JMXRemoteNamespace

protected JMXRemoteNamespace(JMXServiceURL sourceURL,
                             Map<String,?> optionsMap)

Creates a new instance of JMXRemoteNamespace.

This constructor is provided for subclasses. To create a new instance of JMXRemoteNamespace call JMXRemoteNamespace.newJMXRemoteNamespace(sourceURL, optionsMap).

Parameters:

sourceURL - a JMX service URL that can be used to connect to the source MBean Server. The source MBean Server is the remote MBean Server which contains the MBeans that will be mirrored in this namespace.

optionsMap - the options map that will be passed to the JMXConnectorFactory when creating the JMXConnector used to connect to the remote source MBean Server. Can be null, which is equivalent to an empty map.

See Also:

JMXRemoteNamespace.newJMXRemoteNamespace, connect(javax.management.remote.JMXServiceURL, java.util.Map)

Method Detail

getJMXServiceURL

public JMXServiceURL getJMXServiceURL()

Returns the JMXServiceURL that is (or will be) used to connect to the remote name space.

Returns:

The JMXServiceURL used to connect to the remote name space.

See Also:

connect(javax.management.remote.JMXServiceURL, java.util.Map)

getAddress

public JMXServiceURL getAddress()

In this class, this method never returns null, and the address returned is the JMXServiceURL that is used by this object to connect(javax.management.remote.JMXServiceURL, java.util.Map) to the remote name space.

This behaviour might be overriden by subclasses, if needed. For instance, a subclass might want to return null if it doesn't want to expose that JMXServiceURL.

Specified by:

getAddress in interface JMXRemoteNamespaceMBean

Returns:

The JMXServiceURL address that points to the remote name space mirrored by this JMXNamespace MBean, or null.

addNotificationListener

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

Description copied from interface: NotificationBroadcaster

Adds a listener to this MBean.

Specified by:

addNotificationListener in interface NotificationBroadcaster

Parameters:

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

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

handback - An opaque object to be sent back to the listener when a notification is emitted. This object cannot be used by the Notification broadcaster object. It should be resent unchanged with the notification to the listener.

See Also:

NotificationBroadcaster.removeNotificationListener(javax.management.NotificationListener)

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()

A subclass that needs to send its own notifications must override this method in order to return an MBeanNotificationInfo[] array containing both its own notification infos and the notification infos of its super class.

The implementation should probably look like:

      final MBeanNotificationInfo[] myOwnNotifs = { .... };
      final MBeanNotificationInfo[] parentNotifs =
            super.getNotificationInfo();
      final Set mergedResult =
            new HashSet();
      mergedResult.addAll(Arrays.asList(myOwnNotifs));
      mergedResult.addAll(Arrays.asList(parentNotifs));
      return mergeResult.toArray(
             new MBeanNotificationInfo[mergedResult.size()]);
 

Specified by:

getNotificationInfo in interface NotificationBroadcaster

Returns:

the array of possible notifications.

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException

Description copied from interface: NotificationBroadcaster

Removes a listener from this MBean. 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 - A listener that was previously added to this MBean.

Throws:

ListenerNotFoundException - The listener is not registered with the MBean.

See Also:

NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)
                                throws ListenerNotFoundException

Description copied from interface: NotificationEmitter

Removes a listener from this MBean. The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Specified by:

removeNotificationListener in interface NotificationEmitter

Parameters:

listener - A listener that was previously added to this MBean.

filter - The filter that was specified when the listener was added.

handback - The handback that was specified when the listener was added.

Throws:

ListenerNotFoundException - The listener is not registered with the MBean, or it is not registered with the given filter and handback.

sendNotification

protected void sendNotification(Notification n)

Sends a notification to registered listeners. Before the notification is sent, the following steps are performed:

• If n.getSequenceNumber() <= 0 set it to the next available sequence number.
• If n.getSource() == null, set it to the value returned by getObjectName().

This method can be called by subclasses in order to send their own notifications. In that case, these subclasses might also need to override getNotificationInfo() in order to declare their own notification types.

Parameters:

n - The notification to send to registered listeners.

See Also:

NotificationBroadcasterSupport, getNotificationInfo()

newJMXConnector

protected JMXConnector newJMXConnector(JMXServiceURL url,
                                       Map<String,?> optionsMap)
                                throws IOException

Creates a new JMXConnector with the specified url and env options map. The default implementation of this method returns JMXConnectorFactory.newJMXConnector(jmxURL, env). Subclasses can override this method to customize behavior.

Parameters:

url - The JMXServiceURL of the remote server.

optionsMap - An options map that will be passed to the JMXConnectorFactory when creating the JMXConnector that can connect to the remote source MBean Server.

Returns:

A JMXConnector to use to connect to the remote server

Throws:

IOException - if the connector could not be created.

See Also:

JMXConnectorFactory.newJMXConnector(javax.management.remote.JMXServiceURL, java.util.Map), JMXRemoteNamespace(javax.management.remote.JMXServiceURL, java.util.Map)

getMBeanServerConnection

protected MBeanServerConnection getMBeanServerConnection(JMXConnector jmxc)
                                                  throws IOException

Called when a new connection is established using connect(javax.management.remote.JMXServiceURL, java.util.Map) so that subclasses can customize the connection. The default implementation of this method effectively does the following:

 MBeanServerConnection mbsc = jmxc.getMBeanServerConnection();
 try {
     return ClientContext.withDynamicContext(mbsc);
 } catch (IllegalArgumentException e) {
     return mbsc;
 }
 

In other words, it arranges for the client context to be forwarded to the remote MBean Server if the remote MBean Server supports contexts; otherwise it ignores the client context.

Example: connecting to a remote namespace

A subclass that wanted to narrow into a namespace of the remote MBeanServer might look like this:

 class JMXRemoteSubNamespace extends JMXRemoteNamespace {
     private final String subnamespace;

     JMXRemoteSubNamespace(
             JMXServiceURL url, Map<String, ?> env, String subnamespace) {
        super(url, env);
        this.subnamespace = subnamespace;
     }

     @Override
     protected MBeanServerConnection getMBeanServerConnection(
             JMXConnector jmxc) throws IOException {
         MBeanServerConnection mbsc = super.getMBeanServerConnection(jmxc);
         return JMXNamespaces.narrowToNamespace(mbsc, subnamespace);
     }
 }
 

Example: using the Event Service for notifications

Some connectors may have been designed to work with an earlier version of the JMX API, and may not have been upgraded to use the Event Service defined in this version of the JMX API. In that case, and if the remote server to which this JMXRemoteNamespace connects also contains namespaces, it may be necessary to configure explicitly an Event Client Forwarder on the remote server side, and to force the use of an EventClient on this client side.

A subclass of JMXRemoteNamespace can provide an implementation of getMBeanServerConnection that will force notification subscriptions to flow through an EventClient over a legacy protocol. It can do so by overriding this method in the following way:

 class JMXRemoteEventClientNamespace extends JMXRemoteNamespace {
     JMXRemoteEventClientNamespace(JMXServiceURL url, Map<String,?> env) {
         super(url, env);
     }

     @Override
     protected MBeanServerConnection getMBeanServerConnection(JMXConnector jmxc)
             throws IOException {
         MBeanServerConnection mbsc = super.getMBeanServerConnection(jmxc);
         return EventClient.getEventClientConnection(mbsc);
     }
 }
 

Note that the remote server also needs to provide an EventClientDelegateMBean: configuring only the client side (this object) is not enough.

In summary, this technique should be used if the remote server supports JMX namespaces, but uses a JMX Connector Server whose implementation does not transparently use the new Event Service (as would be the case with the JMXMPConnectorServer implementation from the reference implementation of the JMX Remote API 1.0 specification).

Parameters:

jmxc - the newly-created JMXConnector.

Returns:

an MBeanServerConnection connected to the remote MBeanServer.

Throws:

IOException - if the connection cannot be made. If this method throws IOException then the calling connect() method will also fail with an IOException.

See Also:

connect(javax.management.remote.JMXServiceURL, java.util.Map)

connect

public void connect()
             throws IOException

Connects to the underlying remote source name space, if not already connected. If connected, do nothing. Otherwise, creates a new connector from the JMXServiceURL provided at creation time, and connects to the remote source name space.

The source MBeans will not appear in the target name space until the JMXRemoteNamespaceMBean is connected.

It is possible to call connect(), close(), and connect() again. However, closing the connection with the remote name space may cause notification listeners to be lost, unless the client explicitly uses the new JMX event service.

The sequence of events when this method is called includes, effectively, the following code:

 JMXServiceURL url = getJMXServiceURL();
 JMXConnector jmxc = newJMXConnector(url, env);
 jmxc.connect();
 MBeanServerConnection mbsc = getMBeanServerConnection(jmxc);
 

Here, env is a Map containing the entries from the optionsMap that was passed to the constructor or to the newJMXRemoteNamespace factory method.

Subclasses can customize connection behavior by overriding the getJMXServiceURL, newJMXConnector, or getMBeanServerConnection methods.

Specified by:

connect in interface JMXRemoteNamespaceMBean

Throws:

IOException - if connection to the remote source name space fails.

See Also:

isConnected

close

public void close()
           throws IOException

Description copied from interface: JMXRemoteNamespaceMBean

Closes the connection with the remote source name space. If the connection is already closed, do nothing. Otherwise, closes the underlying JMXConnector.

Once closed, it is possible to reopen the connection by calling connect.

Specified by:

close in interface JMXRemoteNamespaceMBean

Throws:

IOException - if the connection to the remote source name space can't be closed properly.

See Also:

isConnected

isConnected

public boolean isConnected()

Description copied from interface: JMXRemoteNamespaceMBean

Tells whether the connection to the remote source name space is opened.

Specified by:

isConnected in interface JMXRemoteNamespaceMBean

Returns:

true if connected.

See Also:

connect, close

preDeregister

public void preDeregister()
                   throws Exception

This name space handler will automatically close(javax.management.remote.JMXConnector) its connection with the remote source in preDeregister.

Specified by:

preDeregister in interface MBeanRegistration

Overrides:

preDeregister in class JMXNamespace

Throws:

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

See Also:

MBeanRegistration

getMBeanCount

public Integer getMBeanCount()
                      throws IOException

This method calls getMBeanCount() on the remote namespace.

Specified by:

getMBeanCount in interface JMXNamespaceMBean

Overrides:

getMBeanCount in class JMXNamespace

Returns:

the number of MBeans registered in the name space handled by this JMXNamespace.

Throws:

IOException - if an IOException is raised when communicating with the remote source namespace.

See Also:

MBeanServerConnection.getMBeanCount

getDomains

public String[] getDomains()
                    throws IOException

This method returns the result of calling getDomains() on the remote namespace.

Specified by:

getDomains in interface JMXNamespaceMBean

Overrides:

getDomains in class JMXNamespace

Returns:

the list of domains currently implemented in the name space handled by this JMXNamespace.

Throws:

IOException - if an IOException is raised when communicating with the remote source namespace.

See Also:

MBeanServerConnection.getDomains

getDefaultDomain

public String getDefaultDomain()
                        throws IOException

This method returns the result of calling getDefaultDomain() on the remote namespace.

Specified by:

getDefaultDomain in interface JMXNamespaceMBean

Overrides:

getDefaultDomain in class JMXNamespace

Returns:

the default domain for the name space handled by this JMXNamespace.

Throws:

IOException - if an IOException is raised when communicating with the remote source namespace.

See Also:

MBeanServerConnection.getDefaultDomain

newJMXRemoteNamespace

public static JMXRemoteNamespace newJMXRemoteNamespace(JMXServiceURL sourceURL,
                                                       Map<String,?> optionsMap)

Creates a new instance of JMXRemoteNamespace.

Parameters:

sourceURL - a JMX service URL that can be used to connect to the source MBean Server. The source MBean Server is the remote MBean Server which contains the MBeans that will be mirrored in this namespace.

optionsMap - An options map that will be passed to the JMXConnectorFactory when creating the JMXConnector used to connect to the remote source MBean Server. Can be null, which is equivalent to an empty map.

See Also:

JMXRemoteNamespace(sourceURL,optionsMap), JMXConnectorFactory.newJMXConnector(javax.management.remote.JMXServiceURL, java.util.Map)