KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > management > relation > Relation


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 JavaDoc;
11 import java.util.Map JavaDoc;
12
13 import javax.management.ObjectName JavaDoc;
14 import javax.management.InstanceNotFoundException JavaDoc;
15 import javax.management.ReflectionException JavaDoc;
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 JavaDoc getRole(String JavaDoc theRoleName)
55     throws IllegalArgumentException JavaDoc,
56            RoleNotFoundException JavaDoc,
57            RelationServiceNotRegisteredException JavaDoc;
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 JavaDoc getRoles(String JavaDoc[] theRoleNameArray)
77     throws IllegalArgumentException JavaDoc,
78            RelationServiceNotRegisteredException JavaDoc;
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 JavaDoc getRoleCardinality(String JavaDoc theRoleName)
91     throws IllegalArgumentException JavaDoc,
92            RoleNotFoundException JavaDoc;
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 JavaDoc getAllRoles()
105     throws RelationServiceNotRegisteredException JavaDoc;
106
107     /**
108      * Returns all roles in the relation without checking read mode.
109      *
110      * @return a RoleList.
111      */
112     public RoleList JavaDoc 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 JavaDoc theRole)
146     throws IllegalArgumentException JavaDoc,
147            RoleNotFoundException JavaDoc,
148            RelationTypeNotFoundException JavaDoc,
149            InvalidRoleValueException JavaDoc,
150            RelationServiceNotRegisteredException JavaDoc,
151                RelationNotFoundException JavaDoc;
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 JavaDoc setRoles(RoleList JavaDoc theRoleList)
178     throws IllegalArgumentException JavaDoc,
179            RelationServiceNotRegisteredException JavaDoc,
180                RelationTypeNotFoundException JavaDoc,
181                RelationNotFoundException JavaDoc;
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 JavaDoc theObjName,
210                       String JavaDoc theRoleName)
211     throws IllegalArgumentException JavaDoc,
212                RoleNotFoundException JavaDoc,
213                InvalidRoleValueException JavaDoc,
214                RelationServiceNotRegisteredException JavaDoc,
215                RelationTypeNotFoundException JavaDoc,
216                RelationNotFoundException JavaDoc;
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 JavaDoc getReferencedMBeans();
225
226     /**
227      * Returns name of associated relation type.
228      *
229      * @return the name of the relation type.
230      */
231     public String JavaDoc 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 JavaDoc 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 JavaDoc getRelationId();
247 }
248
Popular Tags