javax.management
接口 Descriptor

所有超级接口：

Cloneable, Serializable

所有已知实现类：

DescriptorSupport, ImmutableDescriptor

public interface Descriptor
     

      extends 
      Serializable, 
      Cloneable
     

JMX 元素的附加元数据。Descriptor 与 MBeanInfo、MBeanAttributeInfo 等关联。它由一个字段集合组成。字段由一个名称和一个关联值组成。

字段名称不区分大小写。名称 descriptorType、descriptortype 和 DESCRIPTORTYPE 都是等效的。但是，第一次设置字段时所使用的大小写将保留在 getFields() 和 getFieldNames() 方法的结果中。

并非所有的字段名称和值都可以预定义。任何程序都可以定义和添加新字段。

描述符可以是可变的，也可以是不可变的。不可变的描述符一旦创建就不能更改。对于不可变的描述符，可以修改描述符内容的 Descriptor 方法将抛出异常。不可变的描述符通常是 ImmutableDescriptor 或子类的实例。可变描述符通常是 DescriptorSupport 或子类的实例。

某些字段由 JMX 实现使用。这意味着这类字段的存在可以改变 JMX API 的行为，或者可以在 JMX API 返回的描述符中设置这类字段。这些字段在下表中将以斜体 形式出现，每个字段在 JMX 类中都有一个相应的常量。例如，字段 defaultValue 由常量 JMX.DEFAULT_VALUE_FIELD 表示。

在下表中描述了某些其他字段的常规含意，但 JMX 实现不必了解或设置它们。

在此版本或所有未来版本中由 JMX 规范定义的字段名称将永远不会包含句点 (.)。通过在名称中包含句点，用户可以安全地创建自己的字段，并能确保这些名称不会与任何将来的 JMX API 版本相冲突。建议遵循 Java 包命名约定以避免不同来源的字段名称发生冲突。例如，由 example.com 创建的字段可能有名称 com.example.interestLevel。

注意，defaultValue、legalValues、maxValue 和 minValue 字段中的值应该与对关联的 MBeanAttributeInfo 或 MBeanParameterInfo 调用 getType() 方法所返回的类型一致。对于 MXBean，这意味着它们应该属于映射的 Java 类型，该类型在 MXBean 类型映射规则中称作 opendata(J)。

某些附加字段由 Model MBean 定义。请参阅 ModelMBeanInfo 和相关的类，以及 JMX 规范中的 "Model MBean" 一章。

从以下版本开始：

1.5

getFieldValue

Object getFieldValue(String fieldName)
                     throws RuntimeOperationsException

返回指定字段名的值，如果该名称不存在任何值，则返回 null。

参数：

fieldName - 字段名称。

返回：

相应的值，如果字段不存在，则返回 null。

抛出：

RuntimeOperationsException - 如果字段名称不合法。

setField

void setField(String fieldName,
              Object fieldValue)
              throws RuntimeOperationsException

设置特定字段名的值。这将修改现有的字段或添加一个新字段。

设置前将验证该字段值。如果该值无效，则将抛出一个异常。有效性的含义依赖于描述符实现。

参数：

fieldName - 要设置的字段的名称。不能为 null 或空。

fieldValue - 针对该字段名称所设置的字段值。如果 null 是字段的有效值，则可以为 null。

抛出：

RuntimeOperationsException - 如果字段名或字段值不合法（包装的异常为 IllegalArgumentException）；或者描述符不可变（包装的异常为 UnsupportedOperationException）。

getFields

String[] getFields()

以 string 数组的形式返回此 descriptor 中所包含的所有字段。

返回：

各字段的 String 数组，格式为 fieldName=fieldValue。
如果字段值不是一个 String，则对该值调用 toString() 方法并将返回值（用圆括号括起来）用作所返回数组中字段的值。如果字段的值为 null，则返回数组中的字段值将为空。如果描述符为空，则将得到一个空数组。

另请参见：

setFields(java.lang.String[], java.lang.Object[])

getFieldNames

String[] getFieldNames()

返回描述符中的所有字段名。

返回：

字段名称的 String 数组。如果描述符为空，则将得到一个空数组。

getFieldValues

Object[] getFieldValues(String... fieldNames)

以 Object 数组的形式返回该 descriptor 中的所有字段值。返回值的顺序与 fieldNames String 数组参数的顺序相同。

