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

javax.management.event
Class EventClient

java.lang.Object
  javax.management.event.EventClient

All Implemented Interfaces:

EventConsumer, NotificationManager

public class EventClient
extends Object
implements EventConsumer, NotificationManager

This class is used to manage its notification listeners on the client side in the same way as on the MBean server side. This class needs to work with an EventClientDelegateMBean on the server side.

A user can specify an EventRelay object to specify how to receive notifications forwarded by the EventClientDelegateMBean. By default, the class FetchingEventRelay is used.

A user can specify an Executor to distribute notifications to local listeners. If no executor is specified, the thread in the EventRelay which calls EventReceiver.receive will be reused to distribute the notifications (in other words, to call the handleNotification method of the appropriate listeners). It is useful to make a separate thread do this distribution in some cases. For example, if network communication is slow, the forwarding thread can concentrate on communication while, locally, the distributing thread distributes the received notifications. Another usage is to share a thread pool between many clients, for scalability. Note, though, that if the Executor can create more than one thread then it is possible that listeners will see notifications in a different order from the order in which they were sent.

An object of this class sends notifications to listeners added with addEventClientListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object). The type of each such notification is one of FAILED, NONFATAL, or NOTIFS_LOST.

Since:

JMX 2.0

Field Summary

Modifier and Type	Field and Description
static long	DEFAULT_REQUESTED_LEASE_TIME The default lease time that EventClient instances will request, in milliseconds.
static String	FAILED A notification string type used by an EventClient object to inform a listener added by addEventClientListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object) that it failed to get notifications from a remote server, and that it is possible that no more notifications will be delivered.
static String	NONFATAL Reports that an unexpected exception has been received by the EventRelay object but that it is non-fatal.
static String	NOTIFS_LOST A notification string type used by an EventClient object to inform a listener added by addEventClientListener that it has detected that notifications have been lost.

Constructor and Description

EventClient(EventClientDelegateMBean delegate)
Constructs an EventClient object with a specified EventClientDelegateMBean.

EventClient(EventClientDelegateMBean delegate, EventRelay eventRelay, Executor distributingExecutor, ScheduledExecutorService leaseScheduler, long requestedLeaseTime)
Constructs an EventClient object with the specified EventClientDelegateMBean, EventRelay object, and distributing thread.

EventClient(MBeanServerConnection conn)
Constructs a default EventClient object.

Method Summary

Modifier and Type	Method and Description
void	addEventClientListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to receive the EventClient notifications specified in getEventClientNotificationInfo().
Collection<ListenerInfo>	addListeners(Collection<ListenerInfo> listeners) Adds a set of listeners to the remote MBeanServer.
void	addNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to a registered MBean.
void	close() Closes this EventClient, removes all listeners and stops receiving notifications.
boolean	closed() Determine if this EventClient is closed.
String	getClientId() Get the client id of this EventClient in the EventClientDelegateMBean.
static MBeanServerConnection	getEventClientConnection(MBeanServerConnection conn) Constructs an MBeanServerConnection that uses an EventClient object, if the underlying connection has an EventClientDelegateMBean.
static MBeanServerConnection	getEventClientConnection(MBeanServerConnection conn, EventRelay eventRelay) Constructs an MBeanServerConnection that uses an EventClient object with a user-specific EventRelay object.
MBeanNotificationInfo[]	getEventClientNotificationInfo() Get the types of notification that an EventClient can send to listeners added with addEventClientListener.
EventRelay	getEventRelay() Return the EventRelay associated with this EventClient.
Collection<ListenerInfo>	getListeners() Returns the collection of listeners that have been added through this EventClient and not subsequently removed.
long	getRequestedLeaseTime() Return the lease time that this EventClient requests on every lease renewal.
void	removeEventClientListener(NotificationListener listener) Removes a listener added to receive EventClient notifications specified in getEventClientNotificationInfo().
void	removeNotificationListener(ObjectName name, NotificationListener listener) Removes a listener from a registered MBean.
void	removeNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from a registered MBean.
void	subscribe(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) Subscribes a listener to receive events from an MBean or a set of MBeans represented by an ObjectName pattern.
void	unsubscribe(ObjectName name, NotificationListener listener) Unsubscribes a listener which is listening to an MBean or a set of MBeans represented by an ObjectName pattern.

