| /* NotificationBroadcasterSupport.java -- Supporting implementation. |
| Copyright (C) 2007 Free Software Foundation, Inc. |
| |
| This file is part of GNU Classpath. |
| |
| GNU Classpath is free software; you can redistribute it and/or modify |
| it under the terms of the GNU General Public License as published by |
| the Free Software Foundation; either version 2, or (at your option) |
| any later version. |
| |
| GNU Classpath is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| General Public License for more details. |
| |
| You should have received a copy of the GNU General Public License |
| along with GNU Classpath; see the file COPYING. If not, write to the |
| Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
| 02110-1301 USA. |
| |
| Linking this library statically or dynamically with other modules is |
| making a combined work based on this library. Thus, the terms and |
| conditions of the GNU General Public License cover the whole |
| combination. |
| |
| As a special exception, the copyright holders of this library give you |
| permission to link this library with independent modules to produce an |
| executable, regardless of the license terms of these independent |
| modules, and to copy and distribute the resulting executable under |
| terms of your choice, provided that you also meet, for each linked |
| independent module, the terms and conditions of the license of that |
| module. An independent module is a module which is not derived from |
| or based on this library. If you modify this library, you may extend |
| this exception to your version of the library, but you are not |
| obligated to do so. If you do not wish to do so, delete this |
| exception statement from your version. */ |
| |
| package javax.management; |
| |
| import gnu.javax.management.ListenerData; |
| |
| import java.util.ArrayList; |
| import java.util.Iterator; |
| import java.util.List; |
| |
| import java.util.concurrent.Executor; |
| |
| /** |
| * <p> |
| * Provides an implementation of the {@link NotificationEmitter} |
| * interface, which beans may utilise by extension. By default, |
| * a synchronous dispatch system is provided, whereby the |
| * {@link #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 <code>handleNotification</code> |
| * method, or by providing an {@link java.util.concurrent.Executor} to |
| * use. With the latter, the dispatch of a notification to a particular |
| * listener will form one task performed by the executor. |
| * </p> |
| * <p> |
| * Any exceptions thrown by the dispatch process will be caught, allowing |
| * other listeners to still receive the notification. However, any |
| * {@link Error}s that are thrown will be propogated to the caller of |
| * {@link #sendNotification(Notification)}. |
| * </p> |
| * |
| * @author Andrew John Hughes (gnu_andrew@member.fsf.org) |
| * @since 1.5 |
| */ |
| public class NotificationBroadcasterSupport |
| implements NotificationEmitter |
| { |
| |
| /** |
| * The executor for dispatch, or |
| * <code>null</code> if this thread should |
| * handle dispatch itself. |
| */ |
| private Executor executor; |
| |
| /** |
| * An array containing information on each |
| * notification, or <code>null</code> if an |
| * empty array should be returned by |
| * {@link #getNotificationInfo()}. |
| */ |
| private MBeanNotificationInfo[] info; |
| |
| /** |
| * The list of listeners registered with |
| * this broadcaster. |
| */ |
| private final List<ListenerData> listeners = |
| new ArrayList<ListenerData>(); |
| |
| /** |
| * Constructs a {@link NotificationBroadcasterSupport} using |
| * the default synchronous dispatch model, where a single |
| * thread sends the notification to all listeners. This |
| * is equivalent to calling |
| * <code>NotificationBroadcasterSupport(null, null)</code>. |
| */ |
| public NotificationBroadcasterSupport() |
| { |
| this(null, (MBeanNotificationInfo[]) null); |
| } |
| |
| /** |
| * Constructs a {@link NotificationBroadcasterSupport} where |
| * the specified (@link java.util.concurrent.Executor} is used |
| * to perform each invocation of the |
| * {@link #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 |
| * <code>NotificationBroadcasterSupport(executor, null)</code>. |
| * |
| * @param executor the executor to use for each call to |
| * <code>handleNotification()</code>. |
| * @since 1.6 |
| */ |
| public NotificationBroadcasterSupport(Executor executor) |
| { |
| this(executor, (MBeanNotificationInfo) null); |
| } |
| |
| /** |
| * Constructs a {@link NotificationBroadcasterSupport} using |
| * the default synchronous dispatch model, where a single |
| * thread sends the notification to all listeners. The specified |
| * {@link MBeanNotificationInfo} array is used to provide |
| * information about the notifications on calls to |
| * {@link #getNotificationInfo()}, where a clone will be |
| * returned if the array is non-empty. This is equivalent to |
| * calling <code>NotificationBroadcasterSupport(null, info)</code>. |
| * |
| * @param info an array of {@link MBeanNotificationInfo} objects |
| * describing the notifications delivered by this |
| * broadcaster. This may be <code>null</code>, which |
| * is taken as being equivalent to an empty array. |
| */ |
| public NotificationBroadcasterSupport(MBeanNotificationInfo... info) |
| { |
| this(null, info); |
| } |
| |
| /** |
| * Constructs a {@link NotificationBroadcasterSupport} where |
| * the specified (@link java.util.concurrent.Executor} is used |
| * to perform each invocation of the |
| * {@link #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 |
| * {@link MBeanNotificationInfo} array is used to provide |
| * information about the notifications on calls to |
| * {@link #getNotificationInfo()}, where a clone will be |
| * returned if the array is non-empty. |
| * |
| * @param executor the executor to use for each call to |
| * <code>handleNotification()</code>. |
| * @param info an array of {@link MBeanNotificationInfo} objects |
| * describing the notifications delivered by this |
| * broadcaster. This may be <code>null</code>, which |
| * is taken as being equivalent to an empty array. |
| * @since 1.6 |
| */ |
| public NotificationBroadcasterSupport(Executor executor, |
| MBeanNotificationInfo... info) |
| { |
| this.executor = executor; |
| this.info = info; |
| } |
| |
| /** |
| * 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. |
| * |
| * @param listener the new listener, who will receive |
| * notifications from this broadcasting bean. |
| * @param filter a filter to determine which notifications are |
| * delivered to the listener, or <code>null</code> |
| * if no filtering is required. |
| * @param passback an object to be passed to the listener with |
| * each notification. |
| * @throws IllegalArgumentException if <code>listener</code> is |
| * <code>null</code>. |
| * @see #removeNotificationListener(NotificationListener) |
| */ |
| public void addNotificationListener(NotificationListener listener, |
| NotificationFilter filter, |
| Object passback) |
| throws IllegalArgumentException |
| { |
| if (listener == null) |
| throw new IllegalArgumentException("Null listener added to bean."); |
| listeners.add(new ListenerData(listener, filter, passback)); |
| } |
| |
| /** |
| * 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. |
| * |
| * @return the array of possible notifications. |
| */ |
| public MBeanNotificationInfo[] getNotificationInfo() |
| { |
| if (info == null || info.length == 0) |
| return new MBeanNotificationInfo[0]; |
| return (MBeanNotificationInfo[]) info.clone(); |
| } |
| |
| /** |
| * 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 |
| * <code>listener.handleNotification(notif, passback)</code>. |
| * |
| * @param listener the listener to send the notification to. |
| * @param notif the notification to dispatch. |
| * @param passback the passback object of the listener. |
| */ |
| protected void handleNotification(NotificationListener listener, |
| Notification notif, |
| Object passback) |
| { |
| listener.handleNotification(notif, passback); |
| } |
| |
| /** |
| * 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 |
| * {@link NotificationEmitter}. |
| * |
| * @param listener the listener to remove. |
| * @throws ListenerNotFoundException if the specified listener |
| * is not registered with this bean. |
| * @see #addNotificationListener(NotificationListener, NotificationFilter, |
| * java.lang.Object) |
| */ |
| public void removeNotificationListener(NotificationListener listener) |
| throws ListenerNotFoundException |
| { |
| Iterator<ListenerData> it = listeners.iterator(); |
| boolean foundOne = false; |
| while (it.hasNext()) |
| { |
| if (it.next().getListener() == listener) |
| { |
| it.remove(); |
| foundOne = true; |
| } |
| } |
| if (!foundOne) |
| throw new ListenerNotFoundException("The specified listener, " + listener + |
| "is not registered with this bean."); |
| } |
| |
| /** |
| * 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. |
| * <code>null</code> 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 {@link NotificationBroadcaster}. |
| * |
| * @param listener the listener to remove. |
| * @param filter the filter of the listener to remove. |
| * @param passback the passback object of the listener to remove. |
| * @throws ListenerNotFoundException if the specified listener |
| * is not registered with this bean. |
| * @see #addNotificationListener(NotificationListener, NotificationFilter, |
| * java.lang.Object) |
| */ |
| public void removeNotificationListener(NotificationListener listener, |
| NotificationFilter filter, |
| Object passback) |
| throws ListenerNotFoundException |
| { |
| if (!(listeners.remove(new ListenerData(listener, filter, passback)))) |
| { |
| throw new ListenerNotFoundException("The specified listener, " + listener + |
| " with filter " + filter + |
| "and passback " + passback + |
| ", is not registered with this bean."); |
| } |
| } |
| |
| /** |
| * <p> |
| * Performs delivery of the notification. If an executor |
| * was specified on construction, this will be used to call |
| * {@link #handleNotification(NotificationListener, Notification, |
| * Object)}. If the executor is <code>null</code>, however, |
| * this thread calls the method itself in order to perform a |
| * synchronous dispatch of the notification to all eligible |
| * listeners. |
| * </p> |
| * <p> |
| * Prior to either process taking place, the listeners are filtered. |
| * Notifications are only delivered if the filter is either |
| * <code>null</code> or returns true from the |
| * {@link NotificationFilter#isNotificationEnabled(Notification)} |
| * method. |
| * </p> |
| * |
| * @param notif the notification to send. |
| */ |
| public void sendNotification(Notification notif) |
| { |
| for (ListenerData ldata : listeners) |
| { |
| NotificationFilter filter = ldata.getFilter(); |
| if (filter == null || filter.isNotificationEnabled(notif)) |
| { |
| if (executor == null) |
| try |
| { |
| handleNotification(ldata.getListener(), notif, |
| ldata.getPassback()); |
| } |
| catch (Exception e) { /* Ignore */ } |
| else |
| executor.execute(new DispatchTask(ldata, notif)); |
| } |
| } |
| } |
| |
| /** |
| * The dispatch task to be performed by an executor. |
| */ |
| private final class DispatchTask |
| implements Runnable |
| { |
| |
| /** |
| * The data on the listener being called. |
| */ |
| private ListenerData ldata; |
| |
| /** |
| * The notification to send. |
| */ |
| private Notification notif; |
| |
| /** |
| * Construct a new {@link DispatchTask}. |
| * |
| * @param ldata the listener data. |
| * @param notif the notification to send. |
| */ |
| public DispatchTask(ListenerData ldata, |
| Notification notif) |
| { |
| this.ldata = ldata; |
| this.notif = notif; |
| } |
| |
| /** |
| * Dispatch the notification. |
| */ |
| public void run() |
| { |
| try |
| { |
| handleNotification(ldata.getListener(), notif, |
| ldata.getPassback()); |
| } |
| catch (Exception e) { /* Ignore */ } |
| } |
| } |
| |
| } |
| |