javax.management.relation
接口 RelationServiceMBean

所有已知实现类：

RelationService

public interface RelationServiceMBean

Relation Service 负责创建和删除关系类型和关系，还负责处理一致性和提供查询机制。

从以下版本开始：

1.5

方法摘要

void	addRelation(ObjectName theRelObjectName) 作为 Relation Service 中的关系添加由用户创建（且由其在 MBean Server 中注册）的 MBean。
void	addRelationType(RelationType theRelTypeObj) 作为关系类型添加给定的对象。
Integer	checkRoleReading(String theRoleName, String theRelTypeName) 检查给定 Role 能否在给定类型的关系中读取。
Integer	checkRoleWriting(Role theRole, String theRelTypeName, Boolean theInitFlg) 检查给定 Role 能否在给定类型的关系中设置。
void	createRelation(String theRelId, String theRelTypeName, RoleList theRoleList) 创建给定关系类型的简单关系（由 RelationSupport 对象表示），并将其添加到 Relation Service 中。
void	createRelationType(String theRelTypeName, RoleInfo[] theRoleInfoArray) 用给定的角色信息（由 RoleInfo 对象提供）创建一个关系类型（RelationTypeSupport 对象），并将其添加到 Relation Service 中。
Map	findAssociatedMBeans(ObjectName theMBeanName, String theRelTypeName, String theRoleName) 检索与关系中给定关系相关的 MBean。
Map	findReferencingRelations(ObjectName theMBeanName, String theRelTypeName, String theRoleName) 检索在其中引用给定 MBean 的关系。
List	findRelationsOfType(String theRelTypeName) 返回给定类型的关系的关系 id。
List	getAllRelationIds() 返回由 Relation Service 处理的所有关系的所有关系 id。
List	getAllRelationTypeNames() 检索所有已知关系类型的名称。
RoleResult	getAllRoles(String theRelId) 返回关系中存在的所有角色。
boolean	getPurgeFlag() 返回一个标志，以指示注销关系中引用的 MBean 时是否接收到通知，是否必须执行关系的直接“肃清”（查找不再有效的关系），或者是否只在显式调用 purgeRelations 方法时执行该操作。
Map	getReferencedMBeans(String theRelId) 检索关系的各种角色中引用的 MBean。
String	getRelationTypeName(String theRelId) 返回给定关系的相关关系类型的名称。
List	getRole(String theRelId, String theRoleName) 检索给定关系中给定角色名称的角色值。
Integer	getRoleCardinality(String theRelId, String theRoleName) 检索给定角色中当前引用的 MBean 数。
RoleInfo	getRoleInfo(String theRelTypeName, String theRoleInfoName) 检索给定关系类型的给定角色的角色信息。
List	getRoleInfos(String theRelTypeName) 检索给定关系类型的角色信息（RoleInfo 对象）的列表。
RoleResult	getRoles(String theRelId, String[] theRoleNameArray) 检索给定关系中具有给定名称的角色值。
Boolean	hasRelation(String theRelId) 用给定的关系 id 检查是否存在 Relation Service 中标识的关系。
void	isActive() 检查该 Relation Service 是否处于活动状态。
String	isRelation(ObjectName theObjName) 如果 Relation Service 中作为关系添加 MBean，则返回与给定 ObjectName 相关的关系 id。
ObjectName	isRelationMBean(String theRelId) 如果用 MBean 表示关系（由用户创建且作为 Relation Service 中的关系添加），则返回该 MBean 的 ObjectName。
void	purgeRelations() 肃清关系。
void	removeRelation(String theRelId) 从 Relation Service 移除给定的关系。
void	removeRelationType(String theRelTypeName) 从 Relation Service 中移除给定的关系类型。
void	sendRelationCreationNotification(String theRelId) 发送关系创建通知 (RelationNotification)。
void	sendRelationRemovalNotification(String theRelId, List theUnregMBeanList) 发送关系移除通知 (RelationNotification)。
void	sendRoleUpdateNotification(String theRelId, Role theNewRole, List theOldRoleValue) 发送给定关系中的角色更新通知 (RelationNotification)。
void	setPurgeFlag(boolean thePurgeFlg) 设置一个标志，以指示注销关系中引用的 MBean 时是否接收到通知，是否必须执行关系的直接“肃清”（查找不再有效的关系），或者是否只在显式调用 purgeRelations 方法时执行该操作。
void	setRole(String theRelId, Role theRole) 以给定关系设置给定角色。
RoleResult	setRoles(String theRelId, RoleList theRoleList) 以给定关系设置给定角色。
void	updateRoleMap(String theRelId, Role theNewRole, List theOldRoleValue) 针对给定关系中给定角色的更新来处理 Relation Service 角色映射的更新。

