JavaTM Platform
Standard Ed. 6

javax.management.relation
接口 Relation

所有已知子接口:
RelationSupportMBean
所有已知实现类:
RelationSupport

public interface Relation

此接口必须由任何 MBean 类(期望表示为一种使用 Relation Service 管理的关系)来实现。

简单的关系(即只有角色,没有属性或方法)可以由 Relation Service 直接创建(表示为 RelationSupport 对象,由 Relation Service 内部处理)。

如果用户希望表示更复杂的关系(包括属性和/或方法),则其必须提供自己实现 Relation 接口的类。这可以通过从 RelationSupport 类继承得到,也可以通过实现该接口得到(全权或者委托给 RelationSupport 对象成员)。

指定这样的用户关系类是为了引入属性和/或方法。这些都要向远程管理公开。因此,这意味着任何用户关系类都必须是一个 MBean 类。

从以下版本开始:
1.5

方法摘要
 RoleResult getAllRoles()
          返回该关系中存在的所有角色。
 Map<ObjectName,List<String>> getReferencedMBeans()
          检索在该关系的各种角色中引用的 MBean。
 String getRelationId()
          返回关系标识符(用于唯一标识 Relation Service 内的关系)。
 ObjectName getRelationServiceName()
          返回处理关系的 Relation Service 的 ObjectName。
 String getRelationTypeName()
          返回相关关系类型的名称。
 List<ObjectName> getRole(String roleName)
          检索给定角色名称的角色值。
 Integer getRoleCardinality(String roleName)
          返回当前在给定角色中引用的 MBean 数。
 RoleResult getRoles(String[] roleNameArray)
          检索具有给定名称的角色值。
 void handleMBeanUnregistration(ObjectName objectName, String roleName)
          在注销角色中引用的 MBean 时由 Relation Service 使用的回调。
 RoleList retrieveAllRoles()
          返回关系中的所有角色,不检查读取模式。
 void setRole(Role role)
          设置给定角色。
 RoleResult setRoles(RoleList roleList)
          设置给定的角色。
 

方法详细信息

getRole

List<ObjectName> getRole(String roleName)
                         throws IllegalArgumentException,
                                RoleNotFoundException,
                                RelationServiceNotRegisteredException
检索给定角色名称的角色值。

按照关系类型检查角色是否存在及是否可读。

参数:
roleName - 角色名称
返回:
作为角色值的 ObjectName 对象的 ArrayList
抛出:
IllegalArgumentException - 如果为 null 角色名称
RoleNotFoundException - 如果:

- 不存在具有给定名称的角色

- 角色不可读。

RelationServiceNotRegisteredException - 如果 Relation Service 未在 MBean Server 中注册
另请参见:
setRole(javax.management.relation.Role)

getRoles

RoleResult getRoles(String[] roleNameArray)
                    throws IllegalArgumentException,
                           RelationServiceNotRegisteredException
检索具有给定名称的角色值。

按照关系类型检查每个角色是否存在及是否可读。

参数:
roleNameArray - 要检索的角色名称的数组
返回:
RoleResult 对象,包括一个 RoleList(针对成功检索到的角色)和一个 RoleUnresolvedList(针对未检索到的角色)。
抛出:
IllegalArgumentException - 如果是 null 角色名称
RelationServiceNotRegisteredException - 如果 Relation Service 未在 MBean Server 中注册。
另请参见:
setRoles(javax.management.relation.RoleList)

getRoleCardinality

Integer getRoleCardinality(String roleName)
                           throws IllegalArgumentException,
                                  RoleNotFoundException
返回当前在给定角色中引用的 MBean 数。

参数:
roleName - 角色名称
返回:
当前在此角色中引用的 MBean 数
抛出:
IllegalArgumentException - 如果是 null 角色名称
RoleNotFoundException - 如果不存在具有给定名称的角色

getAllRoles

RoleResult getAllRoles()
                       throws RelationServiceNotRegisteredException
返回该关系中存在的所有角色。

返回:
RoleResult 对象,该对象包括一个 RoleList(针对成功检索到的角色)和一个 RoleUnresolvedList(针对不可读的角色)。
抛出:
RelationServiceNotRegisteredException - 如果 Relation Service 未在 MBean Server 中注册

retrieveAllRoles

RoleList retrieveAllRoles()
返回关系中的所有角色,不检查读取模式。

返回:
一个 RoleList。

setRole

