FileDocCategorySizeDatePackage
Relation.javaAPI DocJava SE 6 API9559Tue Jun 10 00:26:16 BST 2008javax.management.relation

Relation

public interface Relation
This interface has to be implemented by any MBean class expected to represent a relation managed using the Relation Service.

Simple relations, i.e. having only roles, no properties or methods, can be created directly by the Relation Service (represented as RelationSupport objects, internally handled by the Relation Service).

If the user wants to represent more complex relations, involving properties and/or methods, he has to provide his own class implementing the Relation interface. This can be achieved either by inheriting from RelationSupport class, or by implementing the interface (fully or delegation to a RelationSupport object member).

Specifying such user relation class is to introduce properties and/or methods. Those have to be exposed for remote management. So this means that any user relation class must be a MBean class.

since
1.5

Fields Summary
Constructors Summary
Methods Summary
public javax.management.relation.RoleResultgetAllRoles()
Returns all roles present in the relation.

return
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not readable).
exception
RelationServiceNotRegisteredException if the Relation Service is not registered in the MBean Server

public java.util.MapgetReferencedMBeans()
Retrieves MBeans referenced in the various roles of the relation.

return
a HashMap mapping:

ObjectName -> ArrayList of String (role names)

public java.lang.StringgetRelationId()
Returns relation identifier (used to uniquely identify the relation inside the Relation Service).

return
the relation id.

public javax.management.ObjectNamegetRelationServiceName()
Returns ObjectName of the Relation Service handling the relation.

return
the ObjectName of the Relation Service.

public java.lang.StringgetRelationTypeName()
Returns name of associated relation type.

return
the name of the relation type.

public java.util.ListgetRole(java.lang.String roleName)
Retrieves role value for given role name.

Checks if the role exists and is readable according to the relation type.

param
roleName name of role
return
the ArrayList of ObjectName objects being the role value
exception
IllegalArgumentException if null role name
exception
RoleNotFoundException if:

- there is no role with given name

- the role is not readable.

exception
RelationServiceNotRegisteredException if the Relation Service is not registered in the MBean Server
see
#setRole

public java.lang.IntegergetRoleCardinality(java.lang.String roleName)
Returns the number of MBeans currently referenced in the given role.

param
roleName name of role
return
the number of currently referenced MBeans in that role
exception
IllegalArgumentException if null role name
exception
RoleNotFoundException if there is no role with given name

public javax.management.relation.RoleResultgetRoles(java.lang.String[] roleNameArray)
Retrieves values of roles with given names.

Checks for each role if it exists and is readable according to the relation type.

param
roleNameArray array of names of roles to be retrieved
return
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not retrieved).
exception
IllegalArgumentException if null role name
exception
RelationServiceNotRegisteredException if the Relation Service is not registered in the MBean Server
see
#setRoles

public voidhandleMBeanUnregistration(javax.management.ObjectName objectName, java.lang.String roleName)
Callback used by the Relation Service when a MBean referenced in a role is unregistered.

The Relation Service will call this method to let the relation take action to reflect the impact of such unregistration.

BEWARE. the user is not expected to call this method.

Current implementation is to set the role with its current value (list of ObjectNames of referenced MBeans) without the unregistered one.

param
objectName ObjectName of unregistered MBean
param
roleName name of role where the MBean is referenced
exception
IllegalArgumentException if null parameter
exception
RoleNotFoundException if role does not exist in the relation or is not writable
exception
InvalidRoleValueException if role value does not conform to the associated role info (this will never happen when called from the Relation Service)
exception
RelationServiceNotRegisteredException if the Relation Service is not registered in the MBean Server
exception
RelationTypeNotFoundException if the relation type has not been declared in the Relation Service.
exception
RelationNotFoundException if this method is called for a relation MBean not added in the Relation Service.

public javax.management.relation.RoleListretrieveAllRoles()
Returns all roles in the relation without checking read mode.

return
a RoleList.

public voidsetRole(javax.management.relation.Role role)
Sets the given role.

Will check the role according to its corresponding role definition provided in relation's relation type

Will send a notification (RelationNotification with type RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the relation is a MBean or not).

param
role role to be set (name and new value)
exception
IllegalArgumentException if null role
exception
RoleNotFoundException if there is no role with the supplied role's name or if the role is not writable (no test on the write access mode performed when initializing the role)
exception
InvalidRoleValueException if value provided for role is not valid, i.e.:

- the number of referenced MBeans in given value is less than expected minimum degree

- the number of referenced MBeans in provided value exceeds expected maximum degree

- one referenced MBean in the value is not an Object of the MBean class expected for that role

- a MBean provided for that role does not exist.

exception
RelationServiceNotRegisteredException if the Relation Service is not registered in the MBean Server
exception
RelationTypeNotFoundException if the relation type has not been declared in the Relation Service.
exception
RelationNotFoundException if the relation has not been added in the Relation Service.
see
#getRole

public javax.management.relation.RoleResultsetRoles(javax.management.relation.RoleList roleList)
Sets the given roles.

Will check the role according to its corresponding role definition provided in relation's relation type

Will send one notification (RelationNotification with type RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the relation is a MBean or not) per updated role.

param
roleList list of roles to be set
return
a RoleResult object, including a RoleList (for roles successfully set) and a RoleUnresolvedList (for roles not set).
exception
IllegalArgumentException if null role list
exception
RelationServiceNotRegisteredException if the Relation Service is not registered in the MBean Server
exception
RelationTypeNotFoundException if the relation type has not been declared in the Relation Service.
exception
RelationNotFoundException if the relation MBean has not been added in the Relation Service.
see
#getRoles