方法详细信息

isActive

void isActive()
              throws RelationServiceNotRegisteredException

检查该 Relation Service 是否处于活动状态。当前的条件是，Relation Service 必须在 MBean Server 中注册。

抛出：

RelationServiceNotRegisteredException - 如果其尚未注册

getPurgeFlag

boolean getPurgeFlag()

返回一个标志，以指示注销关系中引用的 MBean 时是否接收到通知，是否必须执行关系的直接“肃清”（查找不再有效的关系），或者是否只在显式调用 purgeRelations 方法时执行该操作。

true 表示立即肃清。

返回：

如果是直接肃清，则返回 true。

另请参见：

setPurgeFlag(boolean)

setPurgeFlag

void setPurgeFlag(boolean thePurgeFlg)

设置一个标志，以指示注销关系中引用的 MBean 时是否接收到通知，是否必须执行关系的直接“肃清”（查找不再有效的关系），或者是否只在显式调用 purgeRelations 方法时执行该操作。

true 表示立即肃清。

参数：

thePurgeFlg - 标志

另请参见：

getPurgeFlag()

createRelationType

void createRelationType(String theRelTypeName,
                        RoleInfo[] theRoleInfoArray)
                        throws IllegalArgumentException,
                               InvalidRelationTypeException

用给定的角色信息（由 RoleInfo 对象提供）创建一个关系类型（RelationTypeSupport 对象），并将其添加到 Relation Service 中。

参数：

theRelTypeName - 关系类型的名称

theRoleInfoArray - 角色信息的数组

抛出：

IllegalArgumentException - 如果是 null 参数

InvalidRelationTypeException - 如果：

- 具有该名称的关系类型已经存在

- 两个不同的角色信息使用了同一个名称

- 未提供角色信息

- 提供了一个 null 角色信息

addRelationType

void addRelationType(RelationType theRelTypeObj)
                     throws IllegalArgumentException,
                            InvalidRelationTypeException

作为关系类型添加给定的对象。该对象期望实现 RelationType 接口。

参数：

theRelTypeObj - 关系类型对象（实现该 RelationType 接口）

抛出：

IllegalArgumentException - 如果是 null 参数

InvalidRelationTypeException - 如果已经存在具有该名称的关系类型

getAllRelationTypeNames

List getAllRelationTypeNames()

检索所有已知关系类型的名称。

返回：

关系类型名称的 ArrayList（字符串）

getRoleInfos

List getRoleInfos(String theRelTypeName)
                  throws IllegalArgumentException,
                         RelationTypeNotFoundException

检索给定关系类型的角色信息（RoleInfo 对象）的列表。

参数：

theRelTypeName - 关系类型的名称

返回：

RoleInfo 的 ArrayList。

抛出：

IllegalArgumentException - 如果是 null 参数

RelationTypeNotFoundException - 如果不存在具有该名称的关系类型。

getRoleInfo

RoleInfo getRoleInfo(String theRelTypeName,
                     String theRoleInfoName)
                     throws IllegalArgumentException,
                            RelationTypeNotFoundException,
                            RoleInfoNotFoundException

检索给定关系类型的给定角色的角色信息。

参数：

theRelTypeName - 关系类型的名称

theRoleInfoName - 角色的名称

返回：

RoleInfo 对象。

抛出：

IllegalArgumentException - 如果是 null 参数

RelationTypeNotFoundException - 如果在 Relation Service 中的关系类型未知

RoleInfoNotFoundException - 如果该角色不是该关系类型的一部分。

removeRelationType

void removeRelationType(String theRelTypeName)
                        throws RelationServiceNotRegisteredException,
                               IllegalArgumentException,
                               RelationTypeNotFoundException

从 Relation Service 中移除给定的关系类型。

此类型的关系对象将从 Relation Service 中移除。

参数：

theRelTypeName - 要移除的关系类型名称

抛出：

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

IllegalArgumentException - 如果是 null 参数

RelationTypeNotFoundException - 如果不存在具有该名称的关系类型

createRelation

