1 /*
2 * Portions Copyright 2000-2006 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25 /*
26 * @author IBM Corp.
27 *
28 * Copyright IBM Corp. 1999-2000. All rights reserved.
29 */
30
31 package javax.management;
32
33 import java.io.Serializable;
34
35 // Javadoc imports:
36 import java.lang.management.MemoryUsage;
37 import java.util.Arrays;
38 import java.util.ResourceBundle;
39
40 import javax.management.openmbean.CompositeData;
41 import javax.management.openmbean.OpenMBeanAttributeInfoSupport;
42 import javax.management.openmbean.OpenMBeanOperationInfoSupport;
43 import javax.management.openmbean.OpenMBeanParameterInfoSupport;
44 import javax.management.openmbean.OpenType;
45
46 /**
47 * <p>Additional metadata for a JMX element. A {@code Descriptor}
48 * is associated with a {@link MBeanInfo}, {@link MBeanAttributeInfo}, etc.
49 * It consists of a collection of fields. A field is a name and an
50 * associated value.</p>
51 *
52 * <p>Field names are not case-sensitive. The names {@code descriptorType},
53 * {@code descriptortype}, and {@code DESCRIPTORTYPE} are all equivalent.
54 * However, the case that was used when the field was first set is preserved
55 * in the result of the {@link #getFields} and {@link #getFieldNames}
56 * methods.</p>
57 *
58 * <p>Not all field names and values are predefined.
59 * New fields can be defined and added by any program.</p>
60 *
61 * <p>A descriptor can be mutable or immutable.
62 * An immutable descriptor, once created, never changes.
63 * The <code>Descriptor</code> methods that could modify the contents
64 * of the descriptor will throw an exception
65 * for an immutable descriptor. Immutable descriptors are usually
66 * instances of {@link ImmutableDescriptor} or a subclass. Mutable
67 * descriptors are usually instances of
68 * {@link javax.management.modelmbean.DescriptorSupport} or a subclass.
69 *
70 * <p>Certain fields are used by the JMX implementation. This means
71 * either that the presence of the field may change the behavior of
72 * the JMX API or that the field may be set in descriptors returned by
73 * the JMX API. These fields appear in <i>italics</i> in the table
74 * below, and each one has a corresponding constant in the {@link JMX}
75 * class. For example, the field {@code defaultValue} is represented
76 * by the constant {@link JMX#DEFAULT_VALUE_FIELD}.</p>
77 *
78 * <p>Certain other fields have conventional meanings described in the
79 * table below but they are not required to be understood or set by
80 * the JMX implementation.</p>
81 *
82 * <p>Field names defined by the JMX specification in this and all
83 * future versions will never contain a period (.). Users can safely
84 * create their own fields by including a period in the name and be
85 * sure that these names will not collide with any future version of
86 * the JMX API. It is recommended to follow the Java package naming
87 * convention to avoid collisions between field names from different
88 * origins. For example, a field created by {@code example.com} might
89 * have the name {@code com.example.interestLevel}.</p>
90 *
91 * <p>Note that the values in the {@code defaultValue}, {@code
92 * legalValues}, {@code maxValue}, and {@code minValue} fields should
93 * be consistent with the type returned by the {@code getType()}
94 * method for the associated {@code MBeanAttributeInfo} or {@code
95 * MBeanParameterInfo}. For MXBeans, this means that they should be
96 * of the mapped Java type, called <em>opendata</em>(J) in the <a
97 * href="MXBean.html#mapping-rules">MXBean type mapping rules</a>.</p>
98 *
99 * <table border="1" cellpadding="5">
100 *
101 * <tr><th>Name</th><th>Type</th><th>Used in</th><th>Meaning</th></tr>
102 *
103 * <tr><td><a name="defaultValue"><i>defaultValue</i></a><td>Object</td>
104 * <td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
105 *
106 * <td>Default value for an attribute or parameter. See
107 * {@link javax.management.openmbean}.</td>
108 *
109 * <tr><td>deprecated</td><td>String</td><td>Any</td>
110 *
111 * <td>An indication that this element of the information model is no
112 * longer recommended for use. A set of MBeans defined by an
113 * application is collectively called an <em>information model</em>.
114 * The convention is for the value of this field to contain a string
115 * that is the version of the model in which the element was first
116 * deprecated, followed by a space, followed by an explanation of the
117 * deprecation, for example {@code "1.3 Replaced by the Capacity
118 * attribute"}.</td>
119 *
120 * <tr><td>descriptionResource<br>BundleBaseName</td><td>String</td><td>Any</td>
121 *
122 * <td>The base name for the {@link ResourceBundle} in which the key given in
123 * the {@code descriptionResourceKey} field can be found, for example
124 * {@code "com.example.myapp.MBeanResources"}. The meaning of this
125 * field is defined by this specification but the field is not set or
126 * used by the JMX API itself.</td>
127 *
128 * <tr><td>descriptionResourceKey</td><td>String</td><td>Any</td>
129 *
130 * <td>A resource key for the description of this element. In
131 * conjunction with the {@code descriptionResourceBundleBaseName},
132 * this can be used to find a localized version of the description.
133 * The meaning of this field is defined by this specification but the
134 * field is not set or used by the JMX API itself.</td>
135 *
136 * <tr><td>enabled</td><td>String</td>
137 * <td>MBeanAttributeInfo<br>MBeanNotificationInfo<br>MBeanOperationInfo</td>
138 *
139 * <td>The string {@code "true"} or {@code "false"} according as this
140 * item is enabled. When an attribute or operation is not enabled, it
141 * exists but cannot currently be accessed. A user interface might
142 * present it as a greyed-out item. For example, an attribute might
143 * only be meaningful after the {@code start()} method of an MBean has
144 * been called, and is otherwise disabled. Likewise, a notification
145 * might be disabled if it cannot currently be emitted but could be in
146 * other circumstances.</td>
147 *
148 * <tr><td><a name="immutableInfo"><i>immutableInfo</i></a><td>String</td>
149 * <td>MBeanInfo</td>
150 *
151 * <td>The string {@code "true"} or {@code "false"} according as this
152 * MBean's MBeanInfo is <em>immutable</em>. When this field is true,
153 * the MBeanInfo for the given MBean is guaranteed not to change over
154 * the lifetime of the MBean. Hence, a client can read it once and
155 * cache the read value. When this field is false or absent, there is
156 * no such guarantee, although that does not mean that the MBeanInfo
157 * will necessarily change.</td>
158 *
159 * <tr><td>infoTimeout</td><td>String<br>Long</td><td>MBeanInfo</td>
160 *
161 * <td>The time in milli-seconds that the MBeanInfo can reasonably be
162 * expected to be unchanged. The value can be a {@code Long} or a
163 * decimal string. This provides a hint from a DynamicMBean or any
164 * MBean that does not define {@code immutableInfo} as {@code true}
165 * that the MBeanInfo is not likely to change within this period and
166 * therefore can be cached. When this field is missing or has the
167 * value zero, it is not recommended to cache the MBeanInfo unless it
168 * has the {@code immutableInfo} set to {@code true}.</td></tr>
169 *
170 * <tr><td><a name="interfaceClassName"><i>interfaceClassName</i></a></td>
171 * <td>String</td><td>MBeanInfo</td>
172 *
173 * <td>The Java interface name for a Standard MBean or MXBean, as
174 * returned by {@link Class#getName()}. A Standard MBean or MXBean
175 * registered directly in the MBean Server or created using the {@link
176 * StandardMBean} class will have this field in its MBeanInfo
177 * Descriptor.</td>
178 *
179 * <tr><td><a name="legalValues"><i>legalValues</i></a></td>
180 * <td>{@literal Set<?>}</td><td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
181 *
182 * <td>Legal values for an attribute or parameter. See
183 * {@link javax.management.openmbean}.</td>
184 *
185 * <tr><td><a name="maxValue"><i>maxValue</i></a><td>Object</td>
186 * <td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
187 *
188 * <td>Maximum legal value for an attribute or parameter. See
189 * {@link javax.management.openmbean}.</td>
190 *
191 * <tr><td><a name="metricType">metricType</a><td>String</td>
192 * <td>MBeanAttributeInfo<br>MBeanOperationInfo</td>
193 *
194 * <td>The type of a metric, one of the strings "counter" or "gauge".
195 * A metric is a measurement exported by an MBean, usually an
196 * attribute but sometimes the result of an operation. A metric that
197 * is a <em>counter</em> has a value that never decreases except by
198 * being reset to a starting value. Counter metrics are almost always
199 * non-negative integers. An example might be the number of requests
200 * received. A metric that is a <em>gauge</em> has a numeric value
201 * that can increase or decrease. Examples might be the number of
202 * open connections or a cache hit rate or a temperature reading.
203 *
204 * <tr><td><a name="minValue"><i>minValue</i></a><td>Object</td>
205 * <td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
206 *
207 * <td>Minimum legal value for an attribute or parameter. See
208 * {@link javax.management.openmbean}.</td>
209 *
210 * <tr><td><a name="mxbean"><i>mxbean</i></a><td>String</td>
211 * <td>MBeanInfo</td>
212 *
213 * <td>The string {@code "true"} or {@code "false"} according as this
214 * MBean is an {@link MXBean}. A Standard MBean or MXBean registered
215 * directly with the MBean Server or created using the {@link
216 * StandardMBean} class will have this field in its MBeanInfo
217 * Descriptor.</td>
218 *
219 * <tr><td><a name="openType"><i>openType</i></a><td>{@link OpenType}</td>
220 * <td>MBeanAttributeInfo<br>MBeanOperationInfo<br>MBeanParameterInfo</td>
221 *
222 * <td><p>The Open Type of this element. In the case of {@code
223 * MBeanAttributeInfo} and {@code MBeanParameterInfo}, this is the
224 * Open Type of the attribute or parameter. In the case of {@code
225 * MBeanOperationInfo}, it is the Open Type of the return value. This
226 * field is set in the Descriptor for all instances of {@link
227 * OpenMBeanAttributeInfoSupport}, {@link
228 * OpenMBeanOperationInfoSupport}, and {@link
229 * OpenMBeanParameterInfoSupport}. It is also set for attributes,
230 * operations, and parameters of MXBeans.</p>
231 *
232 * <p>This field can be set for an {@code MBeanNotificationInfo}, in
233 * which case it indicates the Open Type that the {@link
234 * Notification#getUserData() user data} will have.</td>
235 *
236 * <tr><td><a name="originalType"><i>originalType</i></a><td>String</td>
237 * <td>MBeanAttributeInfo<br>MBeanOperationInfo<br>MBeanParameterInfo</td>
238 *
239 * <td><p>The original Java type of this element as it appeared in the
240 * {@link MXBean} interface method that produced this {@code
241 * MBeanAttributeInfo} (etc). For example, a method<br> <code>public
242 * </code> {@link MemoryUsage}<code> getHeapMemoryUsage();</code><br>
243 * in an MXBean interface defines an attribute called {@code
244 * HeapMemoryUsage} of type {@link CompositeData}. The {@code
245 * originalType} field in the Descriptor for this attribute will have
246 * the value {@code "java.lang.management.MemoryUsage"}.
247 *
248 * <p>The format of this string is described in the section <a
249 * href="MXBean.html#type-names">Type Names</a> of the MXBean
250 * specification.</p>
251 *
252 * <tr><td>severity</td><td>String<br>Integer</td>
253 * <td>MBeanNotificationInfo</td>
254 *
255 * <td>The severity of this notification. It can be 0 to mean
256 * unknown severity or a value from 1 to 6 representing decreasing
257 * levels of severity. It can be represented as a decimal string or
258 * an {@code Integer}.</td>
259 *
260 * <tr><td>since</td><td>String</td><td>Any</td>
261 *
262 * <td>The version of the information model in which this element
263 * was introduced. A set of MBeans defined by an application is
264 * collectively called an <em>information model</em>. The
265 * application may also define versions of this model, and use the
266 * {@code "since"} field to record the version in which an element
267 * first appeared.</td>
268 *
269 * <tr><td>units</td><td>String</td>
270 * <td>MBeanAttributeInfo<br>MBeanParameterInfo<br>MBeanOperationInfo</td>
271 *
272 * <td>The units in which an attribute, parameter, or operation return
273 * value is measured, for example {@code "bytes"} or {@code
274 * "seconds"}.</td>
275 *
276 * </table>
277 *
278 * <p>Some additional fields are defined by Model MBeans. See
279 * {@link javax.management.modelmbean.ModelMBeanInfo ModelMBeanInfo}
280 * and related classes and the chapter "Model MBeans" of the
281 * <a href="http://java.sun.com/products/JavaManagement/download.html">
282 * JMX Specification</a>.</p>
283 *
284 * @since 1.5
285 */
286 public interface Descriptor extends Serializable, Cloneable
287 {
288
289 /**
290 * Returns the value for a specific field name, or null if no value
291 * is present for that name.
292 *
293 * @param fieldName the field name.
294 *
295 * @return the corresponding value, or null if the field is not present.
296 *
297 * @exception RuntimeOperationsException if the field name is illegal.
298 */
299 public Object getFieldValue(String fieldName)
300 throws RuntimeOperationsException;
301
302 /**
303 * <p>Sets the value for a specific field name. This will
304 * modify an existing field or add a new field.</p>
305 *
306 * <p>The field value will be validated before it is set.
307 * If it is not valid, then an exception will be thrown.
308 * The meaning of validity is dependent on the descriptor
309 * implementation.</p>
310 *
311 * @param fieldName The field name to be set. Cannot be null or empty.
312 * @param fieldValue The field value to be set for the field
313 * name. Can be null if that is a valid value for the field.
314 *
315 * @exception RuntimeOperationsException if the field name or field value
316 * is illegal (wrapped exception is {@link IllegalArgumentException}); or
317 * if the descriptor is immutable (wrapped exception is
318 * {@link UnsupportedOperationException}).
319 */
320 public void setField(String fieldName, Object fieldValue)
321 throws RuntimeOperationsException;
322
323
324 /**
325 * Returns all of the fields contained in this descriptor as a string array.
326 *
327 * @return String array of fields in the format <i>fieldName=fieldValue</i>
328 * <br>If the value of a field is not a String, then the toString() method
329 * will be called on it and the returned value, enclosed in parentheses,
330 * used as the value for the field in the returned array. If the value
331 * of a field is null, then the value of the field in the returned array
332 * will be empty. If the descriptor is empty, you will get
333 * an empty array.
334 *
335 * @see #setFields
336 */
337 public String[] getFields();
338
339
340 /**
341 * Returns all the field names in the descriptor.
342 *
343 * @return String array of field names. If the descriptor is empty,
344 * you will get an empty array.
345 */
346 public String[] getFieldNames();
347
348 /**
349 * Returns all the field values in the descriptor as an array of Objects. The
350 * returned values are in the same order as the {@code fieldNames} String array parameter.
351 *
352 * @param fieldNames String array of the names of the fields that
353 * the values should be returned for. If the array is empty then
354 * an empty array will be returned. If the array is null then all
355 * values will be returned, as if the parameter were the array
356 * returned by {@link #getFieldNames()}. If a field name in the
357 * array does not exist, including the case where it is null or
358 * the empty string, then null is returned for the matching array
359 * element being returned.
360 *
361 * @return Object array of field values. If the list of {@code fieldNames}
362 * is empty, you will get an empty array.
363 */
364 public Object[] getFieldValues(String... fieldNames);
365
366 /**
367 * Removes a field from the descriptor.
368 *
369 * @param fieldName String name of the field to be removed.
370 * If the field name is illegal or the field is not found,
371 * no exception is thrown.
372 *
373 * @exception RuntimeOperationsException if a field of the given name
374 * exists and the descriptor is immutable. The wrapped exception will
375 * be an {@link UnsupportedOperationException}.
376 */
377 public void removeField(String fieldName);
378
379 /**
380 * <p>Sets all fields in the field names array to the new value with
381 * the same index in the field values array. Array sizes must match.</p>
382 *
383 * <p>The field value will be validated before it is set.
384 * If it is not valid, then an exception will be thrown.
385 * If the arrays are empty, then no change will take effect.</p>
386 *
387 * @param fieldNames String array of field names. The array and array
388 * elements cannot be null.
389 * @param fieldValues Object array of the corresponding field values.
390 * The array cannot be null. Elements of the array can be null.
391 *
392 * @throws RuntimeOperationsException if the change fails for any reason.
393 * Wrapped exception is {@link IllegalArgumentException} if
394 * {@code fieldNames} or {@code fieldValues} is null, or if
395 * the arrays are of different lengths, or if there is an
396 * illegal value in one of them.
397 * Wrapped exception is {@link UnsupportedOperationException}
398 * if the descriptor is immutable, and the call would change
399 * its contents.
400 *
401 * @see #getFields
402 */
403 public void setFields(String[] fieldNames, Object[] fieldValues)
404 throws RuntimeOperationsException;
405
406
407 /**
408 * <p>Returns a descriptor which is equal to this descriptor.
409 * Changes to the returned descriptor will have no effect on this
410 * descriptor, and vice versa. If this descriptor is immutable,
411 * it may fulfill this condition by returning itself.</p>
412 * @exception RuntimeOperationsException for illegal value for field names
413 * or field values.
414 * If the descriptor construction fails for any reason, this exception will
415 * be thrown.
416 * @return A descriptor which is equal to this descriptor.
417 */
418 public Object clone() throws RuntimeOperationsException;
419
420
421 /**
422 * Returns true if all of the fields have legal values given their
423 * names.
424 *
425 * @return true if the values are legal.
426 *
427 * @exception RuntimeOperationsException If the validity checking fails for
428 * any reason, this exception will be thrown.
429 * The method returns false if the descriptor is not valid, but throws
430 * this exception if the attempt to determine validity fails.
431 */
432 public boolean isValid() throws RuntimeOperationsException;
433
434 /**
435 * Compares this descriptor to the given object. The objects are equal if
436 * the given object is also a Descriptor, and if the two Descriptors have
437 * the same field names (possibly differing in case) and the same
438 * associated values. The respective values for a field in the two
439 * Descriptors are equal if the following conditions hold:</p>
440 *
441 * <ul>
442 * <li>If one value is null then the other must be too.</li>
443 * <li>If one value is a primitive array then the other must be a primitive
444 * array of the same type with the same elements.</li>
445 * <li>If one value is an object array then the other must be too and
446 * {@link Arrays#deepEquals(Object[],Object[])} must return true.</li>
447 * <li>Otherwise {@link Object#equals(Object)} must return true.</li>
448 * </ul>
449 *
450 * @param obj the object to compare with.
451 *
452 * @return {@code true} if the objects are the same; {@code false}
453 * otherwise.
454 *
455 * @since 1.6
456 */
457 public boolean equals(Object obj);
458
459 /**
460 * <p>Returns the hash code value for this descriptor. The hash
461 * code is computed as the sum of the hash codes for each field in
462 * the descriptor. The hash code of a field with name {@code n}
463 * and value {@code v} is {@code n.toLowerCase().hashCode() ^ h}.
464 * Here {@code h} is the hash code of {@code v}, computed as
465 * follows:</p>
466 *
467 * <ul>
468 * <li>If {@code v} is null then {@code h} is 0.</li>
469 * <li>If {@code v} is a primitive array then {@code h} is computed using
470 * the appropriate overloading of {@code java.util.Arrays.hashCode}.</li>
471 * <li>If {@code v} is an object array then {@code h} is computed using
472 * {@link Arrays#deepHashCode(Object[])}.</li>
473 * <li>Otherwise {@code h} is {@code v.hashCode()}.</li>
474 * </ul>
475 *
476 * @return A hash code value for this object.
477 *
478 * @since 1.6
479 */
480 public int hashCode();
481 }
Save This Page