1 /*
2 * Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 /*
26 * @author IBM Corp.
27 *
28 * Copyright IBM Corp. 1999-2000. All rights reserved.
29 */
30
31 package javax.management.modelmbean;
32
33 import javax.management.Descriptor;
34 import javax.management.MBeanAttributeInfo;
35 import javax.management.MBeanConstructorInfo;
36 import javax.management.RuntimeOperationsException;
37 import javax.management.MBeanException;
38 import javax.management.MBeanNotificationInfo;
39 import javax.management.MBeanOperationInfo;
40
41 /**
42 * This interface is implemented by the ModelMBeanInfo for every ModelMBean. An implementation of this interface
43 * must be shipped with every JMX Agent.
44 * <P>
45 * Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's
46 * createMBean method. The resource then sets the ModelMBeanInfo and Descriptors for the ModelMBean
47 * instance. The attributes, operations, and notifications exposed via the ModelMBeanInfo for the
48 * ModelMBean comprise the management interface and are accessible
49 * from MBeans, connectors/adaptors like other MBeans. Through the Descriptors, values and methods in
50 * the managed application can be defined and mapped to attributes and operations of the ModelMBean.
51 * This mapping can be defined during development in a file or dynamically and
52 * programmatically at runtime.
53 * <P>
54 * Every ModelMBean which is instantiated in the MBeanServer becomes manageable:
55 * its attributes, operations, and notifications
56 * become remotely accessible through the connectors/adaptors connected to that MBeanServer.
57 * A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean.
58 * By instantiating a ModelMBean, resources are guaranteed that the MBean is valid.
59 *
60 * MBeanException and RuntimeOperationsException must be thrown on every public method. This allows
61 * for wrapping exceptions from distributed communications (RMI, EJB, etc.)
62 *
63 * @since 1.5
64 */
65
66 public interface ModelMBeanInfo
67 {
68
69
70 /**
71 * Returns a Descriptor array consisting of all
72 * Descriptors for the ModelMBeanInfo of type inDescriptorType.
73 *
74 * @param inDescriptorType value of descriptorType field that must be set for the descriptor
75 * to be returned. Must be "mbean", "attribute", "operation", "constructor" or "notification".
76 * If it is null or empty then all types will be returned.
77 *
78 * @return Descriptor array containing all descriptors for the ModelMBean if type inDescriptorType.
79 *
80 * @exception MBeanException Wraps a distributed communication Exception.
81 * @exception RuntimeOperationsException Wraps an IllegalArgumentException when the descriptorType in parameter is
82 * not one of: "mbean", "attribute", "operation", "constructor", "notification", empty or null.
83 *
84 * @see #setDescriptors
85 */
86 public Descriptor[] getDescriptors(String inDescriptorType)
87 throws MBeanException, RuntimeOperationsException;
88
89 /**
90 * Adds or replaces descriptors in the ModelMBeanInfo.
91 *
92 * @param inDescriptors The descriptors to be set in the ModelMBeanInfo. Null
93 * elements of the list will be ignored. All descriptors must have name and descriptorType fields.
94 *
95 * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null or invalid descriptor.
96 * @exception MBeanException Wraps a distributed communication Exception.
97 *
98 * @see #getDescriptors
99 */
100 public void setDescriptors(Descriptor[] inDescriptors)
101 throws MBeanException, RuntimeOperationsException;
102
103 /**
104 * Returns a Descriptor requested by name and descriptorType.
105 *
106 * @param inDescriptorName The name of the descriptor.
107 * @param inDescriptorType The type of the descriptor being
108 * requested. If this is null or empty then all types are
109 * searched. Valid types are 'mbean', 'attribute', 'constructor'
110 * 'operation', and 'notification'. This value will be equal to
111 * the 'descriptorType' field in the descriptor that is returned.
112 *
113 * @return Descriptor containing the descriptor for the ModelMBean
114 * with the same name and descriptorType. If no descriptor is
115 * found, null is returned.
116 *
117 * @exception MBeanException Wraps a distributed communication Exception.
118 * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null descriptor name or null or invalid type.
119 * The type must be "mbean","attribute", "constructor", "operation", or "notification".
120 *
121 * @see #setDescriptor
122 */
123
124 public Descriptor getDescriptor(String inDescriptorName, String inDescriptorType)
125 throws MBeanException, RuntimeOperationsException;
126
127 /**
128 * Sets descriptors in the info array of type inDescriptorType
129 * for the ModelMBean. The setDescriptor method of the
130 * corresponding ModelMBean*Info will be called to set the
131 * specified descriptor.
132 *
133 * @param inDescriptor The descriptor to be set in the
134 * ModelMBean. It must NOT be null. All descriptors must have
135 * name and descriptorType fields.
136 * @param inDescriptorType The type of the descriptor being
137 * set. If this is null then the descriptorType field in the
138 * descriptor is used. If specified this value must be set in
139 * the descriptorType field in the descriptor. Must be
140 * "mbean","attribute", "constructor", "operation", or
141 * "notification".
142 *
143 * @exception RuntimeOperationsException Wraps an
144 * IllegalArgumentException for illegal or null arguments or
145 * if the name field of the descriptor is not found in the
146 * corresponding MBeanAttributeInfo or MBeanConstructorInfo or
147 * MBeanNotificationInfo or MBeanOperationInfo.
148 * @exception MBeanException Wraps a distributed communication
149 * Exception.
150 *
151 * @see #getDescriptor
152 */
153
154 public void setDescriptor(Descriptor inDescriptor, String inDescriptorType)
155 throws MBeanException, RuntimeOperationsException;
156
157
158 /**
159 * <p>Returns the ModelMBean's descriptor which contains MBean wide
160 * policies. This descriptor contains metadata about the MBean and default
161 * policies for persistence and caching.</p>
162 *
163 * <P id="descriptor">
164 * The fields in the descriptor are defined, but not limited to, the
165 * following. Note that when the Type in this table is Number, a String
166 * that is the decimal representation of a Long can also be used.</P>
167 *
168 * <table border="1" cellpadding="5">
169 * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr>
170 * <tr><td>name</td><td>String</td>
171 * <td>MBean name.</td></tr>
172 * <tr><td>descriptorType</td><td>String</td>
173 * <td>Must be "mbean".</td></tr>
174 * <tr><td>displayName</td><td>String</td>
175 * <td>Name of MBean to be used in displays.</td></tr>
176 * <tr><td>persistPolicy</td><td>String</td>
177 * <td>One of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never.
178 * See the section "MBean Descriptor Fields" in the JMX specification
179 * document.</td></tr>
180 * <tr><td>persistLocation</td><td>String</td>
181 * <td>The fully qualified directory name where the MBean should be
182 * persisted (if appropriate).</td></tr>
183 * <tr><td>persistFile</td><td>String</td>
184 * <td>File name into which the MBean should be persisted.</td></tr>
185 * <tr><td>persistPeriod</td><td>Number</td>
186 * <td>Frequency of persist cycle in seconds, for OnTime and
187 * NoMoreOftenThan PersistPolicy</td></tr>
188 * <tr><td>currencyTimeLimit</td><td>Number</td>
189 * <td>How long cached value is valid: <0 never, =0 always,
190 * >0 seconds.</td></tr>
191 * <tr><td>log</td><td>String</td>
192 * <td>t: log all notifications, f: log no notifications.</td></tr>
193 * <tr><td>logfile</td><td>String</td>
194 * <td>Fully qualified filename to log events to.</td></tr>
195 * <tr><td>visibility</td><td>Number</td>
196 * <td>1-4 where 1: always visible 4: rarely visible.</td></tr>
197 * <tr><td>export</td><td>String</td>
198 * <td>Name to be used to export/expose this MBean so that it is
199 * findable by other JMX Agents.</td></tr>
200 * <tr><td>presentationString</td><td>String</td>
201 * <td>XML formatted string to allow presentation of data to be
202 * associated with the MBean.</td></tr>
203 * </table>
204 *
205 * <P>
206 * The default descriptor is: name=className,descriptorType="mbean", displayName=className,
207 * persistPolicy="never",log="F",visibility="1"
208 * If the descriptor does not contain all these fields, they will be added with these default values.
209 *
210 * <p><b>Note:</b> because of inconsistencies in previous versions of
211 * this specification, it is recommended not to use negative or zero
212 * values for <code>currencyTimeLimit</code>. To indicate that a
213 * cached value is never valid, omit the
214 * <code>currencyTimeLimit</code> field. To indicate that it is
215 * always valid, use a very large number for this field.</p>
216 *
217 * @return the MBean descriptor.
218 *
219 * @exception MBeanException Wraps a distributed communication
220 * Exception.
221 *
222 * @exception RuntimeOperationsException a {@link
223 * RuntimeException} occurred while getting the descriptor.
224 *
225 * @see #setMBeanDescriptor
226 */
227 public Descriptor getMBeanDescriptor()
228 throws MBeanException, RuntimeOperationsException;
229
230 /**
231 * Sets the ModelMBean's descriptor. This descriptor contains default, MBean wide
232 * metadata about the MBean and default policies for persistence and caching. This operation
233 * does a complete replacement of the descriptor, no merging is done. If the descriptor to
234 * set to is null then the default descriptor will be created.
235 * The default descriptor is: name=className,descriptorType="mbean", displayName=className,
236 * persistPolicy="never",log="F",visibility="1"
237 * If the descriptor does not contain all these fields, they will be added with these default values.
238 *
239 * See {@link #getMBeanDescriptor getMBeanDescriptor} method javadoc for description of valid field names.
240 *
241 * @param inDescriptor the descriptor to set.
242 *
243 * @exception MBeanException Wraps a distributed communication Exception.
244 * @exception RuntimeOperationsException Wraps an IllegalArgumentException for invalid descriptor.
245 *
246 *
247 * @see #getMBeanDescriptor
248 */
249
250 public void setMBeanDescriptor(Descriptor inDescriptor)
251 throws MBeanException, RuntimeOperationsException;
252
253
254 /**
255 * Returns a ModelMBeanAttributeInfo requested by name.
256 *
257 * @param inName The name of the ModelMBeanAttributeInfo to get.
258 * If no ModelMBeanAttributeInfo exists for this name null is returned.
259 *
260 * @return the attribute info for the named attribute, or null
261 * if there is none.
262 *
263 * @exception MBeanException Wraps a distributed communication
264 * Exception.
265 * @exception RuntimeOperationsException Wraps an
266 * IllegalArgumentException for a null attribute name.
267 *
268 */
269
270 public ModelMBeanAttributeInfo getAttribute(String inName)
271 throws MBeanException, RuntimeOperationsException;
272
273
274 /**
275 * Returns a ModelMBeanOperationInfo requested by name.
276 *
277 * @param inName The name of the ModelMBeanOperationInfo to get.
278 * If no ModelMBeanOperationInfo exists for this name null is returned.
279 *
280 * @return the operation info for the named operation, or null
281 * if there is none.
282 *
283 * @exception MBeanException Wraps a distributed communication Exception.
284 * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null operation name.
285 *
286 */
287
288 public ModelMBeanOperationInfo getOperation(String inName)
289 throws MBeanException, RuntimeOperationsException;
290
291
292 /**
293 * Returns a ModelMBeanNotificationInfo requested by name.
294 *
295 * @param inName The name of the ModelMBeanNotificationInfo to get.
296 * If no ModelMBeanNotificationInfo exists for this name null is returned.
297 *
298 * @return the info for the named notification, or null if there
299 * is none.
300 *
301 * @exception MBeanException Wraps a distributed communication Exception.
302 * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null notification name.
303 *
304 */
305 public ModelMBeanNotificationInfo getNotification(String inName)
306 throws MBeanException, RuntimeOperationsException;
307
308 /**
309 * Creates and returns a copy of this object.
310 */
311 public java.lang.Object clone();
312
313 /**
314 * Returns the list of attributes exposed for management.
315 * Each attribute is described by an <CODE>MBeanAttributeInfo</CODE> object.
316 *
317 * @return An array of <CODE>MBeanAttributeInfo</CODE> objects.
318 */
319 public MBeanAttributeInfo[] getAttributes();
320
321 /**
322 * Returns the name of the Java class of the MBean described by
323 * this <CODE>MBeanInfo</CODE>.
324 *
325 * @return the Java class name.
326 */
327 public java.lang.String getClassName();
328
329 /**
330 * Returns the list of the public constructors of the MBean.
331 * Each constructor is described by an <CODE>MBeanConstructorInfo</CODE> object.
332 *
333 * @return An array of <CODE>MBeanConstructorInfo</CODE> objects.
334 */
335 public MBeanConstructorInfo[] getConstructors();
336
337 /**
338 * Returns a human readable description of the MBean.
339 *
340 * @return the description.
341 */
342 public java.lang.String getDescription();
343
344 /**
345 * Returns the list of the notifications emitted by the MBean.
346 * Each notification is described by an <CODE>MBeanNotificationInfo</CODE> object.
347 * <P>
348 * In addition to any notification specified by the application,
349 * a ModelMBean may always send also two additional notifications:
350 * <UL>
351 * <LI> One with descriptor name "GENERIC" and displayName "jmx.modelmbean.generic"
352 * <LI> Second is a standard attribute change notification
353 * with descriptor name "ATTRIBUTE_CHANGE" and displayName "jmx.attribute.change"
354 * </UL>
355 * Thus any implementation of ModelMBeanInfo should always add those two notifications
356 * in addition to those specified by the application.
357 *
358 * @return An array of <CODE>MBeanNotificationInfo</CODE> objects.
359 */
360 public MBeanNotificationInfo[] getNotifications();
361
362 /**
363 * Returns the list of operations of the MBean.
364 * Each operation is described by an <CODE>MBeanOperationInfo</CODE> object.
365 *
366 * @return An array of <CODE>MBeanOperationInfo</CODE> objects.
367 */
368 public MBeanOperationInfo[] getOperations();
369
370 }