参数：

fieldNames - 字段名称的 String 数组，应该返回这些字段的值。如果该数组为空，则将返回一个空数组。如果数组为 null，则将返回所有值，如同参数是 getFieldNames() 返回的数组一样。如果数组中某个字段名不存在（包括字段名为 null 或空字符串的情况），则对于要返回的匹配数组元素，将返回 null。

返回：

字段值的 Object 数组。如果 fieldNames 列表为空，则将得到一个空数组。

removeField

void removeField(String fieldName)

从该 descriptor 中删除字段。

参数：

fieldName - 要移除的字段的 String 名称。如果字段名不合法或找不到字段，则不抛出任何异常。

抛出：

RuntimeOperationsException - 如果存在给定名称的字段且描述符不可变。包装的异常将是一个 UnsupportedOperationException。

setFields

void setFields(String[] fieldNames,
               Object[] fieldValues)
               throws RuntimeOperationsException

将字段名称数组中的所有字段设置为与字段值数组中的索引相同的新值。数组大小必须是匹配的。

设置前将验证该字段值。如果该值无效，则将抛出一个异常。如果数组为空，则所有更改都将无效。

参数：

fieldNames - 字段名称的 String 数组。数组和数组元素不能为 null。

fieldValues - 对应字段值的 Object 数组。数组不能为 null。数组的元素可以为 null。

抛出：

RuntimeOperationsException - 如果由于某种原因更改失败。如果 fieldNames 或 fieldValues 为 null，或者数组的长度不同，或者其中一个数组存在非法值，则包装的异常为 IllegalArgumentException。如果描述符不可变，且调用将更改其内容，则包装的异常为 UnsupportedOperationException。

另请参见：

getFields()

clone

Object clone()
             throws RuntimeOperationsException

返回一个与此描述符相等的描述符。对返回的描述符进行的更改不影响此描述符，反之亦然。如果此描述符不可变，则将通过返回其本身来完成此条件。

返回：

一个与此描述符相等的描述符。

抛出：

RuntimeOperationsException - 如果字段名或字段值为非法值。如果描述符构造由于任何原因而失败，都将抛出此异常。

isValid

boolean isValid()
                throws RuntimeOperationsException

如果所有字段在给定其名称的情况下都有合法值，则返回 true。

返回：

如果值是合法的，则返回 true。

抛出：

RuntimeOperationsException - 如果有效性检查由于任何原因而失败，都将抛出此异常。如果描述符无效，则该方法返回 false，但如果确定有效性的尝试失败，则将抛出此异常。

equals

boolean equals(Object obj)

将此描述符与给定对象比较。如果给定对象也是一个 Descriptor，并且如果两个 Descriptor 具有相同的字段名（可能有不同的情况）且有相同的关联值，则对象相等。如果具备下列条件，则两个 Descriptor 中字段的各个值都相等：

• 如果一个值为 null，则其他值也必须为 null。
• 如果一个值是基本类型数组，则其他值必须是同一类型的基本类型数组，且具有相同的元素。
• 如果一个值是对象数组，则其他值也必须是对象数组，并且 Arrays.deepEquals(Object[],Object[]) 必须返回 true。
• 其他情况下，Object.equals(Object) 必须返回 true。

覆盖：

类 Object 中的 equals

参数：

obj - 要与之比较的对象。

返回：

如果对象相等，则返回 true；否则，返回 false。

从以下版本开始：

1.6

另请参见：

Object.hashCode(), Hashtable

hashCode

int hashCode()

返回此描述符的哈希码值。该哈希码是描述符中每个字段的哈希码的总和。具有名称 n 和值 v 的字段的哈希码是 n.toLowerCase().hashCode() ^ h。此处 h 是 v 的哈希码，计算方式如下：

• 如果 v 为 null，则 h 为 0。
• 如果 v 是基本类型数组，则使用 java.util.Arrays.hashCode 的适当重载形式计算 h。
• 如果 v 是对象数组，则使用 Arrays.deepHashCode(Object[]) 计算 h。
• 否则，h 为 v.hashCode()。

覆盖：

类 Object 中的 hashCode

返回：

此对象的哈希码值。

从以下版本开始：

1.6

另请参见：

Object.equals(java.lang.Object), Hashtable