void createRelation(String theRelId,
                    String theRelTypeName,
                    RoleList theRoleList)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RoleNotFoundException,
                           InvalidRelationIdException,
                           RelationTypeNotFoundException,
                           InvalidRoleValueException

创建给定关系类型的简单关系（由 RelationSupport 对象表示），并将其添加到 Relation Service 中。

按照在参数中提供的角色列表初始化角色。将未按此方法初始化的角色设置为 ObjectName 的空 ArrayList。

发送带类型 RELATION_BASIC_CREATION 的 RelationNotification。

参数：

theRelId - 关系标识符，用来惟一地标识 Relation Service 中的关系

theRelTypeName - 关系类型的名称（必须在 Relation Service 中创建）

theRoleList - 要初始化该关系的角色的角色列表（可以为 null）。

抛出：

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

IllegalArgumentException - 如果是 null 参数

RoleNotFoundException - 如果为关系类型中不存在的角色提供值

InvalidRelationIdException - 如果关系 id 已经使用

RelationTypeNotFoundException - 如果在 Relation Service 中关系类型是未知的

InvalidRoleValueException - 如果：

- 两个不同的角色使用了同一个角色名称

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

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

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

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

addRelation

void addRelation(ObjectName theRelObjectName)
                 throws IllegalArgumentException,
                        RelationServiceNotRegisteredException,
                        NoSuchMethodException,
                        InvalidRelationIdException,
                        InstanceNotFoundException,
                        InvalidRelationServiceException,
                        RelationTypeNotFoundException,
                        RoleNotFoundException,
                        InvalidRoleValueException

作为 Relation Service 中的关系添加由用户创建（且由其在 MBean Server 中注册）的 MBean。

要作为关系添加 MBean，其必须遵循以下做法：

- 实现该 Relation 接口

- 具有 RelationService ObjectName，即当前 Relation Service 的 ObjectName

- 具有在当前 Relation Service 中惟一且未使用的关系 id

- 具有关系类型，即在 Relation Service 中创建的关系类型

- 具有遵循在关系类型中提供的角色信息的角色。

参数：

theRelObjectName - 要添加的关系 MBean 的 ObjectName。

抛出：

IllegalArgumentException - 如果是 null 参数

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

NoSuchMethodException - 如果 MBean 未实现 Relation 接口

InvalidRelationIdException - 如果：

- MBean 中没有关系标识符

- 在 Relation Service 中已经使用关系标识符

InstanceNotFoundException - 如果尚未注册给定 ObjectName 的 MBean

InvalidRelationServiceException - 如果：

- MBean 中没有 Relation Service 名称

- MBean 中的 Relation Service 名称不是当前 Relation Service 的名称

RelationTypeNotFoundException - 如果：

- MBean 中没有关系类型名称

- MBean 中的关系类型名称与 Relation Service 中创建的关系类型不对应

InvalidRoleValueException - 如果：

- 角色中引用的 MBean 数小于期望的最小程度

- 角色中引用的 MBean 数超过期望的最大程度

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

- 为角色提供的 MBean 不存在

RoleNotFoundException - 如果为关系类型中不存在的角色提供了值

isRelationMBean

ObjectName isRelationMBean(String theRelId)
                           throws IllegalArgumentException,
                                  RelationNotFoundException

如果用 MBean 表示关系（由用户创建且作为 Relation Service 中的关系添加），则返回该 MBean 的 ObjectName。

参数：

theRelId - 标识关系的关系 id

返回：

相应关系 MBean 的 ObjectName；如果该关系不是 MBean，则返回 null。

抛出：

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果不存在与该 id 相关的关系

isRelation

String isRelation(ObjectName theObjName)
                  throws IllegalArgumentException

如果 Relation Service 中作为关系添加 MBean，则返回与给定 ObjectName 相关的关系 id。

参数：

theObjName - 假定关系的 ObjectName

返回：

关系 id（字符串）；或返回 null（如果 ObjectName 不是由 Relation Service 处理的关系）

抛出：

IllegalArgumentException - 如果是 null 参数

hasRelation

Boolean hasRelation(String theRelId)
                    throws IllegalArgumentException

用给定的关系 id 检查是否存在 Relation Service 中标识的关系。

参数：

theRelId - 标识关系的关系 id

返回：

boolean： 如果存在关系，则返回 true；否则返回 false

抛出：

IllegalArgumentException - 如果是 null 参数

getAllRelationIds

List getAllRelationIds()

