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。