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

Package javax.management.event

Defines the Event Service, which provides extended support for JMX notifications.

See:
Description

Interface Summary

Interface	Description
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.
EventConsumer	This interface specifies methods to subscribe a listener to receive events from an MBean or a set of MBeans.
EventForwarder	This interface can be used to specify a custom forwarding mechanism for EventClientDelegateMBean to forward events to the client.
EventReceiver	An object implementing this interface is passed by an EventClient to its EventRelay, to allow the EventRelay to communicate received notifications to the EventClient.
EventRelay	This interface is used to specify a way to receive notifications from a remote MBean server and then to forward the notifications to an EventClient.
NotificationManager	This interface specifies methods to add and remove notification listeners on named MBeans.
RMIPushServer	The RMIPushEventRelay exports an RMI object of this class and sends a client stub for that object to the associated RMIPushEventForwarder in a remote MBean server.

Class Summary

Class	Description
EventClient	This class is used to manage its notification listeners on the client side in the same way as on the MBean server side.
EventClientDelegate	This is the default implementation of the MBean EventClientDelegateMBean.
EventSubscriber	An object that can be used to subscribe for notifications from all MBeans in an MBeanServer that match a pattern.
FetchingEventForwarder	This class is used by FetchingEventRelay.
FetchingEventRelay	This class is an implementation of the EventRelay interface.
ListenerInfo	This class specifies all the information required to register a user listener into a remote MBean server.
RMIPushEventForwarder	This class is used by RMIPushEventRelay.
RMIPushEventRelay	This class is an implementation of the EventRelay interface, using push mode.

Exception Summary

Exception	Description
EventClientNotFoundException	Thrown if an event client identifier is unknown.

Package javax.management.event Description

Defines the Event Service, which provides extended support for JMX notifications.

The Event Service provides greater control over notification handling than the default technique using MBeanServer.addNotificationListener or MBeanServerConnection.addNotificationListener.

Here are some reasons you may want to use the Event Service:

• To receive notifications from a set of MBeans defined by an ObjectName pattern, such as com.example.config:type=Cache,*.
• When the notification-handling behavior of the connector you are using does not match your requirements. For example, with the standard RMI connector you can lose notifications if there are very many of them in the MBean Server you are connected to, even if you are only listening for a small proportion of them.
• To change the threading behavior of notification dispatch.
• To define a different transport for notifications, for example to arrange for them to be delivered through the Java Message Service (JMS). The Event Service comes with one alternative transport as standard, a "push-mode" RMI transport.
• To handle notifications on behalf of MBeans (often virtual) in a namespace.

The Event Service is new in version 2.0 of the JMX API, which is the version introduced in version 7 of the Java SE platform. It is not usually possible to use the Event Service when connecting remotely to an MBean Server that is running an earlier version.

Handling remote notifications with the Event Service

Prior to version 2.0 of the JMX API, every connector had to include logic to handle notifications. The standard RMI and JMXMP connectors defined by JSR 160 handle notifications in a way that is not always appropriate for applications. Specifically, the connector server adds one listener to every MBean that might emit notifications, and adds all received notifications to a fixed-size buffer. This means that if there are very many notifications, a remote client may miss some, even if it is only registered for a very small subset of notifications. Furthermore, since every NotificationBroadcaster MBean gets a listener from the connector server, MBeans cannot usefully optimize by only sending notifications when there is a listener. Finally, since the connector server uses just one listener per MBean, MBeans cannot impose custom behavior per listener, such as security checks or localized notifications.

The Event Service does not have these restrictions. The RMI connector that is included in this version of the JMX API uses the Event Service by default, although it can be configured to have the previous behavior if required.

The Event Service can be used with any connector via the method EventClient.getEventClientConnection, like this:

 JMXConnector conn = ...;
 MBeanServerConnection mbsc = conn.getMBeanServerConnection();
 MBeanServerConnection eventMbsc = EventClient.getEventClientConnection(mbsc);
 

If you add listeners using eventMbsc.addNotificationListener instead of mbsc.addNotificationListener, then they will be handled by the Event Service rather than by the connector's notification system.

For the Event Service to work, either the EventClientDelegateMBean must be registered in the MBean Server, or the connector server must be configured to simulate the existence of this MBean, for example using EventClientDelegate.newForwarder. The standard RMI connector is so configured by default. The EventClientDelegateMBean documentation has further details.

Receiving notifications from a set of MBeans

The Event Server allows you to receive notifications from every MBean that matches an ObjectName pattern. For local clients (in the same JVM as the MBean Server), the EventSubscriber class can be used for this. For remote clients, or if the same code is to be used locally and remotely, use an EventClient.

EventSubscriber and EventClient correctly handle the case where a new MBean is registered under a name that matches the pattern. Notifications from the new MBean will also be received.

Here is how to receive notifications from all MBeans in a local MBeanServer that match com.example.config:type=Cache,*:

 MBeanServer mbs = ...;
 NotificationListener listener = ...;
 ObjectName pattern = new ObjectName("com.example.config:type=Cache,*");
 EventSubscriber esub = EventSubscriber.getEventSubscriber(mbs);
 esub.subscribe(pattern, listener, null, null);
 

