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

javax.management.event
Interface EventClientDelegateMBean

All Known Implementing Classes:

EventClientDelegate

public interface EventClientDelegateMBean

This interface specifies necessary methods on the MBean server side for a JMX remote client to manage its notification listeners as if they are local. Users do not usually work directly with this MBean; instead, the EventClient class is designed to be used directly by the user.

A default implementation of this interface can be added to an MBean Server in one of several ways.

• The most usual is to insert an MBeanServerForwarder between the Connector Server and the MBean Server, that will intercept accesses to the Event Client Delegate MBean and treat them as the real MBean would. This forwarder is inserted by default with the standard RMI Connector Server, and can also be created explicitly using EventClientDelegate.newForwarder.

• A variant on the above is to replace the MBean Server that is used locally with a forwarder as described above. Since MBeanServerForwarder extends MBeanServer, you can use a forwarder anywhere you would have used the original MBean Server. The code to do this replacement typically looks something like this:

   MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();  // or whatever
   mbs = EventClientDelegate.newForwarder(mbs, null);
   // now use mbs just as you did before, but it will have an EventClientDelegate
   

• The final way is to create an instance of EventClientDelegate and register it in the MBean Server under the standard name:

   MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();  // or whatever
   EventClientDelegate ecd = EventClientDelegate.getEventClientDelegate(mbs);
   mbs.registerMBean(ecd, EventClientDelegateMBean.OBJECT_NAME);
   
   

Since:

JMX 2.0

Field Summary

Modifier and Type	Field and Description
static int	EVENT_CLIENT_LISTENER_ID A unique listener identifier specified for an EventClient.
static ObjectName	OBJECT_NAME The standard ObjectName used to register the default EventClientDelegateMBean.
static String	OBJECT_NAME_STRING The string representation of OBJECT_NAME.

Method Summary

Modifier and Type	Method and Description
String	addClient(String className, Object[] params, String[] sig) Adds a new client to the EventClientDelegateMBean with a user-specified EventForwarder to forward notifications to the client.
String	addClient(String className, ObjectName classLoader, Object[] params, String[] sig) Adds a new client to the EventClientDelegateMBean with a user-specified EventForwarder to forward notifications to the client.
Integer	addListener(String clientId, ObjectName name, NotificationFilter filter) Adds a listener to receive notifications from an MBean and returns a non-negative integer as the identifier of the listener.
Integer	addSubscriber(String clientId, ObjectName name, NotificationFilter filter) Subscribes a listener to receive notifications from an MBean or a set of MBeans represented by an ObjectName pattern.
NotificationResult	fetchNotifications(String clientId, long startSequenceNumber, int maxNotifs, long timeout) Called by a client to fetch notifications that are to be sent to its listeners.
Integer[]	getListenerIds(String clientID) Returns the identifiers of listeners added or subscribed to with the specified client identifier.
long	lease(String clientId, long timeout) An EventClient calls this method to keep its clientId alive in this MBean.
void	removeClient(String clientID) Removes an added client.
void	removeListenerOrSubscriber(String clientId, Integer listenerId) Removes a listener, to stop receiving notifications.

Field Detail

OBJECT_NAME_STRING

static final String OBJECT_NAME_STRING

The string representation of OBJECT_NAME.

See Also:

Constant Field Values

OBJECT_NAME

static final ObjectName OBJECT_NAME

The standard ObjectName used to register the default EventClientDelegateMBean. The name is "javax.management.event:type=EventClientDelegate".

EVENT_CLIENT_LISTENER_ID

static final int EVENT_CLIENT_LISTENER_ID

A unique listener identifier specified for an EventClient. Any notification associated with this id is intended for the EventClient which receives the notification, rather than a listener added using that EventClient.

See Also:

Constant Field Values

Method Detail

addClient

String addClient(String className,
                 Object[] params,
                 String[] sig)
                 throws IOException,
                        MBeanException

Adds a new client to the EventClientDelegateMBean with a user-specified EventForwarder to forward notifications to the client. The EventForwarder is created by calling MBeanServer.instantiate(String, Object[], String[]).

Parameters:

className - The class name used to create an EventForwarder.

params - An array containing the parameters of the constructor to be invoked.

sig - An array containing the signature of the constructor to be invoked

Returns:

A client identifier.

Throws:

IOException - Reserved for a remote call to throw on the client side.

MBeanException - An exception thrown when creating the user specified EventForwarder.

addClient

String addClient(String className,
                 ObjectName classLoader,
                 Object[] params,
                 String[] sig)
                 throws IOException,
                        MBeanException

Adds a new client to the EventClientDelegateMBean with a user-specified EventForwarder to forward notifications to the client. The EventForwarder is created by calling MBeanServer.instantiate(String, ObjectName, Object[], String[]). A user-specified class loader is used to create this EventForwarder.

Parameters:

className - The class name used to create an EventForwarder.

