J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Portions Copyright 2000-2006 Sun Microsystems, Inc. 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. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any questions. |
| 24 | */ |
| 25 | /* |
| 26 | * @author IBM Corp. |
| 27 | * |
| 28 | * Copyright IBM Corp. 1999-2000. All rights reserved. |
| 29 | */ |
| 30 | |
| 31 | package javax.management.modelmbean; |
| 32 | |
| 33 | import javax.management.Attribute; |
| 34 | import javax.management.AttributeChangeNotification; |
| 35 | import javax.management.ListenerNotFoundException; |
| 36 | import javax.management.MBeanException; |
| 37 | import javax.management.Notification; |
| 38 | import javax.management.NotificationBroadcaster; |
| 39 | import javax.management.NotificationListener; |
| 40 | import javax.management.RuntimeOperationsException; |
| 41 | |
| 42 | /** |
| 43 | * This interface must be implemented by the ModelMBeans. An implementation of this interface |
| 44 | * must be shipped with every JMX Agent. |
| 45 | * <P> |
| 46 | * Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's |
| 47 | * createMBean method. The resource then sets the ModelMBeanInfo (with Descriptors) for the ModelMBean |
| 48 | * instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible |
| 49 | * from MBeans, connectors/adaptors like other MBeans. Through the ModelMBeanInfo Descriptors, values and methods in |
| 50 | * the managed application can be defined and mapped to attributes and operations of the ModelMBean. |
| 51 | * This mapping can be defined during development in an XML formatted file or dynamically and |
| 52 | * programmatically at runtime. |
| 53 | * <P> |
| 54 | * Every ModelMBean which is instantiated in the MBeanServer becomes manageable: |
| 55 | * its attributes and operations |
| 56 | * become remotely accessible through the connectors/adaptors connected to that MBeanServer. |
| 57 | * A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean. |
| 58 | * By instantiating a ModelMBean, resources are guaranteed that the MBean is valid. |
| 59 | * <P> |
| 60 | * MBeanException and RuntimeOperationsException must be thrown on every public method. This allows |
| 61 | * for wrapping exceptions from distributed communications (RMI, EJB, etc.). These exceptions do |
| 62 | * not have to be thrown by the implementation except in the scenarios described in the specification |
| 63 | * and javadoc. |
| 64 | * |
| 65 | * @since 1.5 |
| 66 | */ |
| 67 | |
| 68 | public interface ModelMBeanNotificationBroadcaster extends NotificationBroadcaster |
| 69 | { |
| 70 | |
| 71 | /** |
| 72 | * Sends a Notification which is passed in to the registered |
| 73 | * Notification listeners on the ModelMBean as a |
| 74 | * jmx.modelmbean.generic notification. |
| 75 | * |
| 76 | * @param ntfyObj The notification which is to be passed to |
| 77 | * the 'handleNotification' method of the listener object. |
| 78 | * |
| 79 | * @exception MBeanException Wraps a distributed communication Exception. |
| 80 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException: |
| 81 | * The Notification object passed in parameter is null. |
| 82 | * |
| 83 | */ |
| 84 | |
| 85 | public void sendNotification(Notification ntfyObj) |
| 86 | throws MBeanException, RuntimeOperationsException; |
| 87 | |
| 88 | /** |
| 89 | * Sends a Notification which contains the text string that is passed in |
| 90 | * to the registered Notification listeners on the ModelMBean. |
| 91 | * |
| 92 | * @param ntfyText The text which is to be passed in the Notification to the 'handleNotification' |
| 93 | * method of the listener object. |
| 94 | * the constructed Notification will be: |
| 95 | * type "jmx.modelmbean.generic" |
| 96 | * source this ModelMBean instance |
| 97 | * sequence 1 |
| 98 | * |
| 99 | * |
| 100 | * @exception MBeanException Wraps a distributed communication Exception. |
| 101 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException: |
| 102 | * The Notification text string passed in parameter is null. |
| 103 | * |
| 104 | */ |
| 105 | public void sendNotification(String ntfyText) |
| 106 | throws MBeanException, RuntimeOperationsException; |
| 107 | |
| 108 | /** |
| 109 | * Sends an attributeChangeNotification which is passed in to |
| 110 | * the registered attributeChangeNotification listeners on the |
| 111 | * ModelMBean. |
| 112 | * |
| 113 | * @param notification The notification which is to be passed |
| 114 | * to the 'handleNotification' method of the listener object. |
| 115 | * |
| 116 | * @exception MBeanException Wraps a distributed communication Exception. |
| 117 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException: The AttributeChangeNotification object passed in parameter is null. |
| 118 | * |
| 119 | */ |
| 120 | public void sendAttributeChangeNotification(AttributeChangeNotification notification) |
| 121 | throws MBeanException, RuntimeOperationsException; |
| 122 | |
| 123 | |
| 124 | /** |
| 125 | * Sends an attributeChangeNotification which contains the old value and new value for the |
| 126 | * attribute to the registered AttributeChangeNotification listeners on the ModelMBean. |
| 127 | * <P> |
| 128 | * @param oldValue The original value for the Attribute |
| 129 | * @param newValue The current value for the Attribute |
| 130 | *<P> |
| 131 | * <PRE> |
| 132 | * The constructed attributeChangeNotification will be: |
| 133 | * type "jmx.attribute.change" |
| 134 | * source this ModelMBean instance |
| 135 | * sequence 1 |
| 136 | * attributeName oldValue.getName() |
| 137 | * attributeType oldValue's class |
| 138 | * attributeOldValue oldValue.getValue() |
| 139 | * attributeNewValue newValue.getValue() |
| 140 | * </PRE> |
| 141 | * |
| 142 | * @exception MBeanException Wraps a distributed communication Exception. |
| 143 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException: An Attribute object passed in parameter is null |
| 144 | * or the names of the two Attribute objects in parameter are not the same. |
| 145 | */ |
| 146 | public void sendAttributeChangeNotification(Attribute oldValue, Attribute newValue) |
| 147 | throws MBeanException, RuntimeOperationsException; |
| 148 | |
| 149 | |
| 150 | /** |
| 151 | * Registers an object which implements the NotificationListener interface as a listener. This |
| 152 | * object's 'handleNotification()' method will be invoked when any attributeChangeNotification is issued through |
| 153 | * or by the ModelMBean. This does not include other Notifications. They must be registered |
| 154 | * for independently. An AttributeChangeNotification will be generated for this attributeName. |
| 155 | * |
| 156 | * @param listener The listener object which will handles notifications emitted by the registered MBean. |
| 157 | * @param attributeName The name of the ModelMBean attribute for which to receive change notifications. |
| 158 | * If null, then all attribute changes will cause an attributeChangeNotification to be issued. |
| 159 | * @param handback The context to be sent to the listener with the notification when a notification is emitted. |
| 160 | * |
| 161 | * @exception IllegalArgumentException The listener cannot be null. |
| 162 | * @exception MBeanException Wraps a distributed communication Exception. |
| 163 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException The attribute name passed in parameter does not exist. |
| 164 | * |
| 165 | * @see #removeAttributeChangeNotificationListener |
| 166 | */ |
| 167 | public void addAttributeChangeNotificationListener(NotificationListener listener, |
| 168 | String attributeName, |
| 169 | Object handback) |
| 170 | throws MBeanException, RuntimeOperationsException, IllegalArgumentException; |
| 171 | |
| 172 | |
| 173 | /** |
| 174 | * Removes a listener for attributeChangeNotifications from the RequiredModelMBean. |
| 175 | * |
| 176 | * @param listener The listener name which was handling notifications emitted by the registered MBean. |
| 177 | * This method will remove all information related to this listener. |
| 178 | * @param attributeName The attribute for which the listener no longer wants to receive attributeChangeNotifications. |
| 179 | * If null the listener will be removed for all attributeChangeNotifications. |
| 180 | * |
| 181 | * @exception ListenerNotFoundException The listener is not registered in the MBean or is null. |
| 182 | * @exception MBeanException Wraps a distributed communication Exception. |
| 183 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException If the inAttributeName parameter does not |
| 184 | * correspond to an attribute name. |
| 185 | * |
| 186 | * @see #addAttributeChangeNotificationListener |
| 187 | */ |
| 188 | |
| 189 | public void removeAttributeChangeNotificationListener(NotificationListener listener, |
| 190 | String attributeName) |
| 191 | throws MBeanException, RuntimeOperationsException, ListenerNotFoundException; |
| 192 | |
| 193 | } |