模块 java.management
包 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() 方法返回的类型一致。对于 MXBeans，这意味着它们应该是映射的 Java 类型，在 MXBean类型映射规则 中称为 opendata (J)。

描述符字段
Name Type 用于 意义
defaultValue Object MBeanAttributeInfo
MBeanParameterInfo		 属性或参数的默认值。参见 javax.management.openmbean 。
弃用 String 任何 指示不再推荐使用信息模型的这个元素。应用程序定义的一组 MBean 统称为 information model 。惯例是此字段的值包含一个字符串，该字符串是该元素首先被弃用的模型版本，后跟一个空格，然后是对弃用的解释，例如 "1.3 Replaced by the Capacity attribute" 。
描述资源
BundleBaseName		 String 任何 ResourceBundle 的基本名称，其中可以找到 descriptionResourceKey 字段中给出的密钥，例如 "com.example.myapp.MBeanResources" 。该字段的含义由本规范定义，但 JMX API 本身并未设置或使用该字段。
描述资源键 String 任何 用于描述此元素的资源键。结合 descriptionResourceBundleBaseName ，这可用于查找描述的本地化版本。该字段的含义由本规范定义，但 JMX API 本身并未设置或使用该字段。
启用 String MBeanAttributeInfo
MBeanNotificationInfo
MBeanOperationInfo		 字符串 "true" 或 "false" 根据此项启用。当未启用属性或操作时，它存在但当前无法访问。用户界面可能会将其显示为灰色项。例如，属性可能仅在调用 MBean 的 start() 方法后才有意义，否则将被禁用。同样，如果当前无法发出但可能在其他情况下发出通知，则通知可能会被禁用。
异常 String[] MBeanAttributeInfo、MBeanConstructorInfo、MBeanOperationInfo 调用构造函数或操作或获取属性时可能抛出的异常的类名。该字段的含义由本规范定义，但 JMX API 本身并未设置或使用该字段。设置属性时抛出的异常由字段 setExceptions 指定。
不可变信息 String MBeanInfo 根据此 MBean 的 MBeanInfo 的字符串 "true" 或 "false" 是 immutable 。当此字段为真时，保证给定 MBean 的 MBeanInfo 在 MBean 的生命周期内不会更改。因此，客户端可以读取一次并缓存读取的值。当该字段为假或不存在时，就没有这样的保证，尽管这并不意味着 MBeanInfo 一定会更改。另请参阅 "jmx.mbean.info.changed" 通知。
infoTimeout String
Long		 MBeanInfo 可以合理预期 MBeanInfo 不变的时间（以毫秒为单位）。该值可以是 Long 或十进制字符串。这提供了来自 DynamicMBean 或任何未将 immutableInfo 定义为 true 的 MBean 的提示，MBeanInfo 在此期间内不太可能更改，因此可以缓存。当此字段缺失或值为零时，不建议缓存 MBeanInfo，除非它的 immutableInfo 设置为 true 或者它的 MBeanNotificationInfo 数组中有 "jmx.mbean.info.changed" 。
接口类名 String MBeanInfo Standard MBean 或 MXBean 的 Java 接口名称，由 Class.getName() 返回。直接在 MBean 服务中注册或使用 StandardMBean 类创建的标准 MBean 或 MXBean 将在其 MBeanInfo 描述符中包含此字段。
legalValues 设置<?> MBeanAttributeInfo
MBeanParameterInfo		 属性或参数的合法值。参见 javax.management.openmbean 。
locale String 任何 MBeanInfo、MBeanAttributeInfo 等中描述的 locale，由 Locale.toString() 返回。
最大值 Object MBeanAttributeInfo
MBeanParameterInfo		 属性或参数的最大合法值。参见 javax.management.openmbean 。
公制类型 String MBeanAttributeInfo
MBeanOperationInfo		 指标的类型，字符串“counter”或“gauge”之一。度量是 MBean 导出的度量，通常是属性，但有时是操作的结果。 counter 的度量标准具有一个永不减少的值，除非重置为起始值。计数器指标几乎总是非负整数。一个例子可能是收到的请求数。 gauge 的指标具有可以增加或减少的数值。示例可能是打开的连接数或缓存命中率或温度读数。
minValue Object MBeanAttributeInfo
MBeanParameterInfo		 属性或参数的最小合法值。参见 javax.management.openmbean 。
MXbean String MBeanInfo 根据此 MBean，字符串 "true" 或 "false" 是一个 MXBean 。直接向 MBean 服务注册或使用 StandardMBean 类创建的标准 MBean 或 MXBean 将在其 MBeanInfo 描述符中包含此字段。
开放类型 OpenType MBeanAttributeInfo
MBeanOperationInfo
MBeanParameterInfo

