javax.management
Class NotificationBroadcasterSupport

java.lang.Object
  extended by javax.management.NotificationBroadcasterSupport
All Implemented Interfaces:
NotificationBroadcaster, NotificationEmitter

public class NotificationBroadcasterSupport
extends Object
implements NotificationEmitter

Provides an implementation of the NotificationEmitter interface, which beans may utilise by extension. By default, a synchronous dispatch system is provided, whereby the handleNotification(NotificationListener, Notification, Object) is called once per listener by {*@link #sendNotification(Notification)} before returning. Thus, unless the listener is remote, it will have received the notification before the method returns. This may be changed by overriding the handleNotification method, or by providing an Executor to use. With the latter, the dispatch of a notification to a particular listener will form one task performed by the executor.

Any exceptions thrown by the dispatch process will be caught, allowing other listeners to still receive the notification. However, any Errors that are thrown will be propogated to the caller of sendNotification(Notification).

Since:
1.5

Constructor Summary
NotificationBroadcasterSupport()
          Constructs a NotificationBroadcasterSupport using the default synchronous dispatch model, where a single thread sends the notification to all listeners.
NotificationBroadcasterSupport(java.util.concurrent.Executor executor)
          Constructs a NotificationBroadcasterSupport where the specified (@link java.util.concurrent.Executor} is used to perform each invocation of the handleNotification(NotificationListener, Notification, Object) method.
NotificationBroadcasterSupport(java.util.concurrent.Executor executor, MBeanNotificationInfo... info)
          Constructs a NotificationBroadcasterSupport where the specified (@link java.util.concurrent.Executor} is used to perform each invocation of the handleNotification(NotificationListener, Notification, Object) method.
NotificationBroadcasterSupport(MBeanNotificationInfo... info)
          Constructs a NotificationBroadcasterSupport using the default synchronous dispatch model, where a single thread sends the notification to all listeners.
 
Method Summary
 void addNotificationListener(NotificationListener listener, NotificationFilter filter, Object passback)
          Registers the specified listener as a new recipient of notifications from this bean.
 MBeanNotificationInfo[] getNotificationInfo()
          Returns an array describing the notifications this bean may send to its registered listeners.
protected  void handleNotification(NotificationListener listener, Notification notif, Object passback)
          This method is called on a per-listener basis, either from this thread or the supplied executor, and may be overridden by subclasses which wish to change how notifications are delivered.
 void removeNotificationListener(NotificationListener listener)
          Removes the specified listener from the list of recipients of notifications from this bean.
 void removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object passback)
          Removes the specified listener from the list of recipients of notifications from this bean.
 void sendNotification(Notification notif)
           Performs delivery of the notification.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NotificationBroadcasterSupport

public NotificationBroadcasterSupport()
Constructs a NotificationBroadcasterSupport using the default synchronous dispatch model, where a single thread sends the notification to all listeners. This is equivalent to calling NotificationBroadcasterSupport(null, null).


NotificationBroadcasterSupport

public NotificationBroadcasterSupport(java.util.concurrent.Executor executor)
Constructs a NotificationBroadcasterSupport where the specified (@link java.util.concurrent.Executor} is used to perform each invocation of the handleNotification(NotificationListener, Notification, Object) method. Filtering is performed beforehand, by this thread; only calls which have successfully passed through the filter are sent to the executor. This is equivalent to calling NotificationBroadcasterSupport(executor, null).

Parameters:
executor - the executor to use for each call to handleNotification().
Since:
1.6

NotificationBroadcasterSupport

public NotificationBroadcasterSupport(MBeanNotificationInfo... info)
Constructs a NotificationBroadcasterSupport using the default synchronous dispatch model, where a single thread sends the notification to all listeners. The specified MBeanNotificationInfo array is used to provide information about the notifications on calls to getNotificationInfo(), where a clone will be returned if the array is non-empty. This is equivalent to calling NotificationBroadcasterSupport(null, info).

