JavaTM Platform
Standard Ed. 6

javax.management
类 ObjectName

java.lang.Object
  继承者 javax.management.ObjectName
所有已实现的接口:
Serializable, Comparable<ObjectName>, QueryExp

public class ObjectName
extends Object
implements Comparable<ObjectName>, QueryExp

表示 MBean 的对象名,或者能够与多个 MBean 名称相匹配的模式。此类的实例是不可变的。

可使用此类的实例表示:

由两部分(域和键属性)组成的对象名。

是一个不包括冒号字符 (:) 的由字符组成的字符串。建议域不要包含字符串 "//",该字符串保留供将来使用。

如果域至少包括一个通配符星号 (*) 或问号 (?),则该对象名就是一个模式。星号匹配任意零或多个字符的序列,而问号则匹配任意单个字符。

如果域为空,则由 MBean 服务器(在其中使用 ObjectName)的默认域 在特定的上下文中替换它。

键属性 是一个无序的键和关联值的集合。

每个 都是一个由字符组成的非空字符串,不可以包含任何逗号 (,)、等号 (=)、冒号、星号或问号字符。在一个给定的 ObjectName 中,同一个键不能出现两次。

每个与键关联的 都是由字符组成的字符串,或者由引号括起来或者不括起来。

无引号值 可能是一个空的字符串,不包含任意逗号、等号、冒号和引号。

如果无引号值 包括至少一个通配符星号或问号,则该对象名就是一个属性值模式

