javax.management.relation
Interface RelationServiceMBean

All Known Implementing Classes:

RelationService (src)

public interface RelationServiceMBean

This interface defines the management interface for a relation service.

The relation service performs the following functions:
Creating and deleting relation types and relations.
Making sure relations are consistent as defined by information in their relation types/roles.
Allowing relations to be queried.

Revisions:

20020312 Adrian Brock:

• Fixed wrong exception types thrown
• Add missing method getRoles(String, String[])

isActive

public void isActive()
              throws RelationServiceNotRegisteredException (src) 

Checks whether the relation service is active, i.e. it is registered with an MBeanServer.

Throws:

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

getPurgeFlag

public boolean getPurgeFlag()

Retrieves the purge flag. This flag controls whether all relations have to validated when notification is received of an MBeans unregistration or whether the purgeRelations() method has to be called.

Returns:

true for an immediate purge on unregistration, false otherwise.

setPurgeFlag

public void setPurgeFlag(boolean value)

Sets the purge flag. This flag controls whether all relations have to validated when notification is received of an MBeans unregistration or whether the purgeRelations() method has to be called.

Parameters:

value - true for an immediate purge on unregistration, false otherwise.

createRelationType

public void createRelationType(java.lang.String relationTypeName,
                               RoleInfo (src) [] roleInfos)
                        throws java.lang.IllegalArgumentException,
                               InvalidRelationTypeException (src) 

Create a relation type within the relation service.

Parameters:

relationTypeName - the relation type name.

roleInfos - an array of role infos.

Throws:

java.lang.IllegalArgumentException - for a null relation type.

InvalidRelationTypeException (src) - if a relation type already exists in the relation service with the given name, there are problems with the role infos.

addRelationType

public void addRelationType(RelationType (src)  relationType)
                     throws java.lang.IllegalArgumentException,
                            InvalidRelationTypeException (src) 

Add a relation type to the relation service.

Parameters:

relationType - the relation type.

Throws:

java.lang.IllegalArgumentException - for a null relation type.

InvalidRelationTypeException (src) - if a relation type already exists in the relation service with the given name.

getAllRelationTypeNames

public java.util.List getAllRelationTypeNames()

Retrieves all the relation type names.

Returns:

an ArrayList of relation type names

getRoleInfos

public java.util.List getRoleInfos(java.lang.String relationTypeName)
                            throws java.lang.IllegalArgumentException,
                                   RelationTypeNotFoundException (src) 

Retrieves all the role information for a given relation type.

Parameters:

relationTypeName - the relation type name

Returns:

an ArrayList of role information.

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationTypeNotFoundException (src) - when the relation id does not exist.

getRoleInfo

public RoleInfo (src)  getRoleInfo(java.lang.String relationTypeName,
                            java.lang.String roleInfoName)
                     throws java.lang.IllegalArgumentException,
                            RelationTypeNotFoundException (src) ,
                            RoleInfoNotFoundException (src) 

Retrieves the role information for a given relation type.

Parameters:

relationTypeName - the relation type name

roleInfoName - the role information name

Returns:

the role information.

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationTypeNotFoundException (src) - when the relation type does not exist.

RoleInfoNotFoundException (src) - when the role information does not exist for the relation type.

removeRelationType

public void removeRelationType(java.lang.String relationTypeName)
                        throws RelationServiceNotRegisteredException (src) ,
                               java.lang.IllegalArgumentException,
                               RelationTypeNotFoundException (src) 

Removes a relation type from the relation service.

Any relations using this relation type are also removed.

Parameters:

relationTypeName - the relation type name

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationTypeNotFoundException (src) - when the relation type does not exist.

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

createRelation

public void createRelation(java.lang.String relationId,
                           java.lang.String relationTypeName,
                           RoleList (src)  roleList)
                    throws RelationServiceNotRegisteredException (src) ,
                           java.lang.IllegalArgumentException,
                           RoleNotFoundException (src) ,
                           InvalidRelationIdException (src) ,
                           RelationTypeNotFoundException (src) ,
                           InvalidRoleValueException (src) 

