KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * @(#)RelationServiceMBean.java 1.26 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 javax.management.ObjectName JavaDoc;
11 import javax.management.InstanceNotFoundException JavaDoc;
12
13 import java.util.List JavaDoc;
14 import java.util.Map JavaDoc;
15
16 /**
17  * The Relation Service is in charge of creating and deleting relation types
18  * and relations, of handling the consistency and of providing query
19  * mechanisms.
20  *
21  * @since 1.5
22  */

23 public interface RelationServiceMBean {
24
25     /**
26      * Checks if the Relation Service is active.
27      * Current condition is that the Relation Service must be registered in the
28      * MBean Server
29      *
30      * @exception RelationServiceNotRegisteredException if it is not
31      * registered
32      */

33     public void isActive()
34     throws RelationServiceNotRegisteredException JavaDoc;
35
36     //
37
// Accessors
38
//
39

40     /**
41      * Returns the flag to indicate if when a notification is received for the
42      * unregistration of an MBean referenced in a relation, if an immediate
43      * "purge" of the relations (look for the relations no longer valid)
44      * has to be performed, or if that will be performed only when the
45      * purgeRelations method is explicitly called.
46      * <P>true is immediate purge.
47      *
48      * @return true if purges are immediate.
49      *
50      * @see #setPurgeFlag
51      */

52     public boolean getPurgeFlag();
53
54     /**
55      * Sets the flag to indicate if when a notification is received for the
56      * unregistration of an MBean referenced in a relation, if an immediate
57      * "purge" of the relations (look for the relations no longer valid)
58      * has to be performed, or if that will be performed only when the
59      * purgeRelations method is explicitly called.
60      * <P>true is immediate purge.
61      *
62      * @param thePurgeFlg flag
63      *
64      * @see #getPurgeFlag
65      */

66     public void setPurgeFlag(boolean thePurgeFlg);
67
68     //
69
// Relation type handling
70
//
71

72     /**
73      * Creates a relation type (RelationTypeSupport object) with given
74      * role infos (provided by the RoleInfo objects), and adds it in the
75      * Relation Service.
76      *
77      * @param theRelTypeName name of the relation type
78      * @param theRoleInfoArray array of role infos
79      *
80      * @exception IllegalArgumentException if null parameter
81      * @exception InvalidRelationTypeException If:
82      * <P>- there is already a relation type with that name
83      * <P>- the same name has been used for two different role infos
84      * <P>- no role info provided
85      * <P>- one null role info provided
86      */

87     public void createRelationType(String JavaDoc theRelTypeName,
88                    RoleInfo JavaDoc[] theRoleInfoArray)
89     throws IllegalArgumentException JavaDoc,
90            InvalidRelationTypeException JavaDoc;
91
92     /**
93      * Adds given object as a relation type. The object is expected to
94      * implement the RelationType interface.
95      *
96      * @param theRelTypeObj relation type object (implementing the
97      * RelationType interface)
98      *
99      * @exception IllegalArgumentException if null parameter
100      * @exception InvalidRelationTypeException if there is already a relation
101      * type with that name
102      */

103     public void addRelationType(RelationType JavaDoc theRelTypeObj)
104     throws IllegalArgumentException JavaDoc,
105            InvalidRelationTypeException JavaDoc;
106
107     /**
108      * Retrieves names of all known relation types.
109      *
110      * @return ArrayList of relation type names (Strings)
111      */

112     public List JavaDoc getAllRelationTypeNames();
113
114     /**
115      * Retrieves list of role infos (RoleInfo objects) of a given relation
116      * type.
117      *
118      * @param theRelTypeName name of relation type
119      *
120      * @return ArrayList of RoleInfo.
121      *
122      * @exception IllegalArgumentException if null parameter
123      * @exception RelationTypeNotFoundException if there is no relation type
124      * with that name.
125      */

126     public List JavaDoc getRoleInfos(String JavaDoc theRelTypeName)
127     throws IllegalArgumentException JavaDoc,
128            RelationTypeNotFoundException JavaDoc;
129
130     /**
131      * Retrieves role info for given role of a given relation type.
132      *
133      * @param theRelTypeName name of relation type
134      * @param theRoleInfoName name of role
135      *
136      * @return RoleInfo object.
137      *
138      * @exception IllegalArgumentException if null parameter
139      * @exception RelationTypeNotFoundException if the relation type is not
140      * known in the Relation Service
141      * @exception RoleInfoNotFoundException if the role is not part of the
142      * relation type.
143      */

144     public RoleInfo JavaDoc getRoleInfo(String JavaDoc theRelTypeName,
145                 String JavaDoc theRoleInfoName)
146     throws IllegalArgumentException JavaDoc,
147            RelationTypeNotFoundException JavaDoc,
148                RoleInfoNotFoundException JavaDoc;
149
150     /**
151      * Removes given relation type from Relation Service.
152      * <P>The relation objects of that type will be removed from the
153      * Relation Service.
154      *
155      * @param theRelTypeName name of the relation type to be removed
156      *
157      * @exception RelationServiceNotRegisteredException if the Relation
158      * Service is not registered in the MBean Server
159      * @exception IllegalArgumentException if null parameter
160      * @exception RelationTypeNotFoundException If there is no relation type
161      * with that name
162      */

163     public void removeRelationType(String JavaDoc theRelTypeName)
164     throws RelationServiceNotRegisteredException JavaDoc,
165            IllegalArgumentException JavaDoc,
166            RelationTypeNotFoundException JavaDoc;
167
168     //
169
// Relation handling
170
//
171

172     /**
173      * Creates a simple relation (represented by a RelationSupport object) of
174      * given relation type, and adds it in the Relation Service.
175      * <P>Roles are initialized according to the role list provided in
176      * parameter. The ones not initialized in this way are set to an empty
177      * ArrayList of ObjectNames.
178      * <P>A RelationNotification, with type RELATION_BASIC_CREATION, is sent.
179      *
180      * @param theRelId relation identifier, to identify uniquely the relation
181      * inside the Relation Service
182      * @param theRelTypeName name of the relation type (has to be created
183      * in the Relation Service)
184      * @param theRoleList role list to initialize roles of the relation (can
185      * be null).
186      *
187      * @exception RelationServiceNotRegisteredException if the Relation
188      * Service is not registered in the MBean Server
189      * @exception IllegalArgumentException if null parameter
190      * @exception RoleNotFoundException if a value is provided for a role
191      * that does not exist in the relation type
192      * @exception InvalidRelationIdException if relation id already used
193      * @exception RelationTypeNotFoundException if relation type not known in
194      * Relation Service
195      * @exception InvalidRoleValueException if:
196      * <P>- the same role name is used for two different roles
197      * <P>- the number of referenced MBeans in given value is less than
198      * expected minimum degree
199      * <P>- the number of referenced MBeans in provided value exceeds expected
200      * maximum degree
201      * <P>- one referenced MBean in the value is not an Object of the MBean
202      * class expected for that role
203      * <P>- an MBean provided for that role does not exist
204      */

205     public void createRelation(String JavaDoc theRelId,
206                    String JavaDoc theRelTypeName,
207                    RoleList JavaDoc theRoleList)
208     throws RelationServiceNotRegisteredException JavaDoc,
209            IllegalArgumentException JavaDoc,
210                RoleNotFoundException JavaDoc,
211                InvalidRelationIdException JavaDoc,
212                RelationTypeNotFoundException JavaDoc,
213                InvalidRoleValueException JavaDoc;
214
215     /**
216      * Adds an MBean created by the user (and registered by him in the MBean
217      * Server) as a relation in the Relation Service.
218      * <P>To be added as a relation, the MBean must conform to the
219      * following:
220      * <P>- implement the Relation interface
221      * <P>- have for RelationService ObjectName the ObjectName of current
222      * Relation Service
223      * <P>- have a relation id that is unique and unused in current Relation Service
224      * <P>- have for relation type a relation type created in the Relation
225      * Service
226      * <P>- have roles conforming to the role info provided in the relation
227      * type.
228      *
229      * @param theRelObjectName ObjectName of the relation MBean to be added.
230      *
231      * @exception IllegalArgumentException if null parameter
232      * @exception RelationServiceNotRegisteredException if the Relation
233      * Service is not registered in the MBean Server
234      * @exception NoSuchMethodException If the MBean does not implement the
235      * Relation interface
236      * @exception InvalidRelationIdException if:
237      * <P>- no relation identifier in MBean
238      * <P>- the relation identifier is already used in the Relation Service
239      * @exception InstanceNotFoundException if the MBean for given ObjectName
240      * has not been registered
241      * @exception InvalidRelationServiceException if:
242      * <P>- no Relation Service name in MBean
243      * <P>- the Relation Service name in the MBean is not the one of the
244      * current Relation Service
245      * @exception RelationTypeNotFoundException if:
246      * <P>- no relation type name in MBean
247      * <P>- the relation type name in MBean does not correspond to a relation
248      * type created in the Relation Service
249      * @exception InvalidRoleValueException if:
250      * <P>- the number of referenced MBeans in a role is less than
251      * expected minimum degree
252      * <P>- the number of referenced MBeans in a role exceeds expected
253      * maximum degree
254      * <P>- one referenced MBean in the value is not an Object of the MBean
255      * class expected for that role
256      * <P>- an MBean provided for a role does not exist
257      * @exception RoleNotFoundException if a value is provided for a role
258      * that does not exist in the relation type
259      */

260     public void addRelation(ObjectName JavaDoc theRelObjectName)
261     throws IllegalArgumentException JavaDoc,
262            RelationServiceNotRegisteredException JavaDoc,
263            NoSuchMethodException JavaDoc,
264            InvalidRelationIdException JavaDoc,
265            InstanceNotFoundException JavaDoc,
266            InvalidRelationServiceException JavaDoc,
267                RelationTypeNotFoundException JavaDoc,
268                RoleNotFoundException JavaDoc,
269            InvalidRoleValueException JavaDoc;
270
271     /**
272      * If the relation is represented by an MBean (created by the user and
273      * added as a relation in the Relation Service), returns the ObjectName of
274      * the MBean.
275      *
276      * @param theRelId relation id identifying the relation
277      *
278      * @return ObjectName of the corresponding relation MBean, or null if
279      * the relation is not an MBean.
280      *
281      * @exception IllegalArgumentException if null parameter
282      * @exception RelationNotFoundException there is no relation associated
283      * to that id
284      */

285     public ObjectName JavaDoc isRelationMBean(String JavaDoc theRelId)
286     throws IllegalArgumentException JavaDoc,
287            RelationNotFoundException JavaDoc;
288
289     /**
290      * Returns the relation id associated to the given ObjectName if the
291      * MBean has been added as a relation in the Relation Service.
292      *
293      * @param theObjName ObjectName of supposed relation
294      *
295      * @return relation id (String) or null (if the ObjectName is not a
296      * relation handled by the Relation Service)
297      *
298      * @exception IllegalArgumentException if null parameter
299      */

300     public String JavaDoc isRelation(ObjectName JavaDoc theObjName)
301     throws IllegalArgumentException JavaDoc;
302
303     /**
304      * Checks if there is a relation identified in Relation Service with given
305      * relation id.
306      *
307      * @param theRelId relation id identifying the relation
308      *
309      * @return boolean: true if there is a relation, false else
310      *
311      * @exception IllegalArgumentException if null parameter
312      */

313     public Boolean JavaDoc hasRelation(String JavaDoc theRelId)
314     throws IllegalArgumentException JavaDoc;
315
316     /**
317      * Returns all the relation ids for all the relations handled by the
318      * Relation Service.
319      *
320      * @return ArrayList of String
321      */

322     public List JavaDoc getAllRelationIds();
323
324     /**
325      * Checks if given Role can be read in a relation of the given type.
326      *
327      * @param theRoleName name of role to be checked
328      * @param theRelTypeName name of the relation type
329      *
330      * @return an Integer wrapping an integer corresponding to possible
331      * problems represented as constants in RoleUnresolved:
332      * <P>- 0 if role can be read
333      * <P>- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME
334      * <P>- integer corresponding to RoleStatus.ROLE_NOT_READABLE
335      *
336      * @exception IllegalArgumentException if null parameter
337      * @exception RelationTypeNotFoundException if the relation type is not
338      * known in the Relation Service
339      */

340     public Integer JavaDoc checkRoleReading(String JavaDoc theRoleName,
341                     String JavaDoc theRelTypeName)
342     throws IllegalArgumentException JavaDoc,
343                RelationTypeNotFoundException JavaDoc;
344
345     /**
346      * Checks if given Role can be set in a relation of given type.
347      *
348      * @param theRole role to be checked
349      * @param theRelTypeName name of relation type
350      * @param theInitFlg flag to specify that the checking is done for the
351      * initialization of a role, write access shall not be verified.
352      *
353      * @return an Integer wrapping an integer corresponding to possible
354      * problems represented as constants in RoleUnresolved:
355      * <P>- 0 if role can be set
356      * <P>- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME
357      * <P>- integer for RoleStatus.ROLE_NOT_WRITABLE
358      * <P>- integer for RoleStatus.LESS_THAN_MIN_ROLE_DEGREE
359      * <P>- integer for RoleStatus.MORE_THAN_MAX_ROLE_DEGREE
360      * <P>- integer for RoleStatus.REF_MBEAN_OF_INCORRECT_CLASS
361      * <P>- integer for RoleStatus.REF_MBEAN_NOT_REGISTERED
362      *
363      * @exception IllegalArgumentException if null parameter
364      * @exception RelationTypeNotFoundException if unknown relation type
365      */

366     public Integer JavaDoc checkRoleWriting(Role JavaDoc theRole,
367                     String JavaDoc theRelTypeName,
368                     Boolean JavaDoc theInitFlg)
369     throws IllegalArgumentException JavaDoc,
370            RelationTypeNotFoundException JavaDoc;
371
372     /**
373      * Sends a notification (RelationNotification) for a relation creation.
374      * The notification type is:
375      * <P>- RelationNotification.RELATION_BASIC_CREATION if the relation is an
376      * object internal to the Relation Service
377      * <P>- RelationNotification.RELATION_MBEAN_CREATION if the relation is a
378      * MBean added as a relation.
379      * <P>The source object is the Relation Service itself.
380      * <P>It is called in Relation Service createRelation() and
381      * addRelation() methods.
382      *
383      * @param theRelId relation identifier of the updated relation
384      *
385      * @exception IllegalArgumentException if null parameter
386      * @exception RelationNotFoundException if there is no relation for given
387      * relation id
388      */

389     public void sendRelationCreationNotification(String JavaDoc theRelId)
390     throws IllegalArgumentException JavaDoc,
391            RelationNotFoundException JavaDoc;
392
393     /**
394      * Sends a notification (RelationNotification) for a role update in the
395      * given relation. The notification type is:
396      * <P>- RelationNotification.RELATION_BASIC_UPDATE if the relation is an
397      * object internal to the Relation Service
398      * <P>- RelationNotification.RELATION_MBEAN_UPDATE if the relation is a
399      * MBean added as a relation.
400      * <P>The source object is the Relation Service itself.
401      * <P>It is called in relation MBean setRole() (for given role) and
402      * setRoles() (for each role) methods (implementation provided in
403      * RelationSupport class).
404      * <P>It is also called in Relation Service setRole() (for given role) and
405      * setRoles() (for each role) methods.
406      *
407      * @param theRelId relation identifier of the updated relation
408      * @param theNewRole new role (name and new value)
409      * @param theOldRoleValue old role value (List of ObjectName objects)
410      *
411      * @exception IllegalArgumentException if null parameter
412      * @exception RelationNotFoundException if there is no relation for given
413      * relation id
414      */

415     public void sendRoleUpdateNotification(String JavaDoc theRelId,
416                        Role JavaDoc theNewRole,
417                        List JavaDoc theOldRoleValue)
418     throws IllegalArgumentException JavaDoc,
419            RelationNotFoundException JavaDoc;
420
421     /**
422      * Sends a notification (RelationNotification) for a relation removal.
423      * The notification type is:
424      * <P>- RelationNotification.RELATION_BASIC_REMOVAL if the relation is an
425      * object internal to the Relation Service
426      * <P>- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is a
427      * MBean added as a relation.
428      * <P>The source object is the Relation Service itself.
429      * <P>It is called in Relation Service removeRelation() method.
430      *
431      * @param theRelId relation identifier of the updated relation
432      * @param theUnregMBeanList List of ObjectNames of MBeans expected
433      * to be unregistered due to relation removal (can be null)
434      *
435      * @exception IllegalArgumentException if null parameter
436      * @exception RelationNotFoundException if there is no relation for given
437      * relation id
438      */

439     public void sendRelationRemovalNotification(String JavaDoc theRelId,
440                         List JavaDoc theUnregMBeanList)
441     throws IllegalArgumentException JavaDoc,
442            RelationNotFoundException JavaDoc;
443
444     /**
445      * Handles update of the Relation Service role map for the update of given
446      * role in given relation.
447      * <P>It is called in relation MBean setRole() (for given role) and
448      * setRoles() (for each role) methods (implementation provided in
449      * RelationSupport class).
450      * <P>It is also called in Relation Service setRole() (for given role) and
451      * setRoles() (for each role) methods.
452      * <P>To allow the Relation Service to maintain the consistency (in case
453      * of MBean unregistration) and to be able to perform queries, this method
454      * must be called when a role is updated.
455      *
456      * @param theRelId relation identifier of the updated relation
457      * @param theNewRole new role (name and new value)
458      * @param theOldRoleValue old role value (List of ObjectName objects)
459      *
460      * @exception IllegalArgumentException if null parameter
461      * @exception RelationServiceNotRegisteredException if the Relation
462      * Service is not registered in the MBean Server
463      * @exception RelationNotFoundException if no relation for given id.
464      */

465     public void updateRoleMap(String JavaDoc theRelId,
466                   Role JavaDoc theNewRole,
467                   List JavaDoc theOldRoleValue)
468     throws IllegalArgumentException JavaDoc,
469            RelationServiceNotRegisteredException JavaDoc,
470                RelationNotFoundException JavaDoc;
471
472     /**
473      * Removes given relation from the Relation Service.
474      * <P>A RelationNotification notification is sent, its type being:
475      * <P>- RelationNotification.RELATION_BASIC_REMOVAL if the relation was
476      * only internal to the Relation Service
477      * <P>- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is
478      * registered as an MBean.
479      * <P>For MBeans referenced in such relation, nothing will be done,
480      *
481      * @param theRelId relation id of the relation to be removed
482      *
483      * @exception RelationServiceNotRegisteredException if the Relation
484      * Service is not registered in the MBean Server
485      * @exception IllegalArgumentException if null parameter
486      * @exception RelationNotFoundException if no relation corresponding to
487      * given relation id
488      */

489     public void removeRelation(String JavaDoc theRelId)
490     throws RelationServiceNotRegisteredException JavaDoc,
491            IllegalArgumentException JavaDoc,
492            RelationNotFoundException JavaDoc;
493
494     /**
495      * Purges the relations.
496      *
497      * <P>Depending on the purgeFlag value, this method is either called
498      * automatically when a notification is received for the unregistration of
499      * an MBean referenced in a relation (if the flag is set to true), or not
500      * (if the flag is set to false).
501      * <P>In that case it is up to the user to call it to maintain the
502      * consistency of the relations. To be kept in mind that if an MBean is
503      * unregistered and the purge not done immediately, if the ObjectName is
504      * reused and assigned to another MBean referenced in a relation, calling
505      * manually this purgeRelations() method will cause trouble, as will
506      * consider the ObjectName as corresponding to the unregistered MBean, not
507      * seeing the new one.
508      *
509      * <P>The behavior depends on the cardinality of the role where the
510      * unregistered MBean is referenced:
511      * <P>- if removing one MBean reference in the role makes its number of
512      * references less than the minimum degree, the relation has to be removed.
513      * <P>- if the remaining number of references after removing the MBean
514      * reference is still in the cardinality range, keep the relation and
515      * update it calling its handleMBeanUnregistration() callback.
516      *
517      * @exception RelationServiceNotRegisteredException if the Relation
518      * Service is not registered in the MBean Server.
519      */

520     public void purgeRelations()
521     throws RelationServiceNotRegisteredException JavaDoc;
522
523     /**
524      * Retrieves the relations where a given MBean is referenced.
525      * <P>This corresponds to the CIM "References" and "ReferenceNames"
526      * operations.
527      *
528      * @param theMBeanName ObjectName of MBean
529      * @param theRelTypeName can be null; if specified, only the relations
530      * of that type will be considered in the search. Else all relation types
531      * are considered.
532      * @param theRoleName can be null; if specified, only the relations
533      * where the MBean is referenced in that role will be returned. Else all
534      * roles are considered.
535      *
536      * @return an HashMap, where the keys are the relation ids of the relations
537      * where the MBean is referenced, and the value is, for each key,
538      * an ArrayList of role names (as an MBean can be referenced in several
539      * roles in the same relation).
540      *
541      * @exception IllegalArgumentException if null parameter
542      */

543     public Map JavaDoc findReferencingRelations(ObjectName JavaDoc theMBeanName,
544                     String JavaDoc theRelTypeName,
545                     String JavaDoc theRoleName)
546     throws IllegalArgumentException JavaDoc;
547
548     /**
549      * Retrieves the MBeans associated to given one in a relation.
550      * <P>This corresponds to CIM Associators and AssociatorNames operations.
551      *
552      * @param theMBeanName ObjectName of MBean
553      * @param theRelTypeName can be null; if specified, only the relations
554      * of that type will be considered in the search. Else all
555      * relation types are considered.
556      * @param theRoleName can be null; if specified, only the relations
557      * where the MBean is referenced in that role will be considered. Else all
558      * roles are considered.
559      *
560      * @return an HashMap, where the keys are the ObjectNames of the MBeans
561      * associated to given MBean, and the value is, for each key, an ArrayList
562      * of the relation ids of the relations where the key MBean is
563      * associated to given one (as they can be associated in several different
564      * relations).
565      *
566      * @exception IllegalArgumentException if null parameter
567      */

568     public Map JavaDoc findAssociatedMBeans(ObjectName JavaDoc theMBeanName,
569                     String JavaDoc theRelTypeName,
570                     String JavaDoc theRoleName)
571     throws IllegalArgumentException JavaDoc;
572
573     /**
574      * Returns the relation ids for relations of the given type.
575      *
576      * @param theRelTypeName relation type name
577      *
578      * @return an ArrayList of relation ids.
579      *
580      * @exception IllegalArgumentException if null parameter
581      * @exception RelationTypeNotFoundException if there is no relation type
582      * with that name.
583      */

584     public List JavaDoc findRelationsOfType(String JavaDoc theRelTypeName)
585     throws IllegalArgumentException JavaDoc,
586                RelationTypeNotFoundException JavaDoc;
587
588     /**
589      * Retrieves role value for given role name in given relation.
590      *
591      * @param theRelId relation id
592      * @param theRoleName name of role
593      *
594      * @return the ArrayList of ObjectName objects being the role value
595      *
596      * @exception RelationServiceNotRegisteredException if the Relation
597      * Service is not registered
598      * @exception IllegalArgumentException if null parameter
599      * @exception RelationNotFoundException if no relation with given id
600      * @exception RoleNotFoundException if:
601      * <P>- there is no role with given name
602      * <P>or
603      * <P>- the role is not readable.
604      *
605      * @see #setRole
606      */

607     public List JavaDoc getRole(String JavaDoc theRelId,
608             String JavaDoc theRoleName)
609     throws RelationServiceNotRegisteredException JavaDoc,
610            IllegalArgumentException JavaDoc,
611                RelationNotFoundException JavaDoc,
612                RoleNotFoundException JavaDoc;
613
614     /**
615      * Retrieves values of roles with given names in given relation.
616      *
617      * @param theRelId relation id
618      * @param theRoleNameArray array of names of roles to be retrieved
619      *
620      * @return a RoleResult object, including a RoleList (for roles
621      * successfully retrieved) and a RoleUnresolvedList (for roles not
622      * retrieved).
623      *
624      * @exception RelationServiceNotRegisteredException if the Relation
625      * Service is not registered in the MBean Server
626      * @exception IllegalArgumentException if null parameter
627      * @exception RelationNotFoundException if no relation with given id
628      *
629      * @see #setRoles
630      */

631     public RoleResult JavaDoc getRoles(String JavaDoc theRelId,
632                    String JavaDoc[] theRoleNameArray)
633     throws RelationServiceNotRegisteredException JavaDoc,
634            IllegalArgumentException JavaDoc,
635            RelationNotFoundException JavaDoc;
636
637     /**
638      * Returns all roles present in the relation.
639      *
640      * @param theRelId relation id
641      *
642      * @return a RoleResult object, including a RoleList (for roles
643      * successfully retrieved) and a RoleUnresolvedList (for roles not
644      * readable).
645      *
646      * @exception IllegalArgumentException if null parameter
647      * @exception RelationNotFoundException if no relation for given id
648      * @exception RelationServiceNotRegisteredException if the Relation
649      * Service is not registered in the MBean Server
650      */

651     public RoleResult JavaDoc getAllRoles(String JavaDoc theRelId)
652         throws IllegalArgumentException JavaDoc,
653            RelationNotFoundException JavaDoc,
654            RelationServiceNotRegisteredException JavaDoc;
655
656     /**
657      * Retrieves the number of MBeans currently referenced in the
658      * given role.
659      *
660      * @param theRelId relation id
661      * @param theRoleName name of role
662      *
663      * @return the number of currently referenced MBeans in that role
664      *
665      * @exception IllegalArgumentException if null parameter
666      * @exception RelationNotFoundException if no relation with given id
667      * @exception RoleNotFoundException if there is no role with given name
668      */

669     public Integer JavaDoc getRoleCardinality(String JavaDoc theRelId,
670                       String JavaDoc theRoleName)
671     throws IllegalArgumentException JavaDoc,
672                RelationNotFoundException JavaDoc,
673                RoleNotFoundException JavaDoc;
674
675     /**
676      * Sets the given role in given relation.
677      * <P>Will check the role according to its corresponding role definition
678      * provided in relation's relation type
679      * <P>The Relation Service will keep track of the change to keep the
680      * consistency of relations by handling referenced MBean unregistrations.
681      *
682      * @param theRelId relation id
683      * @param theRole role to be set (name and new value)
684      *
685      * @exception RelationServiceNotRegisteredException if the Relation
686      * Service is not registered in the MBean Server
687      * @exception IllegalArgumentException if null parameter
688      * @exception RelationNotFoundException if no relation with given id
689      * @exception RoleNotFoundException if:
690      * <P>- internal relation
691      * <P>and
692      * <P>- the role does not exist or is not writable
693      * @exception InvalidRoleValueException if internal relation and value
694      * provided for role is not valid:
695      * <P>- the number of referenced MBeans in given value is less than
696      * expected minimum degree
697      * <P>or
698      * <P>- the number of referenced MBeans in provided value exceeds expected
699      * maximum degree
700      * <P>or
701      * <P>- one referenced MBean in the value is not an Object of the MBean
702      * class expected for that role
703      * <P>or
704      * <P>- an MBean provided for that role does not exist
705      * @exception RelationTypeNotFoundException if unknown relation type
706      *
707      * @see #getRole
708      */

709     public void setRole(String JavaDoc theRelId,
710             Role JavaDoc theRole)
711     throws RelationServiceNotRegisteredException JavaDoc,
712            IllegalArgumentException JavaDoc,
713            RelationNotFoundException JavaDoc,
714            RoleNotFoundException JavaDoc,
715            InvalidRoleValueException JavaDoc,
716            RelationTypeNotFoundException JavaDoc;
717
718     /**
719      * Sets the given roles in given relation.
720      * <P>Will check the role according to its corresponding role definition
721      * provided in relation's relation type
722      * <P>The Relation Service keeps track of the changes to keep the
723      * consistency of relations by handling referenced MBean unregistrations.
724      *
725      * @param theRelId relation id
726      * @param theRoleList list of roles to be set
727      *
728      * @return a RoleResult object, including a RoleList (for roles
729      * successfully set) and a RoleUnresolvedList (for roles not
730      * set).
731      *
732      * @exception RelationServiceNotRegisteredException if the Relation
733      * Service is not registered in the MBean Server
734      * @exception IllegalArgumentException if null parameter
735      * @exception RelationNotFoundException if no relation with given id
736      *
737      * @see #getRoles
738      */

739     public RoleResult JavaDoc setRoles(String JavaDoc theRelId,
740                    RoleList JavaDoc theRoleList)
741     throws RelationServiceNotRegisteredException JavaDoc,
742            IllegalArgumentException JavaDoc,
743                RelationNotFoundException JavaDoc;
744
745     /**
746      * Retrieves MBeans referenced in the various roles of the relation.
747      *
748      * @param theRelId relation id
749      *
750      * @return a HashMap mapping:
751      * <P> ObjectName -> ArrayList of String (role
752      * names)
753      *
754      * @exception IllegalArgumentException if null parameter
755      * @exception RelationNotFoundException if no relation for given
756      * relation id
757      */

758     public Map JavaDoc getReferencedMBeans(String JavaDoc theRelId)
759     throws IllegalArgumentException JavaDoc,
760            RelationNotFoundException JavaDoc;
761
762     /**
763      * Returns name of associated relation type for given relation.
764      *
765      * @param theRelId relation id
766      *
767      * @return the name of the associated relation type.
768      *
769      * @exception IllegalArgumentException if null parameter
770      * @exception RelationNotFoundException if no relation for given
771      * relation id
772      */

773     public String JavaDoc getRelationTypeName(String JavaDoc theRelId)
774     throws IllegalArgumentException JavaDoc,
775            RelationNotFoundException JavaDoc;
776 }
777
Popular Tags