javax.management.relation
Interface Relation

All Known Subinterfaces:

RelationSupportMBean (src)

All Known Implementing Classes:

RelationSupport (src)

public interface Relation

This interface is implemented by an MBean that represents a relation.

Relations with only roles can be created by the relation service using a RelationSupport (src) object.

More complicated relations have to implemented manually. The RelationSupport (src) can be used to help in the implementation.

Any properties or methods must be exposed for management by the implementing MBean.

getRole

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

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.

Parameters:

roleName - the role name.

Returns:

the role.

Throws:

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

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

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

getRoles

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

Retrieves the roles in this relation with the passed names.

Parameters:

roleNames - an array of role names

Returns:

the roles both resolved and unresolved.

Throws:

java.lang.IllegalArgumentException - for a null role names.

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

getRoleCardinality

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

Retrieves the number of MBeans in a given role.

Parameters:

roleName - the role name.

Returns:

the number of MBeans.

Throws:

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

RoleNotFoundException (src) - when there is no such role.

getAllRoles

public RoleResult (src)  getAllRoles()
                       throws RelationServiceNotRegisteredException (src) 

Retrieves all the roles in this relation.

Returns:

the roles both resolved and unresolved.

Throws:

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

retrieveAllRoles

public RoleList (src)  retrieveAllRoles()

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

Returns:

the list of roles.

setRole

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

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.

Parameters:

role - the new role.

Throws:

java.lang.IllegalArgumentException - for a null role.

InvalidRoleValueException (src) - if the role is not valid.

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

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

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

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

setRoles

public RoleResult (src)  setRoles(RoleList (src)  roleList)
                    throws java.lang.IllegalArgumentException,
                           RelationServiceNotRegisteredException (src) ,
                           RelationTypeNotFoundException (src) ,
                           RelationNotFoundException (src) 

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.

Parameters:

roleList - the new roles.

Returns:

the resulting role result.

Throws:

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

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

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

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

handleMBeanUnregistration

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

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

Parameters:

objectName - the object name unregistered.

roleName - the role the containing the object.

Throws:

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

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

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

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

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

java.lang.IllegalArgumentException

getReferencedMBeans

public java.util.Map getReferencedMBeans()

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.

Returns:

the map of object names and their roles.

getRelationTypeName

public java.lang.String getRelationTypeName()

Retrieves the relation type for this relation.

Returns:

the relation type.

getRelationServiceName

public ObjectName (src)  getRelationServiceName()

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

Returns:

the relation service object name.

getRelationId

public java.lang.String getRelationId()

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

Returns:

the unique id.