Module java.management
Package javax.management

Interface Descriptor

所有超接口:
Cloneable, Serializable
所有已知实现类:
DescriptorSupport, ImmutableDescriptor
public interface Descriptor extends Serializable, Cloneable

用于JMX元素的附加元数据。一个描述符与一个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()方法返回的类型一致。对于MXBeans，这意味着它们应该是映射的Java类型，称为MXBean类型映射规则中的opendata(J)。

描述符字段
名称 类型 用途 含义
defaultValue 对象 MBeanAttributeInfo
MBeanParameterInfo		 属性或参数的默认值。请参阅 javax.management.openmbean。
deprecated 字符串 任意 指示信息模型的此元素不再建议使用。应用程序定义的一组 MBeans 被称为一个 信息模型。约定是该字段的值应包含一个字符串，即元素首次被弃用的模型版本，后跟一个解释该弃用的空间，例如 "1.3 被 Capacity 属性替换"。
descriptionResource
BundleBaseName		 字符串 任意 在 ResourceBundle 中找到 descriptionResourceKey 字段中给定键的基本名称，例如 "com.example.myapp.MBeanResources"。此字段的含义由此规范定义，但 JMX API 本身不设置或使用该字段。
descriptionResourceKey 字符串 任意 此元素描述的资源键。与 descriptionResourceBundleBaseName 结合使用，可用于查找描述的本地化版本。此字段的含义由此规范定义，但 JMX API 本身不设置或使用该字段。
enabled 字符串 MBeanAttributeInfo
MBeanNotificationInfo
MBeanOperationInfo		 此项是否启用的字符串 "true" 或 "false"。当属性或操作未启用时，它存在但当前无法访问。用户界面可能将其呈现为灰色项。例如，仅在调用 MBean 的 start() 方法后属性才有意义，否则将被禁用。同样，如果通知当前无法发出但在其他情况下可以发出，则可能会禁用通知。
exceptions 字符串数组 MBeanAttributeInfo, MBeanConstructorInfo, MBeanOperationInfo 在调用构造函数或操作或获取属性时可能抛出的异常的类名。此字段的含义由此规范定义，但 JMX API 本身不设置或使用该字段。设置属性时抛出的异常由字段 setExceptions 指定。
immutableInfo 字符串 MBeanInfo 此 MBean 的 MBeanInfo 是否 不可变 的字符串 "true" 或 "false"。当此字段为 true 时，给定 MBean 的 MBeanInfo 在其生命周期内保证不会更改。因此，客户端可以读取一次并缓存读取值。当此字段为 false 或不存在时，没有这样的保证，尽管这并不意味着 MBeanInfo 必定会更改。另请参阅 "jmx.mbean.info.changed" 通知。
infoTimeout 字符串
长整型		 MBeanInfo MBeanInfo 可合理预期不会更改的毫秒数。该值可以是 Long 或十进制字符串。这为 DynamicMBean 或任何未将 immutableInfo 定义为 true 的 MBean 提供了一个提示，表明 MBeanInfo 在此期间不太可能更改，因此可以缓存。当此字段缺失或值为零时，不建议缓存 MBeanInfo，除非其具有将 immutableInfo 设置为 true 或其在其 MBeanNotificationInfo 数组中具有 "jmx.mbean.info.changed" 的情况。
interfaceClassName 字符串 MBeanInfo 标准 MBean 或 MXBean 的 Java 接口名称，由 Class.getName() 返回。直接在 MBean 服务器中注册的标准 MBean 或使用 StandardMBean 类创建的 MXBean 将在其 MBeanInfo 描述符中具有此字段。
legalValues Set<?> MBeanAttributeInfo
MBeanParameterInfo		 属性或参数的合法值。请参阅 javax.management.openmbean。
locale 字符串 任意 此 MBeanInfo、MBeanAttributeInfo 等中描述的描述的 locale，由 Locale.toString() 返回。
maxValue 对象 MBeanAttributeInfo
MBeanParameterInfo		 属性或参数的最大合法值。请参阅 javax.management.openmbean。
metricType 字符串 MBeanAttributeInfo
MBeanOperationInfo		 度量的类型，为 "counter" 或 "gauge" 中的一个字符串。度量是由 MBean 导出的测量值，通常是属性，但有时是操作的结果。作为 counter 的度量具有一个值，除非将其重置为起始值，否则永远不会减少。计数器度量几乎总是非负整数。例如，接收的请求数量。作为 gauge 的度量具有可以增加或减少的数值。示例可能包括打开的连接数、缓存命中率或温度读数。
minValue 对象 MBeanAttributeInfo
MBeanParameterInfo		 属性或参数的最小合法值。请参阅 javax.management.openmbean。
mxbean 字符串 MBeanInfo 此 MBean 是否为 MXBean 的字符串 "true" 或 "false"。直接在 MBean 服务器中注册的标准 MBean 或使用 StandardMBean 类创建的 MXBean 将在其 MBeanInfo 描述符中具有此字段。
openType OpenType MBeanAttributeInfo
MBeanOperationInfo
MBeanParameterInfo