返回由 Relation Service 处理的所有关系的所有关系 id。

返回：

String 的 ArrayList

checkRoleReading

Integer checkRoleReading(String theRoleName,
                         String theRelTypeName)
                         throws IllegalArgumentException,
                                RelationTypeNotFoundException

检查给定 Role 能否在给定类型的关系中读取。

参数：

theRoleName - 要检查的角色名称

theRelTypeName - 关系类型的名称

返回：

包装整数的 Integer，该整数对应于 RoleUnresolved 中用常量表示的可能问题：

- 如果角色可读，则用 0 表示

- 对应于 RoleStatus.NO_ROLE_WITH_NAME 用整数

- 对应于 RoleStatus.ROLE_NOT_READABLE 用整数

抛出：

IllegalArgumentException - 如果是 null 参数

RelationTypeNotFoundException - 如果 Relation Service 中的关系类型是未知的

checkRoleWriting

Integer checkRoleWriting(Role theRole,
                         String theRelTypeName,
                         Boolean theInitFlg)
                         throws IllegalArgumentException,
                                RelationTypeNotFoundException

检查给定 Role 能否在给定类型的关系中设置。

参数：

theRole - 要检查的角色

theRelTypeName - 关系类型的名称

theInitFlg - 指定已完成角色的初始化检查，并且不验证写入访问的标志。

返回：

包装整数的 Integer，该整数对应于 RoleUnresolved 中用常量表示的可能问题：

- 如果角色可以设置，则用 0 表示

- 对应于 RoleStatus.NO_ROLE_WITH_NAME 用整数表示

- 对应于 RoleStatus.ROLE_NOT_WRITABLE 用整数表示

- 对应于 RoleStatus.LESS_THAN_MIN_ROLE_DEGREE 用整数

- 对应于 RoleStatus.MORE_THAN_MAX_ROLE_DEGREE 用整数

- 对应于 RoleStatus.REF_MBEAN_OF_INCORRECT_CLASS 用整数

- 对应于 RoleStatus.REF_MBEAN_NOT_REGISTERED 用整数

抛出：

IllegalArgumentException - 如果是 null 参数

RelationTypeNotFoundException - 如果是未知关系类型

sendRelationCreationNotification

void sendRelationCreationNotification(String theRelId)
                                      throws IllegalArgumentException,
                                             RelationNotFoundException

发送关系创建通知 (RelationNotification)。通知类型是：

- RelationNotification.RELATION_BASIC_CREATION，如果该关系是 Relation Service 内部的一个对象

- RelationNotification.RELATION_MBEAN_CREATION，如果该关系是作为关系添加的 MBean。

源对象是 Relation Service 本身。

它在 Relation Service createRelation() 和 addRelation() 方法中调用。

参数：

theRelId - 更新的关系的关系标识符

抛出：

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果不存在给定关系 id 的关系

sendRoleUpdateNotification

void sendRoleUpdateNotification(String theRelId,
                                Role theNewRole,
                                List theOldRoleValue)
                                throws IllegalArgumentException,
                                       RelationNotFoundException

发送给定关系中的角色更新通知 (RelationNotification)。通知类型是：

- RelationNotification.RELATION_BASIC_UPDATE，如果该关系是 Relation Service 内部的一个对象

- RelationNotification.RELATION_MBEAN_UPDATE，如果该关系是作为关系添加的 MBean。

源对象是 Relation Service 本身。

它在关系 MBean setRole()（针对给定角色）和 setRoles()（针对每个角色）方法（RelationSupport 类中提供的实现）中调用。

它还在 Relation Service setRole()（针对给定角色）和 setRoles()（针对每个角色）方法中调用。

参数：

theRelId - 更新的关系的关系标识符

theNewRole - 新的角色（名称和新的值）

theOldRoleValue - 旧角色值（ObjectName 对象的列表）

抛出：

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果不存在给定关系 id 的关系

sendRelationRemovalNotification

void sendRelationRemovalNotification(String theRelId,
                                     List theUnregMBeanList)
                                     throws IllegalArgumentException,
                                            RelationNotFoundException

发送关系移除通知 (RelationNotification)。通知类型是：

- RelationNotification.RELATION_BASIC_REMOVAL，如果该关系是 Relation Service 内部的一个对象

- RelationNotification.RELATION_MBEAN_REMOVAL，如果该关系是作为关系添加的 MBean。

源对象是 Relation Service 本身。

