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 */ public interface Relation { /** * Retrieves role value for given role name. *
Checks if the role exists and is readable according to the relation * type. * * @param theRoleName 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 List getRole(String theRoleName) throws IllegalArgumentException, RoleNotFoundException, RelationServiceNotRegisteredException; /** * Retrieves values of roles with given names. *
Checks for each role if it exists and is readable according to the * relation type. * * @param theRoleNameArray 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 RoleResult getRoles(String[] theRoleNameArray) throws IllegalArgumentException, RelationServiceNotRegisteredException; /** * Returns the number of MBeans currently referenced in the given role. * * @param theRoleName 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 Integer getRoleCardinality(String theRoleName) throws IllegalArgumentException, RoleNotFoundException; /** * 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 RoleResult getAllRoles() throws RelationServiceNotRegisteredException; /** * Returns all roles in the relation without checking read mode. * * @return a RoleList. */ public RoleList retrieveAllRoles(); /** * 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 theRole role to be set (name and new value) * * @exception IllegalArgumentException if null role * @exception RoleNotFoundException if the role is not writable (no * test on the write access mode performed when initialising 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 void setRole(Role theRole) throws IllegalArgumentException, RoleNotFoundException, RelationTypeNotFoundException, InvalidRoleValueException, RelationServiceNotRegisteredException, RelationNotFoundException; /** * 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 theRoleList 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 name * @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 */ public RoleResult setRoles(RoleList theRoleList) throws IllegalArgumentException, RelationServiceNotRegisteredException, RelationTypeNotFoundException, RelationNotFoundException; /** * 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 theObjName ObjectName of unregistered MBean * @param theRoleName 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 void handleMBeanUnregistration(ObjectName theObjName, String theRoleName) throws IllegalArgumentException, RoleNotFoundException, InvalidRoleValueException, RelationServiceNotRegisteredException, RelationTypeNotFoundException, RelationNotFoundException; /** * Retrieves MBeans referenced in the various roles of the relation. * * @return a HashMap mapping: *
ObjectName -> ArrayList of String (role names) */ public Map getReferencedMBeans(); /** * Returns name of associated relation type. * * @return the name of the relation type. */ public String getRelationTypeName(); /** * Returns ObjectName of the Relation Service handling the relation. * * @return the ObjectName of the Relation Service. */ public ObjectName getRelationServiceName(); /** * Returns relation identifier (used to uniquely identify the relation * inside the Relation Service). * * @return the relation id. */ public String getRelationId(); }