此元素的开放类型。对于 MBeanAttributeInfo 和 MBeanParameterInfo，这是属性或参数的开放类型。对于 MBeanOperationInfo，它是返回值的开放类型。此字段在所有 OpenMBeanAttributeInfoSupport、OpenMBeanOperationInfoSupport 和 OpenMBeanParameterInfoSupport 的实例的描述符中设置。对于 MXBeans 的属性、操作和参数也是如此。

此字段可以设置为 MBeanNotificationInfo，在这种情况下，它指示 user data 将具有的开放类型。
originalType 字符串 MBeanAttributeInfo
MBeanOperationInfo
MBeanParameterInfo

此元素的原始 Java 类型，即在生成此 MBeanAttributeInfo（等）的 MXBean 接口方法中出现的类型。例如，一个方法
public MemoryUsage getHeapMemoryUsage();
在 MXBean 接口中定义了一个名为 HeapMemoryUsage 类型为 CompositeData 的属性。此属性的描述符中的 originalType 字段将具有值 "java.lang.management.MemoryUsage"。

此字符串的格式在 MXBean 规范的 类型名称 部分中描述。
setExceptions 字符串数组 MBeanAttributeInfo 设置属性时可能抛出的异常的类名。此字段的含义由此规范定义，但 JMX API 本身不设置或使用该字段。获取属性时抛出的异常由字段 exceptions 指定。
severity 字符串
整数		 MBeanNotificationInfo 此通知的严重性。可以为 0 表示未知严重性，或从 1 到 6 的值表示递减的严重性级别。可以表示为十进制字符串或 Integer。
since 字符串 任意 此元素首次引入的信息模型的版本。应用程序定义的一组 MBeans 被称为一个 信息模型。应用程序还可以定义此模型的版本，并使用 "since" 字段记录元素首次出现的版本。
units 字符串 MBeanAttributeInfo
MBeanParameterInfo
MBeanOperationInfo		 属性、参数或操作返回值的度量单位，例如 "bytes" 或 "seconds"。

一些额外的字段由模型MBeans定义。请参阅ModelMBeanInfo，ModelMBeanAttributeInfo，ModelMBeanConstructorInfo，ModelMBeanNotificationInfo，以及ModelMBeanOperationInfo的信息，以及JMX规范中的“模型MBeans”章节。以下表格总结了这些字段。请注意，当此表中的类型为Number时，也可以使用Long的十进制表示形式。

没有阻止在不是模型MBeans的MBeans中使用这些字段。例如，displayName，severity和visibility字段在模型MBeans之外也很有趣。但是，只有模型MBeans对这些字段有预定义的行为。

