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)。

名称	类型	使用范围	含义
defaultValue	Object	MBeanAttributeInfo MBeanParameterInfo	属性或参数的默认值。请参阅 javax.management.openmbean。
deprecated	String	所有	建议不再使用此信息模型元素的指示。应用程序定义的一组 MBean 总称为信息模型。此字段值的惯例是包含一个字符串，该字符串中首先是元素第一次被废弃时的模型版本，后跟空格，然后是对废弃的解释，例如 "1.3 Replaced by the Capacity attribute"。
descriptionResource BundleBaseName	String	所有	ResourceBundle 的基本名称，可以在该 ResourceBundle 中找到在 descriptionResourceKey 字段中给定的键，例如 "com.example.myapp.MBeanResources"。此字段的含义由此规范定义，但 JMX API 本身不会设置或使用该字段。
descriptionResourceKey	String	所有	描述此元素的资源键。它可以与 descriptionResourceBundleBaseName 一起使用来查找描述的本地化版本。此字段的含义由此规范定义，但 JMX API 本身不会设置或使用该字段。
enabled	String	MBeanAttributeInfo MBeanNotificationInfo MBeanOperationInfo	根据此项启用与否，决定字符串为 "true" 或 "false"。不启用属性或操作时，它仍存在，但当前无法访问。用户界面可能将其表示为灰色项。例如，只有调用了 MBean 的 start() 方法后属性才可能有意义，否则它将被禁用。同样，如果当前无法发出通知但其他情况下可以发出时，则它可能被禁用。
immutableInfo	String	MBeanInfo	根据此 MBean 的 MBeanInfo 是否为不可变，决定字符串为 "true" 或 "false"。此字段为 true 时，可以保证给定 MBean 的 MBeanInfo 不会随 MBean 的生存期而更改。因此，客户端可以对其进行一次读取并缓存读取值。此字段为 false 或不存在时，则无法提供这样的保证，虽然这并不意味着 MBeanInfo 一定发生变化。
infoTimeout	String Long	MBeanInfo	MBeanInfo 理应不会更改的时间，以毫秒为单位。该值可以是 Long，也可以是十进制字符串。这从 DynamicMBean 或任何没有将 immutableInfo 定义为 true 的 MBean 中得出一个提示，MBeanInfo 不可能在此期间发生变化，因此可以缓存。此字段丢失或具有 0 值时，不建议缓存 MBeanInfo，除非它将 immutableInfo 设置为 true。
interfaceClassName	String	MBeanInfo	Standard MBean 或 MXBean 的 Java 接口名称，由 Class.getName() 返回。直接在 MBean Server 中注册或使用 StandardMBean 类创建的 Standard MBean 或 MXBean 将在其 MBeanInfo Descriptor 中包含此字段。
legalValues	Set<?>	MBeanAttributeInfo MBeanParameterInfo	属性或参数的合法值。请参阅 javax.management.openmbean。
maxValue	Object	MBeanAttributeInfo MBeanParameterInfo	属性或参数的最大合法值。请参阅 javax.management.openmbean。
metricType	String	MBeanAttributeInfo MBeanOperationInfo	规格的类型，字符串 "counter" 或 "gauge" 之一。规格是由 MBean 导出的尺度，通常是一个属性，但有时是操作的结果。作为 counter 的规格有一个永远不会减少的值，除了将其重置为初始值之外。计数器规格几乎总是为非负整数。例如接收到的请求数。作为 gauge 的规格有一个可以增加或减少的数字值。例如打开的连接数、缓存命中率、读取的温度。
minValue	Object	MBeanAttributeInfo MBeanParameterInfo	属性或参数的最小合法值。请参阅 javax.management.openmbean。
mxbean	String	MBeanInfo	根据此 MBean 是否为 MXBean，决定字符串为 &quot;true&quot; 或 &quot;false&quot;。直接在 MBean Server 中注册或使用 StandardMBean 类创建的 Standard MBean 或 MXBean 将在其 MBeanInfo Descriptor 中包含此字段。
openType	OpenType	MBeanAttributeInfo MBeanOperationInfo MBeanParameterInfo	此元素的开放类型。在 MBeanAttributeInfo 和 MBeanParameterInfo 的情况下，它是属性或参数的开放类型。在 MBeanOperationInfo 的情况下，它是返回值的开放类型。此字段在 OpenMBeanAttributeInfoSupport、OpenMBeanOperationInfoSupport 和 OpenMBeanParameterInfoSupport 的所有实例的 Descriptor 中设置。它还可以为 MXBean 的属性、操作和参数进行设置。 此字段可以为 MBeanNotificationInfo 进行设置，在此情况下，它指示用户数据将具有的开放类型。
originalType	String	MBeanAttributeInfo MBeanOperationInfo MBeanParameterInfo	此元素的原始 Java 类型，在生成此 MBeanAttributeInfo（等）的 MXBean 接口方法中显示。例如，MXBean 接口中的方法 public MemoryUsage getHeapMemoryUsage(); 定义称为 HeapMemoryUsage 的类型为 CompositeData 的属性。此属性的 Descriptor 中的 originalType 字段将包含值 &quot;java.lang.management.MemoryUsage&quot;。 此字符串的格式将在 MXBean 规范的类型名称一节中描述。
severity	String Integer	MBeanNotificationInfo	此通知的严重性。它可以为 0，表示严重性未知；也可以为 1 到 6 之间的值，表示递减的严重性级别。它可以表示为十进制字符串或 Integer。
since	String	所有	引入此元素的信息模型的版本。应用程序定义的一组 MBean 总称为信息模型。应用程序也可以定义此模型的版本，并且使用 &quot;since&quot; 字段来记录元素第一次出现的版本。
units	String	MBeanAttributeInfo MBeanParameterInfo MBeanOperationInfo	测量属性、参数或操作返回值的单位，如 &quot;bytes&quot; 或 &quot;seconds&quot;。

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

从以下版本开始：

1.5

方法摘要

Object	clone() 返回一个与此描述符相等的描述符。
boolean	equals(Object obj) 将此描述符与给定对象比较。
String[]	getFieldNames() 返回描述符中的所有字段名。
String[]	getFields() 以 string 数组的形式返回此 descriptor 中所包含的所有字段。
Object	getFieldValue(String fieldName) 返回指定字段名的值，如果该名称不存在任何值，则返回 null。
Object[]	getFieldValues(String... fieldNames) 以 Object 数组的形式返回该 descriptor 中的所有字段值。
int	hashCode() 返回此描述符的哈希码值。
boolean	isValid() 如果所有字段在给定其名称的情况下都有合法值，则返回 true。
void	removeField(String fieldName) 从该 descriptor 中删除字段。
void	setField(String fieldName, Object fieldValue) 设置特定字段名的值。
void	setFields(String[] fieldNames, Object[] fieldValues) 将字段名称数组中的所有字段设置为与字段值数组中的索引相同的新值。

方法详细信息

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