|
Java example source code file (Descriptor.java)
The Descriptor.java Java example source code
/*
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
* @author IBM Corp.
*
* Copyright IBM Corp. 1999-2000. All rights reserved.
*/
package javax.management;
import java.io.Serializable;
// Javadoc imports:
import java.lang.management.MemoryUsage;
import java.util.Arrays;
import java.util.Locale;
import java.util.ResourceBundle;
import javax.management.openmbean.CompositeData;
import javax.management.openmbean.OpenMBeanAttributeInfoSupport;
import javax.management.openmbean.OpenMBeanOperationInfoSupport;
import javax.management.openmbean.OpenMBeanParameterInfoSupport;
import javax.management.openmbean.OpenType;
/**
* <p>Additional metadata for a JMX element. A {@code Descriptor}
* is associated with a {@link MBeanInfo}, {@link MBeanAttributeInfo}, etc.
* It consists of a collection of fields. A field is a name and an
* associated value.</p>
*
* <p>Field names are not case-sensitive. The names {@code descriptorType},
* {@code descriptortype}, and {@code DESCRIPTORTYPE} are all equivalent.
* However, the case that was used when the field was first set is preserved
* in the result of the {@link #getFields} and {@link #getFieldNames}
* methods.</p>
*
* <p>Not all field names and values are predefined.
* New fields can be defined and added by any program.</p>
*
* <p>A descriptor can be mutable or immutable.
* An immutable descriptor, once created, never changes.
* The <code>Descriptor methods that could modify the contents
* of the descriptor will throw an exception
* for an immutable descriptor. Immutable descriptors are usually
* instances of {@link ImmutableDescriptor} or a subclass. Mutable
* descriptors are usually instances of
* {@link javax.management.modelmbean.DescriptorSupport} or a subclass.
*
* <p>Certain fields are used by the JMX implementation. This means
* either that the presence of the field may change the behavior of
* the JMX API or that the field may be set in descriptors returned by
* the JMX API. These fields appear in <i>italics in the table
* below, and each one has a corresponding constant in the {@link JMX}
* class. For example, the field {@code defaultValue} is represented
* by the constant {@link JMX#DEFAULT_VALUE_FIELD}.</p>
*
* <p>Certain other fields have conventional meanings described in the
* table below but they are not required to be understood or set by
* the JMX implementation.</p>
*
* <p>Field names defined by the JMX specification in this and all
* future versions will never contain a period (.). Users can safely
* create their own fields by including a period in the name and be
* sure that these names will not collide with any future version of
* the JMX API. It is recommended to follow the Java package naming
* convention to avoid collisions between field names from different
* origins. For example, a field created by {@code example.com} might
* have the name {@code com.example.interestLevel}.</p>
*
* <p>Note that the values in the {@code defaultValue}, {@code
* legalValues}, {@code maxValue}, and {@code minValue} fields should
* be consistent with the type returned by the {@code getType()}
* method for the associated {@code MBeanAttributeInfo} or {@code
* MBeanParameterInfo}. For MXBeans, this means that they should be
* of the mapped Java type, called <em>opendata(J) in the .
*
* <table border="1" cellpadding="5" summary="Descriptor Fields">
*
* <tr> | defaultValue | Object | * <td>MBeanAttributeInfodeprecated | String | Any | * * <td>An indication that this element of the information model is no * longer recommended for use. A set of MBeans defined by an * application is collectively called an <em>information model. * The convention is for the value of this field to contain a string * that is the version of the model in which the element was first * deprecated, followed by a space, followed by an explanation of the * deprecation, for example {@code "1.3 Replaced by the Capacity * attribute"}.</td> * * <tr>descriptionResource * BundleBaseName</td> | String | Any | * * <td>The base name for the {@link ResourceBundle} in which the key given in * the {@code descriptionResourceKey} field can be found, for example * {@code "com.example.myapp.MBeanResources"}. The meaning of this * field is defined by this specification but the field is not set or * used by the JMX API itself.</td> * * <tr>descriptionResourceKey | * <td>StringAny | * * <td>A resource key for the description of this element. In * conjunction with the {@code descriptionResourceBundleBaseName}, * this can be used to find a localized version of the description. * The meaning of this field is defined by this specification but the * field is not set or used by the JMX API itself.</td> * * <tr>enabled | String | * <td>MBeanAttributeInfoexceptions | String[] | * <td>MBeanAttributeInfo, MBeanConstructorInfo, MBeanOperationInfo * * <td>The class names of the exceptions that can be thrown when invoking a * constructor or operation, or getting an attribute. The meaning of this field * is defined by this specification but the field is not set or used by the * JMX API itself. Exceptions thrown when * setting an attribute are specified by the field * <a href="#setExceptions">{@code setExceptions}. * * <tr id="immutableInfo">immutableInfo | String | * <td>MBeanInfo * * <td>The string {@code "true"} or {@code "false"} according as this * MBean's MBeanInfo is <em>immutable. When this field is true, * the MBeanInfo for the given MBean is guaranteed not to change over * the lifetime of the MBean. Hence, a client can read it once and * cache the read value. When this field is false or absent, there is * no such guarantee, although that does not mean that the MBeanInfo * will necessarily change. See also the <a * href="MBeanInfo.html#info-changed">{@code "jmx.mbean.info.changed"}</a> * notification.</td> * * <tr id="infoTimeout">infoTimeout | String Long | MBeanInfo | * * <td>The time in milli-seconds that the MBeanInfo can reasonably be * expected to be unchanged. The value can be a {@code Long} or a * decimal string. This provides a hint from a DynamicMBean or any * MBean that does not define {@code immutableInfo} as {@code true} * that the MBeanInfo is not likely to change within this period and * therefore can be cached. When this field is missing or has the * value zero, it is not recommended to cache the MBeanInfo unless it * has the {@code immutableInfo} set to {@code true} or it has <a * href="MBeanInfo.html#info-changed">{@code "jmx.mbean.info.changed"}</a> in * its {@link MBeanNotificationInfo} array.</td> * * <tr id="interfaceClassName">interfaceClassName | * <td>StringMBeanInfo | * * <td>The Java interface name for a Standard MBean or MXBean, as * returned by {@link Class#getName()}. A Standard MBean or MXBean * registered directly in the MBean Server or created using the {@link * StandardMBean} class will have this field in its MBeanInfo * Descriptor.</td> * * <tr id="legalValues">legalValues | * <td>{@literal Set}MBeanAttributeInfo MBeanParameterInfo |
*
* <td>Legal values for an attribute or parameter. See
* {@link javax.management.openmbean}.</td>
*
* <tr id="locale">locale | * <td>StringAny | * * <td>The {@linkplain Locale locale} of the description in this * {@code MBeanInfo}, {@code MBeanAttributeInfo}, etc, as returned * by {@link Locale#toString()}.</td> * * <tr id="maxValue">maxValue | Object | * <td>MBeanAttributeInfometricType | String | * <td>MBeanAttributeInfominValue | Object | * <td>MBeanAttributeInfomxbean | String | * <td>MBeanInfo * * <td>The string {@code "true"} or {@code "false"} according as this * MBean is an {@link MXBean}. A Standard MBean or MXBean registered * directly with the MBean Server or created using the {@link * StandardMBean} class will have this field in its MBeanInfo * Descriptor.</td> * * <tr id="openType">openType | {@link OpenType} | * <td>MBeanAttributeInfooriginalType | String | * <td>MBeanAttributeInfosetExceptions | String[] | * <td>MBeanAttributeInfo * * <td>The class names of the exceptions that can be thrown when setting * an attribute. The meaning of this field * is defined by this specification but the field is not set or used by the * JMX API itself. Exceptions thrown when getting an attribute are specified * by the field <a href="#exceptions">{@code exceptions}. * * <tr>severity | String Integer |
* <td>MBeanNotificationInfo
*
* <td>The severity of this notification. It can be 0 to mean
* unknown severity or a value from 1 to 6 representing decreasing
* levels of severity. It can be represented as a decimal string or
* an {@code Integer}.</td>
*
* <tr>since | String | Any | * * <td>The version of the information model in which this element * was introduced. A set of MBeans defined by an application is * collectively called an <em>information model. The * application may also define versions of this model, and use the * {@code "since"} field to record the version in which an element * first appeared.</td> * * <tr>units | String | * <td>MBeanAttributeInfo