它在 Relation Service removeRelation() 方法中调用。

参数：

theRelId - 更新的关系的关系标识符

theUnregMBeanList - 期望因为关系移除而注销的 MBean 的 ObjectName 列表（可以为 null）

抛出：

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果不存在给定关系 id 的关系

updateRoleMap

void updateRoleMap(String theRelId,
                   Role theNewRole,
                   List theOldRoleValue)
                   throws IllegalArgumentException,
                          RelationServiceNotRegisteredException,
                          RelationNotFoundException

针对给定关系中给定角色的更新来处理 Relation Service 角色映射的更新。

它在关系 MBean setRole()（针对给定角色）和 setRoles()（针对每个角色）方法（RelationSupport 类中提供的实现）中调用。

它还在 Relation Service setRole()（针对给定角色）和 setRoles()（针对每个角色）方法中调用。

为了允许 Relation Service 维护一致性（MBean 注销时）以及能够执行查询，更新角色时必须调用此方法。

参数：

theRelId - 已更新关系的关系标识符

theNewRole - 新的角色（名称和新值）

theOldRoleValue - 旧角色值（ObjectName 对象的列表）

抛出：

IllegalArgumentException - 如果是 null 参数

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

RelationNotFoundException - 如果没有给定 id 的关系。

removeRelation

void removeRelation(String theRelId)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RelationNotFoundException

从 Relation Service 移除给定的关系。

发送 RelationNotification 通知，其类型是：

- RelationNotification.RELATION_BASIC_REMOVAL，如果该关系只在 Relation Service 内部

- RelationNotification.RELATION_MBEAN_REMOVAL，如果该关系作为 MBean 注册。

对于在这样的关系中引用的 MBean，将不执行任何操作，

参数：

theRelId - 要移除的关系的关系 id

抛出：

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

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果没有对应于给定关系 id 的关系

purgeRelations

void purgeRelations()
                    throws RelationServiceNotRegisteredException

肃清关系。

根据 purgeFlag 值，此方法即可以在接收到关系中引用的 MBean 的注销通知时自动调用（如果将该标志设置为 true），也可以不调用（如果将该标志设置为 false）。

在此情况下，用户负责调用它来维护关系的一致性。一定要记住：如果注销 MBean 但没立即执行肃清，这时如果重新使用 ObjectName 并将其指派给关系中另一个引用的 MBean，那么手动调用此 purgeRelations() 就会出现问题，因为这样会认为此 ObjectName 就是已注销的 MBean，不把它看作新的 MBean。

该行为取决于在其中引用注销的 MBean 的角色数量：

- 如果移除角色中的一个 MBean 引用使其引用数少于最小程度，则必须移除该关系。

- 如果移除 MBean 引用后剩余的引用数仍然在该容量范围内，则保持该关系并在调用其 handleMBeanUnregistration() 回调时更新。

抛出：

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

findReferencingRelations

Map findReferencingRelations(ObjectName theMBeanName,
                             String theRelTypeName,
                             String theRoleName)
                             throws IllegalArgumentException

检索在其中引用给定 MBean 的关系。

这对应于 CIM "Reference" 和 "ReferenceName" 操作。

参数：

theMBeanName - MBean 的 ObjectName

theRelTypeName - 可以为 null；如果已指定，则将只在搜索时考虑该类型的关系。其他情况下将考虑所有关系类型。

theRoleName - 可以为 null；如果已指定，则只返回将在该角色中引用的 MBean 关系。其他情况要考虑所有角色。

返回：

HashMap，密钥为在其中引用 MBean 的关系的关系 id，并且每个密钥的值是角色名称的 ArrayList（因为 MBean 可以在同一关系中的几个角色中引用）。

抛出：

IllegalArgumentException - 如果是 null 参数

findAssociatedMBeans

Map findAssociatedMBeans(ObjectName theMBeanName,
                         String theRelTypeName,
                         String theRoleName)
                         throws IllegalArgumentException

检索与关系中给定关系相关的 MBean。

这对应于 CIM Associator 和 AssociatorName 操作。

参数：

theMBeanName - MBean 的 ObjectName

theRelTypeName - 可以为 null；如果已指定，则将只在搜索时考虑该类型的关系。其他情况下将考虑所有关系类型。

theRoleName - 可以为 null；如果已指定，则只返回将在该角色中引用的 MBean 关系。其他情况要考虑所有角色。

返回：

