Java tutorial
/* * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code 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 * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.management; import java.util.Collections; import java.util.List; import java.util.Objects; import java.util.concurrent.CopyOnWriteArrayList; import java.util.concurrent.Executor; import com.sun.jmx.remote.util.ClassLogger; /** * <p>Provides an implementation of {@link * javax.management.NotificationEmitter NotificationEmitter} * interface. This can be used as the super class of an MBean that * sends notifications.</p> * * <p>By default, the notification dispatch model is synchronous. * That is, when a thread calls sendNotification, the * <code>NotificationListener.handleNotification</code> method of each listener * is called within that thread. You can override this default * by overriding <code>handleNotification</code> in a subclass, or by passing an * Executor to the constructor.</p> * * <p>If the method call of a filter or listener throws an {@link Exception}, * then that exception does not prevent other listeners from being invoked. However, * if the method call of a filter or of {@code Executor.execute} or of * {@code handleNotification} (when no {@code Excecutor} is specified) throws an * {@link Error}, then that {@code Error} is propagated to the caller of * {@link #sendNotification sendNotification}.</p> * * <p>Remote listeners added using the JMX Remote API (see JMXConnector) are not * usually called synchronously. That is, when sendNotification returns, it is * not guaranteed that any remote listeners have yet received the notification.</p> * * @since 1.5 */ public class NotificationBroadcasterSupport implements NotificationEmitter { /** * Constructs a NotificationBroadcasterSupport where each listener is invoked by the * thread sending the notification. This constructor is equivalent to * {@link NotificationBroadcasterSupport#NotificationBroadcasterSupport(Executor, * MBeanNotificationInfo[] info) NotificationBroadcasterSupport(null, null)}. */ public NotificationBroadcasterSupport() { this(null, (MBeanNotificationInfo[]) null); } /** * Constructs a NotificationBroadcasterSupport where each listener is invoked using * the given {@link java.util.concurrent.Executor}. When {@link #sendNotification * sendNotification} is called, a listener is selected if it was added with a null * {@link NotificationFilter}, or if {@link NotificationFilter#isNotificationEnabled * isNotificationEnabled} returns true for the notification being sent. The call to * <code>NotificationFilter.isNotificationEnabled</code> takes place in the thread * that called <code>sendNotification</code>. Then, for each selected listener, * {@link Executor#execute executor.execute} is called with a command * that calls the <code>handleNotification</code> method. * This constructor is equivalent to * {@link NotificationBroadcasterSupport#NotificationBroadcasterSupport(Executor, * MBeanNotificationInfo[] info) NotificationBroadcasterSupport(executor, null)}. * @param executor an executor used by the method <code>sendNotification</code> to * send each notification. If it is null, the thread calling <code>sendNotification</code> * will invoke the <code>handleNotification</code> method itself. * @since 1.6 */ public NotificationBroadcasterSupport(Executor executor) { this(executor, (MBeanNotificationInfo[]) null); } /** * <p>Constructs a NotificationBroadcasterSupport with information * about the notifications that may be sent. Each listener is * invoked by the thread sending the notification. This * constructor is equivalent to {@link * NotificationBroadcasterSupport#NotificationBroadcasterSupport(Executor, * MBeanNotificationInfo[] info) * NotificationBroadcasterSupport(null, info)}.</p> * * <p>If the <code>info</code> array is not empty, then it is * cloned by the constructor as if by {@code info.clone()}, and * each call to {@link #getNotificationInfo()} returns a new * clone.</p> * * @param info an array indicating, for each notification this * MBean may send, the name of the Java class of the notification * and the notification type. Can be null, which is equivalent to * an empty array. * * @since 1.6 */ public NotificationBroadcasterSupport(MBeanNotificationInfo... info) { this(null, info); } /** * <p>Constructs a NotificationBroadcasterSupport with information about the notifications that may be sent, * and where each listener is invoked using the given {@link java.util.concurrent.Executor}.</p> * * <p>When {@link #sendNotification sendNotification} is called, a * listener is selected if it was added with a null {@link * NotificationFilter}, or if {@link * NotificationFilter#isNotificationEnabled isNotificationEnabled} * returns true for the notification being sent. The call to * <code>NotificationFilter.isNotificationEnabled</code> takes * place in the thread that called * <code>sendNotification</code>. Then, for each selected * listener, {@link Executor#execute executor.execute} is called * with a command that calls the <code>handleNotification</code> * method.</p> * * <p>If the <code>info</code> array is not empty, then it is * cloned by the constructor as if by {@code info.clone()}, and * each call to {@link #getNotificationInfo()} returns a new * clone.</p> * * @param executor an executor used by the method * <code>sendNotification</code> to send each notification. If it * is null, the thread calling <code>sendNotification</code> will * invoke the <code>handleNotification</code> method itself. * * @param info an array indicating, for each notification this * MBean may send, the name of the Java class of the notification * and the notification type. Can be null, which is equivalent to * an empty array. * * @since 1.6 */ public NotificationBroadcasterSupport(Executor executor, MBeanNotificationInfo... info) { this.executor = (executor != null) ? executor : defaultExecutor; notifInfo = info == null ? NO_NOTIFICATION_INFO : info.clone(); } /** * Adds a listener. * * @param listener The listener to receive notifications. * @param filter The filter object. If filter is null, no * filtering will be performed before handling notifications. * @param handback An opaque object to be sent back to the * listener when a notification is emitted. This object cannot be * used by the Notification broadcaster object. It should be * resent unchanged with the notification to the listener. * * @exception IllegalArgumentException thrown if the listener is null. * * @see #removeNotificationListener */ public void addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) { if (listener == null) { throw new IllegalArgumentException("Listener can't be null"); } listenerList.add(new ListenerInfo(listener, filter, handback)); } public void removeNotificationListener(NotificationListener listener) throws ListenerNotFoundException { ListenerInfo wildcard = new WildcardListenerInfo(listener); boolean removed = listenerList.removeAll(Collections.singleton(wildcard)); if (!removed) throw new ListenerNotFoundException("Listener not registered"); } public void removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) throws ListenerNotFoundException { ListenerInfo li = new ListenerInfo(listener, filter, handback); boolean removed = listenerList.remove(li); if (!removed) { throw new ListenerNotFoundException( "Listener not registered " + "(with this filter and " + "handback)"); // or perhaps not registered at all } } public MBeanNotificationInfo[] getNotificationInfo() { if (notifInfo.length == 0) return notifInfo; else return notifInfo.clone(); } /** * Sends a notification. * * If an {@code Executor} was specified in the constructor, it will be given one * task per selected listener to deliver the notification to that listener. * * @param notification The notification to send. */ public void sendNotification(Notification notification) { if (notification == null) { return; } boolean enabled; for (ListenerInfo li : listenerList) { try { enabled = li.filter == null || li.filter.isNotificationEnabled(notification); } catch (Exception e) { if (logger.debugOn()) { logger.debug("sendNotification", e); } continue; } if (enabled) { executor.execute(new SendNotifJob(notification, li)); } } } /** * <p>This method is called by {@link #sendNotification * sendNotification} for each listener in order to send the * notification to that listener. It can be overridden in * subclasses to change the behavior of notification delivery, * for instance to deliver the notification in a separate * thread.</p> * * <p>The default implementation of this method is equivalent to * <pre> * listener.handleNotification(notif, handback); * </pre> * * @param listener the listener to which the notification is being * delivered. * @param notif the notification being delivered to the listener. * @param handback the handback object that was supplied when the * listener was added. * */ protected void handleNotification(NotificationListener listener, Notification notif, Object handback) { listener.handleNotification(notif, handback); } // private stuff private static class ListenerInfo { NotificationListener listener; NotificationFilter filter; Object handback; ListenerInfo(NotificationListener listener, NotificationFilter filter, Object handback) { this.listener = listener; this.filter = filter; this.handback = handback; } @Override public boolean equals(Object o) { if (!(o instanceof ListenerInfo)) return false; ListenerInfo li = (ListenerInfo) o; if (li instanceof WildcardListenerInfo) return (li.listener == listener); else return (li.listener == listener && li.filter == filter && li.handback == handback); } @Override public int hashCode() { return Objects.hashCode(listener); } } private static class WildcardListenerInfo extends ListenerInfo { WildcardListenerInfo(NotificationListener listener) { super(listener, null, null); } @Override public boolean equals(Object o) { assert (!(o instanceof WildcardListenerInfo)); return o.equals(this); } @Override public int hashCode() { return super.hashCode(); } } private List<ListenerInfo> listenerList = new CopyOnWriteArrayList<ListenerInfo>(); // since 1.6 private final Executor executor; private final MBeanNotificationInfo[] notifInfo; private final static Executor defaultExecutor = new Executor() { // DirectExecutor using caller thread public void execute(Runnable r) { r.run(); } }; private static final MBeanNotificationInfo[] NO_NOTIFICATION_INFO = new MBeanNotificationInfo[0]; private class SendNotifJob implements Runnable { public SendNotifJob(Notification notif, ListenerInfo listenerInfo) { this.notif = notif; this.listenerInfo = listenerInfo; } public void run() { try { handleNotification(listenerInfo.listener, notif, listenerInfo.handback); } catch (Exception e) { if (logger.debugOn()) { logger.debug("SendNotifJob-run", e); } } } private final Notification notif; private final ListenerInfo listenerInfo; } private static final ClassLogger logger = new ClassLogger("javax.management", "NotificationBroadcasterSupport"); }