001 /*
002 * Portions Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 /*
026 * @(#)author IBM Corp.
027 *
028 * Copyright IBM Corp. 1999-2000. All rights reserved.
029 */
030
031 package javax.management.modelmbean;
032
033 import javax.management.Attribute;
034 import javax.management.AttributeChangeNotification;
035 import javax.management.ListenerNotFoundException;
036 import javax.management.MBeanException;
037 import javax.management.Notification;
038 import javax.management.NotificationBroadcaster;
039 import javax.management.NotificationListener;
040 import javax.management.RuntimeOperationsException;
041
042 /**
043 * This interface must be implemented by the ModelMBeans. An implementation of this interface
044 * must be shipped with every JMX Agent.
045 * <P>
046 * Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's
047 * createMBean method. The resource then sets the ModelMBeanInfo (with Descriptors) for the ModelMBean
048 * instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible
049 * from MBeans, connectors/adaptors like other MBeans. Through the ModelMBeanInfo Descriptors, values and methods in
050 * the managed application can be defined and mapped to attributes and operations of the ModelMBean.
051 * This mapping can be defined during development in an XML formatted file or dynamically and
052 * programmatically at runtime.
053 * <P>
054 * Every ModelMBean which is instantiated in the MBeanServer becomes manageable:
055 * its attributes and operations
056 * become remotely accessible through the connectors/adaptors connected to that MBeanServer.
057 * A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean.
058 * By instantiating a ModelMBean, resources are guaranteed that the MBean is valid.
059 * <P>
060 * MBeanException and RuntimeOperationsException must be thrown on every public method. This allows
061 * for wrapping exceptions from distributed communications (RMI, EJB, etc.). These exceptions do
062 * not have to be thrown by the implementation except in the scenarios described in the specification
063 * and javadoc.
064 *
065 * @since 1.5
066 */
067
068 public interface ModelMBeanNotificationBroadcaster extends
069 NotificationBroadcaster {
070
071 /**
072 * Sends a Notification which is passed in to the registered
073 * Notification listeners on the ModelMBean as a
074 * jmx.modelmbean.generic notification.
075 *
076 * @param ntfyObj The notification which is to be passed to
077 * the 'handleNotification' method of the listener object.
078 *
079 * @exception MBeanException Wraps a distributed communication Exception.
080 * @exception RuntimeOperationsException Wraps an IllegalArgumentException:
081 * The Notification object passed in parameter is null.
082 *
083 */
084
085 public void sendNotification(Notification ntfyObj)
086 throws MBeanException, RuntimeOperationsException;
087
088 /**
089 * Sends a Notification which contains the text string that is passed in
090 * to the registered Notification listeners on the ModelMBean.
091 *
092 * @param ntfyText The text which is to be passed in the Notification to the 'handleNotification'
093 * method of the listener object.
094 * the constructed Notification will be:
095 * type "jmx.modelmbean.generic"
096 * source this ModelMBean instance
097 * sequence 1
098 *
099 *
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(
121 AttributeChangeNotification notification)
122 throws MBeanException, RuntimeOperationsException;
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,
147 Attribute newValue) throws MBeanException,
148 RuntimeOperationsException;
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(
168 NotificationListener listener, String attributeName,
169 Object handback) throws MBeanException,
170 RuntimeOperationsException, IllegalArgumentException;
171
172 /**
173 * Removes a listener for attributeChangeNotifications from the RequiredModelMBean.
174 *
175 * @param listener The listener name which was handling notifications emitted by the registered MBean.
176 * This method will remove all information related to this listener.
177 * @param attributeName The attribute for which the listener no longer wants to receive attributeChangeNotifications.
178 * If null the listener will be removed for all attributeChangeNotifications.
179 *
180 * @exception ListenerNotFoundException The listener is not registered in the MBean or is null.
181 * @exception MBeanException Wraps a distributed communication Exception.
182 * @exception RuntimeOperationsException Wraps an IllegalArgumentException If the inAttributeName parameter does not
183 * correspond to an attribute name.
184 *
185 * @see #addAttributeChangeNotificationListener
186 */
187
188 public void removeAttributeChangeNotificationListener(
189 NotificationListener listener, String attributeName)
190 throws MBeanException, RuntimeOperationsException,
191 ListenerNotFoundException;
192
193 }
|