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