此元素的开放类型。在 MBeanAttributeInfo 和 MBeanParameterInfo 的情况下，这是属性或参数的开放类型。在 MBeanOperationInfo 的情况下，它是返回值的开放类型。该字段在 OpenMBeanAttributeInfoSupport 、OpenMBeanOperationInfoSupport 和 OpenMBeanParameterInfoSupport 的所有实例的描述符中设置。它还为 MXBean 的属性、操作和参数设置。

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

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

该字符串的格式在 MXBean 规范的 类型名称 部分进行了描述。
设置异常 String[] MBeanAttributeInfo 设置属性时可以抛出的异常的类名。该字段的含义由本规范定义，但 JMX API 本身并未设置或使用该字段。获取属性时抛出的异常由字段 exceptions 指定。
严重程度 String
Integer		 MBeanNotificationInfo 此通知的严重性。它可以是 0 表示未知的严重性，也可以是 1 到 6 之间的值表示严重性的降低级别。它可以表示为十进制字符串或 Integer 。
since String 任何 引入此元素的信息模型的版本。应用程序定义的一组 MBean 统称为 information model 。应用程序还可以定义此模型的版本，并使用"since" 字段来记录元素首次出现的版本。
单位 String MBeanAttributeInfo
MBeanParameterInfo
MBeanOperationInfo		 测量属性、参数或操作返回值的单位，例如 "bytes" 或 "seconds" 。

一些附加字段由模型 MBean 定义。请参阅 ModelMBeanInfo 、ModelMBeanAttributeInfo 、ModelMBeanConstructorInfo 、ModelMBeanNotificationInfo 和 ModelMBeanOperationInfo 的信息，以及 JMX规范 的“模型 MBean”一章。下表总结了这些字段。请注意，当此表中的 Type 为 Number 时，也可以使用作为 Long 的十进制表示形式的 String。

没有什么可以阻止在不是模型 MBean 的 MBean 中使用这些字段。例如，displayName、严重程度 和 能见度 字段在 Model MBean 之外很受关注。但只有模型 MBean 对这些字段具有预定义的行为。