Create a simple relation using RelationSupport (src) for a relation type within the relation service.

Roles not initialised are set to an empty ArrayList.

A RELATION_BASIC_CREATION notification is sent.

Parameters:

relationId - the relation id of the relation

relationTypeName - the relation type of the relation

roleList - the roles to initialise in the relation (can be null)

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationServiceNotRegisteredException (src) - when the relation service is not registered with the MBeanServer.

InvalidRelationIdException (src) - if the relation id is already used by another relation.

RelationTypeNotFoundException (src) - if there is no relation type in the relation or the relation type has not been registered with the relation service.

InvalidRoleValueException (src) - if the number of MBeans in a role is outside the bounds of the RoleInfo defined in the relation type, one of the MBeans is not of the correct class, an MBean does not exist, the same role name is used in two different relations.

RoleNotFoundException (src) - if a role in the relation is not in the relation type.

addRelation

public void addRelation(ObjectName (src)  relation)
                 throws java.lang.IllegalArgumentException,
                        RelationServiceNotRegisteredException (src) ,
                        java.lang.NoSuchMethodException,
                        InvalidRelationIdException (src) ,
                        InstanceNotFoundException (src) ,
                        InvalidRelationServiceException (src) ,
                        RelationTypeNotFoundException (src) ,
                        RoleNotFoundException (src) ,
                        InvalidRoleValueException (src) 

Add a manually created relation to the relation service. It must be registered with the same MBeanService as the relation service.

A RELATION_MBEAN_CREATION notification is sent.

Parameters:

relation - the object name of the relation

Throws:

java.lang.IllegalArgumentException - for a null object name.

java.lang.NoSuchMethodException - if the mbean does not implement the Relation interface.

RelationServiceNotRegisteredException (src) - when the relation service is not registered with the MBeanServer.

InstanceNotFoundException (src) - when the relation is not registered in the MBeanServer.

InvalidRelationIdException (src) - if the relation id is already used by another relation.

InvalidRelationServiceException (src) - if the relation service in the relation is null or is not the relation service to which it is being added.

RelationTypeNotFoundException (src) - if there is no relation type in the relation or the relation type has not been registered with the relation service.

InvalidRoleValueException (src) - if the number of MBeans in a role is outside the bounds of the RoleInfo defined in the relation type, one of the MBeans is not of the correct class or an MBean does not exist.

RoleNotFoundException (src) - if a role in the relation is not in the relation type.

isRelationMBean

public ObjectName (src)  isRelationMBean(java.lang.String relationId)
                           throws java.lang.IllegalArgumentException,
                                  RelationNotFoundException (src) 

Checks whether the passed relation id is an MBean created by a user or has been internally created by the relation service.

Parameters:

relationId - the relation id to check

Returns:

the object name of the MBean when it is externally created, null otherwise.

Throws:

java.lang.IllegalArgumentException - for a null object name.

RelationNotFoundException (src) - when the relation id does not exist.

isRelation

public java.lang.String isRelation(ObjectName (src)  objectName)
                            throws java.lang.IllegalArgumentException

Checks whether the passed object name is a relation in this relation service.

Parameters:

objectName - the name of the MBean to check

Returns:

the relation id the MBean is registered as, or null when not registered.

Throws:

java.lang.IllegalArgumentException - for a null object name.

hasRelation

public java.lang.Boolean hasRelation(java.lang.String relationId)
                              throws java.lang.IllegalArgumentException

Checks whether the relation service has the passed relation id.

Parameters:

relationId - the relation id

Returns:

true when it has the relationId, false otherwise.

Throws:

java.lang.IllegalArgumentException - for a null parameter.

getAllRelationIds

public java.util.List getAllRelationIds()

Retrieves all the relation ids.