classLoader - An ObjectName registered as a ClassLoader MBean.

params - An array containing the parameters of the constructor to be invoked.

sig - An array containing the signature of the constructor to be invoked

Returns:

A client identifier.

Throws:

IOException - Reserved for a remote call to throw on the client side.

MBeanException - An exception thrown when creating the user specified EventForwarder.

removeClient

void removeClient(String clientID)
                  throws EventClientNotFoundException,
                         IOException

Removes an added client. Calling this method will remove all listeners added with the client.

Throws:

EventClientNotFoundException - If the clientId is not found.

IOException - Reserved for a remote call to throw on the client side.

getListenerIds

Integer[] getListenerIds(String clientID)
                         throws EventClientNotFoundException,
                                IOException

Returns the identifiers of listeners added or subscribed to with the specified client identifier.

If no listener is currently registered with the client, an empty array is returned.

Parameters:

clientID - The client identifier with which the listeners are added or subscribed to.

Returns:

An array of listener identifiers.

Throws:

EventClientNotFoundException - If the clientId is not found.

IOException - Reserved for a remote call to throw on the client side.

addListener

Integer addListener(String clientId,
                    ObjectName name,
                    NotificationFilter filter)
                    throws InstanceNotFoundException,
                           EventClientNotFoundException,
                           IOException

Adds a listener to receive notifications from an MBean and returns a non-negative integer as the identifier of the listener.

This method is called by an EventClient to implement the method EventClient.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object).

Parameters:

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

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

clientId - The client identifier with which the listener is added.

Returns:

A listener identifier.

Throws:

EventClientNotFoundException - Thrown if the clientId is not found.

InstanceNotFoundException - Thrown if the MBean is not found.

IOException - Reserved for a remote call to throw on the client side.

addSubscriber

Integer addSubscriber(String clientId,
                      ObjectName name,
                      NotificationFilter filter)
                      throws EventClientNotFoundException,
                             IOException

Subscribes a listener to receive notifications from an MBean or a set of MBeans represented by an ObjectName pattern. (It is not an error if no MBeans match the pattern at the time this method is called.)

Returns a non-negative integer as the identifier of the listener.

This method is called by an EventClient to execute its method EventClient.subscribe(ObjectName, NotificationListener, NotificationFilter, Object).

Parameters:

clientId - The remote client's identifier.

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

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

Returns:

A listener identifier.

Throws:

IllegalArgumentException - If the name or listener is null.

EventClientNotFoundException - If the client ID is not found.

IOException - Reserved for a remote client to throw if an I/O error occurs.

See Also:

EventConsumer.subscribe(ObjectName, NotificationListener, NotificationFilter,Object), removeListenerOrSubscriber(String, Integer)

removeListenerOrSubscriber

void removeListenerOrSubscriber(String clientId,
                                Integer listenerId)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       EventClientNotFoundException,
                                       IOException

Removes a listener, to stop receiving notifications.

This method is called by an EventClient to execute its methods EventClient.removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), EventClient.removeNotificationListener(ObjectName, NotificationListener), and EventClient.unsubscribe(javax.management.ObjectName, javax.management.NotificationListener).

Parameters:

clientId - The client identifier with which the listener was added.

listenerId - The listener identifier to be removed. This must be an identifier returned by a previous addListener or addSubscriber call.

Throws:

InstanceNotFoundException - if the MBean on which the listener was added no longer exists.

ListenerNotFoundException - if there is no listener with the given listenerId.

EventClientNotFoundException - if the clientId is not found.

IOException - Reserved for a remote call to throw on the client side.

fetchNotifications

NotificationResult fetchNotifications(String clientId,
                                      long startSequenceNumber,
                                      int maxNotifs,
                                      long timeout)
                                      throws EventClientNotFoundException,
                                             IOException

Called by a client to fetch notifications that are to be sent to its listeners.

Parameters:

clientId - The client's identifier.

startSequenceNumber - The first sequence number to consider.

timeout - The maximum waiting time.

maxNotifs - The maximum number of notifications to return.

Throws:

EventClientNotFoundException - Thrown if the clientId is not found.

IllegalArgumentException - if the client was added with an EventForwarder that is not a FetchingEventForwarder.

IOException - Reserved for a remote call to throw on the client side.

lease

long lease(String clientId,
           long timeout)
           throws IOException,
                  EventClientNotFoundException

An EventClient calls this method to keep its clientId alive in this MBean. The client will be removed if the lease times out.

Parameters:

clientId - The client's identifier.

timeout - The time in milliseconds by which the lease is to be extended. The value zero has no special meaning, so it will cause the lease to time out immediately.

Returns:

The new lifetime of the lease in milliseconds. This may be different from the requested time.

Throws:

EventClientNotFoundException - if the clientId is not found.

IOException - reserved for a remote call to throw on the client side.

IllegalArgumentException - if clientId is null or timeout is negative.