javax.management.relation
类 RelationSupport

java.lang.Object
  javax.management.relation.RelationSupport

所有已实现的接口：

MBeanRegistration, Relation, RelationSupportMBean

public class RelationSupport
extends Object
implements RelationSupportMBean, MBeanRegistration

RelationSupport 对象由 Relation Service 内部使用，表示任何关系型的具有不限数量的角色的简单关系（只有角色，没有属性或方法）。作为内部表示形式，不会将它向用户公开。

RelationSupport 类遵循标准的 MBean 设计模式。因此，用户可以决定将 RelationSupport 对象本身实例化为 MBean（因为它遵循 MBean 设计模式），以便在 MBean Server 中注册，然后将其添加到 Relation Service 中。

用户还可以在创建自己的 MBean 关系类时让其扩展 RelationSupport，以检索所需接口的实现（请参见下面内容）。

它还可以在用户关系 MBean 类中让一个成员成为 RelationSupport 对象，并通过将所有接口委托给此成员来实现所需接口。

RelationSupport 实现 Relation 接口（将由 Relation Service 处理）。

它还实现 MBeanRegistration 接口，以便能够检索它在其中注册的 MBean Server（如果注册为 MBean），从而访问其 Relation Service。

从以下版本开始：

1.5

构造方法摘要

RelationSupport(String theRelId, ObjectName theRelServiceName, MBeanServer theRelServiceMBeanServer, String theRelTypeName, RoleList theRoleList)
创建对象。

RelationSupport(String theRelId, ObjectName theRelServiceName, String theRelTypeName, RoleList theRoleList)
创建对象。

方法摘要

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 使用的回调。
Boolean	isInRelationService() 返回指定该对象是否仍然由 Relation Service 处理的内部标志。
void	postDeregister() 允许 MBean 在已从 MBean 服务器注销之后执行所需要的任何操作。
void	postRegister(Boolean registrationDone) 允许 MBean 在被注册到 MBean 服务器或注销失败后执行任何所需要的操作。
void	preDeregister() 允许该 MBean 在从 MBean 服务器注销之前执行它所需要的任何操作。
ObjectName	preRegister(MBeanServer server, ObjectName name) 允许 MBean 在被注册到 MBean 服务器之前执行它所需要的任何操作。
RoleList	retrieveAllRoles() 返回关系中的所有角色，不检查读取模式。
void	setRelationServiceManagementFlag(Boolean theFlg) 指定此关系是否由 Relation Service 处理。
void	setRole(Role theRole) 设置给定的角色。
RoleResult	setRoles(RoleList theRoleList) 设置给定的角色。

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

RelationSupport

public RelationSupport(String theRelId,
                       ObjectName theRelServiceName,
                       String theRelTypeName,
                       RoleList theRoleList)
                throws InvalidRoleValueException,
                       IllegalArgumentException

创建对象。

在用户要将 RelationSupport 对象注册为 MBean 时，或者在创建扩展 RelationSupport 的用户关系 MBean 类时，必须使用此构造方法。

在 Relation Service 级别不执行任何操作，即不添加 RelationSupport 对象，也不检查提供的值是否正确。始终创建该对象，除以下情况外：

- 不提供任何强制参数

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

为了将该对象作为关系处理，务必使用 Relation Service 方法 addRelation() 将其添加到 Relation Service 中。

参数：

theRelId - 关系标识符，用来在 Relation Service 中标识关系。

期望在给定的 Relation Service 中惟一。

theRelServiceName - 将在其中注册关系的 Relation Service 的 ObjectName。

它是必需的，因为这是知道给定关系的关系类型定义的 Relation Service，所以将能够检查更新操作（集）。

theRelTypeName - 关系类型的名称。

期望已在给定的 Relation Service 中创建。

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

期望遵循相关关系类型中的关系信息。

抛出：

InvalidRoleValueException - 如果两个角色使用了同一个名称。

IllegalArgumentException - 如果所需值（Relation Service 对象名称等）未以参数形式提供。

RelationSupport

public RelationSupport(String theRelId,
                       ObjectName theRelServiceName,
                       MBeanServer theRelServiceMBeanServer,
                       String theRelTypeName,
                       RoleList theRoleList)
                throws InvalidRoleValueException,
                       IllegalArgumentException