Returns:

an ArrayList of relation ids.

checkRoleReading

public java.lang.Integer checkRoleReading(java.lang.String roleName,
                                          java.lang.String relationTypeName)
                                   throws java.lang.IllegalArgumentException,
                                          RelationTypeNotFoundException (src) 

Checks whether the passed role can be read in the given relation type.

The return value is either zero when readable or a value from RoleStatus (src) .

Parameters:

roleName - the name of the role to check.

relationTypeName - the relation type to check.

Returns:

the result described above.

Throws:

java.lang.IllegalArgumentException - for a null parameters.

RelationTypeNotFoundException (src) - if the relation type does exist in the relation service.

checkRoleWriting

public java.lang.Integer checkRoleWriting(Role (src)  role,
                                          java.lang.String relationTypeName,
                                          java.lang.Boolean initFlag)
                                   throws java.lang.IllegalArgumentException,
                                          RelationTypeNotFoundException (src) 

Checks whether the passed role can be written in the given relation type.

The return value is either zero when writable or a value from RoleStatus (src) .

Parameters:

role - the role to check.

relationTypeName - the relation type to check.

initFlag - write access is not check when this flag is true.

Returns:

the result described above.

Throws:

java.lang.IllegalArgumentException - for a null parameters.

RelationTypeNotFoundException (src) - if the relation type does exist in the relation service.

sendRelationCreationNotification

public void sendRelationCreationNotification(java.lang.String relationId)
                                      throws java.lang.IllegalArgumentException,
                                             RelationNotFoundException (src) 

Sends a relation creation notification

For internally created relations, a RELATION_BASIC_CREATION notification is sent.

For externally created relations, a RELATION_MBEAN_CREATION notification is sent.

The source is this relation service.

This method is called by addRelation() and createRelation()

Parameters:

relationId - the relation id

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationNotFoundException (src) - when the relation id does not exist.

sendRoleUpdateNotification

public void sendRoleUpdateNotification(java.lang.String relationId,
                                       Role (src)  newRole,
                                       java.util.List oldRoleValue)
                                throws java.lang.IllegalArgumentException,
                                       RelationNotFoundException (src) 

Sends a relation update notification

For internally created relations, a RELATION_BASIC_UPDATE notification is sent.

For externally created relations, a RELATION_MBEAN_UPDATE notification is sent.

The source is this relation service.

This method is called from the RelationSupport setRole() and setRoles() methods.

Parameters:

relationId - the relation id

newRole - the new role

oldRoleValue - a list of MBeans in the old role

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationNotFoundException (src) - when the relation id does not exist.

sendRelationRemovalNotification

public void sendRelationRemovalNotification(java.lang.String relationId,
                                            java.util.List unregMBeans)
                                     throws java.lang.IllegalArgumentException,
                                            RelationNotFoundException (src) 

Sends a relation removal notification

For internally created relations, a RELATION_BASIC_REMOVAL notification is sent.

For externally created relations, a RELATION_MBEAN_REMOVAL notification is sent.

The source is this relation service.

This method is called by removeRelation()

Parameters:

relationId - the relation id

unregMBeans - a list of MBeans to be unregistered due to this removal (can be null)

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationNotFoundException (src) - when the relation id does not exist.

updateRoleMap

public void updateRoleMap(java.lang.String relationId,
                          Role (src)  newRole,
                          java.util.List oldRoleValue)
                   throws java.lang.IllegalArgumentException,
                          RelationServiceNotRegisteredException (src) ,
                          RelationNotFoundException (src) 

Handles the update of the relation service role map when a role is changed.

It is called from RelationSupport setRole() and setRoles() and the relation service's setRole() and setRoles() methods.

The relation service will keep track the MBeans unregistration to maintain the consistency of the relation.

Parameters:

relationId - the relation id

newRole - the new role

oldRoleValue - a list of MBeans in the old role

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationNotFoundException (src) - when the relation id does not exist.

RelationServiceNotRegisteredException (src) - when the relation service has not been registered with an MBeanServer

removeRelation

public void removeRelation(java.lang.String relationId)
                    throws RelationServiceNotRegisteredException (src) ,
                           java.lang.IllegalArgumentException,
                           RelationNotFoundException (src) 

Removes a relation from the relation service.

For internally created relations, a RELATION_BASIC_REMOVAL notification is sent.

For externally created relations, a RELATION_MBEAN_REMOVAL notification is sent.

The MBeans referenced in the relation are unaffected.

Parameters:

relationId - the relation id

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationNotFoundException (src) - when the relation id does not exist.

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

purgeRelations

public void purgeRelations()
                    throws RelationServiceNotRegisteredException (src) 

Purge relations. This method is called automatically when the purge flag is true and an MBean in a relation is unregistered.

Not purging relations automatically can lead to problems when the same object name is reused.

If the unregistration causes a role to go below its minimal cardinality, the relation is removed. Otherwise the relation's handleMBeanUnregistration() is called.

Throws:

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

findReferencingRelations

public java.util.Map findReferencingRelations(ObjectName (src)  mbeanName,
                                              java.lang.String relationTypeName,
                                              java.lang.String roleName)
                                       throws java.lang.IllegalArgumentException

Retrieves MBeans referencing the passed MBean in the passed relation type and role.

Parameters:

mbeanName - the name of the referenced MBean

relationTypeName - the relation type, null means check all relation types.

roleName - the role, null means check all roles.

Returns:

a HashMap with keys of the referencing MBeans with the value for each MBean an ArrayList of Relation Types.

Throws:

java.lang.IllegalArgumentException - for a null object name.

findAssociatedMBeans

public java.util.Map findAssociatedMBeans(ObjectName (src)  mbeanName,
                                          java.lang.String relationTypeName,
                                          java.lang.String roleName)
                                   throws java.lang.IllegalArgumentException

Retrieves MBeans associated with the passed MBean in the passed relation type and role.

Parameters:

mbeanName - the name of the reference MBean

relationTypeName - the relation type, null means check all relation types.

roleName - the role, null means check all roles.

Returns:

a HashMap with keys of the related MBeans with the value for each MBean an ArrayList of Relation Types.

Throws:

java.lang.IllegalArgumentException - for a null object name.

findRelationsOfType

public java.util.List findRelationsOfType(java.lang.String relationTypeName)
                                   throws java.lang.IllegalArgumentException,
                                          RelationTypeNotFoundException (src) 

Retrieves the relation ids for relations of the passed type.

Parameters:

relationTypeName - the relation type.

Returns:

an ArrayList of relation ids.

Throws:

java.lang.IllegalArgumentException - for a null relation type name.

RelationTypeNotFoundException (src) - if there is no relation type with the passed name.

getRole

public java.util.List getRole(java.lang.String relationId,
                              java.lang.String roleName)
                       throws RelationServiceNotRegisteredException (src) ,
                              java.lang.IllegalArgumentException,
                              RelationNotFoundException (src) ,
                              RoleNotFoundException (src) 

Retrieves MBeans in a role for a given relation id.

Parameters:

relationId - the relation id

roleName - the role name

Returns:

an ArrayList of object names for mbeans in the role.

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationNotFoundException (src) - when the relation id does not exist.

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

RoleNotFoundException (src) - when the role does not exist or is not readable.

getRoles

public RoleResult (src)  getRoles(java.lang.String relationId,
                           java.lang.String[] roleNames)
                    throws RelationServiceNotRegisteredException (src) ,
                           java.lang.IllegalArgumentException,
                           RelationNotFoundException (src) 

Retrieves selected roles for a relation.

Parameters:

relationId - the relation id

roleNames - an array of role name

Returns:

a RoleResult containing resolved and unresolved roles.

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationNotFoundException (src) - when the relation id does not exist.

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

getAllRoles

public RoleResult (src)  getAllRoles(java.lang.String relationId)
                       throws java.lang.IllegalArgumentException,
                              RelationNotFoundException (src) ,
                              RelationServiceNotRegisteredException (src) 

Retrieves all the roles for a given relation id.

Parameters:

relationId - the relation id

Returns:

a RoleResult with a RoleList for readable roles and a RoleUnresolvedList for roles that are not readable.

Throws:

java.lang.IllegalArgumentException - for a null relation id.

RelationNotFoundException (src) - when the relation id does not exist.

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

getRoleCardinality

public java.lang.Integer getRoleCardinality(java.lang.String relationId,
                                            java.lang.String roleName)
                                     throws java.lang.IllegalArgumentException,
                                            RelationNotFoundException (src) ,
                                            RoleNotFoundException (src) 

Retrieves the number of MBeans in a role for a given relation id.

Parameters:

relationId - the relation id

roleName - the role name

Returns:

the number of mbeans in the role

Throws:

java.lang.IllegalArgumentException - for a null parameter.

RelationNotFoundException (src) - when the relation id does not exist.

RoleNotFoundException (src) - when the role does not exist or is not readable.

setRole

public void setRole(java.lang.String relationId,
                    Role (src)  role)
             throws RelationServiceNotRegisteredException (src) ,
                    java.lang.IllegalArgumentException,
                    RelationNotFoundException (src) ,
                    RoleNotFoundException (src) ,
                    InvalidRoleValueException (src) ,
                    RelationTypeNotFoundException (src) 

Sets the role in the passed relation.

The role will be validated according to information in the relation type.

The relation service will keep track the MBeans unregistration to maintain the consistency of the relation.

Parameters:

relationId - the relation to change the role for.

role - the new role

Throws:

java.lang.IllegalArgumentException - for null parameters

RelationServiceNotRegisteredException (src) - when the relation service has not been registered with an MBeanServer

RelationNotFoundException (src) - when the relation does not exist in the relation service.

RoleNotFoundException (src) - when this is an internal relation or the role does not exist or it is not writable.

InvalidRoleValueException (src) - when the role is not valid according to information in the relation type.

RelationTypeNotFoundException (src) - if the relation type is not known.

setRoles

public RoleResult (src)  setRoles(java.lang.String relationId,
                           RoleList (src)  roles)
                    throws RelationServiceNotRegisteredException (src) ,
                           java.lang.IllegalArgumentException,
                           RelationNotFoundException (src) 

Sets the roles in the passed relation.

The roles will be validated according to information in the relation type.

The relation service will keep track the MBeans unregistration to maintain the consistency of the relation.

Parameters:

relationId - the relation to change the role for.

roles - the list of roles

Throws:

java.lang.IllegalArgumentException - for null parameters

RelationServiceNotRegisteredException (src) - when the relation service has not been registered with an MBeanServer

RelationNotFoundException (src) - when the relation does not exist in the relation service.

getReferencedMBeans

public java.util.Map getReferencedMBeans(java.lang.String relationId)
                                  throws java.lang.IllegalArgumentException,
                                         RelationNotFoundException (src) 

Retrieves all the MBeans referenced in all the roles of a relation.

Parameters:

relationId - the relation id

Returns:

a HashMap with a key of the MBeans and the values an array list of the role names for each MBean.

Throws:

java.lang.IllegalArgumentException - for a null relation id.

RelationNotFoundException (src) - when the relation id does not exist.

getRelationTypeName

public java.lang.String getRelationTypeName(java.lang.String relationId)
                                     throws java.lang.IllegalArgumentException,
                                            RelationNotFoundException (src) 

Retrieves the relation type name for the passed relation.

Parameters:

relationId - the relation id

Returns:

the relation type name.

Throws:

java.lang.IllegalArgumentException - for a null relation id.

RelationNotFoundException (src) - when the relation id does not exist.