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 MBeanAttributeInfo
.
Field names are not case-sensitive, but are case-preserving
(in that the same use of case will be returned by
getFields()
and getFieldNames()
).
The type of the value should match the type returned
by the getType()
method of the associated
Info
object. In the case of 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 ImmutableDescriptor
,
while mutable descriptors are usually instances or subclasses
of 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 | MBeanAttributeInfo ,
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 | MBeanAttributeInfo ,
MBeanNotificationInfo , MBeanOperationInfo |
Specifies whether the annotated element is currently enabled or
not, via a value of either "true" or "false" .
| |
immutableInfo | String | 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 | 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 | MBeanInfo |
The Java interface name associated with the bean, as returned
by Class.getName() . |
|
legalValues | Set> | MBeanAttributeInfo ,
MBeanParameterInfo | Legal values for an attribute or parameter. | |
maxValue | Object | MBeanAttributeInfo ,
MBeanParameterInfo | Maximum legal value for an attribute or parameter. | |
metricType | String | MBeanAttributeInfo ,
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 | MBeanAttributeInfo ,
MBeanParameterInfo | Minimum legal value for an attribute or parameter. | |
mxbean | String | MBeanInfo |
Specifies whether the annotated element is an MXBean or
not, via a value of either "true" or "false" .
| |
openType | OpenType |
MBeanAttributeInfo , MBeanOperationInfo | ,
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 MXBean s. |
|
originalType | String | MBeanAttributeInfo ,
MBeanOperationInfo , MBeanParameterInfo |
The original Java type of an element which has been converted
to another type according to the MXBean typing rules.
For example, 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 | 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 | MBeanAttributeInfo ,
MBeanOperationInfo , 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 javax.management.modelmbean.ModelMBeanInfo
.
Modifier and Type | Method and Description |
---|---|
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
name=value . |
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.
|
Object clone() throws RuntimeOperationsException
RuntimeOperationsException
- if creation of the new
descriptor fails for any
reason.boolean equals(Object obj)
Returns true if this descriptor is equivalent to the supplied object. This is true if the following holds:
Descriptor
.null
, the other must be.Object
array, the other
must be and Arrays.deepEquals(Object[],Object[])
must return true.Object.equals(Object)
must return true.equals
in class Object
obj
- the object to compare according to the above.Object.equals(Object)
,
Object.hashCode()
String[] getFieldNames()
String[] getFields()
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.Object.toString()
method,
and included as "(" + string + ")"
.If the descriptor is empty, an empty array is returned.
setFields(String[],Object[])
Object getFieldValue(String name)
null
if no value is present for the given field name.name
- the field name.null
if there
is no value present.RuntimeOperationsException
- if the field name is illegal.Object[] getFieldValues(String... names)
null
leads to behaviour equivalent to
getFields()
. Field values are obtained as specified
in 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.names
- an array of field names whose values should
be returned.getFields()
,
getFieldValue(String)
int hashCode()
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 Arrays
.v
is an Object
array, then the hash code is computed using the
Arrays.deepHashCode(Object[])
method.v.hashCode()
.
hashCode
in class Object
Object.equals(Object)
,
Object.hashCode()
boolean isValid() throws RuntimeOperationsException
RuntimeOperationsException
- if the validity check
fails for some reason.void removeField(String name)
name
- the name of the field to remove.RuntimeOperationsException
- if the field exists
and the descriptor is
immutable. This wraps
an UnsupportedOperationException
.void setField(String name, Object value) throws RuntimeOperationsException
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.RuntimeOperationsException
- if the name or value is
illegal (wrapping a
IllegalArgumentException
)
or if the descriptor is
immutable (wrapping a
UnsupportedOperationException
.void setFields(String[] names, Object[] values)
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.RuntimeOperationsException
- if the arrays differ in
length, or a name or value is
illegal (wrapping a
IllegalArgumentException
)
or if the descriptor is
immutable (wrapping a
UnsupportedOperationException
.setField(String,Object)