Descriptor.java revision 406
0N/A * Portions Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 0N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * Copyright IBM Corp. 1999-2000. All rights reserved. 0N/A * <p>Additional metadata for a JMX element. A {@code Descriptor} 0N/A * is associated with a {@link MBeanInfo}, {@link MBeanAttributeInfo}, etc. 0N/A * It consists of a collection of fields. A field is a name and an 0N/A * associated value.</p> 0N/A * <p>Field names are not case-sensitive. The names {@code descriptorType}, 0N/A * {@code descriptortype}, and {@code DESCRIPTORTYPE} are all equivalent. 0N/A * However, the case that was used when the field was first set is preserved 0N/A * in the result of the {@link #getFields} and {@link #getFieldNames} 0N/A * <p>Not all field names and values are predefined. 0N/A * New fields can be defined and added by any program.</p> 0N/A * <p>A descriptor can be mutable or immutable. 0N/A * An immutable descriptor, once created, never changes. 0N/A * The <code>Descriptor</code> methods that could modify the contents 0N/A * of the descriptor will throw an exception 0N/A * for an immutable descriptor. Immutable descriptors are usually 0N/A * instances of {@link ImmutableDescriptor} or a subclass. Mutable 0N/A * descriptors are usually instances of 0N/A * {@link javax.management.modelmbean.DescriptorSupport} or a subclass. 0N/A * <p>Certain fields are used by the JMX implementation. This means 0N/A * either that the presence of the field may change the behavior of 0N/A * the JMX API or that the field may be set in descriptors returned by 0N/A * the JMX API. These fields appear in <i>italics</i> in the table 0N/A * below, and each one has a corresponding constant in the {@link JMX} 0N/A * class. For example, the field {@code defaultValue} is represented 0N/A * by the constant {@link JMX#DEFAULT_VALUE_FIELD}.</p> 0N/A * <p>Certain other fields have conventional meanings described in the 0N/A * table below but they are not required to be understood or set by 0N/A * the JMX implementation.</p> 0N/A * <p>Field names defined by the JMX specification in this and all 0N/A * future versions will never contain a period (.). Users can safely 0N/A * create their own fields by including a period in the name and be 0N/A * sure that these names will not collide with any future version of 0N/A * the JMX API. It is recommended to follow the Java package naming 0N/A * convention to avoid collisions between field names from different 0N/A * origins. For example, a field created by {@code example.com} might 0N/A * have the name {@code com.example.interestLevel}.</p> 0N/A * <p>Note that the values in the {@code defaultValue}, {@code 0N/A * legalValues}, {@code maxValue}, and {@code minValue} fields should 0N/A * be consistent with the type returned by the {@code getType()} 0N/A * method for the associated {@code MBeanAttributeInfo} or {@code 0N/A * MBeanParameterInfo}. For MXBeans, this means that they should be 0N/A * of the mapped Java type, called <em>opendata</em>(J) in the <a 0N/A * <table border="1" cellpadding="5"> 0N/A * <tr><th>Name</th><th>Type</th><th>Used in</th><th>Meaning</th></tr> 0N/A * <tr><td><a name="defaultValue"><i>defaultValue</i></a><td>Object</td> 0N/A * <td>MBeanAttributeInfo<br>MBeanParameterInfo</td> 0N/A * <td>Default value for an attribute or parameter. See 0N/A * {@link javax.management.openmbean}.</td> 0N/A * <tr><td>deprecated</td><td>String</td><td>Any</td> 0N/A * <td>An indication that this element of the information model is no 0N/A * longer recommended for use. A set of MBeans defined by an 0N/A * application is collectively called an <em>information model</em>. 0N/A * The convention is for the value of this field to contain a string 0N/A * that is the version of the model in which the element was first 0N/A * deprecated, followed by a space, followed by an explanation of the 0N/A * deprecation, for example {@code "1.3 Replaced by the Capacity 406N/A * <tr id="descriptionResourceBundleBaseName"> 406N/A * <td>descriptionResource<br>BundleBaseName</td><td>String</td><td>Any</td> 0N/A * <td>The base name for the {@link ResourceBundle} in which the key given in 0N/A * the {@code descriptionResourceKey} field can be found, for example 406N/A * {@code "com.example.myapp.MBeanResources"}.</td> 406N/A * <tr id="descriptionResourceKey"> 406N/A * <td>descriptionResourceKey</td><td>String</td><td>Any</td> 0N/A * <td>A resource key for the description of this element. In 0N/A * conjunction with the {@code descriptionResourceBundleBaseName}, 406N/A * this can be used to find a localized version of the description.</td> 0N/A * <tr><td>enabled</td><td>String</td> 0N/A * <td>MBeanAttributeInfo<br>MBeanNotificationInfo<br>MBeanOperationInfo</td> 0N/A * <td>The string {@code "true"} or {@code "false"} according as this 0N/A * item is enabled. When an attribute or operation is not enabled, it 0N/A * exists but cannot currently be accessed. A user interface might 0N/A * present it as a greyed-out item. For example, an attribute might 0N/A * only be meaningful after the {@code start()} method of an MBean has 0N/A * been called, and is otherwise disabled. Likewise, a notification 0N/A * might be disabled if it cannot currently be emitted but could be in 0N/A * other circumstances.</td> 0N/A * <tr><td><a name="immutableInfo"><i>immutableInfo</i></a><td>String</td> 0N/A * <td>MBeanInfo</td> 0N/A * <td>The string {@code "true"} or {@code "false"} according as this 0N/A * MBean's MBeanInfo is <em>immutable</em>. When this field is true, 0N/A * the MBeanInfo for the given MBean is guaranteed not to change over 0N/A * the lifetime of the MBean. Hence, a client can read it once and 0N/A * cache the read value. When this field is false or absent, there is 0N/A * no such guarantee, although that does not mean that the MBeanInfo 0N/A * will necessarily change.</td> 0N/A * <tr><td>infoTimeout</td><td>String<br>Long</td><td>MBeanInfo</td> 0N/A * <td>The time in milli-seconds that the MBeanInfo can reasonably be 0N/A * expected to be unchanged. The value can be a {@code Long} or a 0N/A * decimal string. This provides a hint from a DynamicMBean or any 0N/A * MBean that does not define {@code immutableInfo} as {@code true} 0N/A * that the MBeanInfo is not likely to change within this period and 0N/A * therefore can be cached. When this field is missing or has the 0N/A * value zero, it is not recommended to cache the MBeanInfo unless it 0N/A * has the {@code immutableInfo} set to {@code true}.</td></tr> 0N/A * <tr><td><a name="interfaceClassName"><i>interfaceClassName</i></a></td> 0N/A * <td>String</td><td>MBeanInfo</td> 0N/A * <td>The Java interface name for a Standard MBean or MXBean, as 0N/A * returned by {@link Class#getName()}. A Standard MBean or MXBean 0N/A * registered directly in the MBean Server or created using the {@link 0N/A * StandardMBean} class will have this field in its MBeanInfo 0N/A * <tr><td><a name="legalValues"><i>legalValues</i></a></td> 0N/A * <td>{@literal Set<?>}</td><td>MBeanAttributeInfo<br>MBeanParameterInfo</td> 0N/A * <td>Legal values for an attribute or parameter. See 0N/A * {@link javax.management.openmbean}.</td> 0N/A * <tr><td><a name="maxValue"><i>maxValue</i></a><td>Object</td> 0N/A * <td>MBeanAttributeInfo<br>MBeanParameterInfo</td> 0N/A * <td>Maximum legal value for an attribute or parameter. See 0N/A * {@link javax.management.openmbean}.</td> 0N/A * <tr><td><a name="metricType">metricType</a><td>String</td> 0N/A * <td>MBeanAttributeInfo<br>MBeanOperationInfo</td> 0N/A * <td>The type of a metric, one of the strings "counter" or "gauge". 0N/A * A metric is a measurement exported by an MBean, usually an 0N/A * attribute but sometimes the result of an operation. A metric that 0N/A * is a <em>counter</em> has a value that never decreases except by 0N/A * being reset to a starting value. Counter metrics are almost always 0N/A * non-negative integers. An example might be the number of requests 0N/A * received. A metric that is a <em>gauge</em> has a numeric value 0N/A * that can increase or decrease. Examples might be the number of 0N/A * open connections or a cache hit rate or a temperature reading. 0N/A * <tr><td><a name="minValue"><i>minValue</i></a><td>Object</td> 0N/A * <td>MBeanAttributeInfo<br>MBeanParameterInfo</td> 0N/A * <td>Minimum legal value for an attribute or parameter. See 0N/A * {@link javax.management.openmbean}.</td> 0N/A * <tr><td><a name="mxbean"><i>mxbean</i></a><td>String</td> 0N/A * <td>MBeanInfo</td> 0N/A * <td>The string {@code "true"} or {@code "false"} according as this 0N/A * MBean is an {@link MXBean}. A Standard MBean or MXBean registered 0N/A * directly with the MBean Server or created using the {@link 0N/A * StandardMBean} class will have this field in its MBeanInfo 406N/A * <tr><td id="mxbeanMappingFactoryClass"><i>mxbeanMappingFactoryClass</i> 406N/A * <td>The name of the {@link MXBeanMappingFactory} class that was used for this 406N/A * MXBean, if it was not the {@linkplain MXBeanMappingFactory#DEFAULT default} 0N/A * <tr><td><a name="openType"><i>openType</i></a><td>{@link OpenType}</td> 0N/A * <td>MBeanAttributeInfo<br>MBeanOperationInfo<br>MBeanParameterInfo</td> 0N/A * <td><p>The Open Type of this element. In the case of {@code 0N/A * MBeanAttributeInfo} and {@code MBeanParameterInfo}, this is the 0N/A * Open Type of the attribute or parameter. In the case of {@code 0N/A * MBeanOperationInfo}, it is the Open Type of the return value. This 0N/A * field is set in the Descriptor for all instances of {@link 0N/A * OpenMBeanAttributeInfoSupport}, {@link 0N/A * OpenMBeanOperationInfoSupport}, and {@link 0N/A * OpenMBeanParameterInfoSupport}. It is also set for attributes, 0N/A * operations, and parameters of MXBeans.</p> 0N/A * <p>This field can be set for an {@code MBeanNotificationInfo}, in 0N/A * which case it indicates the Open Type that the {@link 0N/A * Notification#getUserData() user data} will have.</td> 0N/A * <tr><td><a name="originalType"><i>originalType</i></a><td>String</td> 0N/A * <td>MBeanAttributeInfo<br>MBeanOperationInfo<br>MBeanParameterInfo</td> 0N/A * <td><p>The original Java type of this element as it appeared in the 0N/A * {@link MXBean} interface method that produced this {@code 0N/A * MBeanAttributeInfo} (etc). For example, a method<br> <code>public 0N/A * </code> {@link MemoryUsage}<code> getHeapMemoryUsage();</code><br> 0N/A * in an MXBean interface defines an attribute called {@code 0N/A * HeapMemoryUsage} of type {@link CompositeData}. The {@code 0N/A * originalType} field in the Descriptor for this attribute will have 0N/A * the value {@code "java.lang.management.MemoryUsage"}. 0N/A * <p>The format of this string is described in the section <a 0N/A * specification.</p> 0N/A * <tr><td>severity</td><td>String<br>Integer</td> 0N/A * <td>MBeanNotificationInfo</td> 0N/A * <td>The severity of this notification. It can be 0 to mean 0N/A * unknown severity or a value from 1 to 6 representing decreasing 0N/A * levels of severity. It can be represented as a decimal string or 0N/A * an {@code Integer}.</td> 0N/A * <tr><td>since</td><td>String</td><td>Any</td> 0N/A * <td>The version of the information model in which this element 0N/A * was introduced. A set of MBeans defined by an application is 0N/A * collectively called an <em>information model</em>. The 0N/A * application may also define versions of this model, and use the 0N/A * {@code "since"} field to record the version in which an element 0N/A * first appeared.</td> 0N/A * <tr><td>units</td><td>String</td> 0N/A * <td>MBeanAttributeInfo<br>MBeanParameterInfo<br>MBeanOperationInfo</td> 0N/A * <td>The units in which an attribute, parameter, or operation return 0N/A * value is measured, for example {@code "bytes"} or {@code 0N/A * <p>Some additional fields are defined by Model MBeans. See 0N/A * {@link javax.management.modelmbean.ModelMBeanInfo ModelMBeanInfo} 0N/A * and related classes and the chapter "Model MBeans" of the 0N/A * JMX Specification</a>.</p> 0N/A * Returns the value for a specific field name, or null if no value 0N/A * is present for that name. 0N/A * @param fieldName the field name. 0N/A * @return the corresponding value, or null if the field is not present. 0N/A * @exception RuntimeOperationsException if the field name is illegal. 0N/A * <p>Sets the value for a specific field name. This will 0N/A * modify an existing field or add a new field.</p> 0N/A * <p>The field value will be validated before it is set. 0N/A * If it is not valid, then an exception will be thrown. 0N/A * The meaning of validity is dependent on the descriptor 0N/A * implementation.</p> 0N/A * @param fieldName The field name to be set. Cannot be null or empty. 0N/A * @param fieldValue The field value to be set for the field 0N/A * name. Can be null if that is a valid value for the field. 0N/A * @exception RuntimeOperationsException if the field name or field value 0N/A * is illegal (wrapped exception is {@link IllegalArgumentException}); or 0N/A * if the descriptor is immutable (wrapped exception is 0N/A * {@link UnsupportedOperationException}). 0N/A * Returns all of the fields contained in this descriptor as a string array. 0N/A * @return String array of fields in the format <i>fieldName=fieldValue</i> 0N/A * <br>If the value of a field is not a String, then the toString() method 0N/A * will be called on it and the returned value, enclosed in parentheses, 0N/A * used as the value for the field in the returned array. If the value 0N/A * of a field is null, then the value of the field in the returned array 0N/A * will be empty. If the descriptor is empty, you will get 0N/A * Returns all the field names in the descriptor. 0N/A * @return String array of field names. If the descriptor is empty, 0N/A * you will get an empty array. 0N/A * Returns all the field values in the descriptor as an array of Objects. The 0N/A * returned values are in the same order as the {@code fieldNames} String array parameter. 0N/A * @param fieldNames String array of the names of the fields that 0N/A * the values should be returned for. If the array is empty then 0N/A * an empty array will be returned. If the array is null then all 0N/A * values will be returned, as if the parameter were the array 0N/A * returned by {@link #getFieldNames()}. If a field name in the 0N/A * array does not exist, including the case where it is null or 0N/A * the empty string, then null is returned for the matching array 0N/A * element being returned. 0N/A * @return Object array of field values. If the list of {@code fieldNames} 0N/A * is empty, you will get an empty array. 0N/A * Removes a field from the descriptor. 0N/A * @param fieldName String name of the field to be removed. 0N/A * If the field name is illegal or the field is not found, 0N/A * no exception is thrown. 0N/A * @exception RuntimeOperationsException if a field of the given name 0N/A * exists and the descriptor is immutable. The wrapped exception will 0N/A * be an {@link UnsupportedOperationException}. 0N/A * <p>Sets all fields in the field names array to the new value with 0N/A * the same index in the field values array. Array sizes must match.</p> 0N/A * <p>The field value will be validated before it is set. 0N/A * If it is not valid, then an exception will be thrown. 0N/A * If the arrays are empty, then no change will take effect.</p> 0N/A * @param fieldNames String array of field names. The array and array 0N/A * elements cannot be null. 0N/A * @param fieldValues Object array of the corresponding field values. 0N/A * The array cannot be null. Elements of the array can be null. 0N/A * @throws RuntimeOperationsException if the change fails for any reason. 0N/A * Wrapped exception is {@link IllegalArgumentException} if 0N/A * {@code fieldNames} or {@code fieldValues} is null, or if 0N/A * the arrays are of different lengths, or if there is an 0N/A * illegal value in one of them. 0N/A * Wrapped exception is {@link UnsupportedOperationException} 0N/A * if the descriptor is immutable, and the call would change 0N/A * <p>Returns a descriptor which is equal to this descriptor. 0N/A * Changes to the returned descriptor will have no effect on this 0N/A * descriptor, and vice versa. If this descriptor is immutable, 0N/A * it may fulfill this condition by returning itself.</p> 0N/A * @exception RuntimeOperationsException for illegal value for field names 0N/A * If the descriptor construction fails for any reason, this exception will 0N/A * @return A descriptor which is equal to this descriptor. 0N/A * Returns true if all of the fields have legal values given their 0N/A * @return true if the values are legal. 0N/A * @exception RuntimeOperationsException If the validity checking fails for 0N/A * any reason, this exception will be thrown. 0N/A * The method returns false if the descriptor is not valid, but throws 0N/A * this exception if the attempt to determine validity fails. 0N/A * Compares this descriptor to the given object. The objects are equal if 0N/A * the given object is also a Descriptor, and if the two Descriptors have 0N/A * the same field names (possibly differing in case) and the same 0N/A * associated values. The respective values for a field in the two 0N/A * Descriptors are equal if the following conditions hold:</p> 0N/A * <li>If one value is null then the other must be too.</li> 0N/A * <li>If one value is a primitive array then the other must be a primitive 0N/A * array of the same type with the same elements.</li> 0N/A * <li>If one value is an object array then the other must be too and 0N/A * {@link Arrays#deepEquals(Object[],Object[])} must return true.</li> 0N/A * <li>Otherwise {@link Object#equals(Object)} must return true.</li> 0N/A * @param obj the object to compare with. 0N/A * @return {@code true} if the objects are the same; {@code false} 0N/A * <p>Returns the hash code value for this descriptor. The hash 0N/A * code is computed as the sum of the hash codes for each field in 0N/A * the descriptor. The hash code of a field with name {@code n} 0N/A * and value {@code v} is {@code n.toLowerCase().hashCode() ^ h}. 0N/A * Here {@code h} is the hash code of {@code v}, computed as 0N/A * <li>If {@code v} is null then {@code h} is 0.</li> 0N/A * <li>If {@code v} is a primitive array then {@code h} is computed using 0N/A * the appropriate overloading of {@code java.util.Arrays.hashCode}.</li> 0N/A * <li>If {@code v} is an object array then {@code h} is computed using 0N/A * {@link Arrays#deepHashCode(Object[])}.</li> 0N/A * <li>Otherwise {@code h} is {@code v.hashCode()}.</li> 0N/A * @return A hash code value for this object.