1/* 2 * Copyright (c) 1999, 2005, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 27package javax.management; 28 29import java.util.concurrent.CopyOnWriteArrayList; // for Javadoc 30 31/** 32 * <p>Interface implemented by an MBean that emits Notifications. It 33 * allows a listener to be registered with the MBean as a notification 34 * listener.</p> 35 * 36 * <h3>Notification dispatch</h3> 37 * 38 * <p>When an MBean emits a notification, it considers each listener that has been 39 * added with {@link #addNotificationListener addNotificationListener} and not 40 * subsequently removed with {@link #removeNotificationListener removeNotificationListener}. 41 * If a filter was provided with that listener, and if the filter's 42 * {@link NotificationFilter#isNotificationEnabled isNotificationEnabled} method returns 43 * false, the listener is ignored. Otherwise, the listener's 44 * {@link NotificationListener#handleNotification handleNotification} method is called with 45 * the notification, as well as the handback object that was provided to 46 * {@code addNotificationListener}.</p> 47 * 48 * <p>If the same listener is added more than once, it is considered as many times as it was 49 * added. It is often useful to add the same listener with different filters or handback 50 * objects.</p> 51 * 52 * <p>Implementations of this interface can differ regarding the thread in which the methods 53 * of filters and listeners are called.</p> 54 * 55 * <p>If the method call of a filter or listener throws an {@link Exception}, then that 56 * exception should not prevent other listeners from being invoked. However, if the method 57 * call throws an {@link Error}, then it is recommended that processing of the notification 58 * stop at that point, and if it is possible to propagate the {@code Error} to the sender of 59 * the notification, this should be done.</p> 60 * 61 * <p>New code should use the {@link NotificationEmitter} interface 62 * instead.</p> 63 * 64 * <p>Implementations of this interface and of {@code NotificationEmitter} 65 * should be careful about synchronization. In particular, it is not a good 66 * idea for an implementation to hold any locks while it is calling a 67 * listener. To deal with the possibility that the list of listeners might 68 * change while a notification is being dispatched, a good strategy is to 69 * use a {@link CopyOnWriteArrayList} for this list. 70 * 71 * @since 1.5 72 */ 73public interface NotificationBroadcaster { 74 75 /** 76 * Adds a listener to this MBean. 77 * 78 * @param listener The listener object which will handle the 79 * notifications emitted by the broadcaster. 80 * @param filter The filter object. If filter is null, no 81 * filtering will be performed before handling notifications. 82 * @param handback An opaque object to be sent back to the 83 * listener when a notification is emitted. This object cannot be 84 * used by the Notification broadcaster object. It should be 85 * resent unchanged with the notification to the listener. 86 * 87 * @exception IllegalArgumentException Listener parameter is null. 88 * 89 * @see #removeNotificationListener 90 */ 91 public void addNotificationListener(NotificationListener listener, 92 NotificationFilter filter, 93 Object handback) 94 throws java.lang.IllegalArgumentException; 95 96 /** 97 * Removes a listener from this MBean. If the listener 98 * has been registered with different handback objects or 99 * notification filters, all entries corresponding to the listener 100 * will be removed. 101 * 102 * @param listener A listener that was previously added to this 103 * MBean. 104 * 105 * @exception ListenerNotFoundException The listener is not 106 * registered with the MBean. 107 * 108 * @see #addNotificationListener 109 * @see NotificationEmitter#removeNotificationListener 110 */ 111 public void removeNotificationListener(NotificationListener listener) 112 throws ListenerNotFoundException; 113 114 /** 115 * <p>Returns an array indicating, for each notification this 116 * MBean may send, the name of the Java class of the notification 117 * and the notification type.</p> 118 * 119 * <p>It is not illegal for the MBean to send notifications not 120 * described in this array. However, some clients of the MBean 121 * server may depend on the array being complete for their correct 122 * functioning.</p> 123 * 124 * @return the array of possible notifications. 125 */ 126 public MBeanNotificationInfo[] getNotificationInfo(); 127} 128