| Frames | No Frames |
1: /* NotificationBroadcasterSupport.java -- Supporting implementation. 2: Copyright (C) 2007 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package javax.management; 39: 40: import gnu.javax.management.ListenerData; 41: 42: import java.util.ArrayList; 43: import java.util.Iterator; 44: import java.util.List; 45: 46: import java.util.concurrent.Executor; 47: 48: /** 49: * <p> 50: * Provides an implementation of the {@link NotificationEmitter} 51: * interface, which beans may utilise by extension. By default, 52: * a synchronous dispatch system is provided, whereby the 53: * {@link #handleNotification(NotificationListener, Notification, 54: * Object)} is called once per listener by 55: * {*@link #sendNotification(Notification)} before returning. 56: * Thus, unless the listener is remote, it will have received 57: * the notification before the method returns. 58: * This may be changed by overriding the <code>handleNotification</code> 59: * method, or by providing an {@link java.util.concurrent.Executor} to 60: * use. With the latter, the dispatch of a notification to a particular 61: * listener will form one task performed by the executor. 62: * </p> 63: * <p> 64: * Any exceptions thrown by the dispatch process will be caught, allowing 65: * other listeners to still receive the notification. However, any 66: * {@link Error}s that are thrown will be propogated to the caller of 67: * {@link #sendNotification(Notification)}. 68: * </p> 69: * 70: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 71: * @since 1.5 72: */ 73: public class NotificationBroadcasterSupport 74: implements NotificationEmitter 75: { 76: 77: /** 78: * The executor for dispatch, or 79: * <code>null</code> if this thread should 80: * handle dispatch itself. 81: */ 82: private Executor executor; 83: 84: /** 85: * An array containing information on each 86: * notification, or <code>null</code> if an 87: * empty array should be returned by 88: * {@link #getNotificationInfo()}. 89: */ 90: private MBeanNotificationInfo[] info; 91: 92: /** 93: * The list of listeners registered with 94: * this broadcaster. 95: */ 96: private final List<ListenerData> listeners = 97: new ArrayList<ListenerData>(); 98: 99: /** 100: * Constructs a {@link NotificationBroadcasterSupport} using 101: * the default synchronous dispatch model, where a single 102: * thread sends the notification to all listeners. This 103: * is equivalent to calling 104: * <code>NotificationBroadcasterSupport(null, null)</code>. 105: */ 106: public NotificationBroadcasterSupport() 107: { 108: this(null, (MBeanNotificationInfo[]) null); 109: } 110: 111: /** 112: * Constructs a {@link NotificationBroadcasterSupport} where 113: * the specified (@link java.util.concurrent.Executor} is used 114: * to perform each invocation of the 115: * {@link #handleNotification(NotificationListener, Notification, 116: * Object)} method. Filtering is performed beforehand, by this 117: * thread; only calls which have successfully passed through the 118: * filter are sent to the executor. This is equivalent to calling 119: * <code>NotificationBroadcasterSupport(executor, null)</code>. 120: * 121: * @param executor the executor to use for each call to 122: * <code>handleNotification()</code>. 123: * @since 1.6 124: */ 125: public NotificationBroadcasterSupport(Executor executor) 126: { 127: this(executor, (MBeanNotificationInfo) null); 128: } 129: 130: /** 131: * Constructs a {@link NotificationBroadcasterSupport} using 132: * the default synchronous dispatch model, where a single 133: * thread sends the notification to all listeners. The specified 134: * {@link MBeanNotificationInfo} array is used to provide 135: * information about the notifications on calls to 136: * {@link #getNotificationInfo()}, where a clone will be 137: * returned if the array is non-empty. This is equivalent to 138: * calling <code>NotificationBroadcasterSupport(null, info)</code>. 139: * 140: * @param info an array of {@link MBeanNotificationInfo} objects 141: * describing the notifications delivered by this 142: * broadcaster. This may be <code>null</code>, which 143: * is taken as being equivalent to an empty array. 144: */ 145: public NotificationBroadcasterSupport(MBeanNotificationInfo... info) 146: { 147: this(null, info); 148: } 149: 150: /** 151: * Constructs a {@link NotificationBroadcasterSupport} where 152: * the specified (@link java.util.concurrent.Executor} is used 153: * to perform each invocation of the 154: * {@link #handleNotification(NotificationListener, Notification, 155: * Object)} method. Filtering is performed beforehand, by this 156: * thread; only calls which have successfully passed through the 157: * filter are sent to the executor. The specified 158: * {@link MBeanNotificationInfo} array is used to provide 159: * information about the notifications on calls to 160: * {@link #getNotificationInfo()}, where a clone will be 161: * returned if the array is non-empty. 162: * 163: * @param executor the executor to use for each call to 164: * <code>handleNotification()</code>. 165: * @param info an array of {@link MBeanNotificationInfo} objects 166: * describing the notifications delivered by this 167: * broadcaster. This may be <code>null</code>, which 168: * is taken as being equivalent to an empty array. 169: * @since 1.6 170: */ 171: public NotificationBroadcasterSupport(Executor executor, 172: MBeanNotificationInfo... info) 173: { 174: this.executor = executor; 175: this.info = info; 176: } 177: 178: /** 179: * Registers the specified listener as a new recipient of 180: * notifications from this bean. If non-null, the filter 181: * argument will be used to select which notifications are 182: * delivered. The supplied object will also be passed to 183: * the recipient with each notification. This should not 184: * be modified by the broadcaster, but instead should be 185: * passed unmodified to the listener. 186: * 187: * @param listener the new listener, who will receive 188: * notifications from this broadcasting bean. 189: * @param filter a filter to determine which notifications are 190: * delivered to the listener, or <code>null</code> 191: * if no filtering is required. 192: * @param passback an object to be passed to the listener with 193: * each notification. 194: * @throws IllegalArgumentException if <code>listener</code> is 195: * <code>null</code>. 196: * @see #removeNotificationListener(NotificationListener) 197: */ 198: public void addNotificationListener(NotificationListener listener, 199: NotificationFilter filter, 200: Object passback) 201: throws IllegalArgumentException 202: { 203: if (listener == null) 204: throw new IllegalArgumentException("Null listener added to bean."); 205: listeners.add(new ListenerData(listener, filter, passback)); 206: } 207: 208: /** 209: * Returns an array describing the notifications this 210: * bean may send to its registered listeners. Ideally, this 211: * array should be complete, but in some cases, this may 212: * not be possible. However, be aware that some listeners 213: * may expect this to be so. 214: * 215: * @return the array of possible notifications. 216: */ 217: public MBeanNotificationInfo[] getNotificationInfo() 218: { 219: if (info == null || info.length == 0) 220: return new MBeanNotificationInfo[0]; 221: return (MBeanNotificationInfo[]) info.clone(); 222: } 223: 224: /** 225: * This method is called on a per-listener basis, either 226: * from this thread or the supplied executor, and may be 227: * overridden by subclasses which wish to change how 228: * notifications are delivered. The default 229: * implementation simply calls 230: * <code>listener.handleNotification(notif, passback)</code>. 231: * 232: * @param listener the listener to send the notification to. 233: * @param notif the notification to dispatch. 234: * @param passback the passback object of the listener. 235: */ 236: protected void handleNotification(NotificationListener listener, 237: Notification notif, 238: Object passback) 239: { 240: listener.handleNotification(notif, passback); 241: } 242: 243: /** 244: * Removes the specified listener from the list of recipients 245: * of notifications from this bean. This includes all combinations 246: * of filters and passback objects registered for this listener. 247: * For more specific removal of listeners, see the subinterface 248: * {@link NotificationEmitter}. 249: * 250: * @param listener the listener to remove. 251: * @throws ListenerNotFoundException if the specified listener 252: * is not registered with this bean. 253: * @see #addNotificationListener(NotificationListener, NotificationFilter, 254: * java.lang.Object) 255: */ 256: public void removeNotificationListener(NotificationListener listener) 257: throws ListenerNotFoundException 258: { 259: Iterator<ListenerData> it = listeners.iterator(); 260: boolean foundOne = false; 261: while (it.hasNext()) 262: { 263: if (it.next().getListener() == listener) 264: { 265: it.remove(); 266: foundOne = true; 267: } 268: } 269: if (!foundOne) 270: throw new ListenerNotFoundException("The specified listener, " + listener + 271: "is not registered with this bean."); 272: } 273: 274: /** 275: * Removes the specified listener from the list of recipients 276: * of notifications from this bean. Only the first instance with 277: * the supplied filter and passback object is removed. 278: * <code>null</code> is used as a valid value for these parameters, 279: * rather than as a way to remove all registration instances for 280: * the specified listener; for this behaviour instead, see the details 281: * of the same method in {@link NotificationBroadcaster}. 282: * 283: * @param listener the listener to remove. 284: * @param filter the filter of the listener to remove. 285: * @param passback the passback object of the listener to remove. 286: * @throws ListenerNotFoundException if the specified listener 287: * is not registered with this bean. 288: * @see #addNotificationListener(NotificationListener, NotificationFilter, 289: * java.lang.Object) 290: */ 291: public void removeNotificationListener(NotificationListener listener, 292: NotificationFilter filter, 293: Object passback) 294: throws ListenerNotFoundException 295: { 296: if (!(listeners.remove(new ListenerData(listener, filter, passback)))) 297: { 298: throw new ListenerNotFoundException("The specified listener, " + listener + 299: " with filter " + filter + 300: "and passback " + passback + 301: ", is not registered with this bean."); 302: } 303: } 304: 305: /** 306: * <p> 307: * Performs delivery of the notification. If an executor 308: * was specified on construction, this will be used to call 309: * {@link #handleNotification(NotificationListener, Notification, 310: * Object)}. If the executor is <code>null</code>, however, 311: * this thread calls the method itself in order to perform a 312: * synchronous dispatch of the notification to all eligible 313: * listeners. 314: * </p> 315: * <p> 316: * Prior to either process taking place, the listeners are filtered. 317: * Notifications are only delivered if the filter is either 318: * <code>null</code> or returns true from the 319: * {@link NotificationFilter#isNotificationEnabled(Notification)} 320: * method. 321: * </p> 322: * 323: * @param notif the notification to send. 324: */ 325: public void sendNotification(Notification notif) 326: { 327: for (ListenerData ldata : listeners) 328: { 329: NotificationFilter filter = ldata.getFilter(); 330: if (filter == null || filter.isNotificationEnabled(notif)) 331: { 332: if (executor == null) 333: try 334: { 335: handleNotification(ldata.getListener(), notif, 336: ldata.getPassback()); 337: } 338: catch (Exception e) { /* Ignore */ } 339: else 340: executor.execute(new DispatchTask(ldata, notif)); 341: } 342: } 343: } 344: 345: /** 346: * The dispatch task to be performed by an executor. 347: */ 348: private final class DispatchTask 349: implements Runnable 350: { 351: 352: /** 353: * The data on the listener being called. 354: */ 355: private ListenerData ldata; 356: 357: /** 358: * The notification to send. 359: */ 360: private Notification notif; 361: 362: /** 363: * Construct a new {@link DispatchTask}. 364: * 365: * @param ldata the listener data. 366: * @param notif the notification to send. 367: */ 368: public DispatchTask(ListenerData ldata, 369: Notification notif) 370: { 371: this.ldata = ldata; 372: this.notif = notif; 373: } 374: 375: /** 376: * Dispatch the notification. 377: */ 378: public void run() 379: { 380: try 381: { 382: handleNotification(ldata.getListener(), notif, 383: ldata.getPassback()); 384: } 385: catch (Exception e) { /* Ignore */ } 386: } 387: } 388: 389: }