创建对象。

在用户关系 MBean 实现期望通过委托给 RelationSupport 对象受关系支持的接口时，务必使用此构造方法。

此对象需要知道期望处理该关系的 Relation Service。所以它必须知道 Relation Service 在其中注册的 MBean Server。

按照限制，必须像期望处理它的 Relation Service 一样在同一 MBean Server 中注册关系 MBean。所以必须创建并注册用户关系 MBean，然后可以使用标识的 MBean Server 创建包装的 RelationSupport 对象。

在 Relation Service 级别不执行任何操作，即不添加 RelationSupport 对象，也不检查提供的值是否正确。始终创建该对象，除以下情况外：

- 一个所需的参数也不提供

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

为了将该对象作为关系处理，务必使用 Relation Service 方法 addRelation() 将其添加到 Relation Service 中。

参数：

theRelId - 关系标识符，用来在 Relation Service 中标识关系。

期望在给定的 Relation Service 中惟一。

theRelServiceName - 将在其中注册关系的 Relation Service 的 ObjectName。

它是必需的，因为这是知道给定关系的关系类型定义的 Relation Service，所以将能够检查更新操作（集合）。

theRelServiceMBeanServer - 该包装 MBean 在其中或将在其中注册的 MBean Server。

期望是 Relation Service 在其中或将在其中注册的 MBean Server。

theRelTypeName - 关系类型的名称。

期望已在给定的 Relation Service 中创建该名称。

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

期望遵循相关关系类型中的关系信息。

抛出：

InvalidRoleValueException - 如果两个角色使用了同一个名称。

IllegalArgumentException - 如果所需值（Relation Service 对象名称等）未以参数形式提供。

方法详细信息

getRole

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

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

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

指定者：

接口 Relation 中的 getRole

参数：

theRoleName - 角色名称

返回：

作为角色值的 ObjectName 对象的 ArrayList

抛出：

IllegalArgumentException - 如果为 null 角色名称

RoleNotFoundException - 如果：

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

- 角色不可读。

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

另请参见：

setRole(javax.management.relation.Role)

getRoles

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

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

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

指定者：

接口 Relation 中的 getRoles

参数：

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

返回：

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

抛出：

IllegalArgumentException - 如果是 null 角色名称

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

另请参见：

setRoles(javax.management.relation.RoleList)

getAllRoles

public RoleResult getAllRoles()
                       throws RelationServiceNotRegisteredException

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

指定者：

接口 Relation 中的 getAllRoles

返回：

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

抛出：

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

retrieveAllRoles

public RoleList retrieveAllRoles()

返回关系中的所有角色，不检查读取模式。

指定者：

接口 Relation 中的 retrieveAllRoles

返回：

一个 RoleList

getRoleCardinality

public Integer getRoleCardinality(String theRoleName)
                           throws IllegalArgumentException,
                                  RoleNotFoundException

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

指定者：

接口 Relation 中的 getRoleCardinality

参数：

theRoleName - 角色名称

返回：

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

抛出：

IllegalArgumentException - 如果是 null 角色名称

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

setRole

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

设置给定的角色。

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

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

指定者：

接口 Relation 中的 setRole

参数：

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

public RoleResult setRoles(RoleList theRoleList)
                    throws IllegalArgumentException,
                           RelationServiceNotRegisteredException,
                           RelationTypeNotFoundException,
                           RelationNotFoundException

设置给定的角色。

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

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

指定者：

接口 Relation 中的 setRoles

参数：

theRoleList - 要设置的角色列表

返回：

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

抛出：

IllegalArgumentException - 如果是 null 角色名称

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

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

RelationNotFoundException - 如果尚未在 Relation Service 中添加关系 MBean。

另请参见：

getRoles(java.lang.String[])

handleMBeanUnregistration

public void handleMBeanUnregistration(ObjectName theObjName,
                                      String theRoleName)
                               throws IllegalArgumentException,
                                      RoleNotFoundException,
                                      InvalidRoleValueException,
                                      RelationServiceNotRegisteredException,
                                      RelationTypeNotFoundException,
                                      RelationNotFoundException

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

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

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

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