有引号值 由一个引号 ("),后跟可能为空的字符串,然后是另一个引号所组成。在字符串中,反斜线 (\) 具有特殊的含义,它后面必须是下列某个字符:

引号可能不出现在有引号值中,但紧跟在奇数个连续反斜线后的情况除外。

括住有引号值的引号和该值中的所有反斜线都被视为该值的一部分。

如果引号值 包括至少一个星号或问号,且星号或问号之前没有反斜杠,则将其视为通配符,并且该对象名是一个属性值模式。星号匹配任意零或多个字符的序列,而问号则匹配任意单个字符。

ObjectName 可能是一种属性列表模式。在这种情况下,它可以有零个或多个键和关联值。它与非模式的 ObjectName 匹配,该 ObjectName 的域与相同的键和关联值匹配且包含它们,并且可能包括其他键和值。

当至少有一个 ObjectName 的有引号无引号 键属性值包含通配符星号或问号(如上所述)时,ObjectName 是一个属性值模式。在这种情况下,它有一个或多个键以及关联值,并至少有一个值包含通配符。它与一个无模式 ObjectName 相匹配,该 ObjectName 的域与之匹配,或者包含值与之匹配的相同键;如果属性值模式也是属性列表模式,则无模式 ObjectName 也可以包含其他键和值。

如果 ObjectName 是属性列表模式属性值模式,或者两者都是,则它是一个属性模式

如果某个 ObjectName 的域包含通配符或者 ObjectName 是一个属性模式,则该 ObjectName 是一个模式。

如果某个 ObjectName 不是一个模式,那么它必须至少包含一个键及其关联值。

ObjectName 模式的示例有:

按顺序使用下列元素可将 ObjectName 写为 String:

写为 String 的键属性列表是一个逗号分隔的元素列表。每个元素都是一个星号或一个键属性。键属性由键、等号 (=) 和关联值组成。

键属性列表中最多只能有一个元素为星号。如果键属性列表包含星号元素,则该 ObjectName 是一个属性列表模式。

在表示 ObjectName 的 String 中,空格没有任何特殊含意。例如,String:

 domain: key1 = value1 , key2 = value2
 
表示具有两个键的 ObjectName。每个键的名字包含 6 个字符,其中第一个和最后一个都是空格。与键 " key1 " 相关联的值同样以空格开头和结尾。

除了上述提及的字符限制外,ObjectName 的任何部分都不能包含换行符 ('\n'),无论这些部分是域、键还是值(无引号值和有引号值)。可使用序列 \n 将换行符表示为有引号值。

不管使用何种构造方法构建 ObjectName,关于特殊字符和引号的规则都适用。

为了避免不同供应商所提供的 MBean 之间出现冲突,提供了一个有用的约定:域名由指定该 MBean 的企业的反向 DNS 名开始,后跟一个句点和一个字符串,由该企业决定该字符串的解释。例如,由 Sun Microsystems Inc.(DNS 名是 sun.com)所指定的 MBean 将有 com.sun.MyDomain 这样的域。这基本上与 Java 语言包名的约定相同。

此类的 serialVersionUID1081892073854801359L

从以下版本开始:
1.5
另请参见:
序列化表格

字段摘要
static ObjectName WILDCARD
          定义通配符 "*:*" ObjectName。
 
构造方法摘要
ObjectName(String name)
          根据给定的字符串构造一个对象名。
ObjectName(String domain, Hashtable<String,String> table)
          构造一个对象名,它具有根据哈希表获得的多个键属性。
ObjectName(String domain, String key, String value)
          构造只具有一个键属性的对象名。
 
方法摘要
 boolean apply(ObjectName name)
          测试此 ObjectName(可以是一个模式)是否与另一个 ObjectName 匹配。
 int compareTo(ObjectName name)
          比较两个 ObjectName 实例。
 boolean equals(Object object)
          比较当前的对象名与另一个对象名是否相等。
 String getCanonicalKeyPropertyListString()
          返回键属性列表的字符串表示形式,其中键属性按词汇顺序排序。
 String getCanonicalName()
          返回该名称的规范形式;也就是说,一种字符串表示形式,其中属性按词汇顺序排序。
 String getDomain()
          返回域部分。
static ObjectName getInstance(ObjectName name)
          返回 ObjectName 的实例,该 ObjectName 可用于任何可使用给定对象的地方。
static ObjectName getInstance(String name)
          返回 ObjectName 的实例,该 ObjectName 可用于任何使用 new ObjectName(name) 获得的对象可以使用的地方。
static ObjectName getInstance(String domain, Hashtable<String,String> table)
          返回 ObjectName 的实例,该 ObjectName 可用于任何使用 new ObjectName(domain, table) 获得的对象可以使用的地方。
static ObjectName getInstance(String domain, String key, String value)
          返回 ObjectName 的实例,该 ObjectName 可用于任何使用 new ObjectName(domain, key, value) 获得的对象可以使用的地方。
 String getKeyProperty(String property)
          获得与键属性中某个键相关联的值。
 Hashtable<String,String> getKeyPropertyList()
          以哈希表的形式返回键属性。
 String getKeyPropertyListString()
          返回创建时指定的键属性列表的字符串表示形式。
 int hashCode()
          返回此 ObjectName 的哈希码。
 boolean isDomainPattern()
          根据对象名的域部分检查对象名是否为一个模式。
 boolean isPattern()
          检查该对象名是否为一个模式。
 boolean isPropertyListPattern()
          检查对象名是否为一个键属性列表模式。
 boolean isPropertyPattern()
          检查对象名是否为一个键属性模式。
 boolean isPropertyValuePattern()
          检查对象名是否为值部分至少有一个键属性的模式。
 boolean isPropertyValuePattern(String property)
          检查键属性中与值关联的值是否为一个模式。
static String quote(String s)
          返回给定 String 的有引号形式,使之适合包含在 ObjectName 中。
 void setMBeanServer(MBeanServer mbs)
          设置将在其上执行查询的 MBean 服务器。
 String toString()
          返回该对象名的字符串表示形式。
static String unquote(String q)
          返回给定 String 的无引号形式,如果 qquote(s) 返回的 String,则 unquote(q).equals(s)
 
从类 java.lang.Object 继承的方法
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

字段详细信息

WILDCARD

public static final ObjectName WILDCARD
定义通配符 "*:*" ObjectName。

从以下版本开始:
1.6
构造方法详细信息

ObjectName

public ObjectName(String name)
           throws MalformedObjectNameException,
                  NullPointerException
根据给定的字符串构造一个对象名。

参数:
name - 对象名的字符串表示形式。
抛出:
MalformedObjectNameException - 如果作为参数传递的字符串格式不正确。
NullPointerException - 如果 name 参数为 null。

ObjectName

public ObjectName(String domain,
                  String key,
                  String value)
           throws MalformedObjectNameException,
                  NullPointerException
构造只具有一个键属性的对象名。

参数:
domain - 对象名的域部分。
key - 对象名键属性中的属性。
value - 对象名键属性中的值。
抛出:
MalformedObjectNameException - 如果 domainkeyvalue 包含非法字符,如果 value 未遵循有关引号使用的规则。
NullPointerException - 如果某个参数为 null。

ObjectName

public ObjectName(String domain,
                  Hashtable<String,String> table)
           throws MalformedObjectNameException,
                  NullPointerException
构造一个对象名,它具有根据哈希表获得的多个键属性。

参数:
domain - 对象名的域部分。
table - 包含一个或多个键属性的哈希表。表中每项的键都是对象名中键属性的键。表中的关联值是对象名中的关联值。
抛出:
MalformedObjectNameException - 如果 domain 包含非法字符,或者 table 中的某个键或值包含非法字符,或者 table 中的某个值未遵循有关引号使用的规则。
NullPointerException - 如果某个参数为 null。
方法详细信息

getInstance

public static ObjectName getInstance(String name)
                              throws MalformedObjectNameException,
                                     NullPointerException

返回 ObjectName 的实例,该 ObjectName 可用于任何使用 new ObjectName(name) 获得的对象可以使用的地方。返回的对象可以是 ObjectName 的子类。使用相同的参数调用此方法两次可能会返回相同的对象,或者两个等效但是不同的对象。

参数:
name - 对象名的字符串表示形式。
返回:
与给定 String 相对应的 ObjectName。
抛出:
MalformedObjectNameException - 如果作为参数传递的字符串格式不正确。
NullPointerException - 如果 name 参数为 null。

getInstance

public static ObjectName getInstance(String domain,
                                     String key,
                                     String value)
                              throws MalformedObjectNameException,
                                     NullPointerException

返回 ObjectName 的实例,该 ObjectName 可用于任何使用 new ObjectName(domain, key, value) 获得的对象可以使用的地方。返回的对象可以是 ObjectName 的子类。使用相同的参数调用此方法两次可能会返回相同的对象,或者两个等效但是不同的对象。

参数:
domain - 对象名的域部分。
key - 对象名键属性中的属性。
value - 对象名键属性中的值。
返回:
与给定域、键和值相对应的 ObjectName。
抛出:
MalformedObjectNameException - 如果 domainkeyvalue 包含非法字符,如果 value 未遵循有关引号使用的规则。
NullPointerException - 如果某个参数为 null。

getInstance

public static ObjectName getInstance(String domain,
                                     Hashtable<String,String> table)
                              throws MalformedObjectNameException,
                                     NullPointerException

返回 ObjectName 的实例,该 ObjectName 可用于任何使用 new ObjectName(domain, table) 获得的对象可以使用的地方。返回的对象可以是 ObjectName 的子类。使用相同的参数调用此方法两次可能会返回相同的对象,或者两个等效但是不同的对象。

参数:
domain - 对象名的域部分。
table - 包含一个或多个键属性的哈希表。表中每项的键都是对象名中键属性的键。表中的关联值是对象名中的关联值。
返回:
与给定域和键映射关系相对应的 ObjectName。
抛出:
MalformedObjectNameException - 如果 domain 包含非法字符,或者 table 中的某个键或值包含非法字符,或者 table 中的某个值未遵循有关引号使用的规则。
NullPointerException - 如果某个参数为 null。

getInstance

public static ObjectName getInstance(ObjectName name)
                              throws NullPointerException

返回 ObjectName 的实例,该 ObjectName 可用于任何可使用给定对象的地方。返回的对象可以是 ObjectName 的子类。如果 name 是 ObjectName 子类的名称,则无法保证返回的对象属于同一个类。

返回的值可能与 name 相同,也可能不相同。使用相同的参数调用此方法两次可能会返回相同的对象,或者两个等效但是不同的对象。

因为 ObjectName 是不可变的,所以制作 ObjectName 的副本通常没有用。此方法的主要用途是用于防止恶意的调用者,它可能向敏感代码传递具有可疑行为的子类实例。这种代码可以调用此方法来获得一个已知没有可疑行为的 ObjectName。

参数:
name - ObjectName 类或子类的一个实例
返回:
ObjectName 或已知具有相同语义的子类的实例。如果 name 符合 ObjectName 的语义,则返回的对象等于(尽管不必相同)name
抛出:
NullPointerException - 如果 name 为 null。

isPattern

public boolean isPattern()
检查该对象名是否为一个模式。

如果某个对象名的域包含通配符或者它是一个属性模式,则该对象名是一个模式。

返回:
如果该名称是一个模式,则返回 true;否则返回 false。

isDomainPattern

public boolean isDomainPattern()
根据对象名的域部分检查对象名是否为一个模式。

返回:
如果该名称是一个域模式,则返回 true;否则返回 false。

isPropertyPattern

public boolean isPropertyPattern()
检查对象名是否为一个键属性模式。

如果对象名是键属性列表模式(例如 "d:k=v,*")或属性值模式(例如 "d:k=*"),或者两者都是(例如 "d:k=*,*"),则它是一个键属性模式。

返回:
如果该名称是一个属性模式,则返回 true;否则返回 false。

isPropertyListPattern

public boolean isPropertyListPattern()
检查对象名是否为一个键属性列表模式。

例如,"d:k=v,*" 和 "d:k=*,*" 是键属性列表模式,而 "d:k=*" 则不是。

返回:
如果该名称是一个属性列表模式,则返回 true;否则返回 false。
从以下版本开始:
1.6

isPropertyValuePattern

public boolean isPropertyValuePattern()
检查对象名是否为值部分至少有一个键属性的模式。

例如,"d:k=*" 和 "d:k=*,*" 是属性值模式,而 "d:k=*" 则不是。

返回:
如果该名称是一个属性值模式,则返回 true;否则返回 false。
从以下版本开始:
1.6

isPropertyValuePattern

public boolean isPropertyValuePattern(String property)
                               throws NullPointerException,
                                      IllegalArgumentException
检查键属性中与值关联的值是否为一个模式。

参数:
property - 要检查值的属性。
返回:
如果与给定键关联的值是一个模式,则返回 true;否则返回 false。
抛出:
NullPointerException - 如果 property 为 null。
IllegalArgumentException - 如果 property 对于此 ObjectName 不是有效值。
从以下版本开始:
1.6

getCanonicalName

public String getCanonicalName()

返回该名称的规范形式;也就是说,一种字符串表示形式,其中属性按词汇顺序排序。

更准确地说,该名称的规范形式是一个由域部分、冒号 (:)、规范的键属性列表 和一个模式指示 组成的 String。

规范的键属性列表 是与 getCanonicalKeyPropertyListString() 所述相同的字符串。

模式指示 是:

返回:
该名称的规范形式。

getDomain

public String getDomain()
返回域部分。

返回:
域。

getKeyProperty

public String getKeyProperty(String property)
                      throws NullPointerException
获得与键属性中某个键相关联的值。

参数:
property - 要返回其值的属性。
返回:
属性值,如果此 ObjectName 中没有此种属性,则返回 null。
抛出:
NullPointerException - 如果 property 为 null。

getKeyPropertyList

public Hashtable<String,String> getKeyPropertyList()

以哈希表的形式返回键属性。返回值是一个哈希表,其中每个键是 ObjectName 的键属性列表中的键,并且每个值都是与键关联的值。

返回值可以是不可修改的。如果是可修改的,则更改它对此 ObjectName 没有影响。

返回:
键属性表。

getKeyPropertyListString

public String getKeyPropertyListString()

返回创建时指定的键属性列表的字符串表示形式。如果使用构造方法 ObjectName(String) 构造了此 ObjectName,则返回 String 中的键属性顺序与该构造方法参数中的顺序相同。

返回:
键属性列表字符串。此字符串与 ObjectName 是否为模式无关。

getCanonicalKeyPropertyListString

public String getCanonicalKeyPropertyListString()
返回键属性列表的字符串表示形式,其中键属性按词汇顺序排序。为了根据 MBean 的键属性列表来选择 MBean,在执行字典式比较中使用此方法。词汇顺序就是 String.compareTo(String) 所暗指的顺序。

返回:
规范的键属性列表字符串。此字符串与 ObjectName 是否为模式无关。

toString

public String toString()

返回该对象名的字符串表示形式。未指定此字符串的格式,但是当且仅当两个 ObjectName 相等时才会返回相同的字符串。

覆盖:
Object 中的 toString
返回:
此对象名的字符串表示形式。

equals

public boolean equals(Object object)
比较当前的对象名与另一个对象名是否相等。当且仅当两个 ObjectName 实例的规范形式相等时它们才相等。规范形式是 getCanonicalName() 所描述的字符串。

覆盖:
Object 中的 equals
参数:
object - 要与当前对象名进行比较的对象名。
返回:
如果 object 是一个 ObjectName 并且其规范形式与此 ObjectName 的规范形式相同,则返回 true。
另请参见:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
返回此 ObjectName 的哈希码。

覆盖:
Object 中的 hashCode
返回:
此对象的一个哈希码值。
另请参见:
Object.equals(java.lang.Object), Hashtable

quote

public static String quote(String s)
                    throws NullPointerException

返回给定 String 的有引号形式,使之适合包含在 ObjectName 中。返回的值可用作与 ObjectName 中某个键相关联的值。String s 可包含任何字符。适当使用引号可确保返回的值在 ObjectName 中是合法的。

返回值由引号 ('"')、对应于 s 中字符的字符序列和另一个引号所组成。s 中的字符会不加更改地出现在返回值中,但下列内容除外:

参数:
S - 要用引号形式表示的 String。
返回:
有引号形式的 String。
抛出:
NullPointerException - 如果 s 为 null。

unquote

public static String unquote(String q)
                      throws IllegalArgumentException,
                             NullPointerException

返回给定 String 的无引号形式,如果 qquote(s) 返回的 String,则 unquote(q).equals(s)。如果没有满足 quote(s).equals(q) 的 String s,则 unquote(q) 抛出 IllegalArgumentException。

这些规则意味着在有引号和无引号形式之间存在一对一的映射关系。

参数:
q - 要用无引号形式表示的 String。
返回:
无引号形式的 String。
抛出:
IllegalArgumentException - 如果不能由 quote(java.lang.String) 方法返回 q,例如它没有以引号 (") 开始和结束。
NullPointerException - 如果 q 为 null。

apply

public boolean apply(ObjectName name)
              throws NullPointerException

测试此 ObjectName(可以是一个模式)是否与另一个 ObjectName 匹配。如果 name 是一个模式,则结果是 false。如果此 ObjectName 是一个模式,则当且仅当 name 与该模式匹配时结果才是 true。如果此 ObjectName 和 name 都不是模式,则当且仅当两个 ObjectName 按 equals(Object) 方法的描述相等时结果才是 true。

指定者:
接口 QueryExp 中的 apply
参数:
name - 要进行比较的 MBean 名。
返回:
如果 name 与此 ObjectName 匹配,则返回 true。
抛出:
NullPointerException - 如果 name 为 null。

setMBeanServer

public void setMBeanServer(MBeanServer mbs)
从接口 QueryExp 复制的描述
设置将在其上执行查询的 MBean 服务器。

指定者:
接口 QueryExp 中的 setMBeanServer
参数:
mbs - 将在其上执行查询的 MBean 服务器。

compareTo

public int compareTo(ObjectName name)

比较两个 ObjectName 实例。没有完整地指定 ObjectName 之间的顺序关系,但是存储的 ObjectName 列表一般按照便于阅读的顺序出现。

特别要指出的是,如果两个 ObjectName 实例的域不同,则其顺序为域的字典顺序。键属性列表的顺序仍然没有指定。

例如,以下 ObjectName 实例:

将按以下方式排序:

指定者:
接口 Comparable<ObjectName> 中的 compareTo
参数:
name - 要比较的 ObjectName。
返回:
根据此 ObjectName 小于、等于或大于给定 ObjectName 分别返回负整数、零或正整数。
从以下版本开始:
1.6

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

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