1. /*

  2.  * @(#)Relation.java	1.21 04/02/10

  3.  * 

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package javax.management.relation;

  9. 

  10. import java.util.List;

  11. import java.util.Map;

  12. 

  13. import javax.management.ObjectName;

  14. import javax.management.InstanceNotFoundException;

  15. import javax.management.ReflectionException;

  16. 

  17. /**

  18.  * This interface has to be implemented by any MBean class expected to

  19.  * represent a relation managed using the Relation Service.

  20.  * <P>Simple relations, i.e. having only roles, no properties or methods, can

  21.  * be created directly by the Relation Service (represented as RelationSupport

  22.  * objects, internally handled by the Relation Service).

  23.  * <P>If the user wants to represent more complex relations, involving

  24.  * properties and/or methods, he has to provide his own class implementing the

  25.  * Relation interface. This can be achieved either by inheriting from

  26.  * RelationSupport class, or by implementing the interface (fully or delegation to

  27.  * a RelationSupport object member).

  28.  * <P>Specifying such user relation class is to introduce properties and/or

  29.  * methods. Those have to be exposed for remote management. So this means that

  30.  * any user relation class must be a MBean class.

  31.  *

  32.  * @since 1.5

  33.  */

  34. public interface Relation {

  35. 

  36.     /**

  37.      * Retrieves role value for given role name.

  38.      * <P>Checks if the role exists and is readable according to the relation

  39.      * type.

  40.      *

  41.      * @param theRoleName  name of role

  42.      *

  43.      * @return the ArrayList of ObjectName objects being the role value

  44.      *

  45.      * @exception IllegalArgumentException  if null role name

  46.      * @exception RoleNotFoundException  if:

  47.      * <P>- there is no role with given name

  48.      * <P>- the role is not readable.

  49.      * @exception RelationServiceNotRegisteredException  if the Relation

  50.      * Service is not registered in the MBean Server

  51.      *

  52.      * @see #setRole

  53.      */

  54.     public List getRole(String theRoleName)

  55. 	throws IllegalArgumentException,

  56. 	       RoleNotFoundException,

  57. 	       RelationServiceNotRegisteredException;

  58. 

  59.     /**

  60.      * Retrieves values of roles with given names.

  61.      * <P>Checks for each role if it exists and is readable according to the

  62.      * relation type.

  63.      *

  64.      * @param theRoleNameArray  array of names of roles to be retrieved

  65.      *

  66.      * @return a RoleResult object, including a RoleList (for roles

  67.      * successfully retrieved) and a RoleUnresolvedList (for roles not

  68.      * retrieved).

  69.      *

  70.      * @exception IllegalArgumentException  if null role name

  71.      * @exception RelationServiceNotRegisteredException  if the Relation

  72.      * Service is not registered in the MBean Server

  73.      *

  74.      * @see #setRoles

  75.      */

  76.     public RoleResult getRoles(String[] theRoleNameArray)

  77. 	throws IllegalArgumentException,

  78. 	       RelationServiceNotRegisteredException;

  79. 

  80.     /**

  81.      * Returns the number of MBeans currently referenced in the given role.

  82.      *

  83.      * @param theRoleName  name of role

  84.      *

  85.      * @return the number of currently referenced MBeans in that role

  86.      *

  87.      * @exception IllegalArgumentException  if null role name

  88.      * @exception RoleNotFoundException  if there is no role with given name

  89.      */

  90.     public Integer getRoleCardinality(String theRoleName)

  91. 	throws IllegalArgumentException,

  92. 	       RoleNotFoundException;

  93. 

  94.     /**

  95.      * Returns all roles present in the relation.

  96.      *

  97.      * @return a RoleResult object, including a RoleList (for roles

  98.      * successfully retrieved) and a RoleUnresolvedList (for roles not

  99.      * readable).

  100.      *

  101.      * @exception RelationServiceNotRegisteredException  if the Relation

  102.      * Service is not registered in the MBean Server

  103.      */

  104.     public RoleResult getAllRoles()

  105. 	throws RelationServiceNotRegisteredException;

  106. 

  107.     /**

  108.      * Returns all roles in the relation without checking read mode.

  109.      *

  110.      * @return a RoleList.

  111.      */

  112.     public RoleList retrieveAllRoles();

  113. 

  114.     /**

  115.      * Sets the given role.

  116.      * <P>Will check the role according to its corresponding role definition

  117.      * provided in relation's relation type

  118.      * <P>Will send a notification (RelationNotification with type

  119.      * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the

  120.      * relation is a MBean or not).

  121.      *

  122.      * @param theRole  role to be set (name and new value)

  123.      *

  124.      * @exception IllegalArgumentException  if null role

  125.      * @exception RoleNotFoundException  if the role is not writable (no

  126.      * test on the write access mode performed when initialising the role)

  127.      * @exception InvalidRoleValueException  if value provided for

  128.      * role is not valid, i.e.:

  129.      * <P>- the number of referenced MBeans in given value is less than

  130.      * expected minimum degree

  131.      * <P>- the number of referenced MBeans in provided value exceeds expected

  132.      * maximum degree

  133.      * <P>- one referenced MBean in the value is not an Object of the MBean

  134.      * class expected for that role

  135.      * <P>- a MBean provided for that role does not exist.

  136.      * @exception RelationServiceNotRegisteredException  if the Relation

  137.      * Service is not registered in the MBean Server

  138.      * @exception RelationTypeNotFoundException  if the relation type has not

  139.      * been declared in the Relation Service.

  140.      * @exception RelationNotFoundException  if the relation has not been

  141.      * added in the Relation Service.

  142.      *

  143.      * @see #getRole

  144.      */

  145.     public void setRole(Role theRole)

  146. 	throws IllegalArgumentException,

  147. 	       RoleNotFoundException,

  148. 	       RelationTypeNotFoundException,

  149. 	       InvalidRoleValueException,

  150. 	       RelationServiceNotRegisteredException,

  151.                RelationNotFoundException;

  152. 

  153.     /**

  154.      * Sets the given roles.

  155.      * <P>Will check the role according to its corresponding role definition

  156.      * provided in relation's relation type

  157.      * <P>Will send one notification (RelationNotification with type

  158.      * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the

  159.      * relation is a MBean or not) per updated role.

  160.      *

  161.      * @param theRoleList  list of roles to be set

  162.      *

  163.      * @return a RoleResult object, including a RoleList (for roles

  164.      * successfully set) and a RoleUnresolvedList (for roles not

  165.      * set).

  166.      *

  167.      * @exception IllegalArgumentException  if null role name

  168.      * @exception RelationServiceNotRegisteredException  if the Relation

  169.      * Service is not registered in the MBean Server

  170.      * @exception RelationTypeNotFoundException  if the relation type has not

  171.      * been declared in the Relation Service.

  172.      * @exception RelationNotFoundException  if the relation MBean has not been

  173.      * added in the Relation Service.

  174.      *

  175.      * @see #getRoles

  176.      */

  177.     public RoleResult setRoles(RoleList theRoleList)

  178. 	throws IllegalArgumentException,

  179. 	       RelationServiceNotRegisteredException,

  180.                RelationTypeNotFoundException,

  181.                RelationNotFoundException;

  182. 

  183.     /**

  184.      * Callback used by the Relation Service when a MBean referenced in a role

  185.      * is unregistered.

  186.      * <P>The Relation Service will call this method to let the relation

  187.      * take action to reflect the impact of such unregistration.

  188.      * <P>BEWARE. the user is not expected to call this method.

  189.      * <P>Current implementation is to set the role with its current value

  190.      * (list of ObjectNames of referenced MBeans) without the unregistered

  191.      * one.

  192.      *

  193.      * @param theObjName  ObjectName of unregistered MBean

  194.      * @param theRoleName  name of role where the MBean is referenced

  195.      *

  196.      * @exception IllegalArgumentException  if null parameter

  197.      * @exception RoleNotFoundException  if role does not exist in the

  198.      * relation or is not writable

  199.      * @exception InvalidRoleValueException  if role value does not conform to

  200.      * the associated role info (this will never happen when called from the

  201.      * Relation Service)

  202.      * @exception RelationServiceNotRegisteredException  if the Relation

  203.      * Service is not registered in the MBean Server

  204.      * @exception RelationTypeNotFoundException  if the relation type has not

  205.      * been declared in the Relation Service.

  206.      * @exception RelationNotFoundException  if this method is called for a

  207.      * relation MBean not added in the Relation Service.

  208.      */

  209.     public void handleMBeanUnregistration(ObjectName theObjName,

  210. 					  String theRoleName)

  211. 	throws IllegalArgumentException,

  212.                RoleNotFoundException,

  213.                InvalidRoleValueException,

  214.                RelationServiceNotRegisteredException,

  215.                RelationTypeNotFoundException,

  216.                RelationNotFoundException;

  217. 

  218.     /**

  219.      * Retrieves MBeans referenced in the various roles of the relation.

  220.      *

  221.      * @return a HashMap mapping:

  222.      * <P> ObjectName -> ArrayList of String (role names)

  223.      */

  224.     public Map getReferencedMBeans();

  225. 

  226.     /**

  227.      * Returns name of associated relation type.

  228.      *

  229.      * @return the name of the relation type.

  230.      */

  231.     public String getRelationTypeName();

  232. 

  233.     /**

  234.      * Returns ObjectName of the Relation Service handling the relation.

  235.      *

  236.      * @return the ObjectName of the Relation Service.

  237.      */

  238.     public ObjectName getRelationServiceName();

  239. 

  240.     /**

  241.      * Returns relation identifier (used to uniquely identify the relation

  242.      * inside the Relation Service).

  243.      *

  244.      * @return the relation id.

  245.      */

  246.     public String getRelationId();

  247. }