Here is how to do the same thing remotely:

 MBeanServerConnection mbsc = jmxConnector.getMBeanServerConnection();
 EventClient events = new EventClient(mbsc);
 NotificationListener listener = ...;
 ObjectName pattern = new ObjectName("com.example.config:type=Cache,*");
 events.subscribe(pattern, listener, null, null);
 

Controlling threading behavior for notification dispatch

The EventClient class can be used to control threading of listener dispatch. For example, to arrange for all listeners to be invoked in the same thread, you can create an EventClient like this:

 MBeanServerConnection mbsc = ...;
 Executor singleThreadExecutor = Executors.newSingleThreadExecutor();
 EventClient events = new EventClient(
         mbsc, null, singleThreadExecutor, EventClient.DEFAULT_LEASE_TIMEOUT);
 events.addNotificationListener(...);
 events.subscribe(...);
 

Leasing

The EventClient uses a lease mechanism to ensure that resources are eventually released on the server even if the client does not explicitly clean up. (This can happen through network partitioning, for example.)

When an EventClient registers with the EventClientDelegateMBean using one of the addClient methods, an initial lease is created with a default expiry time. The EventClient requests an explicit lease shortly after that, with a configurable expiry time. Then the EventClient periodically renews the lease before it expires, typically about half way through the lifetime of the lease. If at any point the lease reaches the expiry time of the last renewal then it expires, and EventClient is unregistered as if it had called the removeClient method.

Custom notification transports

When you create an EventClient, you can define the transport that it uses to deliver notifications. The transport might use the Java Message Service (JMS) or any other communication system. Specifying a transport is useful for example when you want different network behavior from the default, or different reliability guarantees. The default transport calls EventClientDelegateMBean.fetchNotifications repeatedly, which usually means that there must be a network connection permanently open between the client and the server. If the same client is connected to many servers this can cause scalability problems. If notifications are relatively rare, then JMS or the push-mode RMI transport may be more suitable.

A transport is implemented by an EventRelay on the client side and a corresponding EventForwarder on the server side. An example is the RMIPushEventRelay and its RMIPushEventForwarder.

To use a given transport with an EventClient, you first create an instance of its EventRelay. Typically the EventRelay's constructor will have a parameter of type MBeanServerConnection or EventClientDelegateMBean, so that it can communicate with the EventClientDelegateMBean in the server. For example, the RMIPushEventForwarder's constructors all take an EventClientDelegateMBean parameter, which is expected to be a proxy for the EventClientDelegateMBean in the server.

When it is created, the EventRelay will call EventClientDelegateMBean.addClient. It passes the name of the EventForwarder class and its constructor parameters. The EventClientDelegateMBean will instantiate this class using MBeanServer.instantiate, and it will return a unique client id.

Then you pass the newly-created EventRelay to one of the EventClient constructors, and you have an EventClient that uses the chosen transport.

For example, when you create an RMIPushEventRelay, it uses MBeanServerDelegateMBean.addClient to create an RMIEventForwarder in the server. Notifications will then be delivered through an RMI communication from the RMIEventForwarder to the RMIPushEventRelay.

Writing a custom transport

To write a custom transport, you need to understand the sequence of events when an EventRelay and its corresponding EventForwarder are created, and when a notification is sent from the EventForwarder to the EventRelay.

When an EventRelay is created:

• The EventRelay must call EventClientDelegateMBean.addClient with the name of the EventForwarder and the constructor parameters.

• EventClientDelegateMBean.addClient will do the following steps:

  • create the EventForwarder using MBeanServer.instantiate;
  • allocate a unique client id;
  • call the new EventForwarder's setClientId method with the new client id;
  • return the client id to the caller.

When an EventClient is created with an EventRelay parameter, it calls EventRelay.setEventReceiver with an EventReceiver that the EventRelay will use to deliver notifications.

When a listener is added using the EventClient, the EventRelay and EventForwarder are not involved.

When an MBean emits a notification and a listener has been added to that MBean using the EventClient:

• The EventForwarder's forward method is called with the notification and a listener id.

• The EventForwarder sends the notification and listener id to the EventRelay using the custom transport.

• The EventRelay delivers the notification by calling EventReceiver.receive.

When the EventClient is closed (EventClient.close):

• The EventClient calls EventRelay.stop.

• The EventClient calls EventClientDelegateMBean.removeClient.

• The EventClientDelegateMBean removes any listeners it had added on behalf of this EventClient.

• The EventClientDelegateMBean calls EventForwarder.close.

Threading and buffering

The EventForwarder.forward method may be called in the thread that the source MBean is using to send its notification. MBeans can expect that notification sending does not block. Therefore a forward method will typically add the notification to a queue, with a separate thread that takes notifications off the queue and sends them.

An EventRelay does not usually need to buffer notifications before giving them to EventReceiver.receive. Although by default each such notification will be sent to potentially-slow listeners, if this is a problem then an Executor can be given to the EventClient constructor to cause the listeners to be called in a different thread.

Since:

1.7