void setRole(Role role)
             throws IllegalArgumentException,
                    RoleNotFoundException,
                    RelationTypeNotFoundException,
                    InvalidRoleValueException,
                    RelationServiceNotRegisteredException,
                    RelationNotFoundException
设置给定角色。

将按照其在关系的关系类型中提供的相应角色定义检查角色

将发送通知(带类型 RELATION_BASIC_UPDATE 或 RELATION_MBEAN_UPDATE 的 RelationNotification,具体取决于该关系是否为 MBean)

参数:
role - 要设置的角色(名称和新值)
抛出:
IllegalArgumentException - 如果是 null 角色。
RoleNotFoundException - 如果不存在具有指定名称的角色,或者该角色不可写(初始化角色时未执行写入访问模式测试)。
InvalidRoleValueException - 如果为角色提供的值无效,例如:

- 给定值中引用的 MBean 数小于期望的最小程度;

- 提供的值中引用的 MBean 数超过期望的最大程度;

- 该值中引用的 MBean 的一个对象不是该角色期望的 MBean 类的对象;

- 如果不存在为该角色提供的 MBean。

RelationServiceNotRegisteredException - 如果 Relation Service 未在 MBean Server 中注册。
RelationTypeNotFoundException - 如果在 Relation Service 中尚未声明该关系类型。
RelationNotFoundException - 如果尚未在 Relation Service 中添加关系。
另请参见:
getRole(java.lang.String)

setRoles

RoleResult setRoles(RoleList roleList)
                    throws IllegalArgumentException,
                           RelationServiceNotRegisteredException,
                           RelationTypeNotFoundException,
                           RelationNotFoundException
设置给定的角色。

将按照其在关系的关系类型中提供的相应角色定义检查角色

每个更新的角色将发送一个通知(带类型 RELATION_BASIC_UPDATE 或 RELATION_MBEAN_UPDATE 的 RelationNotification,具体取决于该关系是否为 MBean)。

参数:
roleList - 要设置的角色列表
返回:
RoleResult 对象,该对象包括一个 RoleList(针对成功设置的角色)和一个 RoleUnresolvedList(针对未成功设置的角色)。
抛出:
IllegalArgumentException - 如果是 null 角色列表;
RelationServiceNotRegisteredException - 如果 Relation Service 未在 MBean Server 中注册;
RelationTypeNotFoundException - 如果在 Relation Service 中尚未声明该关系类型;
RelationNotFoundException - 如果尚未在 Relation Service 中添加关系 MBean。
另请参见:
getRoles(java.lang.String[])

handleMBeanUnregistration

void handleMBeanUnregistration(ObjectName objectName,
                               String roleName)
                               throws IllegalArgumentException,
                                      RoleNotFoundException,
                                      InvalidRoleValueException,
                                      RelationServiceNotRegisteredException,
                                      RelationTypeNotFoundException,
                                      RelationNotFoundException
在注销角色中引用的 MBean 时由 Relation Service 使用的回调。

Relation Service 将调用此方法,以让该关系采取行动来反映这种注销的影响。

小心,不期望用户调用此方法。

当前实现是为了用其当前值(引用的 MBean 的 ObjectName 列表)而不用注销的值设置角色。

参数:
objectName - 注销的 MBean 的 ObjectName
roleName - 在其中引用 MBean 的角色名称
抛出:
IllegalArgumentException - 如果是 null 参数;
RoleNotFoundException - 如果角色不在关系中或不可写;
InvalidRoleValueException - 如果角色值不遵循相关角色信息(这永远不会在从 Relation Service 中调用时发生);
RelationServiceNotRegisteredException - 如果 Relation Service 未在 MBean Server 注册;
RelationTypeNotFoundException - 如果在 Relation Service 中尚未声明该关系类型;
RelationNotFoundException - 如果未在 Relation Service 中添加的关系 MBean 调用此方法。

getReferencedMBeans

Map<ObjectName,List<String>> getReferencedMBeans()
检索在该关系的各种角色中引用的 MBean。

返回:
一个 HashMap 映射:

ObjectName -> ArrayList of String(角色名)


getRelationTypeName

String getRelationTypeName()
返回相关关系类型的名称。

返回:
关系类型的名称。

getRelationServiceName

ObjectName getRelationServiceName()
返回处理关系的 Relation Service 的 ObjectName。

返回:
Relation Service 的 ObjectName。

getRelationId

String getRelationId()
返回关系标识符(用于唯一标识 Relation Service 内的关系)。

返回:
关系 id。

JavaTM Platform
Standard Ed. 6

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

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