Parameters:
info - an array of MBeanNotificationInfo objects describing the notifications delivered by this broadcaster. This may be null, which is taken as being equivalent to an empty array.

NotificationBroadcasterSupport

public NotificationBroadcasterSupport(java.util.concurrent.Executor executor,
                                      MBeanNotificationInfo... info)
Constructs a NotificationBroadcasterSupport where the specified (@link java.util.concurrent.Executor} is used to perform each invocation of the handleNotification(NotificationListener, Notification, Object) method. Filtering is performed beforehand, by this thread; only calls which have successfully passed through the filter are sent to the executor. The specified MBeanNotificationInfo array is used to provide information about the notifications on calls to getNotificationInfo(), where a clone will be returned if the array is non-empty.

Parameters:
executor - the executor to use for each call to handleNotification().
info - an array of MBeanNotificationInfo objects describing the notifications delivered by this broadcaster. This may be null, which is taken as being equivalent to an empty array.
Since:
1.6
Method Detail

addNotificationListener

public void addNotificationListener(NotificationListener listener,
                                    NotificationFilter filter,
                                    Object passback)
                             throws IllegalArgumentException
Registers the specified listener as a new recipient of notifications from this bean. If non-null, the filter argument will be used to select which notifications are delivered. The supplied object will also be passed to the recipient with each notification. This should not be modified by the broadcaster, but instead should be passed unmodified to the listener.

Specified by:
addNotificationListener in interface NotificationBroadcaster
Parameters:
listener - the new listener, who will receive notifications from this broadcasting bean.
filter - a filter to determine which notifications are delivered to the listener, or null if no filtering is required.
passback - an object to be passed to the listener with each notification.
Throws:
IllegalArgumentException - if listener is null.
See Also:
removeNotificationListener(NotificationListener)

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Returns an array describing the notifications this bean may send to its registered listeners. Ideally, this array should be complete, but in some cases, this may not be possible. However, be aware that some listeners may expect this to be so.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Returns:
the array of possible notifications.

handleNotification

protected void handleNotification(NotificationListener listener,
                                  Notification notif,
                                  Object passback)
This method is called on a per-listener basis, either from this thread or the supplied executor, and may be overridden by subclasses which wish to change how notifications are delivered. The default implementation simply calls listener.handleNotification(notif, passback).

Parameters:
listener - the listener to send the notification to.
notif - the notification to dispatch.
passback - the passback object of the listener.

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException
Removes the specified listener from the list of recipients of notifications from this bean. This includes all combinations of filters and passback objects registered for this listener. For more specific removal of listeners, see the subinterface NotificationEmitter.

Specified by:
removeNotificationListener in interface NotificationBroadcaster
Parameters:
listener - the listener to remove.
Throws:
ListenerNotFoundException - if the specified listener is not registered with this bean.
See Also:
addNotificationListener(NotificationListener, NotificationFilter, java.lang.Object)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object passback)
                                throws ListenerNotFoundException
Removes the specified listener from the list of recipients of notifications from this bean. Only the first instance with the supplied filter and passback object is removed. null is used as a valid value for these parameters, rather than as a way to remove all registration instances for the specified listener; for this behaviour instead, see the details of the same method in NotificationBroadcaster.

Specified by:
removeNotificationListener in interface NotificationEmitter
Parameters:
listener - the listener to remove.
filter - the filter of the listener to remove.
passback - the passback object of the listener to remove.
Throws:
ListenerNotFoundException - if the specified listener is not registered with this bean.
See Also:
addNotificationListener(NotificationListener, NotificationFilter, java.lang.Object)

sendNotification

public void sendNotification(Notification notif)

Performs delivery of the notification. If an executor was specified on construction, this will be used to call handleNotification(NotificationListener, Notification, Object). If the executor is null, however, this thread calls the method itself in order to perform a synchronous dispatch of the notification to all eligible listeners.

Prior to either process taking place, the listeners are filtered. Notifications are only delivered if the filter is either null or returns true from the NotificationFilter.isNotificationEnabled(Notification) method.

Parameters:
notif - the notification to send.