History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/javax/management/Descriptor.java (1 of 18352 files). Show all

Unified · Split

java/pkg/javax/management/Descriptor.java+634−0
@@ -0,0 +1,634 @@
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;
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">
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://java.sun.com/products/JavaManagement/download.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">
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+}