compact3

javax.management.relation

Class RelationSupport

java.lang.Object

javax.management.relation.RelationSupport

All Implemented Interfaces:

MBeanRegistration ， Relation ， RelationSupportMBean

public class RelationSupport
extends Object
implements RelationSupportMBean, MBeanRegistration

RelationSupport对象由Relation Service内部使用，用于表示任意关系类型的简单关系（只有角色，无属性或方法）以及无限数量的角色。 作为内部表示，它不会暴露给用户。

RelationSupport类符合标准MBean的设计模式。 因此，用户可以自己将RelationSupport对象实例化为MBean（遵循MBean设计模式），将其注册到MBean服务器中，然后将其添加到关系服务中。

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

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

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

它还实现了MBeanRegistration接口，以便能够检索其注册的MBean服务器（如果注册为MBean）以访问其关系服务。

从以下版本开始：

1.5

构造方法摘要

构造方法

Constructor and Description
RelationSupport(String relationId, ObjectName relationServiceName, MBeanServer relationServiceMBeanServer, String relationTypeName, RoleList list) 创建一个 RelationSupport对象。
RelationSupport(String relationId, ObjectName relationServiceName, String relationTypeName, RoleList list) 创建一个 RelationSupport对象。

方法摘要

Modifier and Type	Method and Description
RoleResult	getAllRoles() 返回关系中存在的所有角色。
Map<ObjectName,List<String>>	getReferencedMBeans() 检索在关系的各种角色中引用的MBean。
String	getRelationId() 返回关系标识符（用于唯一标识关系服务中的关系）。
ObjectName	getRelationServiceName() 返回处理关系的关系服务的ObjectName。
String	getRelationTypeName() 返回关联关系类型的名称。
List<ObjectName>	getRole(String roleName) 检索给定角色名称的角色值。
Integer	getRoleCardinality(String roleName) 返回当前在给定角色中引用的MBean数。
RoleResult	getRoles(String[] roleNameArray) 检索具有给定名称的角色值。
void	handleMBeanUnregistration(ObjectName objectName, String roleName) 当角色引用的MBean未注册时，关系服务使用的回调。
Boolean	isInRelationService() 返回一个内部标志，指定对象是否仍由关系服务处理。
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 flag) 指定该关系是否由关系服务处理。
void	setRole(Role role) 设置给定的角色。
RoleResult	setRoles(RoleList list) 设置给定的角色。

Methods inherited from class java.lang.Object

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

构造方法详细信息

RelationSupport

public RelationSupport(String relationId,
                       ObjectName relationServiceName,
                       String relationTypeName,
                       RoleList list)
                throws InvalidRoleValueException,
                       IllegalArgumentException

创建一个RelationSupport对象。

当RelationSupport对象将由用户注册为MBean时，或者创建类扩展了RelationSupport的用户关系MBean时，必须使用此构造函数。

在关系服务级别没有完成任何操作，即RelationSupport对象未添加到RelationService ，并且不执行检查以查看提供的值是否正确。 对象始终被创建，除非：

- 任何所需的参数是null 。

- 相同的名称用于两个角色。

要作为关系处理，必须使用关联服务方法addRelation（）将RelationSupport对象添加到关系服务。

参数

relationId - 关系标识符，用于标识关系服务中的关系。

预期在给定的关系服务中是唯一的。

relationServiceName - 该关系将被注册的关系服务的ObjectName。

该参数是必需的，因为它是关系服务，它意识到给定关系的关系类型的定义，以便能够检查更新操作（设置）。

relationTypeName - 关系类型的名称。

预计在给定的关系服务中创建。

list - 初始化关系的角色（角色对象）列表。 可以null 。

预期符合相关关系类型的关系信息。

异常

InvalidRoleValueException - 如果两个角色使用相同的名称。

IllegalArgumentException - 如果任何必需的参数（关系id，关系服务对象名称或关系类型名称）是 null 。

RelationSupport

public RelationSupport(String relationId,
                       ObjectName relationServiceName,
                       MBeanServer relationServiceMBeanServer,
                       String relationTypeName,
                       RoleList list)
                throws InvalidRoleValueException,
                       IllegalArgumentException

创建一个RelationSupport对象。

当用户关系MBean通过委托RelationSupport对象实现期望由关系支持的接口时，必须使用此构造函数。

此对象需要知道关系服务预期处理关系。 所以它必须知道关系服务注册的MBean服务器。

根据限制，必须在与预期处理它的关系服务相同的MBean服务器中注册关系MBean。 因此，必须创建和注册用户关系MBean，然后可以在已识别的MBean服务器内创建包装的RelationSupport对象。

