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 ;
11 import javax.management.InstanceNotFoundException ;
12
13 import java.util.List ;
14 import java.util.Map ;
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 ;
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 theRelTypeName,
88                    RoleInfo [] theRoleInfoArray)
89     throws IllegalArgumentException ,
90            InvalidRelationTypeException ;
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 theRelTypeObj)
104     throws IllegalArgumentException ,
105            InvalidRelationTypeException ;
106
107     /**
108      * Retrieves names of all known relation types.
109      *
110      * @return ArrayList of relation type names (Strings)
111      */
112     public List 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 getRoleInfos(String theRelTypeName)
127     throws IllegalArgumentException ,
128            RelationTypeNotFoundException ;
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 getRoleInfo(String theRelTypeName,
145                 String theRoleInfoName)
146     throws IllegalArgumentException ,
147            RelationTypeNotFoundException ,
148                RoleInfoNotFoundException ;
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 theRelTypeName)
164     throws RelationServiceNotRegisteredException ,
165            IllegalArgumentException ,
166            RelationTypeNotFoundException ;
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 theRelId,
206                    String theRelTypeName,
207                    RoleList theRoleList)
208     throws RelationServiceNotRegisteredException ,
209            IllegalArgumentException ,
210                RoleNotFoundException ,
211                InvalidRelationIdException ,
212                RelationTypeNotFoundException ,
213                InvalidRoleValueException ;
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 theRelObjectName)
261     throws IllegalArgumentException ,
262            RelationServiceNotRegisteredException ,
263            NoSuchMethodException ,
264            InvalidRelationIdException ,
265            InstanceNotFoundException ,
266            InvalidRelationServiceException ,
267                RelationTypeNotFoundException ,
268                RoleNotFoundException ,
269            InvalidRoleValueException ;
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 isRelationMBean(String theRelId)
286     throws IllegalArgumentException ,
287            RelationNotFoundException ;
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 isRelation(ObjectName theObjName)
301     throws IllegalArgumentException ;
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 hasRelation(String theRelId)
314     throws IllegalArgumentException ;
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 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 checkRoleReading(String theRoleName,
341                     String theRelTypeName)
342     throws IllegalArgumentException ,
343                RelationTypeNotFoundException ;
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 checkRoleWriting(Role theRole,
367                     String theRelTypeName,
368                     Boolean theInitFlg)
369     throws IllegalArgumentException ,
370            RelationTypeNotFoundException ;
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 theRelId)
390     throws IllegalArgumentException ,
391            RelationNotFoundException ;
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 theRelId,
416                        Role theNewRole,
417                        List theOldRoleValue)
418     throws IllegalArgumentException ,
419            RelationNotFoundException ;
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 theRelId,
440                         List theUnregMBeanList)
441     throws IllegalArgumentException ,
442            RelationNotFoundException ;
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 theRelId,
466                   Role theNewRole,
467                   List theOldRoleValue)
468     throws IllegalArgumentException ,
469            RelationServiceNotRegisteredException ,
470                RelationNotFoundException ;
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 theRelId)
490     throws RelationServiceNotRegisteredException ,
491            IllegalArgumentException ,
492            RelationNotFoundException ;
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 ;
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 findReferencingRelations(ObjectName theMBeanName,
544                     String theRelTypeName,
545                     String theRoleName)
546     throws IllegalArgumentException ;
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 findAssociatedMBeans(ObjectName theMBeanName,
569                     String theRelTypeName,
570                     String theRoleName)
571     throws IllegalArgumentException ;
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 findRelationsOfType(String theRelTypeName)
585     throws IllegalArgumentException ,
586                RelationTypeNotFoundException ;
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 getRole(String theRelId,
608             String theRoleName)
609     throws RelationServiceNotRegisteredException ,
610            IllegalArgumentException ,
611                RelationNotFoundException ,
612                RoleNotFoundException ;
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 getRoles(String theRelId,
632                    String [] theRoleNameArray)
633     throws RelationServiceNotRegisteredException ,
634            IllegalArgumentException ,
635            RelationNotFoundException ;
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 getAllRoles(String theRelId)
652         throws IllegalArgumentException ,
653            RelationNotFoundException ,
654            RelationServiceNotRegisteredException ;
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 getRoleCardinality(String theRelId,
670                       String theRoleName)
671     throws IllegalArgumentException ,
672                RelationNotFoundException ,
673                RoleNotFoundException ;
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 theRelId,
710             Role theRole)
711     throws RelationServiceNotRegisteredException ,
712            IllegalArgumentException ,
713            RelationNotFoundException ,
714            RoleNotFoundException ,
715            InvalidRoleValueException ,
716            RelationTypeNotFoundException ;
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 setRoles(String theRelId,
740                    RoleList theRoleList)
741     throws RelationServiceNotRegisteredException ,
742            IllegalArgumentException ,
743                RelationNotFoundException ;
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 getReferencedMBeans(String theRelId)
759     throws IllegalArgumentException ,
760            RelationNotFoundException ;
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 getRelationTypeName(String theRelId)
774     throws IllegalArgumentException ,
775            RelationNotFoundException ;
776 }
777

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags