ModelMBeanInfo


1   /*
2    * @(#)file      ModelMBeanInfo.java
3    * @(#)author    IBM Corp.
4    * @(#)version   1.24
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  
28  package javax.management.modelmbean;
29  
30  import javax.management.Descriptor  ;
31  import javax.management.DescriptorAccess  ;
32  import javax.management.*;
33  import javax.management.RuntimeOperationsException  ;
34  import javax.management.MBeanException  ;
35  
36  /**
37   * This interface is implemented by the ModelMBeanInfo for every ModelMBean. An implementation of this interface 
38   * must be shipped with every JMX Agent. 
39   * <P>
40   * Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's 
41   * createMBean method.  The resource then sets the ModelMBeanInfo and Descriptors for the ModelMBean
42   * instance. The attributes, operations, and notifications exposed via the ModelMBeanInfo for the 
43   * ModelMBean comprise the management interface and are accessible
44   * from MBeans, connectors/adaptors like other MBeans. Through the Descriptors, values and methods in
45   * the managed application can be defined and mapped to attributes and operations of the ModelMBean.
46   * This mapping can be defined during development in a file or dynamically and
47   * programmatically at runtime. 
48   * <P>
49   * Every ModelMBean which is instantiated in the MBeanServer becomes manageable: 
50   * its attributes, operations, and notifications
51   * become remotely accessible through the connectors/adaptors connected to that MBeanServer. 
52   * A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean.
53   * By instantiating a ModelMBean, resources are guaranteed that the MBean is valid.
54   *
55   * MBeanException and RuntimeOperationsException must be thrown on every public method.  This allows 
56   *  for wrapping exceptions from distributed communications (RMI, EJB, etc.)
57   *
58   * @since 1.5
59   */
60  
61  public interface ModelMBeanInfo
62  {
63  
64  
65      /**
66       * Returns a Descriptor array consisting of all 
67       * Descriptors for the ModelMBeanInfo of type inDescriptorType.
68       *
69       * @param inDescriptorType value of descriptorType field that must be set for the descriptor
70       * to be returned.  Must be "mbean", "attribute", "operation", "constructor" or "notification".
71       * If it is null or empty then all types will be returned.
72       *
73       * @return Descriptor array containing all descriptors for the ModelMBean if type inDescriptorType.
74       *
75       * @exception MBeanException Wraps a distributed communication Exception.
76       * @exception RuntimeOperationsException Wraps an IllegalArgumentException when the descriptorType in parameter is
77       * not one of: "mbean", "attribute", "operation", "constructor", "notification", empty or null.
78       *
79       * @see #setDescriptors
80       */
81      public Descriptor  [] getDescriptors(String   inDescriptorType)
82          throws MBeanException  , RuntimeOperationsException  ;
83  
84      /**
85       * Adds or replaces descriptors in the ModelMBeanInfo.
86       *
87       * @param inDescriptors The descriptors to be set in the ModelMBeanInfo. Null
88       * elements of the list will be ignored.  All descriptors must have name and descriptorType fields.
89       *
90       * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null or invalid descriptor.
91       * @exception MBeanException Wraps a distributed communication Exception.
92       *
93       * @see #getDescriptors
94       */
95      public void setDescriptors(Descriptor  [] inDescriptors)
96          throws MBeanException  , RuntimeOperationsException  ;
97  
98      /**
99       * Returns a Descriptor requested by name and descriptorType.
100      *
101      * @param inDescriptorName The name of the descriptor.
102      * @param inDescriptorType The type of the descriptor being
103      * requested.  If this is null or empty then all types are
104      * searched. Valid types are 'mbean', 'attribute', 'constructor'
105      * 'operation', and 'notification'. This value will be equal to
106      * the 'descriptorType' field in the descriptor that is returned.
107      *
108      * @return Descriptor containing the descriptor for the ModelMBean
109      * with the same name and descriptorType.  If no descriptor is
110      * found, null is returned.
111      *
112      * @exception MBeanException Wraps a distributed communication Exception. 
113      * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null descriptor name or null or invalid type.
114      * The type must be "mbean","attribute", "constructor", "operation", or "notification".
115      *
116      * @see #setDescriptor
117      */
118 
119     public Descriptor   getDescriptor(String   inDescriptorName, String   inDescriptorType)
120         throws MBeanException  , RuntimeOperationsException  ;
121 
122     /**
123      * Sets descriptors in the info array of type inDescriptorType
124      * for the ModelMBean.  The setDescriptor method of the
125      * corresponding ModelMBean*Info will be called to set the
126      * specified descriptor.
127      *
128      * @param inDescriptor The descriptor to be set in the
129      * ModelMBean. It must NOT be null.  All descriptors must have
130      * name and descriptorType fields.
131      * @param inDescriptorType The type of the descriptor being
132      * set. If this is null then the descriptorType field in the
133      * descriptor is used. If specified this value must be set in
134      * the descriptorType field in the descriptor. Must be
135      * "mbean","attribute", "constructor", "operation", or
136      * "notification".
137      *
138      * @exception RuntimeOperationsException Wraps an
139      * IllegalArgumentException for illegal or null arguments or
140      * if the name field of the descriptor is not found in the
141      * corresponding MBeanAttributeInfo or MBeanConstructorInfo or
142      * MBeanNotificationInfo or MBeanOperationInfo.
143      * @exception MBeanException Wraps a distributed communication
144      * Exception.
145      *
146      * @see #getDescriptor
147      */
148 
149     public void setDescriptor(Descriptor   inDescriptor, String   inDescriptorType)
150         throws MBeanException  , RuntimeOperationsException  ;
151 
152 
153     /**
154      * Returns the ModelMBean's descriptor which contains MBean wide policies.  This descriptor contains
155      * metadata about the MBean and default policies for persistence and caching.
156      * <P>
157      * The fields in the descriptor are defined, but not limited to, the following: 
158      * <PRE>
159      * name           : MBean name  
160      * descriptorType : must be "mbean"   
161      * displayName    : name of attribute to be used in displays 
162      * persistPolicy  : OnUpdate|OnTimer|NoMoreOftenThan|Always|Never  
163      * persistLocation : The fully qualified directory name where the MBean should be persisted (if appropriate)
164      * persistFile    : File name into which the MBean should be persisted
165      * persistPeriod  : seconds - frequency of persist cycle for OnTime and NoMoreOftenThan PersistPolicy 
166      * currencyTimeLimit : how long value is valid, &lt;0 never, =0 always, &gt;0 seconds  
167      * log            : where t: log all notifications f: log no notifications
168      * logfile        : fully qualified filename to log events to
169      * visibility     : 1-4 where 1: always visible 4: rarely visible
170      * export         : name to be used to export/expose this MBean so that it is findable by
171      *                  other JMX Agents.   
172      * presentationString : xml formatted string to allow presentation of data to be associated with the MBean. 
173      * </PRE>
174      * <P>
175      * The default descriptor is: name=mbeanName,descriptorType=mbean, displayName=this.getClassName(), 
176      *  persistPolicy=never,log=F,export=F,visibility=1
177      * If the descriptor does not contain all these fields, they will be added with these default values.
178      *
179      * <p><b>Note:</b> because of inconsistencies in previous versions of
180      * this specification, it is recommended not to use negative or zero
181      * values for <code>currencyTimeLimit</code>.  To indicate that a
182      * cached value is never valid, omit the
183      * <code>currencyTimeLimit</code> field.  To indicate that it is
184      * always valid, use a very large number for this field.</p>
185      *
186      * @return the MBean descriptor.
187      *
188      * @exception MBeanException Wraps a distributed communication
189      * Exception.
190      *
191      * @exception RuntimeOperationsException a {@link
192      * RuntimeException} occurred while getting the descriptor.
193      *
194      * @see #setMBeanDescriptor
195      */
196     public Descriptor   getMBeanDescriptor()
197         throws MBeanException  , RuntimeOperationsException  ;
198 
199     /**
200      * Sets the ModelMBean's descriptor.  This descriptor contains default, MBean wide 
201      * metadata about the MBean and default policies for persistence and caching. This operation
202      * does a complete replacement of the descriptor, no merging is done. If the descriptor to
203      * set to is null then the default descriptor will be created.
204      * The default descriptor is: name=mbeanName,descriptorType=mbean, displayName=this.getClassName(), 
205      *  persistPolicy=never,log=F,export=F,visibility=1
206      * If the descriptor does not contain all these fields, they will be added with these default values.
207      *
208      * See {@link #getMBeanDescriptor getMBeanDescriptor} method javadoc for description of valid field names.
209      *
210      * @param inDescriptor the descriptor to set.
211      *
212      * @exception MBeanException Wraps a distributed communication Exception.
213      * @exception RuntimeOperationsException Wraps an IllegalArgumentException  for invalid descriptor. 
214      *
215      *
216      * @see #getMBeanDescriptor
217      */
218 
219     public void setMBeanDescriptor(Descriptor   inDescriptor)
220         throws MBeanException  , RuntimeOperationsException  ;
221 
222 
223     /**
224      * Returns a ModelMBeanAttributeInfo requested by name.
225      *
226      * @param inName The name of the ModelMBeanAttributeInfo to get.
227      * If no ModelMBeanAttributeInfo exists for this name null is returned.
228      *
229      * @return the attribute info for the named attribute, or null
230      * if there is none.
231      *
232      * @exception MBeanException Wraps a distributed communication
233      * Exception.
234      * @exception RuntimeOperationsException Wraps an
235      * IllegalArgumentException for a null attribute name.
236      *
237      */
238 
239     public ModelMBeanAttributeInfo   getAttribute(String   inName)
240         throws MBeanException  , RuntimeOperationsException  ;
241 
242 
243     /**
244      * Returns a ModelMBeanOperationInfo requested by name.
245      *
246      * @param inName The name of the ModelMBeanOperationInfo to get.
247      * If no ModelMBeanOperationInfo exists for this name null is returned.
248      *
249      * @return the operation info for the named operation, or null
250      * if there is none.
251      *
252      * @exception MBeanException Wraps a distributed communication Exception. 
253      * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null operation name.
254      *
255      */
256 
257     public ModelMBeanOperationInfo   getOperation(String   inName)
258         throws MBeanException  , RuntimeOperationsException  ;
259 
260 
261     /**
262      * Returns a ModelMBeanNotificationInfo requested by name.
263      *
264      * @param inName The name of the ModelMBeanNotificationInfo to get.
265      * If no ModelMBeanNotificationInfo exists for this name null is returned.
266      *
267      * @return the info for the named notification, or null if there
268      * is none.
269      *
270      * @exception MBeanException Wraps a distributed communication Exception.
271      * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null notification name.
272      *
273      */
274     public ModelMBeanNotificationInfo   getNotification(String   inName)
275         throws MBeanException  , RuntimeOperationsException  ;
276     
277     /**
278      * Creates and returns a copy of this object.
279      */
280     public java.lang.Object   clone();
281 
282     /**
283      * Returns the list of attributes exposed for management. 
284      * Each attribute is described by an <CODE>MBeanAttributeInfo</CODE> object.
285      *
286      * @return  An array of <CODE>MBeanAttributeInfo</CODE> objects.
287      */    
288     public MBeanAttributeInfo[] getAttributes(); 
289 
290     /**
291      * Returns the name of the Java class of the MBean described by
292      * this <CODE>MBeanInfo</CODE>.
293      *
294      * @return the Java class name.
295      */
296     public java.lang.String   getClassName(); 
297 
298     /**
299      * Returns the list of the public constructors  of the MBean. 
300      * Each constructor is described by an <CODE>MBeanConstructorInfo</CODE> object.
301      *
302      * @return  An array of <CODE>MBeanConstructorInfo</CODE> objects.
303      */
304     public MBeanConstructorInfo[] getConstructors(); 
305 
306     /**
307      * Returns a human readable description of the MBean.
308      *
309      * @return the description.
310      */    
311     public java.lang.String   getDescription(); 
312 
313     /**
314      * Returns the list of the notifications emitted by the MBean. 
315      * Each notification is described by an <CODE>MBeanNotificationInfo</CODE> object.
316      * <P>
317      * In addition to any notification specified by the application, 
318      * a ModelMBean may always send also two additional notifications:
319      * <UL>  
320      * <LI> One with descriptor name "GENERIC" and displayName "jmx.modelmbean.generic" 
321      * <LI> Second is a standard attribute change notification
322      *      with descriptor name "ATTRIBUTE_CHANGE" and displayName "jmx.attribute.change"
323      * </UL>
324      * Thus any implementation of ModelMBeanInfo should always add those two notifications
325      * in addition to those specified by the application.
326      * 
327      * @return  An array of <CODE>MBeanNotificationInfo</CODE> objects.
328      */
329     public MBeanNotificationInfo[] getNotifications(); 
330 
331     /**
332      * Returns the list of operations  of the MBean. 
333      * Each operation is described by an <CODE>MBeanOperationInfo</CODE> object.
334      *
335      * @return  An array of <CODE>MBeanOperationInfo</CODE> objects.
336      */  
337     public MBeanOperationInfo[] getOperations(); 
338 
339 }
340
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags