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	getReferencedMBeans() 检索在该关系的各种角色中引用的 MBean。
String	getRelationId() 返回关系标识符（用于惟一标识 Relation Service 内的关系）。
ObjectName	getRelationServiceName() 返回处理关系的 Relation Service 的 ObjectName。
String	getRelationTypeName() 返回相关关系类型的名称。
List	getRole(String theRoleName) 检索给定角色名称的角色值。
Integer	getRoleCardinality(String theRoleName) 返回当前在给定角色中引用的 MBean 数。
RoleResult	getRoles(String[] theRoleNameArray) 检索具有给定名称的角色值。
void	handleMBeanUnregistration(ObjectName theObjName, String theRoleName) 在注销角色中引用的 MBean 时由 Relation Service 使用的回调。
RoleList	retrieveAllRoles() 返回关系中的所有角色，不检查读取模式。
void	setRole(Role theRole) 设置给定角色。
RoleResult	setRoles(RoleList theRoleList) 设置给定的角色。

方法详细信息

getRole

List getRole(String theRoleName)
             throws IllegalArgumentException,
                    RoleNotFoundException,
                    RelationServiceNotRegisteredException

检索给定角色名称的角色值。

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

参数：

theRoleName - 角色名称

返回：

作为角色值的 ObjectName 对象的 ArrayList

抛出：

IllegalArgumentException - 如果为 null 角色名称

RoleNotFoundException - 如果：

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

- 角色不可读。

RelationServiceNotRegisteredException - 如果 Relation Service 未在 MBean Server 中注册

另请参见：

setRole(javax.management.relation.Role)

getRoles

RoleResult getRoles(String[] theRoleNameArray)
                    throws IllegalArgumentException,
                           RelationServiceNotRegisteredException

检索具有给定名称的角色值。

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

参数：

theRoleNameArray - 要检索的角色名称的数组

返回：

RoleResult 对象，包括一个 RoleList（针对成功检索到的角色）和一个 RoleUnresolvedList（针对未检索到的角色）。

抛出：

IllegalArgumentException - 如果是 null 角色名称

RelationServiceNotRegisteredException - 如果 Relation Service 未在 MBean Server 中注册。

另请参见：

setRoles(javax.management.relation.RoleList)

getRoleCardinality

Integer getRoleCardinality(String theRoleName)
                           throws IllegalArgumentException,
                                  RoleNotFoundException

返回当前在给定角色中引用的 MBean 数。

参数：

theRoleName - 角色名称

返回：

当前在此角色中引用的 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 theRole)
             throws IllegalArgumentException,
                    RoleNotFoundException,
                    RelationTypeNotFoundException,
                    InvalidRoleValueException,
                    RelationServiceNotRegisteredException,
                    RelationNotFoundException

设置给定角色。

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

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

参数：

theRole - 要设置的角色（名称和新值）

抛出：

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 theRoleList)
                    throws IllegalArgumentException,
                           RelationServiceNotRegisteredException,
                           RelationTypeNotFoundException,
                           RelationNotFoundException

设置给定的角色。

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

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

参数：

theRoleList - 要设置的角色列表

返回：

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 theObjName,
                               String theRoleName)
                               throws IllegalArgumentException,
                                      RoleNotFoundException,
                                      InvalidRoleValueException,
                                      RelationServiceNotRegisteredException,
                                      RelationTypeNotFoundException,
                                      RelationNotFoundException

在注销角色中引用的 MBean 时由 Relation Service 使用的回调。

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

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

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

参数：

theObjName - 注销的 MBean 的 ObjectName

theRoleName - 在其中引用 MBean 的角色名称

抛出：

IllegalArgumentException - 如果是 null 参数

RoleNotFoundException - 如果角色不在关系中或不可写

InvalidRoleValueException - 如果角色值不遵循相关角色信息（这永远不会在从 Relation Service 中调用时发生）

RelationServiceNotRegisteredException - 如果 Relation Service 未在 MBean Server 注册

RelationTypeNotFoundException - 如果在 Relation Service 中尚未声明该关系类型。

RelationNotFoundException - 如果未在 Relation Service 中添加的关系 MBean 调用此方法。

getReferencedMBeans

Map 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。