在关系服务级别没有完成任何操作，即RelationSupport对象未添加到RelationService ，并且不执行检查以查看提供的值是否正确。 对象始终被创建，除非：

- 任何必需的参数是null 。

- 相同的名称用于两个角色。

要作为关系处理，必须使用关系服务方法addRelation（）将RelationSupport对象添加到关系服务。

参数

relationId - 关系标识符，用于标识关系服务中的关系。

预期在给定的关系服务中是唯一的。

relationServiceName - 该关系将被注册的关系服务的ObjectName。

该参数是必需的，因为它是关系服务，它意识到给定关系的关系类型的定义，以便能够检查更新操作（设置）。

relationServiceMBeanServer - MBean包装MBean是或将被注册的服务器。

预期是关系服务是或将被注册的MBean服务器。

relationTypeName - 关系类型的名称。

预计在给定的关系服务中创建。

list - 初始化关系的角色列表（Role Objects）。 可以null 。

预期符合相关关系类型的关系信息。

异常

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

IllegalArgumentException - 如果任何必需的参数（关系id，关系服务对象名称，关系服务MBeanServer或关系类型名称）是 null 。

方法详细信息

getRole

public List<ObjectName> getRole(String roleName)
                         throws IllegalArgumentException,
                                RoleNotFoundException,
                                RelationServiceNotRegisteredException

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

检查角色是否存在，并根据关系类型可读。

Specified by:

getRole在接口 Relation

参数

roleName - 角色名称

结果

ObjectName对象的ArrayList是角色值

异常

IllegalArgumentException - 如果为null角色名称

RoleNotFoundException - 如果：

- 给定名字没有任何作用

- 角色不可读。

RelationServiceNotRegisteredException - 如果关系服务未在MBean服务器中注册

另请参见：

setRole(javax.management.relation.Role)

getRoles

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

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

检查每个角色是否存在，并根据关系类型可读。

Specified by:

getRoles在接口 Relation

参数

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

结果

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

异常

IllegalArgumentException - 如果为null角色名称

RelationServiceNotRegisteredException - 如果关系服务未在MBean服务器中注册

另请参见：

setRoles(javax.management.relation.RoleList)

getAllRoles

public RoleResult getAllRoles()
                       throws RelationServiceNotRegisteredException

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

Specified by:

getAllRoles在接口 Relation

结果

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

异常

RelationServiceNotRegisteredException - 如果关系服务未在MBean服务器中注册

retrieveAllRoles

public RoleList retrieveAllRoles()

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

Specified by:

retrieveAllRoles在接口 Relation

结果

一个RoleList

getRoleCardinality

public Integer getRoleCardinality(String roleName)
                           throws IllegalArgumentException,
                                  RoleNotFoundException

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

Specified by:

getRoleCardinality在界面 Relation

参数

roleName - 角色名称

结果

该角色中当前引用的MBean的数量

异常

IllegalArgumentException - 如果为null角色名称

RoleNotFoundException - 如果没有给定名称的角色

setRole

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

设置给定的角色。

将根据其在关系类型中提供的相应角色定义来检查角色

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

Specified by:

setRole在界面 Relation

参数

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

异常

IllegalArgumentException - 如果为null角色

RoleNotFoundException - 如果所提供角色的名称没有角色或角色不可写（在初始化角色时执行的写入访问模式没有测试）

InvalidRoleValueException - 如果为角色提供的值无效，即：

- 给定值中引用的MBean的数量小于预期的最小度

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

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

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

RelationServiceNotRegisteredException - 如果关系服务未在MBean服务器中注册

RelationTypeNotFoundException - 如果关系类型尚未在关系服务中声明

RelationNotFoundException - 如果关系尚未添加到关系服务中。

另请参见：

getRole(java.lang.String)

setRoles

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

设置给定的角色。

将根据其在关系类型中提供的相应角色定义来检查角色

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

Specified by:

setRoles在接口 Relation

参数

list - 要设置的角色列表

结果

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

异常

IllegalArgumentException - 如果为空角色列表

RelationServiceNotRegisteredException - 如果关系服务未在MBean服务器中注册

RelationTypeNotFoundException - 如果关系类型尚未在关系服务中声明。

RelationNotFoundException - 如果关系MBean尚未添加在关系服务中。

另请参见：

getRoles(java.lang.String[])

handleMBeanUnregistration

public void handleMBeanUnregistration(ObjectName objectName,
                                      String roleName)
                               throws IllegalArgumentException,
                                      RoleNotFoundException,
                                      InvalidRoleValueException,
                                      RelationServiceNotRegisteredException,
                                      RelationTypeNotFoundException,
                                      RelationNotFoundException

当角色引用的MBean未注册时，关系服务使用的回调。

关系服务将称之为这种方法，让关系采取行动来反映这种注册的影响。

谨防。 用户不期望调用此方法。

当前实现是使用其当前值（引用的MBean的ObjectNames列表）设置角色，而不注册未注册的值。

Specified by:

handleMBeanUnregistration在接口 Relation

参数

objectName - 未注册的MBean的ObjectName

roleName - roleName MBean的角色名称

异常

IllegalArgumentException - 如果为空参数

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

InvalidRoleValueException - 如果角色值不符合关联的角色信息（当从关系服务调用时，这将永远不会发生）

RelationServiceNotRegisteredException - 如果关系服务未在MBean服务器中注册

RelationTypeNotFoundException - 如果关系类型尚未在关系服务中声明。

RelationNotFoundException - 如果为在关系服务中未添加的关系MBean调用此方法。

getReferencedMBeans

public Map<ObjectName,List<String>> getReferencedMBeans()

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

Specified by:

getReferencedMBeans在接口 Relation

结果

一个HashMap映射：

ObjectName - > ArrayList的String（角色名称）

getRelationTypeName

public String getRelationTypeName()

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

Specified by:

getRelationTypeName在接口 Relation

结果

关系类型的名称。

getRelationServiceName

public ObjectName getRelationServiceName()

返回处理关系的关系服务的ObjectName。

Specified by:

getRelationServiceName在界面 Relation

结果

关系服务的ObjectName。

getRelationId

public String getRelationId()

返回关系标识符（用于唯一标识关系服务中的关系）。

Specified by:

getRelationId在界面 Relation

结果

关系id。

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws 异常

说明从界面复制： MBeanRegistration

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

Specified by:

preRegister在界面 MBeanRegistration

参数

server - MBean将被注册的MBean服务器。

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

结果

要注册MBean的名称。 此值不能为空。 如果name参数不为空，通常不一定是返回值。

异常

异常 - 这个异常将被MBean服务器捕获，并重新抛出为MBeanRegistrationException 。

postRegister

public void postRegister(Boolean registrationDone)

从接口复制： MBeanRegistration

允许MBean在MBean服务器中注册或注册失败后执行所需的操作。

如果此方法的实现抛出一个RuntimeException或Error ，则MBean服务器的重新抛出那些内部RuntimeMBeanException或RuntimeErrorException分别。 但是，在postRegister中postRegister将不会更改MBean的状态：如果MBean已经注册（ registrationDone是true ），那么MBean将保持注册。

这可能会导致调用createMBean()或registerMBean()的代码createMBean() registerMBean() ，因为这样的代码可能会假设在引发异常时MBean注册失败。 因此，建议的实现postRegister不抛出运行时异常或错误，如果能够避免它。

Specified by:

postRegister在接口 MBeanRegistration

参数

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

preDeregister

public void preDeregister()
                   throws 异常

说明从界面： MBeanRegistration复制

允许MBean在MBean服务器取消注册之前执行所需的任何操作。

Specified by:

preDeregister中的 MBeanRegistration

异常

异常 - 此异常将被MBean服务器捕获，并重新抛出为MBeanRegistrationException 。

postDeregister

public void postDeregister()

说明从界面： MBeanRegistration复制

允许MBean在MBean服务器中取消注册后执行所需的任何操作。

如果这种方法的实现会引发一个RuntimeException或Error ，那么MBean服务器将分别推出RuntimeMBeanException或RuntimeErrorException内的那些。 然而，在postDeregister中postDeregister将不会改变MBean的状态：MBean已经成功注销，并将保持不变。

这可能会使代码调用unregisterMBean() ，因为它可能会假设MBean注销失败。 因此，建议的实现postDeregister不抛出运行时异常或错误，如果能够避免它。

Specified by:

postDeregister在接口 MBeanRegistration

isInRelationService

public Boolean isInRelationService()

返回一个内部标志，指定对象是否仍由关系服务处理。

Specified by:

isInRelationService在接口 RelationSupportMBean

结果

一个布尔值等于 Boolean.TRUE，如果对象仍然由关系服务处理， 否则为 Boolean.FALSE。

setRelationServiceManagementFlag

public void setRelationServiceManagementFlag(Boolean flag)
                                      throws IllegalArgumentException

说明从界面复制： RelationSupportMBean

指定该关系是否由关系服务处理。

BEWARE，该方法必须被公开，因为关系服务将通过其管理界面访问该关系。 建议不要使用这种方法。 使用它不影响关系对象在关系服务中的注册，但会提供错误的信息！

Specified by:

setRelationServiceManagementFlag在界面 RelationSupportMBean

参数

flag - 关系是否由关系服务处理。

异常

IllegalArgumentException - if null parameter