com.sun.jdmk.remote.cascading
Interface MBeanServerConnectionFactory

All Known Implementing Classes:

BasicMBeanServerConnectionFactory, LocalMBeanServerConnectionFactory

public interface MBeanServerConnectionFactory

An object that is able to return connections to a given MBeanServer. The MBeanServer could be local (LocalMBeanServerConnectionFactory) or remote (BasicMBeanServerConnectionFactory).

Implementations of the MBeanServerConnectionFactory may or may not support transparent reconnection when the underlying connection is abruptly closed (server going down, network failure, etc...). Whether transparent reconnection is supported or not should be transparent to the client code.

If transparent reconnection is supported, then the MBeanServerConnectionFactory implementation is responsible for transparently initiating a new connection with the server side, by, e.g, obtaining a new JMXConnector from a lookup service.

The MBeanServerConnectionFactory emits JMXConnectionNotification relating to the underlying connection:

• JMXConnectionNotification.OPENED: The connection with the underlying MBeanServer was (re)opened.
• JMXConnectionNotification.CLOSED: The connection with the underlying MBeanServer was closed.
• JMXConnectionNotification.FAILED: The connection with the underlying MBeanServer failed - and can no longer be used.

Implementations that support transparent reconnection could only emit JMXConnectionNotification.OPENED and JMXConnectionNotification.CLOSED notifications. Implementations that do not support transparent reconnection could emit all three notifications. An implementation providing connections to a local MBeanServer could emit none of them.

Since:

Java DMK 5.1

Method Summary

void	addConnectionNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to be informed of changes in connection status.
String	getConnectionId() Gets the current connection's ID from the connector server.
MBeanServerConnection	getMBeanServerConnection() Returns an MBeanServerConnection object representing a remote MBean server.
void	removeConnectionNotificationListener(NotificationListener listener) Removes a listener from the list to be informed of changes in status.
void	removeConnectionNotificationListener(NotificationListener l, NotificationFilter f, Object handback) Removes a listener from the list to be informed of changes in status.

Method Detail

getMBeanServerConnection

MBeanServerConnection getMBeanServerConnection()
                                               throws IOException

Returns an MBeanServerConnection object representing a remote MBean server. For a given MBeanServerConnectionFactory, two successful calls to this method will usually return the same MBeanServerConnection object, though this is not required. In particular, if the MBeanServerConnectionFactory handles transparent reconnection after a server/network failure, it could return a new MBeanServerConnection obtained from a new JMXConnector

Returns:

an object that implements the MBeanServerConnection interface by forwarding its methods to the remote MBean server.

Throws:

IOException - if a valid MBeanServerConnection cannot be created.

See Also:

JMXConnector.getMBeanServerConnection()

addConnectionNotificationListener

void addConnectionNotificationListener(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)

Adds a listener to be informed of changes in connection status. The listener will receive notifications of type JMXConnectionNotification. An implementation can send other types of notifications too.

Any number of listeners can be added with this method. The same listener can be added more than once with the same or different values for the filter and handback. There is no special treatment of a duplicate entry. For example, if a listener is registered twice with no filter, then its handleNotification method will be called twice for each notification.

Parameters:

listener - a listener to receive connection status notifications.

filter - a filter to select which notifications are to be delivered to the listener, or null if all notifications are to be delivered.

handback - an object to be given to the listener along with each notification. Can be null.

Throws:

NullPointerException - if listener is null.

See Also:

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

removeConnectionNotificationListener

void removeConnectionNotificationListener(NotificationListener listener)
                                          throws ListenerNotFoundException

Removes a listener from the list to be informed of changes in status. The listener must previously have been added. If there is more than one matching listener, all are removed.

Parameters:

listener - a listener to receive connection status notifications.

Throws:

NullPointerException - if listener is null.

ListenerNotFoundException - if the listener is not registered with this JMXConnector.

See Also:

removeConnectionNotificationListener(NotificationListener, NotificationFilter, Object), addConnectionNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeConnectionNotificationListener

void removeConnectionNotificationListener(NotificationListener l,
                                          NotificationFilter f,
                                          Object handback)
                                          throws ListenerNotFoundException

Removes a listener from the list to be informed of changes in status. The listener must previously have been added with the same three parameters. If there is more than one matching listener, only one is removed.

Parameters:

l - a listener to receive connection status notifications.

f - a filter to select which notifications are to be delivered to the listener. Can be null.

handback - an object to be given to the listener along with each notification. Can be null.

Throws:

ListenerNotFoundException - if the listener is not registered with this JMXConnector, or is not registered with the given filter and handback.

See Also:

removeConnectionNotificationListener(NotificationListener), addConnectionNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

getConnectionId

String getConnectionId()
                       throws IOException

Gets the current connection's ID from the connector server. For a given connector server, every connection will have a unique id which does not change during the lifetime of the connection.

If this MBeanServerConnectionFactory provides access to a remote MBeanServer, then the connection ID will be the ID of the underlying JMXConnector's connection currently in use. The javax.management.remote package description describes the conventions for such connection IDs. Otherwise, the format of the connection ID is undefined.

Returns:

the unique ID of the current connection. This is the same as the ID that the connector server includes in its JMXConnectionNotifications.

Throws:

IOException - if the connection ID cannot be obtained, for instance because the connection is closed or broken.