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

Implements the management interface for a relation created internally within the relation service. The relation can have only roles - no attributes or methods.

The relation support managed bean can be created externally, including extending it, and then registered with the relation service.

Version:

$Revision: 1.14.4.3 $

Revisions:

20020412 Juha Lindfors:

• Changed MBeanProxy exception handling on create methods -- only need to catch one MBeanProxyCreationException

Author:

Adrian Brock., Juha Lindfors

Constructor Summary

RelationSupport(String relationId, ObjectName relationService, MBeanServer mbeanServer, String relationTypeName, RoleList roleList)
Construct a new relation support object.

RelationSupport(String relationId, ObjectName relationService, String relationTypeName, RoleList roleList)
Construct a new relation support object.

Method Summary

RoleResult	getAllRoles() Retrieves all the roles in this relation.
Map	getReferencedMBeans() Retrieves MBeans referenced by roles of this relation.
String	getRelationId() Retrieves the relation id used to identify the relation within the relation service.
ObjectName	getRelationServiceName() Retrieves the object name of the relation service this relation is registered with.
String	getRelationTypeName() Retrieves the relation type for this relation.
List	getRole(String roleName) Retrieves the role for the passed role name.
Integer	getRoleCardinality(String roleName) Retrieves the number of MBeans in a given role.
RoleResult	getRoles(String[] roleNames) Retrieves the roles in this relation with the passed names.
void	handleMBeanUnregistration(ObjectName objectName, String roleName) The relation service will call this service when an MBean referenced in a role is unregistered.
Boolean	isInRelationService() Check to see whether this relation thinks it is in relation service.
void	postDeregister() This method is called by the MBeanServer after deregistration takes place.
void	postRegister(Boolean registered) This method is called by the MBeanServer after registration takes place or when registration fails.
void	preDeregister() This method is called by the MBeanServer before deregistration takes place.
ObjectName	preRegister(MBeanServer server, ObjectName objectName) This method is called by the MBeanServer before registration takes place.
RoleList	retrieveAllRoles() Retrieve all the roles in this relation without checking the role mode.
void	setRelationServiceManagementFlag(Boolean value) Set the flag to specify whether this relation is registered with the relation service.
void	setRole(Role role) Sets the passed role for this relation.
RoleResult	setRoles(RoleList roleList) Sets the roles.

Methods inherited from class java.lang.Object

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

Constructor Detail

RelationSupport

public RelationSupport(String relationId,
                       ObjectName relationService,
                       String relationTypeName,
                       RoleList roleList)
                throws IllegalArgumentException,
                       InvalidRoleValueException

Construct a new relation support object.

This constructor is intended for use when manually registrating a relation support object or an class that extends it.

Constructing the object does not register it with the relation service, only the following is validated at this stage.

The relation id is mandatory.
The relation service name is mandatory.
. The relation type name is mandatory.
The same name is used for more than one role.

Parameters:

relationId - the relation Id

relationService - the object name of the relation service

relationTypeName - the name of the relation type

roleList - the roles in this relation

Throws:

IllegalArgumentException - for null values.

InvalidRoleValueException - when two roles have the same name.

RelationSupport

public RelationSupport(String relationId,
                       ObjectName relationService,
                       MBeanServer mbeanServer,
                       String relationTypeName,
                       RoleList roleList)
                throws IllegalArgumentException,
                       InvalidRoleValueException

Construct a new relation support object.

This constructor is intended for use when manually registrating a relation that delegates to relation support.

Constructing the object does not register it with the relation service, only the following is validated at this stage.

The relation id is mandatory.
The relation service name is mandatory.
. The mbean service is mandatory.
. The relation type name is mandatory.
The same name is used for more than one role.

Parameters:

relationId - the relation Id

relationService - the object name of the relation service

mbeanServer - the object name of the relation service

relationTypeName - the name of the relation type

roleList - the roles in this relation

Throws:

IllegalArgumentException - for null values.

InvalidRoleValueException - when two roles have the same name.

Method Detail

getAllRoles

public RoleResult getAllRoles()
                       throws RelationServiceNotRegisteredException

Description copied from interface: Relation

Retrieves all the roles in this relation.

Specified by:

getAllRoles in interface Relation

Returns:

the roles both resolved and unresolved.

Throws:

RelationServiceNotRegisteredException - when the relation service is not registered with an MBeanServer.

getReferencedMBeans

public Map getReferencedMBeans()

Description copied from interface: Relation

Retrieves MBeans referenced by roles of this relation.

The return value is a map keyed by MBean object names. The objects are associated with an ArrayList that contains all the role names the MBean has within this relation.

Specified by:

getReferencedMBeans in interface Relation

Returns:

the map of object names and their roles.

getRelationId

public String getRelationId()

Description copied from interface: Relation

Retrieves the relation id used to identify the relation within the relation service.

Specified by:

getRelationId in interface Relation

Returns:

the unique id.

getRelationServiceName

public ObjectName getRelationServiceName()

Description copied from interface: Relation

Retrieves the object name of the relation service this relation is registered with.

Specified by:

getRelationServiceName in interface Relation

Returns:

the relation service object name.

getRelationTypeName

public String getRelationTypeName()

Description copied from interface: Relation

Retrieves the relation type for this relation.

Specified by:

getRelationTypeName in interface Relation

Returns:

the relation type.

getRole

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

Description copied from interface: Relation

Retrieves the role for the passed role name. The role must exist and be readable.

The return value is an ArrayList of object names in the role.

Specified by:

getRole in interface Relation

Parameters:

roleName - the role name.

Returns:

the role.

Throws:

IllegalArgumentException - for a null role name.

RoleNotFoundException - when there is no such role or it is not readable.

RelationServiceNotRegisteredException - when the relation service is not registered with an MBeanServer.

getRoleCardinality

public Integer getRoleCardinality(String roleName)
                           throws IllegalArgumentException,
                                  RoleNotFoundException

Description copied from interface: Relation

Retrieves the number of MBeans in a given role.

Specified by:

getRoleCardinality in interface Relation

Parameters:

roleName - the role name.

Returns:

the number of MBeans.

Throws:

IllegalArgumentException - for a null role name.

RoleNotFoundException - when there is no such role.

getRoles

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

Description copied from interface: Relation

Retrieves the roles in this relation with the passed names.

Specified by:

getRoles in interface Relation

Parameters:

roleNames - an array of role names

Returns:

the roles both resolved and unresolved.

Throws:

IllegalArgumentException - for a null role names.

RelationServiceNotRegisteredException - when the relation service is not registered with an MBeanServer.

handleMBeanUnregistration

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

Description copied from interface: Relation

The relation service will call this service when an MBean referenced in a role is unregistered.

The object name should be removed from the role.

Calling this method manually may result in incorrect behaviour

Specified by:

handleMBeanUnregistration in interface Relation

Parameters:

objectName - the object name unregistered.

roleName - the role the containing the object.

Throws:

RoleNotFoundException - if the role does exist or it is not writable.

InvalidRoleValueException - when the role does not conform to the associated role info.

RelationServiceNotRegisteredException - when the relation service is not registered with an MBeanServer.

RelationTypeNotFoundException - when the relation type has not been registered in the relation service.

RelationNotFoundException - when this method is called for for an MBean not registered with the relation service.

IllegalArgumentException

retrieveAllRoles

public RoleList retrieveAllRoles()

Description copied from interface: Relation

Retrieve all the roles in this relation without checking the role mode.

Specified by:

retrieveAllRoles in interface Relation

Returns:

the list of roles.

setRole

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

Description copied from interface: Relation

Sets the passed role for this relation.

The role is checked according to its role definition in the relation type. The role is not valid if there are the wrong number of MBeans, an MBean is of an incorrect class or an MBean does not exist.

The notification RELATION_BASIC_UPDATE is sent when the relation is not an MBean or RELATION_MBEAN_UPDATE when it is.

Specified by:

setRole in interface Relation

Parameters:

role - the new role.

Throws:

IllegalArgumentException - for a null role.

RoleNotFoundException - if the role is not writable. This test is not performed at initialisation.

RelationTypeNotFoundException - when the relation type has not been registered in the relation service.

InvalidRoleValueException - if the role is not valid.

RelationServiceNotRegisteredException - when the relation service is not registered with an MBeanServer.

RelationNotFoundException - when this method is called for for an MBean not registered with the relation service.

setRoles

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

Description copied from interface: Relation

Sets the roles.

The roles are checked according to its role definition in the relation type. The role is not valid if there are the wrong number of MBeans, an MBean is of an incorrect class or an MBean does not exist.

A notification RELATION_BASIC_UPDATE is sent when the relation is not an MBean or RELATION_MBEAN_UPDATE when it is for every updated role.

The return role result has a role list for successfully updated roles and an unresolved list for roles not set.

Specified by:

setRoles in interface Relation

Parameters:

roleList - the new roles.

Returns:

the resulting role result.

Throws:

IllegalArgumentException - for a null role name.

RelationServiceNotRegisteredException - when the relation service is not registered with an MBeanServer.

RelationTypeNotFoundException - when the relation type has not been registered in the relation service.

RelationNotFoundException - when this method is called for for an MBean not registered with the relation service.

isInRelationService

public Boolean isInRelationService()

Description copied from interface: RelationSupportMBean

Check to see whether this relation thinks it is in relation service.

WARNING: This is not a dynamic check. The flag is set within the relation support object by the relation service, malicious programs may modifiy it to an incorrect value.

Specified by:

isInRelationService in interface RelationSupportMBean

Returns:

true when it is registered.

setRelationServiceManagementFlag

public void setRelationServiceManagementFlag(Boolean value)
                                      throws IllegalArgumentException

Description copied from interface: RelationSupportMBean

Set the flag to specify whether this relation is registered with the relation service.

WARNING: This method is exposed for management by the relation service. Using this method outside of the relation service does not affect the registration with the relation service.

Specified by:

setRelationServiceManagementFlag in interface RelationSupportMBean

Parameters:

value - pass true for managed by the relation service, false otherwise.

Throws:

IllegalArgumentException - for a null value

preRegister

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

Description copied from interface: MBeanRegistration

This method is called by the MBeanServer before registration takes place. The MBean is passed a reference of the MBeanServer it is about to be registered with. The MBean must return the ObjectName it will be registered with. The MBeanServer can pass a suggested object depending upon how the MBean is registered.

The MBean can stop the registration by throwing an exception.The exception is forwarded to the invoker wrapped in an MBeanRegistrationException.

Specified by:

preRegister in interface MBeanRegistration

Returns:

the actual ObjectName to register this MBean with.

Throws:

Exception - for any error, the MBean is not registered.

postRegister

public void postRegister(Boolean registered)

Description copied from interface: MBeanRegistration

This method is called by the MBeanServer after registration takes place or when registration fails.

Specified by:

postRegister in interface MBeanRegistration

Parameters:

registered - the MBeanServer passes true when the MBean was registered, false otherwise.

preDeregister

public void preDeregister()
                   throws Exception

Description copied from interface: MBeanRegistration

This method is called by the MBeanServer before deregistration takes place.

The MBean can throw an exception, this will stop the deregistration. The exception is forwarded to the invoker wrapped in an MBeanRegistrationException.

Specified by:

preDeregister in interface MBeanRegistration

Throws:

Exception

postDeregister

public void postDeregister()

Description copied from interface: MBeanRegistration

This method is called by the MBeanServer after deregistration takes place.

Specified by:

postDeregister in interface MBeanRegistration