ModelMBeanNotificationBroadcaster


1   /*
2    * @(#)file      ModelMBeanNotificationBroadcaster.java
3    * @(#)author    IBM Corp.
4    * @(#)version   1.21
5    * @(#)lastedit      04/02/10
6    */
7   /*
8    * Copyright IBM Corp. 1999-2000.  All rights reserved.
9    * 
10   * The program is provided "as is" without any warranty express or implied,
11   * including the warranty of non-infringement and the implied warranties of
12   * merchantibility and fitness for a particular purpose. IBM will not be
13   * liable for any damages suffered by you or any third party claim against 
14   * you regarding the Program.
15   *
16   * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
17   * This software is the proprietary information of Sun Microsystems, Inc.
18   * Use is subject to license terms.
19   * 
20   * Copyright 2004 Sun Microsystems, Inc.  Tous droits reserves.
21   * Ce logiciel est propriete de Sun Microsystems, Inc.
22   * Distribue par des licences qui en restreignent l'utilisation. 
23   *
24   */
25  
26  
27  package javax.management.modelmbean;
28  
29  import javax.management.*;
30  
31  import javax.management.InstanceNotFoundException  ;
32  
33  /**                    
34   * This interface must be implemented by the ModelMBeans. An implementation of this interface 
35   * must be shipped with every JMX Agent. 
36   * <P>
37   * Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's 
38   * createMBean method.  The resource then sets the ModelMBeanInfo (with Descriptors) for the ModelMBean
39   * instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible
40   * from MBeans, connectors/adaptors like other MBeans. Through the ModelMBeanInfo Descriptors, values and methods in
41   * the managed application can be defined and mapped to attributes and operations of the ModelMBean.
42   * This mapping can be defined during development in an XML formatted file or dynamically and
43   * programmatically at runtime. 
44   * <P>
45   * Every ModelMBean which is instantiated in the MBeanServer becomes manageable: 
46   * its attributes and operations
47   * become remotely accessible through the connectors/adaptors connected to that MBeanServer. 
48   * A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean.
49   * By instantiating a ModelMBean, resources are guaranteed that the MBean is valid.
50   * <P>
51   * MBeanException and RuntimeOperationsException must be thrown on every public method.  This allows 
52   * for wrapping exceptions from distributed communications (RMI, EJB, etc.).  These exceptions do
53   * not have to be thrown by the implementation except in the scenarios described in the specification 
54   * and javadoc.
55   *
56   * @since 1.5
57   */
58  
59  public interface ModelMBeanNotificationBroadcaster extends NotificationBroadcaster
60  {
61  
62      /** 
63       * Sends a Notification which is passed in to the registered
64       * Notification listeners on the ModelMBean as a
65       * jmx.modelmbean.generic notification.
66       *
67       * @param ntfyObj The notification which is to be passed to
68       * the 'handleNotification' method of the listener object.
69       *
70       * @exception MBeanException Wraps a distributed communication Exception.
71       * @exception RuntimeOperationsException Wraps an IllegalArgumentException: 
72       *       The Notification object passed in parameter is null.
73       *
74       */
75  
76      public void sendNotification(Notification ntfyObj)
77      throws MBeanException, RuntimeOperationsException;
78  
79      /** 
80       * Sends a Notification which contains the text string that is passed in
81       * to the registered Notification listeners on the ModelMBean.
82       *
83       * @param ntfyText The text which is to be passed in the Notification to the 'handleNotification'
84       * method of the listener object.  
85       * the constructed Notification will be:
86       *   type        "jmx.modelmbean.generic"
87       *   source      this ModelMBean instance
88       *   sequence    1
89       *
90       *
91       * @exception MBeanException Wraps a distributed communication Exception.
92       * @exception RuntimeOperationsException Wraps an IllegalArgumentException: 
93       *       The Notification text string passed in parameter is null.
94       *
95       */
96      public void sendNotification(String   ntfyText)
97      throws MBeanException, RuntimeOperationsException;
98  
99      /** 
100      * Sends an attributeChangeNotification which is passed in to
101      * the registered attributeChangeNotification listeners on the
102      * ModelMBean.
103      *
104      * @param notification The notification which is to be passed
105      * to the 'handleNotification' method of the listener object.
106      *
107      * @exception MBeanException Wraps a distributed communication Exception.
108      * @exception RuntimeOperationsException Wraps an IllegalArgumentException: The AttributeChangeNotification object passed in parameter is null.
109      *
110      */
111     public void sendAttributeChangeNotification(AttributeChangeNotification notification)
112     throws MBeanException, RuntimeOperationsException;
113 
114 
115     /** 
116      * Sends an attributeChangeNotification which contains the old value and new value for the
117      * attribute to the registered AttributeChangeNotification listeners on the ModelMBean.
118      * <P>
119      * @param oldValue The original value for the Attribute
120      * @param newValue The current value for the Attribute
121      *<P>
122      * <PRE>  
123      * The constructed attributeChangeNotification will be:
124      *   type        "jmx.attribute.change"
125      *   source      this ModelMBean instance
126      *   sequence    1
127      *   attributeName oldValue.getName()
128      *   attributeType oldValue's class
129      *   attributeOldValue oldValue.getValue()
130      *   attributeNewValue newValue.getValue()
131      * </PRE>
132      *
133      * @exception MBeanException Wraps a distributed communication Exception.
134      * @exception RuntimeOperationsException Wraps an IllegalArgumentException: An Attribute object passed in parameter is null
135      * or the names of the two Attribute objects in parameter are not the same.
136      */
137     public void sendAttributeChangeNotification(Attribute oldValue, Attribute newValue)
138     throws MBeanException, RuntimeOperationsException;
139 
140 
141     /**
142      * Registers an object which implements the NotificationListener interface as a listener.  This
143      * object's 'handleNotification()' method will be invoked when any attributeChangeNotification is issued through
144      * or by the ModelMBean.  This does not include other Notifications.  They must be registered
145      * for independently. An AttributeChangeNotification will be generated for this attributeName.
146      *
147      * @param listener The listener object which will handles notifications emitted by the registered MBean.
148      * @param attributeName The name of the ModelMBean attribute for which to receive change notifications.
149      *      If null, then all attribute changes will cause an attributeChangeNotification to be issued.
150      * @param handback The context to be sent to the listener with the notification when a notification is emitted.
151      *
152      * @exception IllegalArgumentException The listener cannot be null.
153      * @exception MBeanException Wraps a distributed communication Exception.
154      * @exception RuntimeOperationsException Wraps an IllegalArgumentException The attribute name passed in parameter does not exist.
155      *
156      * @see #removeAttributeChangeNotificationListener
157      */
158     public void addAttributeChangeNotificationListener(NotificationListener listener,
159                                String   attributeName, 
160                                Object   handback)
161     throws MBeanException, RuntimeOperationsException, IllegalArgumentException  ;
162 
163 
164     /**
165      * Removes a listener for attributeChangeNotifications from the RequiredModelMBean.
166      *
167      * @param listener The listener name which was handling notifications emitted by the registered MBean.
168      * This method will remove all information related to this listener.
169      * @param attributeName The attribute for which the listener no longer wants to receive attributeChangeNotifications.
170      * If null the listener will be removed for all attributeChangeNotifications. 
171      *
172      * @exception ListenerNotFoundException The listener is not registered in the MBean or is null.
173      * @exception MBeanException Wraps a distributed communication Exception.
174      * @exception RuntimeOperationsException Wraps an IllegalArgumentException If the inAttributeName parameter does not
175      * correspond to an attribute name.
176      *
177      * @see #addAttributeChangeNotificationListener
178      */
179 
180     public void removeAttributeChangeNotificationListener(NotificationListener listener,
181                                   String   attributeName)
182     throws MBeanException, RuntimeOperationsException, ListenerNotFoundException;
183 
184 }
185
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags