javax.management
public interface Descriptor extends Serializable, Cloneable
Provides metadata for a management element as a series
of fields, formed from name-value pairs. Descriptors
are usually attached to one of the Info
classes, such as {@link MBeanAttributeInfo}.
Field names are not case-sensitive, but are case-preserving
(in that the same use of case will be returned by
{@link #getFields()} and {@link #getFieldNames()}).
The type of the value should match the type returned
by the getType() method of the associated
Info object. In the case of {@link MXBean}s,
this should be the mapped type returned by the mapping rules.
The contents of a descriptor may be immutable, in which case, attempts to change the contents of the descriptor will cause an exception to be thrown. Immutable descriptors are usually instances or subclasses of {@link ImmutableDescriptor}, while mutable descriptors are usually instances or subclasses of {@link javax.management.modelmbean.DescriptorSupport}.
A series of field names are predefined, but additional
ones can be added as needed. Predefined names never include
a period ('.'), and so additional names may safely avoid
conflicts by including this character. It is recommended that
additional names make use of the same syntax as Java package
names e.g. gnu.classpath.ImportantMetadata.
The predefined names are as follows:
| Name | Type | Used In | Meaning | |
| defaultValue | Object | {@link MBeanAttributeInfo}, {@link MBeanParameterInfo} | Default value for an attribute or parameter. | |
| deprecated | String | Any | The annotated element has been deprecated. Conventially, the field's value takes the form of the version in which the element was deprecated, followed by an explaination. | |
| descriptionResourceBundleBaseName | String | Any | The base name for the bundle in which the descriptionResourceKey
can be found. |
|
| descriptionResourceKey | String | Any | The name of the resource key which contains a localized description of this element. | |
| enabled | String | {@link MBeanAttributeInfo}, {@link MBeanNotificationInfo}, {@link MBeanOperationInfo} | Specifies whether the annotated element is currently enabled or
not, via a value of either "true" or "false".
| |
| immutableInfo | String | {@link MBeanInfo} | If the value of this field is "true", this means that
the annotated element will not change and thus may be cached. |
|
| infoTimeout | String or Long | {@link MBeanInfo} | If this field is present, and non-zero, it will contain a value in milliseconds for which the value of the annotated element will remain unchanged, allowing it to be safely cached for that period. | |
| interfaceClassName | String | {@link MBeanInfo} | The Java interface name associated with the bean, as returned by {@link Class#getName()}. | |
| legalValues | Set | {@link MBeanAttributeInfo}, {@link MBeanParameterInfo} | Legal values for an attribute or parameter. | |
| maxValue | Object | {@link MBeanAttributeInfo}, {@link MBeanParameterInfo} | Maximum legal value for an attribute or parameter. | |
| metricType | String | {@link MBeanAttributeInfo}, {@link MBeanOperationInfo} | Specifies the type of metric represented
by the annotated element. This will be either "counter"
(an increasing value, which will only be reset and never decrease)
or "gauge" (an increasing and decreasing value). |
|
| minValue | Object | {@link MBeanAttributeInfo}, {@link MBeanParameterInfo} | Minimum legal value for an attribute or parameter. | |
| mxbean | String | {@link MBeanInfo} | Specifies whether the annotated element is an {@link MXBean} or
not, via a value of either "true" or "false".
| |
| openType | {@link javax.management.openmbean.OpenType} | {@link MBeanAttributeInfo}, {@link MBeanOperationInfo} | , {@link MBeanNotificationInfo}, {@link MBeanParameterInfo}Specifies the open type of the attribute or parameter, the return
value of the operation or the user data of the notification respectively.
This is present on Open*Info instances and for {@link MXBean}s. |
|
| originalType | String | {@link MBeanAttributeInfo}, {@link MBeanOperationInfo}, {@link MBeanParameterInfo} | The original Java type of an element which has been converted
to another type according to the {@link MXBean} typing rules.
For example, {@link java.lang.management.MemoryType} becomes a
String after conversion. This field would contain
"java.lang.management.MemoryType" to represent the
earlier type of an element with the converted type. |
|
| severity | Integer or String | {@link MBeanNotificationInfo} | Represents the severity of the notification, ranging from 1 (most severe) to 6 (least severe), with 0 representing unknown severity. | |
| since | String | Any | The version in which this field was introduced. | |
| units | String | {@link MBeanAttributeInfo}, {@link MBeanOperationInfo}, {@link MBeanParameterInfo} | The units used by the value of an attribute or parameter,
or the return value of an operation, such as "bytes",
"milliseconds" or "kilogrammes".
|
Some names are also defined as part of the Model MBeans package. See {@link javax.management.modelmbean.ModelMBeanInfo}.
Since: 1.5
| Method Summary | |
|---|---|
| Object | clone()
Returns a clone of this descriptor, which can then be modified
independently of this descriptor. |
| boolean | equals(Object obj) Returns true if this descriptor is equivalent to the supplied object. |
| String[] | getFieldNames()
Returns the field names of the descriptor. |
| String[] | getFields()
Returns all the field name and value pairs, in the
form |
| Object | getFieldValue(String name)
Returns the value of the specified field, or null
if no value is present for the given field name.
|
| Object[] | getFieldValues(String... names)
Returns the values corresponding to the fields named in
the specified array, in the same order. |
| int | hashCode() Returns the hash code of the descriptor. |
| boolean | isValid()
Returns true if all the fields have legal values, given
their names. |
| void | removeField(String name)
Removes a field from the descriptor. |
| void | setField(String name, Object value)
Attempts to set the specified field to the supplied
value. |
| void | setFields(String[] names, Object[] values)
Sets the field named in the first array to the corresponding
value specified in the second. |
Returns: a clone of this descriptor.
Throws: RuntimeOperationsException if creation of the new descriptor fails for any reason.
Returns true if this descriptor is equivalent to the supplied object. This is true if the following holds:
null, the other must be.Parameters: obj the object to compare according to the above.
Returns: true if the above holds.
Since: 1.6
Returns: the field names as an array of Strings.
Returns all the field name and value pairs, in the
form name=value. The value is converted
to a String as follows:
null, the printed
value will be empty."(" + string + ")".If the descriptor is empty, an empty array is returned.
Returns: the field names and values as an array of Strings.
See Also: (String[],Object[])
null
if no value is present for the given field name.
Parameters: name the field name.
Returns: the value of the field, or null if there
is no value present.
Throws: RuntimeOperationsException if the field name is illegal.
null leads to behaviour equivalent to
{@link #getFields()}. Field values are obtained as specified
in {@link #getFieldValue(String)}, with null
being returned if the field is not present. This applies
even if the given field name is null or
the empty string.
Parameters: names an array of field names whose values should be returned.
Returns: the values of the specified fields.
See Also: getFields getFieldValue
Returns the hash code of the descriptor. The hashcode
is computed as the sum of the hashcodes for each field,
which in turn is calculated as the sum of
the hashcode of the name, n, computed
using n.toLowerCase().hashCode(), and the
hashcode of the value, v, computed
using:
v is null, then the
hash code is 0.v is a primitive array, then the
hash code is computed using the appropriate method
from {@link java.util.Arrays}.v is an {@link java.lang.Object}
array, then the hash code is computed using the
{@link java.util.Arrays#deepHashCode(Object[])} method.v.hashCode().
Returns: a hashcode for this descriptor.
Since: 1.6
Returns: true if the values are legal.
Throws: RuntimeOperationsException if the validity check fails for some reason.
Parameters: name the name of the field to remove.
Throws: RuntimeOperationsException if the field exists and the descriptor is immutable. This wraps an {@link UnsupportedOperationException}.
Parameters: name the field to set. Can not be null
or empty. value the value to use, the validity of which is
determined by the implementation.
Throws: RuntimeOperationsException if the name or value is illegal (wrapping a {@link IllegalArgumentException}) or if the descriptor is immutable (wrapping a {@link UnsupportedOperationException}.
Parameters: names the names of the fields to change. Neither
the array or its elements may be null. values the values to use. The array must not be
null. The value of the elements
depends on the validity constraints of the
implementation.
Throws: RuntimeOperationsException if the arrays differ in length, or a name or value is illegal (wrapping a {@link IllegalArgumentException}) or if the descriptor is immutable (wrapping a {@link UnsupportedOperationException}.
See Also: setField