javax.management.modelmbean
类 DescriptorSupport

java.lang.Object
  javax.management.modelmbean.DescriptorSupport

所有已实现的接口：

Serializable, Cloneable, Descriptor

public class DescriptorSupport
extends Object
implements Descriptor

此类表示 ModelMBean 元素的元数据集。描述符是 ModelMBeanInfo、ModelMBeanNotificationInfo、ModelMBeanAttributeInfo、ModelMBeanConstructorInfo 和 ModelMBeanParameterInfo 的一部分。

描述符由字段集合组成。每个字段都采用 fieldname=fieldvalue 格式。字段名称是不区分大小写的，在字段值上将保留大小写。

所有字段名称和值都不是预定义的。任何程序都可以定义和添加新字段。出于实现一致性考虑，某些字段已预定义，并受 ModelMBeanInfo、ModelMBeanAttributeInfo、ModelMBeanConstructorInfo、ModelMBeanNotificationInfo、ModelMBeanOperationInfo 和 ModelMBean 类的支持。

此类的 serialVersionUID 为 -6292969195866300415L。

从以下版本开始：

1.5

另请参见：

序列化表格

DescriptorSupport

public DescriptorSupport()

描述符默认的构造方法。默认的初始描述符大小为 20。此大小会根据需要而增加。
注意，创建的空描述符不是有效的描述符（isValid 方法返回 false）。

DescriptorSupport

public DescriptorSupport(int initNumFields)
                  throws MBeanException,
                         RuntimeOperationsException

描述符构造方法。它使用存储 descriptor 字段的 Map 的初始容量作为参数。容量将根据需要而增加。
注意，创建的空描述符不是有效的描述符（isValid 方法返回 false）。

参数：

initNumFields - 存储 descriptor 字段的 Map 的初始容量。

抛出：

RuntimeOperationsException - 如果 initNumField 的值是非法值 (<= 0)

MBeanException - 如果包装了一个分布式通信异常。

DescriptorSupport

public DescriptorSupport(DescriptorSupport inDescr)

采用 Descriptor 作为参数的描述符构造方法。创建新描述符，它被初始化为传入参数中的描述符的值。

参数：

inDescr - 描述符，用于初始化所构造的描述符。如果该参数为 null 或不包含 descriptor 字段，则将创建一个空 Descriptor。

DescriptorSupport

public DescriptorSupport(String inStr)
                  throws MBeanException,
                         RuntimeOperationsException,
                         XMLParseException

Descriptor 构造方法带有一个 XML String。

XML 字符串的格式是未定义的，但实现必须确保在使用此构造方法进行实例化时，能够使用现有描述符上的 toXMLString() 返回的字符串来实例化一个等效的描述符。

在此实现中，所有字段值都将以 String 形式创建。如果字段值不是 String 形式的，则程序员必须重置或正确转换这些字段。

参数：

inStr - 用于填充此 Descriptor 的 XML 格式的字符串。格式是未定义的，但任何实现必须确保在使用此构造方法进行实例化时，能够使用现有描述符上的 toXMLString 方法返回的字符串来实例化一个等效的描述符。

抛出：

RuntimeOperationsException - 如果传递到参数中的 String inStr 为 null

XMLParseException - 如果解析输入 String 时发生 XML 解析问题

MBeanException - 如果包装了一个分布式通信异常。

DescriptorSupport

public DescriptorSupport(String[] fieldNames,
                         Object[] fieldValues)
                  throws RuntimeOperationsException

带有字段名称和字段值的构造方法。两个数组都不可以为 null。

参数：

fieldNames - 字段名称的 String 数组。此数组的所有元素都不可以为 null。

fieldValues - 对应字段值的 Object 数组。此数组的元素可以为 null。fieldValue 对于 fieldName 必须是有效的（正如 isValid 方法中所定义的那样）。

注：参数的数组大小应是匹配的。如果两个数组均为空，则创建一个空描述符。

抛出：

RuntimeOperationsException - 如果 Names 或 Values 字段的值为非法值。数组长度必须相等。如果因为某种原因导致描述符构造失败，则将抛出此异常。

DescriptorSupport

public DescriptorSupport(String... fields)

带有 fieldName=fieldValue 格式的字段的构造方法。

参数：

fields - 每个元素包含一个字段名称和字段值的 String 数组。如果此数组为 null 或空，则将执行默认的构造方法。忽略 null 字符串或空字符串。

所有字段值都应是 String。如果字段值不是 String，则程序员必须重置或正确转换这些字段。

注：每个字符串都应为 fieldName=fieldValue 形式。字段名称到第一个 = 字符结束；例如，如果 String 为 a=b=c 则字段名称为 a，其值为 b=c。

抛出：

RuntimeOperationsException - 如果 Names 或 Values 字段的值为非法值。字段必须包含 "="。"=fieldValue"、"fieldName" 和 "fieldValue" 是非法的。FieldName 不可以为 null。"fieldName=" 将使该值为 null。如果因为某种原因导致描述符构造失败，则将抛出此异常。

getFieldValue

public Object getFieldValue(String fieldName)
                     throws RuntimeOperationsException

从接口 Descriptor 复制的描述

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

指定者：

接口 Descriptor 中的 getFieldValue

参数：

fieldName - 字段名称。

返回：

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

抛出：

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

setField

public void setField(String fieldName,
                     Object fieldValue)
              throws RuntimeOperationsException