HashMap，密钥是与给定 MBean 相关的 MBean 的 ObjectName，而对于每个密钥而言，该值是这种关系的关系 id 的 ArrayList：密钥 MBean 与给定的 MBean 相关（因为它们可以与几个不同的关系相关）。

抛出：

IllegalArgumentException - 如果是 null 参数

findRelationsOfType

List findRelationsOfType(String theRelTypeName)
                         throws IllegalArgumentException,
                                RelationTypeNotFoundException

返回给定类型的关系的关系 id。

参数：

theRelTypeName - 关系类型名称

返回：

关系 id 的 ArrayList。

抛出：

IllegalArgumentException - 如果是 null 参数

RelationTypeNotFoundException - 如果不存在具有该名称的关系类型。

getRole

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

检索给定关系中给定角色名称的角色值。

参数：

theRelId - 关系 id

theRoleName - 角色名称

返回：

作为角色值的 ObjectName 对象的 ArrayList

抛出：

RelationServiceNotRegisteredException - 如果 Relation Service 未注册

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果没有带给定 id 的关系

RoleNotFoundException - 如果：

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

或者

- 角色不可读。

另请参见：

setRole(java.lang.String, javax.management.relation.Role)

getRoles

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

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

参数：

theRelId - 关系 id

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

返回：

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

抛出：

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

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果没有带给定 id 的关系

另请参见：

setRoles(java.lang.String, javax.management.relation.RoleList)

getAllRoles

RoleResult getAllRoles(String theRelId)
                       throws IllegalArgumentException,
                              RelationNotFoundException,
                              RelationServiceNotRegisteredException

返回关系中存在的所有角色。

参数：

theRelId - 关系 id

返回：

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

抛出：

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果没有指定 id 的关系

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

getRoleCardinality

Integer getRoleCardinality(String theRelId,
                           String theRoleName)
                           throws IllegalArgumentException,
                                  RelationNotFoundException,
                                  RoleNotFoundException

检索给定角色中当前引用的 MBean 数。

参数：

theRelId - 关系 id

theRoleName - 角色名称

返回：

当前在此角色中引用的 MBean 数

抛出：

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果没有带指定 id 的关系

RoleNotFoundException - 如果不存在具有指定名称的角色

setRole

void setRole(String theRelId,
             Role theRole)
             throws RelationServiceNotRegisteredException,
                    IllegalArgumentException,
                    RelationNotFoundException,
                    RoleNotFoundException,
                    InvalidRoleValueException,
                    RelationTypeNotFoundException

以给定关系设置给定角色。

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

通过处理引用的 MBean 注销，Relation Service 将跟踪更改来保持关系的一致性。

参数：

theRelId - 关系 id

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

抛出：

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

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果没有带给定 id 的关系

RoleNotFoundException - 如果：

- 内部关系

以及

- 角色不存在或不可写

InvalidRoleValueException - 如果为内部关系且为角色提供的值无效：

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

或者

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

或者

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

或者

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

RelationTypeNotFoundException - 如果为未知关系类型

另请参见：

getRole(java.lang.String, java.lang.String)

setRoles

RoleResult setRoles(String theRelId,
                    RoleList theRoleList)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RelationNotFoundException

以给定关系设置给定角色。

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

通过处理引用的 MBean 注销，Relation Service 跟踪更改来保持关系的一致性。

参数：

theRelId - 关系 id

theRoleList - 要设置的角色列表

返回：

RoleResult 对象，该对象包括一个 RoleList（针对成功设置的角色）和一个 RoleUnresolvedList（针对未成功设置的角色）。

抛出：

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

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果没有带给定 id 的关系

另请参见：

getRoles(java.lang.String, java.lang.String[])

getReferencedMBeans

Map getReferencedMBeans(String theRelId)
                        throws IllegalArgumentException,
                               RelationNotFoundException

检索关系的各种角色中引用的 MBean。

参数：

theRelId - 关系 id

返回：

一个 HashMap 映射：

ObjectName -> ArrayList of String（角色名）

抛出：

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果不存在给定关系 id 的关系

getRelationTypeName

String getRelationTypeName(String theRelId)
                           throws IllegalArgumentException,
                                  RelationNotFoundException

返回给定关系的相关关系类型的名称。

参数：

theRelId - 关系 id

返回：

相关关系类型的名称。

抛出：

IllegalArgumentException - 如果是 null 参数

RelationNotFoundException - 如果不存在给定关系 id 的关系