ModelMBean 字段
Name Type 用于 意义
类 String ModelMBeanOperationInfo 定义方法的类（完全限定）。
货币时间限制 Number ModelMBeanInfo
ModelMBeanAttributeInfo
ModelMBeanOperationInfo		 缓存值的有效时间：<0 从不，=0 始终，>0 秒。
default Object ModelMBeanAttributeInfo 属性的默认值。
描述符类型 String 任何 描述符的类型，“mbean”、“属性”、“构造方法”、“操作”或“通知”。
显示名称 String 任何 此项目的人类可读名称。
export String ModelMBeanInfo 用于导出/公开此 MBean 的名称，以便其他 JMX 代理可以找到它。
getMethod String ModelMBeanAttributeInfo get 方法的操作描述符的名称。
最后更新时间戳 Number ModelMBeanAttributeInfo
ModelMBeanOperationInfo		 当 value 被设置时。
日志 String ModelMBeanInfo
ModelMBeanNotificationInfo		 t 或 T：记录所有通知，f 或 F：不记录任何通知。
日志文件 String ModelMBeanInfo
ModelMBeanNotificationInfo		 用于记录事件的完全限定文件名。
消息ID String ModelMBeanNotificationInfo 消息文本的唯一键（允许翻译、分析）。
消息文本 String ModelMBeanNotificationInfo 通知文本。
姓名 String 任何 此项目的名称。
持久文件 String ModelMBeanInfo MBean 应保存到的文件名。
坚持位置 String ModelMBeanInfo 应保留 MBean 的完全限定目录名（如果适用）。
持续期 Number ModelMBeanInfo
ModelMBeanAttributeInfo		 持续周期的频率（以秒为单位）。当 persistPolicy 为“OnTimer”或“NoMoreOftenThan”时使用。
坚持策略 String ModelMBeanInfo
ModelMBeanAttributeInfo		 其中之一：OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never。请参阅 JMX 规范文档中的“MBean 描述符字段”部分。
演示字符串 String 任何 XML 格式的字符串以允许显示数据。
协议映射 Descriptor ModelMBeanAttributeInfo 请参阅 JMX 规范文档中的“协议映射支持”部分。映射必须适用于属性，并且可以在运行时更新或扩充条目。
角色 String ModelMBeanConstructorInfo
ModelMBeanOperationInfo		 “constructor”、“operation”、“getter”或“setter”之一。
设置方法 String ModelMBeanAttributeInfo set 方法的操作描述符的名称。
严重程度 Number ModelMBeanNotificationInfo 0-6 其中 0：未知； 1：不可恢复； 2：危急，失败； 3：重大的，严重的； 4：minor, marginal, error； 5：警告； 6：正常，已清除，信息丰富
目标对象 Object ModelMBeanOperationInfo 在其上执行此方法的对象。
目标类型 String ModelMBeanOperationInfo targetObject 的对象引用类型。可以是：ObjectReference |处理 | EJB 句柄 |折旧率 | RMI参考。
value Object ModelMBeanAttributeInfo
ModelMBeanOperationInfo		 属性或操作的当前（缓存）值。
能见度 Number 任何 1-4 其中 1：始终可见，4：很少可见。
自从：
1.5

  • 方法总结

    修饰符和类型
    方法
    描述
    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)
    将字段名称数组中的所有字段设置为字段值数组中具有相同索引的新值。

  • 方法详情

    • getFieldValue

      Object  getFieldValue(String  fieldName) throws RuntimeOperationsException
      返回特定字段名称的值，如果该名称不存在任何值，则返回 null。
      参数：
      fieldName - 字段名称。
      返回：
      相应的值，如果该字段不存在则为 null。
      抛出：
      RuntimeOperationsException - 如果字段名称非法。

    • setField

      void setField(String  fieldName, Object  fieldValue) throws RuntimeOperationsException

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

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

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

    • getFields

      String [] getFields()
      将此描述符中包含的所有字段作为字符串数组返回。
      返回：
      格式字段的字符串数组字段名=字段值
      如果字段的值不是字符串，则将对其调用 toString() 方法，并将返回值（括在括号中）用作返回数组中字段的值。如果某个字段的值为空，则返回数组中该字段的值将为空。如果描述符为空，您将得到一个空数组。
      参见：

    • getFieldNames

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

    • getFieldValues

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

    • removeField

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

    • setFields

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

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

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

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

    • clone

      Object  clone() throws RuntimeOperationsException

      返回等于此描述符的描述符。对返回描述符的更改不会影响此描述符，反之亦然。如果这个描述符是不可变的，它可以通过返回自己来满足这个条件。

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

    • isValid

      boolean isValid() throws RuntimeOperationsException
      如果所有字段都具有给定名称的合法值，则返回 true。
      返回：
      如果值合法则为真。
      抛出：
      RuntimeOperationsException - 如果有效性检查因任何原因失败，将抛出此异常。如果描述符无效，该方法返回 false，但如果尝试确定有效性失败，则抛出此异常。

    • equals

      boolean equals(Object  obj)

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

      • 如果一个值为空，则另一个也必须为空。
      • 如果一个值是原始数组，则另一个值必须是具有相同元素的相同类型的原始数组。
      • 如果一个值是对象数组，那么另一个值也必须是对象数组，并且 Arrays.deepEquals(Object[],Object[]) 必须返回 true。
      • 否则 Object.equals(Object) 必须返回 true。
      重写：
      equals 在类 Object 中
      参数：
      obj - 要与之比较的对象。
      返回：
      true 如果对象相同； false否则。
      自从：
      1.6
      参见：

    • hashCode

      int hashCode()

      返回此描述符的哈希码值。哈希码计算为描述符中每个字段的哈希码之和。名称为 n 且值为 v 的字段的哈希码为 n.toLowerCase().hashCode() ^ h。这里 h 是 v 的哈希码，计算如下：

      • 如果 v 为空，则 h 为 0。
      • 如果 v 是原始数组，则使用 java.util.Arrays.hashCode 的适当重载计算 h。
      • 如果 v 是对象数组，则使用 Arrays.deepHashCode(Object[]) 计算 h。
      • 否则 h 是 v.hashCode() 。
      重写：
      hashCode 在类 Object 中
      返回：
      此对象的哈希码值。
      自从：
      1.6
      参见：