Methods inherited from class java.lang.Object

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

Field Detail

FAILED

public static final String FAILED

A notification string type used by an EventClient object to inform a listener added by addEventClientListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object) that it failed to get notifications from a remote server, and that it is possible that no more notifications will be delivered.

See Also:

addEventClientListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), EventReceiver.failed(java.lang.Throwable), Constant Field Values

NONFATAL

public static final String NONFATAL

Reports that an unexpected exception has been received by the EventRelay object but that it is non-fatal. For example, a notification received is not serializable or its class is not found.

See Also:

addEventClientListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), EventReceiver.nonFatal(java.lang.Exception), Constant Field Values

NOTIFS_LOST

public static final String NOTIFS_LOST

A notification string type used by an EventClient object to inform a listener added by addEventClientListener that it has detected that notifications have been lost. The userData of the notification is a Long which is an upper bound on the number of lost notifications that have just been detected.

See Also:

addEventClientListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), Constant Field Values

DEFAULT_REQUESTED_LEASE_TIME

public static final long DEFAULT_REQUESTED_LEASE_TIME

The default lease time that EventClient instances will request, in milliseconds. This value is 300000L.

See Also:

EventClientDelegateMBean.lease(java.lang.String, long), Constant Field Values

Constructor Detail

EventClient

public EventClient(MBeanServerConnection conn)
            throws IOException

Constructs a default EventClient object.

This object creates a FetchingEventRelay object to receive notifications forwarded by the EventClientDelegateMBean. The EventClientDelegateMBean that it works with is the one registered with the default ObjectName. The thread from the FetchingEventRelay object that fetches the notifications is also used to distribute them.

Parameters:

conn - An MBeanServerConnection object used to communicate with an EventClientDelegateMBean MBean.

Throws:

IllegalArgumentException - If conn is null.

IOException - If an I/O error occurs when communicating with the EventClientDelegateMBean.

EventClient

public EventClient(EventClientDelegateMBean delegate)
            throws IOException

Constructs an EventClient object with a specified EventClientDelegateMBean.

This object creates a FetchingEventRelay object to receive notifications forwarded by the EventClientDelegateMBean. The thread from the FetchingEventRelay object that fetches the notifications is also used to distribute them.

Parameters:

delegate - An EventClientDelegateMBean object to work with.

Throws:

IllegalArgumentException - If delegate is null.

IOException - If an I/O error occurs when communicating with the the EventClientDelegateMBean.

EventClient

public EventClient(EventClientDelegateMBean delegate,
                   EventRelay eventRelay,
                   Executor distributingExecutor,
                   ScheduledExecutorService leaseScheduler,
                   long requestedLeaseTime)
            throws IOException

Constructs an EventClient object with the specified EventClientDelegateMBean, EventRelay object, and distributing thread.

Parameters:

delegate - An EventClientDelegateMBean object to work with. Usually, this will be a proxy constructed using EventClientDelegate.getProxy(javax.management.MBeanServerConnection).

eventRelay - An object used to receive notifications forwarded by the EventClientDelegateMBean. If null, a FetchingEventRelay object will be used.

distributingExecutor - Used to distribute notifications to local listeners. Only one job at a time will be submitted to this Executor. If distributingExecutor is null, the thread that calls EventReceiver.receive from the EventRelay object is used.

leaseScheduler - An object that will be used to schedule the periodic lease updates. If null, a default scheduler will be used.

requestedLeaseTime - The lease time used to keep this client alive in the EventClientDelegateMBean. A value of zero is equivalent to the default value.

Throws:

IllegalArgumentException - If delegate is null.

IOException - If an I/O error occurs when communicating with the EventClientDelegateMBean.

Method Detail

close

public void close()
           throws IOException

Closes this EventClient, removes all listeners and stops receiving notifications.

This method calls EventClientDelegateMBean.removeClient(String) and EventRelay.stop(). Both operations occur even if one of them throws an IOException.