模型MBean字段
名称 类型 用于 含义
class 字符串 ModelMBeanOperationInfo 定义方法的类（完全限定）。
currencyTimeLimit 数字 ModelMBeanInfo
ModelMBeanAttributeInfo
ModelMBeanOperationInfo		 缓存值有效的时间：<0 永不，=0 总是，>0 秒。
default 对象 ModelMBeanAttributeInfo 属性的默认值。
descriptorType 字符串 任何 描述符类型，“mbean”，“attribute”，“constructor”，“operation”或“notification”。
displayName 字符串 任何 此项的可读名称。
export 字符串 ModelMBeanInfo 用于导出/公开此MBean的名称，以便其他JMX代理可以找到。
getMethod 字符串 ModelMBeanAttributeInfo 获取方法的操作描述符名称。
lastUpdatedTimeStamp 数字 ModelMBeanAttributeInfo
ModelMBeanOperationInfo		 设置value时的时间戳。
log 字符串 ModelMBeanInfo
ModelMBeanNotificationInfo		 t或T：记录所有通知，f或F：不记录任何通知。
logFile 字符串 ModelMBeanInfo
ModelMBeanNotificationInfo		 用于记录事件的完全限定文件名。
messageID 字符串 ModelMBeanNotificationInfo 消息文本的唯一键（以允许翻译、分析）。
messageText 字符串 ModelMBeanNotificationInfo 通知的文本。
name 字符串 任何 此项的名称。
persistFile 字符串 ModelMBeanInfo 应将MBean持久化到的文件名。
persistLocation 字符串 ModelMBeanInfo 应将MBean持久化到的完全限定目录名称（如果适用）。
persistPeriod 数字 ModelMBeanInfo
ModelMBeanAttributeInfo		 持久化周期的频率（以秒为单位）。在persistPolicy为“OnTimer”或“NoMoreOftenThan”时使用。
persistPolicy 字符串 ModelMBeanInfo
ModelMBeanAttributeInfo		 其中之一：OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never。请参阅JMX规范文档中的“MBean描述符字段”部分。
presentationString 字符串 任何 XML格式化字符串，用于呈现数据。
protocolMap 描述符 ModelMBeanAttributeInfo 请参阅JMX规范文档中的“协议映射支持”部分。映射必须适用于属性，并且条目可以在运行时更新或增加。
role 字符串 ModelMBeanConstructorInfo
ModelMBeanOperationInfo		 其中之一：“constructor”，“operation”，“getter”或“setter”。
setMethod 字符串 ModelMBeanAttributeInfo 设置方法的操作描述符名称。
severity 数字 ModelMBeanNotificationInfo 0-6，其中0：未知；1：不可恢复；2：关键，失败；3：主要，严重；4：次要，边缘，错误；5：警告；6：正常，已清除，信息
targetObject 对象 ModelMBeanOperationInfo 要执行此方法的对象。
targetType 字符串 ModelMBeanOperationInfo targetObject的对象引用类型。可以是：ObjectReference | Handle | EJBHandle | IOR | RMIReference。
value 对象 ModelMBeanAttributeInfo
ModelMBeanOperationInfo		 属性或操作的当前（缓存的）值。
visibility 数字 任何 1-4，其中1：始终可见，4：很少可见。
自 JDK 版本:
1.5

  • Method Summary

    Modifier and Type
    Method
    Description
    Object
    clone()
    返回一个与此描述符相等的描述符。
    boolean
    equals(Object obj)
    将此描述符与给定对象进行比较。
    String[]
    getFieldNames()
    返回描述符中的所有字段名称。
    String[]
    getFields()
    将此描述符中包含的所有字段作为字符串数组返回。
    Object
    getFieldValue(String fieldName)
    返回特定字段名称的值，如果该名称没有对应的值则返回 null。
    Object[]
    getFieldValues(String... fieldNames)
    返回描述符中所有字段值的对象数组。
    int
    hashCode()
    返回此描述符的哈希码值。
    boolean
    isValid()
    如果所有字段的值都合法，则返回 true。
    void
    removeField(String fieldName)
    从描述符中移除一个字段。
    void
    setField(String fieldName, Object fieldValue)
    设置特定字段名称的值。
    void
    setFields(String[] fieldNames, Object[] fieldValues)
    将字段名称数组中的所有字段设置为字段值数组中相同索引处的新值。

  • Method Details

    • getFieldValue

      Object getFieldValue(String fieldName) throws RuntimeOperationsException
      返回特定字段名称的值，如果该名称没有对应的值则返回 null。
      参数:
      fieldName - 字段名称。
      返回:
      相应的值，如果字段不存在则返回 null。
      抛出:
      RuntimeOperationsException - 如果字段名称不合法。

    • setField

      void setField(String fieldName, Object fieldValue) throws RuntimeOperationsException

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

      在设置值之前，字段值将被验证。如果值无效，则会抛出异常。有效性的含义取决于描述符的实现。

      参数:
      fieldName - 要设置的字段名称。不能为空。
      fieldValue - 要为字段名称设置的字段值。如果该值是字段的有效值，则可以为 null。
      抛出:
      RuntimeOperationsException - 如果字段名称或字段值不合法（包装异常为 IllegalArgumentException）；或如果描述符是不可变的（包装异常为 UnsupportedOperationException）。

    • getFields

      String[] getFields()
      返回描述符中包含的所有字段作为字符串数组。
      返回:
      字段格式为 fieldName=fieldValue 的字符串数组
      如果字段的值不是字符串，则将调用其 toString() 方法，并将返回的值（用括号括起来）作为返回数组中字段的值。如果字段的值为 null，则返回数组中的字段值将为空。如果描述符为空，则将返回一个空数组。
      参见:

    • getFieldNames

      String[] getFieldNames()
      返回描述符中的所有字段名称。
      返回:
      字段名称的字符串数组。如果描述符为空，则将返回一个空数组。

    • getFieldValues

      Object[] getFieldValues(String... fieldNames)
      返回描述符中所有字段值的对象数组。返回的值与 fieldNames 字符串数组参数的顺序相同。
      参数:
      fieldNames - 字段值应该返回的字段名称的字符串数组。如果数组为空，则将返回一个空数组。如果数组为 null，则将返回所有值，就像参数是由 getFieldNames() 返回的数组一样。如果数组中的字段名称不存在，包括为 null 或空字符串的情况，则将为要返回的匹配数组元素返回 null。
      返回:
      字段值的对象数组。如果 fieldNames 列表为空，则将返回一个空数组。

    • removeField

      void removeField(String fieldName)
      从描述符中移除一个字段。
      参数:
      fieldName - 要移除的字段的字符串名称。如果字段名称不合法或字段未找到，则不会抛出异常。
      抛出:
      RuntimeOperationsException - 如果给定名称的字段存在且描述符是不可变的。包装异常将是 UnsupportedOperationException。

    • setFields

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

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

      在设置值之前，字段值将被验证。如果值无效，则会抛出异常。如果数组为空，则不会生效任何更改。

      参数:
      fieldNames - 字段名称的字符串数组。数组和数组元素不能为空。
      fieldValues - 相应字段值的对象数组。数组不能为空。数组元素可以为 null。
      抛出:
      RuntimeOperationsException - 如果更改因任何原因失败。如果 fieldNames 或 fieldValues 为 null，或者数组长度不同，或者其中一个值非法，则包装异常为 IllegalArgumentException。如果描述符是不可变的，并且调用将更改其内容，则包装异常为 UnsupportedOperationException。
      参见:

    • clone

      Object clone() throws RuntimeOperationsException

      返回一个与此描述符相等的描述符。对返回的描述符进行更改不会影响此描述符，反之亦然。如果此描述符是不可变的，则可能通过返回自身来满足此条件。

      返回:
      一个与此描述符相等的描述符。
      抛出:
      RuntimeOperationsException - 对字段名称或字段值的非法值。如果由于任何原因描述符构造失败，则将抛出此异常。

    • isValid

      boolean isValid() throws RuntimeOperationsException
      如果所有字段的值都根据其名称合法，则返回 true。
      返回:
      如果值合法，则返回 true。
      抛出:
      RuntimeOperationsException - 如果由于任何原因验证失败，则将抛出此异常。如果描述符无效，则方法返回 false，但如果尝试确定有效性失败，则会抛出此异常。

    • equals

      boolean equals(Object obj)

      将此描述符与给定对象进行比较。如果给定对象也是描述符，并且两个描述符具有相同的字段名称（可能在大小写上有所不同）和相同的关联值，则对象相等。两个描述符中字段的相应值在以下条件下相等：

      • 如果一个值为 null，则另一个值也必须为 null。
      • 如果一个值是原始数组，则另一个值也必须是具有相同类型和相同元素的相同类型的原始数组。
      • 如果一个值是对象数组，则另一个值也必须是，并且 Arrays.deepEquals(Object[],Object[]) 必须返回 true。
      • 否则，Object.equals(Object) 必须返回 true。
      覆盖:
      equals 在类 Object
      参数:
      obj - 要比较的对象。
      返回:
      如果对象相同则返回 true；否则返回 false。
      自 JDK 版本:
      1.6
      参见:

    • 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()。
      覆盖:
      hashCode 在类 Object
      返回:
      该对象的哈希码值。
      自:
      1.6
      参见: