View Javadoc
1   /*
2    * Copyright (c) 2000, 2013, 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;
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.Locale;
39  import java.util.ResourceBundle;
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" summary="Descriptor Fields">
100  *
101  * <tr><th>Name</th><th>Type</th><th>Used in</th><th>Meaning</th></tr>
102  *
103  * <tr id="defaultValue"><td><i>defaultValue</i><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 id="descriptionResourceBundleBaseName">descriptionResource<br>
121  * BundleBaseName</td><td>String</td><td>Any</td>
122  *
123  * <td>The base name for the {@link ResourceBundle} in which the key given in
124  * the {@code descriptionResourceKey} field can be found, for example
125  * {@code "com.example.myapp.MBeanResources"}.  The meaning of this
126  * field is defined by this specification but the field is not set or
127  * used by the JMX API itself.</td>
128  *
129  * <tr><td id="descriptionResourceKey">descriptionResourceKey</td>
130  * <td>String</td><td>Any</td>
131  *
132  * <td>A resource key for the description of this element.  In
133  * conjunction with the {@code descriptionResourceBundleBaseName},
134  * this can be used to find a localized version of the description.
135  * The meaning of this field is defined by this specification but the
136  * field is not set or used by the JMX API itself.</td>
137  *
138  * <tr><td>enabled</td><td>String</td>
139  * <td>MBeanAttributeInfo<br>MBeanNotificationInfo<br>MBeanOperationInfo</td>
140  *
141  * <td>The string {@code "true"} or {@code "false"} according as this
142  * item is enabled.  When an attribute or operation is not enabled, it
143  * exists but cannot currently be accessed.  A user interface might
144  * present it as a greyed-out item.  For example, an attribute might
145  * only be meaningful after the {@code start()} method of an MBean has
146  * been called, and is otherwise disabled.  Likewise, a notification
147  * might be disabled if it cannot currently be emitted but could be in
148  * other circumstances.</td>
149  *
150  * <tr id="exceptions"><td>exceptions<td>String[]</td>
151  * <td>MBeanAttributeInfo, MBeanConstructorInfo, MBeanOperationInfo</td>
152  *
153  * <td>The class names of the exceptions that can be thrown when invoking a
154  * constructor or operation, or getting an attribute. The meaning of this field
155  * is defined by this specification but the field is not set or used by the
156  * JMX API itself. Exceptions thrown when
157  * setting an attribute are specified by the field
158  * <a href="#setExceptions">{@code setExceptions}</a>.
159  *
160  * <tr id="immutableInfo"><td><i>immutableInfo</i><td>String</td>
161  * <td>MBeanInfo</td>
162  *
163  * <td>The string {@code "true"} or {@code "false"} according as this
164  * MBean's MBeanInfo is <em>immutable</em>.  When this field is true,
165  * the MBeanInfo for the given MBean is guaranteed not to change over
166  * the lifetime of the MBean.  Hence, a client can read it once and
167  * cache the read value.  When this field is false or absent, there is
168  * no such guarantee, although that does not mean that the MBeanInfo
169  * will necessarily change.  See also the <a
170  * href="MBeanInfo.html#info-changed">{@code "jmx.mbean.info.changed"}</a>
171  * notification.</td>
172  *
173  * <tr id="infoTimeout"><td>infoTimeout</td><td>String<br>Long</td><td>MBeanInfo</td>
174  *
175  * <td>The time in milli-seconds that the MBeanInfo can reasonably be
176  * expected to be unchanged.  The value can be a {@code Long} or a
177  * decimal string.  This provides a hint from a DynamicMBean or any
178  * MBean that does not define {@code immutableInfo} as {@code true}
179  * that the MBeanInfo is not likely to change within this period and
180  * therefore can be cached.  When this field is missing or has the
181  * value zero, it is not recommended to cache the MBeanInfo unless it
182  * has the {@code immutableInfo} set to {@code true} or it has <a
183  * href="MBeanInfo.html#info-changed">{@code "jmx.mbean.info.changed"}</a> in
184  * its {@link MBeanNotificationInfo} array.</td></tr>
185  *
186  * <tr id="interfaceClassName"><td><i>interfaceClassName</i></td>
187  * <td>String</td><td>MBeanInfo</td>
188  *
189  * <td>The Java interface name for a Standard MBean or MXBean, as
190  * returned by {@link Class#getName()}.  A Standard MBean or MXBean
191  * registered directly in the MBean Server or created using the {@link
192  * StandardMBean} class will have this field in its MBeanInfo
193  * Descriptor.</td>
194  *
195  * <tr id="legalValues"><td><i>legalValues</i></td>
196  * <td>{@literal Set<?>}</td><td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
197  *
198  * <td>Legal values for an attribute or parameter.  See
199  * {@link javax.management.openmbean}.</td>
200  *
201  * <tr id="locale"><td>locale</td>
202  * <td>String</td><td>Any</td>
203  *
204  * <td>The {@linkplain Locale locale} of the description in this
205  * {@code MBeanInfo}, {@code MBeanAttributeInfo}, etc, as returned
206  * by {@link Locale#toString()}.</td>
207  *
208  * <tr id="maxValue"><td><i>maxValue</i><td>Object</td>
209  * <td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
210  *
211  * <td>Maximum legal value for an attribute or parameter.  See
212  * {@link javax.management.openmbean}.</td>
213  *
214  * <tr id="metricType"><td>metricType</td><td>String</td>
215  * <td>MBeanAttributeInfo<br>MBeanOperationInfo</td>
216  *
217  * <td>The type of a metric, one of the strings "counter" or "gauge".
218  * A metric is a measurement exported by an MBean, usually an
219  * attribute but sometimes the result of an operation.  A metric that
220  * is a <em>counter</em> has a value that never decreases except by
221  * being reset to a starting value.  Counter metrics are almost always
222  * non-negative integers.  An example might be the number of requests
223  * received.  A metric that is a <em>gauge</em> has a numeric value
224  * that can increase or decrease.  Examples might be the number of
225  * open connections or a cache hit rate or a temperature reading.
226  *
227  * <tr id="minValue"><td><i>minValue</i><td>Object</td>
228  * <td>MBeanAttributeInfo<br>MBeanParameterInfo</td>
229  *
230  * <td>Minimum legal value for an attribute or parameter.  See
231  * {@link javax.management.openmbean}.</td>
232  *
233  * <tr id="mxbean"><td><i>mxbean</i><td>String</td>
234  * <td>MBeanInfo</td>
235  *
236  * <td>The string {@code "true"} or {@code "false"} according as this
237  * MBean is an {@link MXBean}.  A Standard MBean or MXBean registered
238  * directly with the MBean Server or created using the {@link
239  * StandardMBean} class will have this field in its MBeanInfo
240  * Descriptor.</td>
241  *
242  * <tr id="openType"><td><i>openType</i><td>{@link OpenType}</td>
243  * <td>MBeanAttributeInfo<br>MBeanOperationInfo<br>MBeanParameterInfo</td>
244  *
245  * <td><p>The Open Type of this element.  In the case of {@code
246  * MBeanAttributeInfo} and {@code MBeanParameterInfo}, this is the
247  * Open Type of the attribute or parameter.  In the case of {@code
248  * MBeanOperationInfo}, it is the Open Type of the return value.  This
249  * field is set in the Descriptor for all instances of {@link
250  * OpenMBeanAttributeInfoSupport}, {@link
251  * OpenMBeanOperationInfoSupport}, and {@link
252  * OpenMBeanParameterInfoSupport}.  It is also set for attributes,
253  * operations, and parameters of MXBeans.</p>
254  *
255  * <p>This field can be set for an {@code MBeanNotificationInfo}, in
256  * which case it indicates the Open Type that the {@link
257  * Notification#getUserData() user data} will have.</td>
258  *
259  * <tr id="originalType"><td><i>originalType</i><td>String</td>
260  * <td>MBeanAttributeInfo<br>MBeanOperationInfo<br>MBeanParameterInfo</td>
261  *
262  * <td><p>The original Java type of this element as it appeared in the
263  * {@link MXBean} interface method that produced this {@code
264  * MBeanAttributeInfo} (etc).  For example, a method<br> <code>public
265  * </code> {@link MemoryUsage}<code> getHeapMemoryUsage();</code><br>
266  * in an MXBean interface defines an attribute called {@code
267  * HeapMemoryUsage} of type {@link CompositeData}.  The {@code
268  * originalType} field in the Descriptor for this attribute will have
269  * the value {@code "java.lang.management.MemoryUsage"}.
270  *
271  * <p>The format of this string is described in the section <a
272  * href="MXBean.html#type-names">Type Names</a> of the MXBean
273  * specification.</p>
274  *
275  * <tr id="setExceptions"><td><i>setExceptions</i><td>String[]</td>
276  * <td>MBeanAttributeInfo</td>
277  *
278  * <td>The class names of the exceptions that can be thrown when setting
279  * an attribute. The meaning of this field
280  * is defined by this specification but the field is not set or used by the
281  * JMX API itself.  Exceptions thrown when getting an attribute are specified
282  * by the field <a href="#exceptions">{@code exceptions}</a>.
283  *
284  * <tr><td>severity</td><td>String<br>Integer</td>
285  * <td>MBeanNotificationInfo</td>
286  *
287  * <td>The severity of this notification.  It can be 0 to mean
288  * unknown severity or a value from 1 to 6 representing decreasing
289  * levels of severity.  It can be represented as a decimal string or
290  * an {@code Integer}.</td>
291  *
292  * <tr><td>since</td><td>String</td><td>Any</td>
293  *
294  * <td>The version of the information model in which this element
295  * was introduced.  A set of MBeans defined by an application is
296  * collectively called an <em>information model</em>.  The
297  * application may also define versions of this model, and use the
298  * {@code "since"} field to record the version in which an element
299  * first appeared.</td>
300  *
301  * <tr><td>units</td><td>String</td>
302  * <td>MBeanAttributeInfo<br>MBeanParameterInfo<br>MBeanOperationInfo</td>
303  *
304  * <td>The units in which an attribute, parameter, or operation return
305  * value is measured, for example {@code "bytes"} or {@code
306  * "seconds"}.</td>
307  *
308  * </table>
309  *
310  * <p>Some additional fields are defined by Model MBeans.  See the
311  * information for <a href="modelmbean/ModelMBeanInfo.html#descriptor"><!--
312  * -->{@code ModelMBeanInfo}</a>,
313  * <a href="modelmbean/ModelMBeanAttributeInfo.html#descriptor"><!--
314  * -->{@code ModelMBeanAttributeInfo}</a>,
315  * <a href="modelmbean/ModelMBeanConstructorInfo.html#descriptor"><!--
316  * -->{@code ModelMBeanConstructorInfo}</a>,
317  * <a href="modelmbean/ModelMBeanNotificationInfo.html#descriptor"><!--
318  * -->{@code ModelMBeanNotificationInfo}</a>, and
319  * <a href="modelmbean/ModelMBeanOperationInfo.html#descriptor"><!--
320  * -->{@code ModelMBeanOperationInfo}</a>, as
321  * well as the chapter "Model MBeans" of the <a
322  * href="http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html">JMX
323  * Specification</a>.  The following table summarizes these fields.  Note
324  * that when the Type in this table is Number, a String that is the decimal
325  * representation of a Long can also be used.</p>
326  *
327  * <p>Nothing prevents the use of these fields in MBeans that are not Model
328  * MBeans.  The <a href="#displayName">displayName</a>, <a href="#severity"><!--
329  * -->severity</a>, and <a href="#visibility">visibility</a> fields are of
330  * interest outside Model MBeans, for example.  But only Model MBeans have
331  * a predefined behavior for these fields.</p>
332  *
333  * <table border="1" cellpadding="5" summary="ModelMBean Fields">
334  *
335  * <tr><th>Name</th><th>Type</th><th>Used in</th><th>Meaning</th></tr>
336  *
337  * <tr><td>class</td><td>String</td><td>ModelMBeanOperationInfo</td>
338  *     <td>Class where method is defined (fully qualified).</td></tr>
339  *
340  * <tr><td>currencyTimeLimit</td><td>Number</td>
341  *     <td>ModelMBeanInfo<br>ModelMBeanAttributeInfo<br>ModelMBeanOperationInfo</td>
342  *     <td>How long cached value is valid: &lt;0 never, =0 always,
343  *         &gt;0 seconds.</td></tr>
344  *
345  * <tr><td>default</td><td>Object</td><td>ModelMBeanAttributeInfo</td>
346  *     <td>Default value for attribute.</td></tr>
347  *
348  * <tr><td>descriptorType</td><td>String</td><td>Any</td>
349  *     <td>Type of descriptor, "mbean", "attribute", "constructor", "operation",
350  *         or "notification".</td></tr>
351  *
352  * <tr id="displayName"><td>displayName</td><td>String</td><td>Any</td>
353  *     <td>Human readable name of this item.</td></tr>
354  *
355  * <tr><td>export</td><td>String</td><td>ModelMBeanInfo</td>
356  *     <td>Name to be used to export/expose this MBean so that it is
357  *         findable by other JMX Agents.</td></tr>
358  *
359  * <tr><td>getMethod</td><td>String</td><td>ModelMBeanAttributeInfo</td>
360  *     <td>Name of operation descriptor for get method.</td></tr>
361  *
362  * <tr><td>lastUpdatedTimeStamp</td><td>Number</td>
363  *     <td>ModelMBeanAttributeInfo<br>ModelMBeanOperationInfo</td>
364  *     <td>When <a href="#value-field">value</a> was set.</td></tr>
365  *
366  * <tr><td>log</td><td>String</td><td>ModelMBeanInfo<br>ModelMBeanNotificationInfo</td>
367  *     <td>t or T: log all notifications, f or F: log no notifications.</td></tr>
368  *
369  * <tr><td>logFile</td><td>String</td><td>ModelMBeanInfo<br>ModelMBeanNotificationInfo</td>
370  *     <td>Fully qualified filename to log events to.</td></tr>
371  *
372  * <tr><td>messageID</td><td>String</td><td>ModelMBeanNotificationInfo</td>
373  *     <td>Unique key for message text (to allow translation, analysis).</td></tr>
374  *
375  * <tr><td>messageText</td><td>String</td><td>ModelMBeanNotificationInfo</td>
376  *     <td>Text of notification.</td></tr>
377  *
378  * <tr><td>name</td><td>String</td><td>Any</td>
379  *     <td>Name of this item.</td></tr>
380  *
381  * <tr><td>persistFile</td><td>String</td><td>ModelMBeanInfo</td>
382  *     <td>File name into which the MBean should be persisted.</td></tr>
383  *
384  * <tr><td>persistLocation</td><td>String</td><td>ModelMBeanInfo</td>
385  *     <td>The fully qualified directory name where the MBean should be
386  *         persisted (if appropriate).</td></tr>
387  *
388  * <tr><td>persistPeriod</td><td>Number</td>
389  *     <td>ModelMBeanInfo<br>ModelMBeanAttributeInfo</td>
390  *     <td>Frequency of persist cycle in seconds. Used when persistPolicy is
391  *         "OnTimer" or "NoMoreOftenThan".</td></tr>
392  *
393  * <tr><td>persistPolicy</td><td>String</td>
394  *     <td>ModelMBeanInfo<br>ModelMBeanAttributeInfo</td>
395  *     <td>One of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never.
396  *         See the section "MBean Descriptor Fields" in the JMX specification
397  *         document.</td></tr>
398  *
399  * <tr><td>presentationString</td><td>String</td><td>Any</td>
400  *     <td>XML formatted string to allow presentation of data.</td></tr>
401  *
402  * <tr><td>protocolMap</td><td>Descriptor</td><td>ModelMBeanAttributeInfo</td>
403  *     <td>See the section "Protocol Map Support" in the JMX specification
404  *         document.  Mappings must be appropriate for the attribute and entries
405  *         can be updated or augmented at runtime.</td></tr>
406  *
407  * <tr><td>role</td><td>String</td>
408  *     <td>ModelMBeanConstructorInfo<br>ModelMBeanOperationInfo</td>
409  *     <td>One of "constructor", "operation", "getter", or "setter".</td></tr>
410  *
411  * <tr><td>setMethod</td><td>String</td><td>ModelMBeanAttributeInfo</td>
412  *     <td>Name of operation descriptor for set method.</td></tr>
413  *
414  * <tr id="severity"><td>severity</td><td>Number</td>
415  *     <td>ModelMBeanNotificationInfo</td>
416  *     <td>0-6 where 0: unknown; 1: non-recoverable;
417  *         2: critical, failure; 3: major, severe;
418  *         4: minor, marginal, error; 5: warning;
419  *         6: normal, cleared, informative</td></tr>
420  *
421  * <tr><td>targetObject</td><td>Object</td><td>ModelMBeanOperationInfo</td>
422  *     <td>Object on which to execute this method.</td></tr>
423  *
424  * <tr><td>targetType</td><td>String</td><td>ModelMBeanOperationInfo</td>
425  *     <td>type of object reference for targetObject. Can be:
426  *         ObjectReference | Handle | EJBHandle | IOR | RMIReference.</td></tr>
427  *
428  * <tr id="value-field"><td>value</td><td>Object</td>
429  *     <td>ModelMBeanAttributeInfo<br>ModelMBeanOperationInfo</td>
430  *     <td>Current (cached) value for attribute or operation.</td></tr>
431  *
432  * <tr id="visibility"><td>visibility</td><td>Number</td><td>Any</td>
433  *     <td>1-4 where 1: always visible, 4: rarely visible.</td></tr>
434  *
435  * </table>
436  *
437  * @since 1.5
438  */
439 public interface Descriptor extends Serializable, Cloneable
440 {
441 
442     /**
443      * Returns the value for a specific field name, or null if no value
444      * is present for that name.
445      *
446      * @param fieldName the field name.
447      *
448      * @return the corresponding value, or null if the field is not present.
449      *
450      * @exception RuntimeOperationsException if the field name is illegal.
451      */
452     public Object getFieldValue(String fieldName)
453             throws RuntimeOperationsException;
454 
455     /**
456      * <p>Sets the value for a specific field name. This will
457      * modify an existing field or add a new field.</p>
458      *
459      * <p>The field value will be validated before it is set.
460      * If it is not valid, then an exception will be thrown.
461      * The meaning of validity is dependent on the descriptor
462      * implementation.</p>
463      *
464      * @param fieldName The field name to be set. Cannot be null or empty.
465      * @param fieldValue The field value to be set for the field
466      * name. Can be null if that is a valid value for the field.
467      *
468      * @exception RuntimeOperationsException if the field name or field value
469      * is illegal (wrapped exception is {@link IllegalArgumentException}); or
470      * if the descriptor is immutable (wrapped exception is
471      * {@link UnsupportedOperationException}).
472      */
473     public void setField(String fieldName, Object fieldValue)
474         throws RuntimeOperationsException;
475 
476 
477     /**
478      * Returns all of the fields contained in this descriptor as a string array.
479      *
480      * @return String array of fields in the format <i>fieldName=fieldValue</i>
481      * <br>If the value of a field is not a String, then the toString() method
482      * will be called on it and the returned value, enclosed in parentheses,
483      * used as the value for the field in the returned array. If the value
484      * of a field is null, then the value of the field in the returned array
485      * will be empty.  If the descriptor is empty, you will get
486      * an empty array.
487      *
488      * @see #setFields
489      */
490     public String[] getFields();
491 
492 
493     /**
494      * Returns all the field names in the descriptor.
495      *
496      * @return String array of field names. If the descriptor is empty,
497      * you will get an empty array.
498      */
499     public String[] getFieldNames();
500 
501     /**
502      * Returns all the field values in the descriptor as an array of Objects. The
503      * returned values are in the same order as the {@code fieldNames} String array parameter.
504      *
505      * @param fieldNames String array of the names of the fields that
506      * the values should be returned for.  If the array is empty then
507      * an empty array will be returned.  If the array is null then all
508      * values will be returned, as if the parameter were the array
509      * returned by {@link #getFieldNames()}.  If a field name in the
510      * array does not exist, including the case where it is null or
511      * the empty string, then null is returned for the matching array
512      * element being returned.
513      *
514      * @return Object array of field values. If the list of {@code fieldNames}
515      * is empty, you will get an empty array.
516      */
517     public Object[] getFieldValues(String... fieldNames);
518 
519     /**
520      * Removes a field from the descriptor.
521      *
522      * @param fieldName String name of the field to be removed.
523      * If the field name is illegal or the field is not found,
524      * no exception is thrown.
525      *
526      * @exception RuntimeOperationsException if a field of the given name
527      * exists and the descriptor is immutable.  The wrapped exception will
528      * be an {@link UnsupportedOperationException}.
529      */
530     public void removeField(String fieldName);
531 
532     /**
533      * <p>Sets all fields in the field names array to the new value with
534      * the same index in the field values array. Array sizes must match.</p>
535      *
536      * <p>The field value will be validated before it is set.
537      * If it is not valid, then an exception will be thrown.
538      * If the arrays are empty, then no change will take effect.</p>
539      *
540      * @param fieldNames String array of field names. The array and array
541      * elements cannot be null.
542      * @param fieldValues Object array of the corresponding field values.
543      * The array cannot be null. Elements of the array can be null.
544      *
545      * @throws RuntimeOperationsException if the change fails for any reason.
546      * Wrapped exception is {@link IllegalArgumentException} if
547      * {@code fieldNames} or {@code fieldValues} is null, or if
548      * the arrays are of different lengths, or if there is an
549      * illegal value in one of them.
550      * Wrapped exception is {@link UnsupportedOperationException}
551      * if the descriptor is immutable, and the call would change
552      * its contents.
553      *
554      * @see #getFields
555      */
556     public void setFields(String[] fieldNames, Object[] fieldValues)
557         throws RuntimeOperationsException;
558 
559 
560     /**
561      * <p>Returns a descriptor which is equal to this descriptor.
562      * Changes to the returned descriptor will have no effect on this
563      * descriptor, and vice versa.  If this descriptor is immutable,
564      * it may fulfill this condition by returning itself.</p>
565      * @exception RuntimeOperationsException for illegal value for field names
566      * or field values.
567      * If the descriptor construction fails for any reason, this exception will
568      * be thrown.
569      * @return A descriptor which is equal to this descriptor.
570      */
571     public Object clone() throws RuntimeOperationsException;
572 
573 
574     /**
575      * Returns true if all of the fields have legal values given their
576      * names.
577      *
578      * @return true if the values are legal.
579      *
580      * @exception RuntimeOperationsException If the validity checking fails for
581      * any reason, this exception will be thrown.
582      * The method returns false if the descriptor is not valid, but throws
583      * this exception if the attempt to determine validity fails.
584      */
585     public boolean isValid() throws RuntimeOperationsException;
586 
587     /**
588      * <p>Compares this descriptor to the given object.  The objects are equal if
589      * the given object is also a Descriptor, and if the two Descriptors have
590      * the same field names (possibly differing in case) and the same
591      * associated values.  The respective values for a field in the two
592      * Descriptors are equal if the following conditions hold:</p>
593      *
594      * <ul>
595      * <li>If one value is null then the other must be too.</li>
596      * <li>If one value is a primitive array then the other must be a primitive
597      * array of the same type with the same elements.</li>
598      * <li>If one value is an object array then the other must be too and
599      * {@link Arrays#deepEquals(Object[],Object[])} must return true.</li>
600      * <li>Otherwise {@link Object#equals(Object)} must return true.</li>
601      * </ul>
602      *
603      * @param obj the object to compare with.
604      *
605      * @return {@code true} if the objects are the same; {@code false}
606      * otherwise.
607      *
608      * @since 1.6
609      */
610     public boolean equals(Object obj);
611 
612     /**
613      * <p>Returns the hash code value for this descriptor.  The hash
614      * code is computed as the sum of the hash codes for each field in
615      * the descriptor.  The hash code of a field with name {@code n}
616      * and value {@code v} is {@code n.toLowerCase().hashCode() ^ h}.
617      * Here {@code h} is the hash code of {@code v}, computed as
618      * follows:</p>
619      *
620      * <ul>
621      * <li>If {@code v} is null then {@code h} is 0.</li>
622      * <li>If {@code v} is a primitive array then {@code h} is computed using
623      * the appropriate overloading of {@code java.util.Arrays.hashCode}.</li>
624      * <li>If {@code v} is an object array then {@code h} is computed using
625      * {@link Arrays#deepHashCode(Object[])}.</li>
626      * <li>Otherwise {@code h} is {@code v.hashCode()}.</li>
627      * </ul>
628      *
629      * @return A hash code value for this object.
630      *
631      * @since 1.6
632      */
633     public int hashCode();
634 }