001: /* JFox, the OpenSource J2EE Application Server
002: *
003: * Copyright (C) 2002 huihoo.org
004: * Distributable under GNU LGPL license
005: * See the GNU Lesser General Public License for more details.
006: */
007:
008: package javax.management.modelmbean;
009:
010: import javax.management.ListenerNotFoundException;
011: import javax.management.RuntimeOperationsException;
012: import javax.management.MBeanException;
013: import javax.management.NotificationListener;
014: import javax.management.Attribute;
015: import javax.management.AttributeChangeNotification;
016: import javax.management.Notification;
017: import javax.management.NotificationEmitter;
018:
019: /**
020: * This interface must be implemented by the ModelMBeans. An implementation of this interface
021: * must be shipped with every JMX Agent.
022: * <P>
023: * Java resources wishing to be manageable instatiate the ModelMBean using the MBeanServer's
024: * createMBean method. The resource then sets the ModelMBeanInfo (with Descriptors) for the ModelMBean
025: * instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible
026: * from Mbeans, connectors/adapters like other MBeans. Through the ModelMBeanInfo Descriptors, values and methods in
027: * the managed application can be defined and mapped to attributes and operations of the ModelMBean.
028: * This mapping can be defined during development in an XML formatted file or dynamically and
029: * programmatically at runtime.
030: * <P>
031: * Every ModelMBean which is instantiated in the MBeanServer becomes manageable:
032: * its attributes and operations
033: * become remotely accessible through the connectors/adaptors connected to that MBeanServer.
034: * A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean.
035: * By instantiating a ModelMBean, resources are guaranteed that the MBean is valid.
036: * <P>
037: * MBeanException and RuntimeOperatiosException must be thrown on every public method. This allows
038: * for wrappering exceptions from distributed communications (RMI, EJB, etc.). These exceptions do
039: * not have to be thrown by teh implementation except in the scenarios described in the specification
040: * and javadoc.
041: *
042: * @author <a href="mailto:young_yy@hotmail.org">Young Yang</a>
043: */
044:
045: public interface ModelMBeanNotificationBroadcaster extends
046: NotificationEmitter {
047:
048: /**
049: * Sends a Notification which is passed in to the registered Notification listeners on
050: * the ModelMBean as a jmx.modelmbean.general notification.
051: *
052: * @param notification - The notification which is to be passed to the 'handleNotification' method
053: * of the listener object.
054: *
055: * @exception MBeanException The initializer of the object has thrown an exception.
056: * @exception RuntimeOperationsException Wraps an IllegalArgumentException:
057: * The Notification object passed in parameter is null or invalid.
058: *
059: */
060: public void sendNotification(Notification notification)
061: throws MBeanException, RuntimeOperationsException;
062:
063: /**
064: * Sends a Notification which contains the text string that is passed in
065: * to the registered Notification listeners on the ModelMBean.
066: *
067: * @param message The text which is to be passed in the Notification to the 'handleNotification'
068: * method of the listener object.
069: * the constructed Notification will be:
070: * type "jmx.modelmbean.general"
071: * source this ModelMBean instance
072: * sequence 1
073: *
074: *
075: * @exception MBeanException The initializer of the object has thrown an exception.
076: * @exception RuntimeOperationsException Wraps an IllegalArgumentException:
077: * The Notification text string passed in parameter is null or invalid.
078: *
079: */
080: public void sendNotification(String message) throws MBeanException,
081: RuntimeOperationsException;
082:
083: /**
084: * Sends an attributeChangeNotification which is passed in to the registered
085: * attributeChangeNotification listeners on the ModelMBean.
086: *
087: * @param notification The notification which is to be passed to the 'handleNotification' method
088: * of the listener object.
089: *
090: * @exception MBeanException The initializer of the object has thrown an exception.
091: * @exception RuntimeOperationsException Wraps an IllegalArgumentException:
092: * The Notification object passed in parameter is null or invalid.
093: *
094: */
095: public void sendAttributeChangeNotification(
096: AttributeChangeNotification notification)
097: throws MBeanException, RuntimeOperationsException;
098:
099: /**
100: * Sends an attributeChangeNotification which contains the old value and new value for the
101: * attribute to the registered AttributeChangeNotification listeners on the ModelMBean.
102: * <P>
103: * @param oldValue The origional value for the Attribute
104: * @param newValue The current value for the Attribute
105: *<P>
106: * <PRE>
107: * The constructed attributeChangeNotification will be:
108: * type "jmx.attribute.change"
109: * source this ModelMBean instance
110: * sequence 1
111: * attributeName oldValue.getNameSpace()
112: * attributeType oldValue's class
113: * attributeOldValue oldValue.getValue()
114: * attributeNewValue newValue.getValue()
115: * </PRE>
116: *
117: * @exception MBeanException to wrapper implementation exceptions
118: * @exception RuntimeOperationsException to wrapper IllegalArgumentExceptions.
119: *
120: */
121: public void sendAttributeChangeNotification(Attribute oldValue,
122: Attribute newValue) throws MBeanException,
123: RuntimeOperationsException;
124:
125: /** These interface should be implemented by any MBean wishing to broadcast AttributeChangeNotifications
126: * to a separate set of listeners that other notifications would go to. All other notifications should
127: * go to listeners who registered using the NotificationBroadcaster interface.
128: * <P>
129: * Use of this interface a convenience and is optional. AttributeChangeNotifications can be sent to all Notification
130: * listeners simply by using the NotificationBroadcaster interface alone.
131: * <P>
132: * Imlementers of this interface must also implement the NotificationBroadcaster interface.
133: * ModelMBeans must implement this interface.
134: */
135: /**
136: * Registers an object which implements the NotificationListener interface as a listener
137: * for AttributeChangeNotifications. This
138: * object's 'handleNotification()' method will be invoked when any attributeChangeNotification is issued through
139: * or by the MBean. This does not include other Notifications. They must be registered
140: * for independently. An AttributeChangeNotification will be generated for this attributeName.
141: *
142: * @param listener The listener object which will handles notifications emitted by the registered MBean.
143: * @param attributeName The name of the MBean attribute for which to receive change notifications.
144: * If null, then all attribute changes will cause an attributeChangeNotification to be issued.
145: * @param handback The context to be sent to the listener with the notification when a notification is emitted.
146: *
147: * @exception IllegalArgumentException Listener is null or attributeName is null.
148: *
149: */
150: public void addAttributeChangeNotificationListener(
151: NotificationListener listener, String attributeName,
152: Object handback) throws MBeanException,
153: RuntimeOperationsException, IllegalArgumentException;
154:
155: /**
156: * Removes a listener for attributeChangeNotifications from the MBean.
157: *
158: * @param listener The listener name which was handling notifications emitted by the registered MBean.
159: * This method will remove all information related to this listener.
160: * @param attributeName The attribute for which the listener no longer wants to receive attributeChangeNotifications.
161: *
162: * @exception ListenerNotFoundException The couple (listener,handback) is not registered in the MBean.
163: * The exception message contains either "listener", "handback" or the object name depending on which object cannot be found.
164: *
165: */
166: public void removeAttributeChangeNotificationListener(
167: NotificationListener listener, String attributeName)
168: throws MBeanException, RuntimeOperationsException,
169: ListenerNotFoundException;
170:
171: }
|