从接口 Descriptor 复制的描述

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

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

指定者：

接口 Descriptor 中的 setField

参数：

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

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

抛出：

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

getFields

public String[] getFields()

从接口 Descriptor 复制的描述

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

指定者：

接口 Descriptor 中的 getFields

返回：

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

另请参见：

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

getFieldNames

public String[] getFieldNames()

从接口 Descriptor 复制的描述

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

指定者：

接口 Descriptor 中的 getFieldNames

返回：

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

getFieldValues

public Object[] getFieldValues(String... fieldNames)

从接口 Descriptor 复制的描述

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

指定者：

接口 Descriptor 中的 getFieldValues

参数：

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

返回：

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

setFields

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

从接口 Descriptor 复制的描述

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

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

指定者：

接口 Descriptor 中的 setFields

参数：

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

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

抛出：

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

另请参见：

Descriptor.getFields()

clone

public Object clone()
             throws RuntimeOperationsException

返回作为 Descriptor 副本的新 Descriptor。

指定者：

接口 Descriptor 中的 clone

覆盖：

类 Object 中的 clone

返回：

此实例的一个副本。

抛出：

RuntimeOperationsException - 如果 Names 或 Values 字段的值为非法值。如果因为某种原因导致描述符构造失败，则将抛出此异常。

另请参见：

Cloneable

removeField

public void removeField(String fieldName)

从接口 Descriptor 复制的描述

从该 descriptor 中删除字段。

指定者：

接口 Descriptor 中的 removeField

参数：

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

equals

public boolean equals(Object o)

将此描述符与给定对象比较。如果给定对象也是一个 Descriptor，并且两个 Descriptor 具有相同的字段名称（有时是不同的）和关联值，则两个对象相等。如果满足以下情况，则两个 Descriptor 字段的各个值相等：

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

指定者：

接口 Descriptor 中的 equals

覆盖：

类 Object 中的 equals

参数：

o - 要与之比较的对象。

返回：

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

另请参见：

Object.hashCode(), Hashtable

hashCode

public int hashCode()

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

• 如果 v 为 null，则 h 为 0。
• 如果 v 是基本类型数组，则使用恰当重载形式的 java.util.Arrays.hashCode 计算 h。
• 如果 v 是对象数组，则使用 Arrays.deepHashCode 计算 h。
• 其他情况下，h 为 v.hashCode()。

指定者：

接口 Descriptor 中的 hashCode

覆盖：

类 Object 中的 hashCode

返回：

此对象的哈希码值。

另请参见：

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

isValid

public boolean isValid()
                throws RuntimeOperationsException

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

此实现不支持与目录或查找服务进行互操作。因此，根据规范，将不对 "export" 字段进行检查。

否则，在以下情况下此实现返回 false：

• 名称和 descriptorType fieldNames 尚未定义，或者为 null、空或不是 String
• 类、角色、getMethod、setMethod fieldNames（如果已定义）为 null 或不是 String
• persistPeriod、currencyTimeLimit、lastUpdatedTimeStamp、lastReturnedTimeStamp（如果已定义）为 null，或者不是 Numeric String 或 Numeric Value（其值 >= -1）
• log fieldName（如果已定义）为 null，或者不是 Boolean，或者不是值为 "t"、"f"、"true"、"false" 的 String 。这些 String 值不能是区分大小写的。
• visibility fieldName（如果已定义）为 null，或者不是 Numeric String 或 Numeric Value（其值 >= 1 且 <= 4）
• severity fieldName（如果已定义）为 null，或不为 Numeric String 或 Numeric Value（其值 >= 0 且 <= 6）
  
• persistPolicy fieldName（如果已定义）为 null，或不是以下字符串之一：
  "OnUpdate"、"OnTimer"、"NoMoreOftenThan"、"OnUnregister"、"Always"、"Never"。这些 String 值不能是区分大小写的。
  

指定者：

接口 Descriptor 中的 isValid

返回：

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

抛出：

RuntimeOperationsException - 如果因为某种原因导致验证检查失败，则将抛出此异常。

toXMLString

public String toXMLString()

返回表示描述符的 XML 字符串。

格式是未定义的，但实现应确保在使用构造方法 DescriptorSupport(String inStr) 进行实例化时，能够使用此方法返回的字符串来构造一个等效描述符。

对于不是 String 对象的字段，可以调用 toString() 来创建值。该值将用括号括起来。不保证能够重新构造这些对象，除非它们已经过特殊设置以有意义的格式支持 toString()，并且具有接受相同格式的 String 的匹配构造方法。

如果描述符为空，则返回以下 String：<Descriptor></Descriptor>

返回：

XML 字符串。

抛出：

RuntimeOperationsException - 如果 Names 或 Values 字段的值为非法值。如果因为某种原因导致 XML 格式的字符串构造失败，则将抛出此异常。

toString

public String toString()

返回表示描述符的可读字符串。该字符串的格式将为 "fieldName=fieldValue,fieldName2=fieldValue2,..."
如果描述符中没有字段，则返回一个空 String。
如果 fieldValue 是一个对象，则对它调用 toString() 方法，其返回值用作括号中的字段值。

覆盖：

类 Object 中的 toString

返回：

该对象的字符串表示形式。

抛出：

RuntimeOperationsException - 如果 Names 或 Values 字段的值为非法值。如果因为某种原因导致描述符字符串出错，则将抛出此异常。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。