Throws:

IOException - if an I/O error occurs when communicating with EventClientDelegateMBean, or if EventRelay.stop() throws an IOException.

closed

public boolean closed()

Determine if this EventClient is closed.

Returns:

True if the EventClient is closed.

getEventRelay

public EventRelay getEventRelay()

Return the EventRelay associated with this EventClient.

Returns:

The EventRelay object used.

getRequestedLeaseTime

public long getRequestedLeaseTime()

Return the lease time that this EventClient requests on every lease renewal.

Returns:

The requested lease time.

See Also:

EventClientDelegateMBean.lease(java.lang.String, long)

addNotificationListener

public void addNotificationListener(ObjectName name,
                                    NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
                             throws InstanceNotFoundException,
                                    IOException

Description copied from interface: NotificationManager

Adds a listener to a registered MBean. Notifications emitted by the MBean will be forwarded to the listener.

Specified by:

addNotificationListener in interface NotificationManager

Parameters:

name - The name of the MBean on which the listener should be added.

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

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

handback - The context to be sent to the listener when a notification is emitted.

Throws:

InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.

IOException - A communication problem occurred when talking to the MBean server.

See Also:

MBeanServerConnection.addNotificationListener( ObjectName, NotificationListener, NotificationFilter, Object).

removeNotificationListener

public void removeNotificationListener(ObjectName name,
                                       NotificationListener listener)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException

Description copied from interface: NotificationManager

Removes a listener from a registered MBean.

If the listener is registered more than once, perhaps with different filters or callbacks, this method will remove all those registrations.

Specified by:

removeNotificationListener in interface NotificationManager

Parameters:

name - The name of the MBean on which the listener should be removed.

listener - The listener to be removed.

Throws:

InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.

ListenerNotFoundException - The listener is not registered in the MBean.

IOException - A communication problem occurred when talking to the MBean server.

See Also:

MBeanServerConnection.removeNotificationListener( ObjectName, NotificationListener).

removeNotificationListener

public void removeNotificationListener(ObjectName name,
                                       NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException

Description copied from interface: NotificationManager

Removes a listener from a registered 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 NotificationManager

Parameters:

name - The name of the MBean on which the listener should be removed.

listener - The listener to be removed.

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

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

Throws:

InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.

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

IOException - A communication problem occurred when talking to the MBean server.

See Also:

MBeanServerConnection.removeNotificationListener( ObjectName, NotificationListener, NotificationFilter, Object).

unsubscribe

public void unsubscribe(ObjectName name,
                        NotificationListener listener)
                 throws ListenerNotFoundException,
                        IOException

Description copied from interface: EventConsumer

Unsubscribes a listener which is listening to an MBean or a set of MBeans represented by an ObjectName pattern.

The listener to be removed must have been added by the subscribe method with the given name. If the name is a pattern, then the subscribe must have used the same pattern. If the same listener has been subscribed more than once to the name, perhaps with different filters or handbacks, then all such listeners are removed.

Specified by:

unsubscribe in interface EventConsumer

Parameters:

name - The name of the MBean or an ObjectName pattern representing a set of MBeans to which the listener was subscribed.

listener - A listener that was previously subscribed to the MBean(s).

Throws:

ListenerNotFoundException - The given listener was not subscribed to the given name.

IOException - for a remote client, thrown if an I/O error occurs.

See Also:

EventConsumer.unsubscribe( ObjectName, NotificationListener).

subscribe

public void subscribe(ObjectName name,
                      NotificationListener listener,
                      NotificationFilter filter,
                      Object handback)
               throws IOException

Description copied from interface: EventConsumer

Subscribes a listener to receive events from an MBean or a set of MBeans represented by an ObjectName pattern.

An event emitted by an MBean is forwarded to every listener that was subscribed with the name of that MBean, or with a pattern that matches that name.

Specified by:

subscribe in interface EventConsumer

Parameters:

name - The name of an MBean or an ObjectName pattern representing a set of MBeans to which the listener should listen.

listener - The listener object that will handle the notifications emitted by the MBeans.

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

handback - The context to be sent to the listener when a notification is emitted.

Throws:

IOException - for a remote client, thrown if an I/O error occurs.

See Also:

EventConsumer.subscribe( ObjectName, NotificationListener, NotificationFilter, Object).

addListeners

public Collection<ListenerInfo> addListeners(Collection<ListenerInfo> listeners)
                                      throws IOException

Adds a set of listeners to the remote MBeanServer. This method can be used to copy the listeners from one EventClient to another.

A listener is represented by a ListenerInfo object. The listener is added by calling subscribe(ObjectName, NotificationListener, NotificationFilter, Object) if the method isSubscription returns true; otherwise it is added by calling addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object).

The method returns the listeners which were added successfully. The elements in the returned collection are a subset of the elements in listeners. If all listeners were added successfully, the two collections are the same. If no listener was added successfully, the returned collection is empty.

Parameters:

listeners - the listeners to add.

Returns:

The listeners that were added successfully.

Throws:

IOException - If an I/O error occurs.

See Also:

getListeners()

getListeners

public Collection<ListenerInfo> getListeners()

Returns the collection of listeners that have been added through this EventClient and not subsequently removed. The returned collection contains one entry for every listener added with addNotificationListener or subscribe and not subsequently removed with removeNotificationListener or unsubscribe, respectively.

Returns:

A collection of listener information. Empty if there are no current listeners or if this EventClient has been closed.

See Also:

addListeners(java.util.Collection)

addEventClientListener

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

Adds a listener to receive the EventClient notifications specified in getEventClientNotificationInfo().

Parameters:

listener - A listener to receive EventClient 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:

removeEventClientListener(javax.management.NotificationListener)

removeEventClientListener

public void removeEventClientListener(NotificationListener listener)
                               throws ListenerNotFoundException

Removes a listener added to receive EventClient notifications specified in getEventClientNotificationInfo().

Parameters:

listener - A listener to receive EventClient notifications.

Throws:

NullPointerException - If listener is null.

ListenerNotFoundException - If the listener is not added to this EventClient.

getEventClientNotificationInfo

public MBeanNotificationInfo[] getEventClientNotificationInfo()

Get the types of notification that an EventClient can send to listeners added with addEventClientListener.

Returns:

Types of notification emitted by this EventClient.

See Also:

FAILED, NONFATAL, NOTIFS_LOST

getEventClientConnection

public static MBeanServerConnection getEventClientConnection(MBeanServerConnection conn)
                                                      throws IOException

Constructs an MBeanServerConnection that uses an EventClient object, if the underlying connection has an EventClientDelegateMBean.

The EventClient object creates a default FetchingEventRelay object to receive notifications forwarded by the EventClientDelegateMBean. The EventClientDelegateMBean it works with is the default one registered with the ObjectName OBJECT_NAME. The thread from the FetchingEventRelay object that fetches the notifications is also used to distribute them.

Parameters:

conn - An MBeanServerConnection object used to communicate with an EventClientDelegateMBean.

Throws:

IllegalArgumentException - If the value of conn is null, or the default EventClientDelegateMBean is not registered.

IOException - If an I/O error occurs.

getEventClientConnection

public static MBeanServerConnection getEventClientConnection(MBeanServerConnection conn,
                                                             EventRelay eventRelay)
                                                      throws IOException

Constructs an MBeanServerConnection that uses an EventClient object with a user-specific EventRelay object.

The EventClientDelegateMBean which it works with is the default one registered with the ObjectName OBJECT_NAME The thread that calls EventReceiver.receive from the EventRelay object is used to distribute notifications to their listeners.

Parameters:

conn - An MBeanServerConnection object used to communicate with an EventClientDelegateMBean.

eventRelay - A user-specific object used to receive notifications forwarded by the EventClientDelegateMBean. If null, the default FetchingEventRelay object is used.

Throws:

IllegalArgumentException - If the value of conn is null, or the default EventClientDelegateMBean is not registered.

IOException - If an I/O error occurs.

getClientId

public String getClientId()

Get the client id of this EventClient in the EventClientDelegateMBean.

Returns:

the client id.

See Also:

EventClientDelegateMBean.addClient