001: /**
002: * The XMOJO Project 5
003: * Copyright © 2003 XMOJO.org. All rights reserved.
004:
005: * NO WARRANTY
006:
007: * BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
008: * THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
009: * OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
010: * PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
011: * OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
012: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
013: * TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE
014: * LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
015: * REPAIR OR CORRECTION.
016:
017: * IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
018: * ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
019: * THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
020: * GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
021: * USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF
022: * DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
023: * PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE),
024: * EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
025: * SUCH DAMAGES.
026: **/package javax.management.modelmbean;
027:
028: import javax.management.Attribute;
029: import javax.management.AttributeChangeNotification;
030: import javax.management.Notification;
031: import javax.management.NotificationListener;
032: import javax.management.NotificationBroadcaster;
033: import javax.management.MBeanException;
034: import javax.management.ListenerNotFoundException;
035: import javax.management.RuntimeOperationsException;
036:
037: /**
038: * This interface must be implemented by the ModelMBeans. An implementation of
039: * this interface must be shipped with every JMX Agent.
040: * <p>
041: * Java resources wishing to be manageable instatiate the ModelMBean using the
042: * MBeanServer's createMBean method. The resource then sets the ModelMBeanInfo
043: * (with Descriptors) for the ModelMBean instance. The attributes and operations
044: * exposed via the ModelMBeanInfo for the ModelMBean are accessible from Mbeans,
045: * connectors/adapters like other MBeans. Through the ModelMBeanInfo Descriptors,
046: * values and methods in the managed application can be defined and mapped to
047: * attributes and operations of the ModelMBean. This mapping can be defined
048: * during development in an XML formatted file or dynamically and
049: * programmatically at runtime.
050: * <p>
051: * Every ModelMBean which is instantiated in the MBeanServer becomes manageable:
052: * its attributes and operations become remotely accessible through the
053: * connectors/adaptors connected to that MBeanServer. A Java object cannot be
054: * registered in the MBeanServer unless it is a JMX compliant MBean. By
055: * instantiating a ModelMBean, resources are guaranteed that the MBean is valid.
056: * <p>
057: * MBeanException and RuntimeOperationsException must be thrown on every public
058: * method. This allows for wrappering exceptions from distributed communications
059: * (RMI, EJB, etc.). These exceptions do not have to be thrown by the
060: * implementation except in the scenarios described in the specification and javadoc.
061: */
062: public interface ModelMBeanNotificationBroadcaster extends
063: NotificationBroadcaster {
064: /**
065: * Registers an object which implements the NotificationListener interface
066: * as a listener for AttributeChangeNotifications. This object's
067: * 'handleNotification()' method will be invoked when any
068: * attributeChangeNotification is issued through or by the MBean. This
069: * does not include other Notifications. They must be registered for
070: * independently. An AttributeChangeNotification will be generated for this
071: * attributeName.
072: *
073: * @param inlistener The listener object which will handles notifications
074: * emitted by the registered MBean.
075: *
076: * @param inAttributeName The name of the MBean attribute for which to
077: * receive change notifications. If null, then all attribute
078: * changes will cause an attributeChangeNotification to be issued.
079: *
080: * @param inhandback The context to be sent to the listener with the
081: * notification when a notification is emitted.
082: *
083: * @exception MBeanException Wrappering exceptions from distributed communications
084: *
085: * @exception RuntimeOPerationsException RuntimeOperationsException
086: * to wrapper IllegalArgumentExceptions.
087: *
088: * @exception IllegalArgumentException Listener is null or attributeName is null.
089: */
090: public void addAttributeChangeNotificationListener(
091: NotificationListener inlistener, String inAttributeName,
092: Object inhandback) throws MBeanException,
093: RuntimeOperationsException, IllegalArgumentException;
094:
095: /**
096: * Removes a listener for attributeChangeNotifications from the MBean.
097: *
098: * @param inlistener The listener name which was handling notifications
099: * emitted by the registered MBean. This method will remove
100: * all information related to this listener.
101: *
102: * @param inAttributeName The attribute for which the listener no longer
103: * wants to receive attributeChangeNotifications.
104: *
105: * @exception MBeanException Wrappering exceptions from distributed communications
106: *
107: * @exception RuntimeOperationsException Wrappering exceptions from
108: * distributed communications
109: *
110: * @exception ListenerNotFoundException The couple (listener,handback) is
111: * not registered in the MBean. The exception message contains
112: * either "listener", "handback" or the object name depending
113: * on which object cannot be found.
114: */
115: public void removeAttributeChangeNotificationListener(
116: NotificationListener inlistener, String inAttributeName)
117: throws MBeanException, RuntimeOperationsException,
118: ListenerNotFoundException;
119:
120: /**
121: * Sends a Notification which is passed in to the registered Notification
122: * listeners on the ModelMBean as a jmx.modelmbean.general notification.
123: *
124: * @param ntfyObj The notification which is to be passed to the
125: * 'handleNotification' method of the listener object.
126: *
127: * @exception MBeanException The initializer of the object has thrown an exception.
128: *
129: * @exception RuntimeOperationsException Wraps an IllegalArgumentException:
130: * The Notification object passed in parameter is null or invalid.
131: */
132: public void sendNotification(Notification ntfyObj)
133: throws MBeanException, RuntimeOperationsException;
134:
135: /**
136: * Sends a Notification which contains the text string that is passed in
137: * to the registered Notification listeners on the ModelMBean.
138: *
139: * @param ntfyText The text which is to be passed in the Notification to
140: * the 'handleNotification' method of the listener object.
141: * the constructed Notification will be:
142: * type "jmx.modelmbean.general"
143: * source this ModelMBean instance
144: * sequence 1
145: *
146: * @exception MBeanException The initializer of the object has thrown an exception.
147: *
148: * @exception RuntimeOperationsException Wraps an IllegalArgumentException:
149: * The Notification text string passed in parameter is null or invalid.
150: */
151: public void sendNotification(String ntfyText)
152: throws MBeanException, RuntimeOperationsException;
153:
154: /**
155: * Sends an attributeChangeNotification which is passed in to the
156: * registered attributeChangeNotification listeners on the ModelMBean.
157: *
158: * @param ntfyObj The notification which is to be passed to the
159: * 'handleNotification' method of the listener object.
160: *
161: * @exception MBeanException The initializer of the object has thrown an exception.
162: *
163: * @exception RuntimeOperationsException Wraps an IllegalArgumentException: The
164: * Notification object passed in parameter is null or invalid.
165: */
166: public void sendAttributeChangeNotification(
167: AttributeChangeNotification ntfyObj) throws MBeanException,
168: RuntimeOperationsException;
169:
170: /**
171: * Sends an attributeChangeNotification which contains the old value and
172: * new value for the attribute to the registered AttributeChangeNotification
173: * listeners on the ModelMBean.
174: *
175: * @param inOldVal The origional value for the Attribute
176: *
177: * @param inNewVal The current value for the Attribute
178: * <p>
179: * <p>
180: * <PRE>
181: * The constructed attributeChangeNotification will be:
182: * type "jmx.attribute.change"
183: * source this ModelMBean instance
184: * sequence 1
185: * attributeName oldValue.getName()
186: * attributeType oldValue's class
187: * attributeOldValue oldValue.getValue()
188: * attributeNewValue newValue.getValue()
189: * </PRE>
190: * <p>
191: *
192: * @exception MBeanException to wrapper implementation exceptions
193: *
194: * @exception RuntimeOperationsException to wrapper IllegalArgumentExceptions.
195: */
196: public void sendAttributeChangeNotification(Attribute inOldVal,
197: Attribute inNewVal) throws MBeanException,
198: RuntimeOperationsException;
199: }
|