指定者：

接口 Relation 中的 handleMBeanUnregistration

参数：

theObjName - 注销的 MBean 的 ObjectName

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

抛出：

IllegalArgumentException - 如果是 null 参数

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

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

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

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

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

getReferencedMBeans

public Map getReferencedMBeans()

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

指定者：

接口 Relation 中的 getReferencedMBeans

返回：

一个 HashMap 映射：

ObjectName -> String 的 ArrayList（角色名）

getRelationTypeName

public String getRelationTypeName()

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

指定者：

接口 Relation 中的 getRelationTypeName

返回：

关系类型的名称。

getRelationServiceName

public ObjectName getRelationServiceName()

返回处理关系的 Relation Service 的 ObjectName。

指定者：

接口 Relation 中的 getRelationServiceName

返回：

Relation Service 的 ObjectName。

getRelationId

public String getRelationId()

返回关系标识符（用于惟一标识 Relation Service 中的关系）。

指定者：

接口 Relation 中的 getRelationId

返回：

关系 id。

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

从接口 MBeanRegistration 复制的描述

允许 MBean 在被注册到 MBean 服务器之前执行它所需要的任何操作。如果未指定 MBean 的名称，则该 MBean 可以提供一个注册名称。如果引发任何异常，则该 MBean 不会被注册到 MBean 服务器中。

指定者：

接口 MBeanRegistration 中的 preRegister

参数：

server - 将要在其中注册该 MBean 的 MBean 服务器。

name - 该 MBean 的对象名。如果 MBeanServer 接口中的某个 createMBean 方法或 registerMBean 方法的 name 参数为 null，则此 name 也为 null。在这种情况下，此方法必须为新 MBean 返回非 null 的 ObjectName。

返回：

MBean 要被注册的名称。此值必须不为 null。如果 name 参数不为 null，则它通常但并非一定为返回值。

抛出：

Exception - MBean 服务器会捕捉此异常并以 MBeanRegistrationException 的形式重新抛出。

postRegister

public void postRegister(Boolean registrationDone)

从接口 MBeanRegistration 复制的描述

允许 MBean 在被注册到 MBean 服务器或注销失败后执行任何所需要的操作。

指定者：

接口 MBeanRegistration 中的 postRegister

参数：

registrationDone - 指示该 MBean 是否已在 MBean 服务器中成功注册。false 值意味着注册阶段已失败。

preDeregister

public void preDeregister()
                   throws Exception

从接口 MBeanRegistration 复制的描述

允许该 MBean 在从 MBean 服务器注销之前执行它所需要的任何操作。

指定者：

接口 MBeanRegistration 中的 preDeregister

抛出：

Exception - MBean 服务器会捕捉此异常并以 MBeanRegistrationException 的形式重新抛出。

postDeregister

public void postDeregister()

从接口 MBeanRegistration 复制的描述

允许 MBean 在已从 MBean 服务器注销之后执行所需要的任何操作。

指定者：

接口 MBeanRegistration 中的 postDeregister

isInRelationService

public Boolean isInRelationService()

返回指定该对象是否仍然由 Relation Service 处理的内部标志。

指定者：

接口 RelationSupportMBean 中的 isInRelationService

返回：

如果该对象仍然由 Relation Service 处理，则返回等于 Boolean.TRUE 的 Boolean 值；否则，返回等于 Boolean.FALSE 的 Boolean 值。

setRelationServiceManagementFlag

public void setRelationServiceManagementFlag(Boolean theFlg)
                                      throws IllegalArgumentException

从接口 RelationSupportMBean 复制的描述

指定此关系是否由 Relation Service 处理。

注意，当 Relation Service 通过其管理接口访问该关系时，此方法必须公开。强烈建议不要使用此方法。使用此方法不影响 Relation Service 中的关系对象的注册，但会提供有关它的错误信息！

指定者：

接口 RelationSupportMBean 中的 setRelationServiceManagementFlag

参数：

theFlg - 该关系是否由 Relation Service 处理的标志。

抛出：

IllegalArgumentException - 如果是 null 参数