1 /*
2 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.management.relation;
27
28 import javax.management.ObjectName;
29 import javax.management.InstanceNotFoundException;
30
31 import java.util.List;
32 import java.util.Map;
33
34 /**
35 * The Relation Service is in charge of creating and deleting relation types
36 * and relations, of handling the consistency and of providing query
37 * mechanisms.
38 *
39 * @since 1.5
40 */
41 public interface RelationServiceMBean {
42
43 /**
44 * Checks if the Relation Service is active.
45 * Current condition is that the Relation Service must be registered in the
46 * MBean Server
47 *
48 * @exception RelationServiceNotRegisteredException if it is not
49 * registered
50 */
51 public void isActive()
52 throws RelationServiceNotRegisteredException;
53
54 //
55 // Accessors
56 //
57
58 /**
59 * Returns the flag to indicate if when a notification is received for the
60 * unregistration of an MBean referenced in a relation, if an immediate
61 * "purge" of the relations (look for the relations no longer valid)
62 * has to be performed, or if that will be performed only when the
63 * purgeRelations method is explicitly called.
64 * <P>true is immediate purge.
65 *
66 * @return true if purges are immediate.
67 *
68 * @see #setPurgeFlag
69 */
70 public boolean getPurgeFlag();
71
72 /**
73 * Sets the flag to indicate if when a notification is received for the
74 * unregistration of an MBean referenced in a relation, if an immediate
75 * "purge" of the relations (look for the relations no longer valid)
76 * has to be performed, or if that will be performed only when the
77 * purgeRelations method is explicitly called.
78 * <P>true is immediate purge.
79 *
80 * @param purgeFlag flag
81 *
82 * @see #getPurgeFlag
83 */
84 public void setPurgeFlag(boolean purgeFlag);
85
86 //
87 // Relation type handling
88 //
89
90 /**
91 * Creates a relation type (RelationTypeSupport object) with given
92 * role infos (provided by the RoleInfo objects), and adds it in the
93 * Relation Service.
94 *
95 * @param relationTypeName name of the relation type
96 * @param roleInfoArray array of role infos
97 *
98 * @exception IllegalArgumentException if null parameter
99 * @exception InvalidRelationTypeException If:
100 * <P>- there is already a relation type with that name
101 * <P>- the same name has been used for two different role infos
102 * <P>- no role info provided
103 * <P>- one null role info provided
104 */
105 public void createRelationType(String relationTypeName,
106 RoleInfo[] roleInfoArray)
107 throws IllegalArgumentException,
108 InvalidRelationTypeException;
109
110 /**
111 * Adds given object as a relation type. The object is expected to
112 * implement the RelationType interface.
113 *
114 * @param relationTypeObj relation type object (implementing the
115 * RelationType interface)
116 *
117 * @exception IllegalArgumentException if null parameter or if
118 * {@link RelationType#getRelationTypeName
119 * relationTypeObj.getRelationTypeName()} returns null.
120 * @exception InvalidRelationTypeException if there is already a relation
121 * type with that name
122 */
123 public void addRelationType(RelationType relationTypeObj)
124 throws IllegalArgumentException,
125 InvalidRelationTypeException;
126
127 /**
128 * Retrieves names of all known relation types.
129 *
130 * @return ArrayList of relation type names (Strings)
131 */
132 public List<String> getAllRelationTypeNames();
133
134 /**
135 * Retrieves list of role infos (RoleInfo objects) of a given relation
136 * type.
137 *
138 * @param relationTypeName name of relation type
139 *
140 * @return ArrayList of RoleInfo.
141 *
142 * @exception IllegalArgumentException if null parameter
143 * @exception RelationTypeNotFoundException if there is no relation type
144 * with that name.
145 */
146 public List<RoleInfo> getRoleInfos(String relationTypeName)
147 throws IllegalArgumentException,
148 RelationTypeNotFoundException;
149
150 /**
151 * Retrieves role info for given role of a given relation type.
152 *
153 * @param relationTypeName name of relation type
154 * @param roleInfoName name of role
155 *
156 * @return RoleInfo object.
157 *
158 * @exception IllegalArgumentException if null parameter
159 * @exception RelationTypeNotFoundException if the relation type is not
160 * known in the Relation Service
161 * @exception RoleInfoNotFoundException if the role is not part of the
162 * relation type.
163 */
164 public RoleInfo getRoleInfo(String relationTypeName,
165 String roleInfoName)
166 throws IllegalArgumentException,
167 RelationTypeNotFoundException,
168 RoleInfoNotFoundException;
169
170 /**
171 * Removes given relation type from Relation Service.
172 * <P>The relation objects of that type will be removed from the
173 * Relation Service.
174 *
175 * @param relationTypeName name of the relation type to be removed
176 *
177 * @exception RelationServiceNotRegisteredException if the Relation
178 * Service is not registered in the MBean Server
179 * @exception IllegalArgumentException if null parameter
180 * @exception RelationTypeNotFoundException If there is no relation type
181 * with that name
182 */
183 public void removeRelationType(String relationTypeName)
184 throws RelationServiceNotRegisteredException,
185 IllegalArgumentException,
186 RelationTypeNotFoundException;
187
188 //
189 // Relation handling
190 //
191
192 /**
193 * Creates a simple relation (represented by a RelationSupport object) of
194 * given relation type, and adds it in the Relation Service.
195 * <P>Roles are initialized according to the role list provided in
196 * parameter. The ones not initialized in this way are set to an empty
197 * ArrayList of ObjectNames.
198 * <P>A RelationNotification, with type RELATION_BASIC_CREATION, is sent.
199 *
200 * @param relationId relation identifier, to identify uniquely the relation
201 * inside the Relation Service
202 * @param relationTypeName name of the relation type (has to be created
203 * in the Relation Service)
204 * @param roleList role list to initialize roles of the relation (can
205 * be null).
206 *
207 * @exception RelationServiceNotRegisteredException if the Relation
208 * Service is not registered in the MBean Server
209 * @exception IllegalArgumentException if null parameter
210 * @exception RoleNotFoundException if a value is provided for a role
211 * that does not exist in the relation type
212 * @exception InvalidRelationIdException if relation id already used
213 * @exception RelationTypeNotFoundException if relation type not known in
214 * Relation Service
215 * @exception InvalidRoleValueException if:
216 * <P>- the same role name is used for two different roles
217 * <P>- the number of referenced MBeans in given value is less than
218 * expected minimum degree
219 * <P>- the number of referenced MBeans in provided value exceeds expected
220 * maximum degree
221 * <P>- one referenced MBean in the value is not an Object of the MBean
222 * class expected for that role
223 * <P>- an MBean provided for that role does not exist
224 */
225 public void createRelation(String relationId,
226 String relationTypeName,
227 RoleList roleList)
228 throws RelationServiceNotRegisteredException,
229 IllegalArgumentException,
230 RoleNotFoundException,
231 InvalidRelationIdException,
232 RelationTypeNotFoundException,
233 InvalidRoleValueException;
234
235 /**
236 * Adds an MBean created by the user (and registered by him in the MBean
237 * Server) as a relation in the Relation Service.
238 * <P>To be added as a relation, the MBean must conform to the
239 * following:
240 * <P>- implement the Relation interface
241 * <P>- have for RelationService ObjectName the ObjectName of current
242 * Relation Service
243 * <P>- have a relation id that is unique and unused in current Relation Service
244 * <P>- have for relation type a relation type created in the Relation
245 * Service
246 * <P>- have roles conforming to the role info provided in the relation
247 * type.
248 *
249 * @param relationObjectName ObjectName of the relation MBean to be added.
250 *
251 * @exception IllegalArgumentException if null parameter
252 * @exception RelationServiceNotRegisteredException if the Relation
253 * Service is not registered in the MBean Server
254 * @exception NoSuchMethodException If the MBean does not implement the
255 * Relation interface
256 * @exception InvalidRelationIdException if:
257 * <P>- no relation identifier in MBean
258 * <P>- the relation identifier is already used in the Relation Service
259 * @exception InstanceNotFoundException if the MBean for given ObjectName
260 * has not been registered
261 * @exception InvalidRelationServiceException if:
262 * <P>- no Relation Service name in MBean
263 * <P>- the Relation Service name in the MBean is not the one of the
264 * current Relation Service
265 * @exception RelationTypeNotFoundException if:
266 * <P>- no relation type name in MBean
267 * <P>- the relation type name in MBean does not correspond to a relation
268 * type created in the Relation Service
269 * @exception InvalidRoleValueException if:
270 * <P>- the number of referenced MBeans in a role is less than
271 * expected minimum degree
272 * <P>- the number of referenced MBeans in a role exceeds expected
273 * maximum degree
274 * <P>- one referenced MBean in the value is not an Object of the MBean
275 * class expected for that role
276 * <P>- an MBean provided for a role does not exist
277 * @exception RoleNotFoundException if a value is provided for a role
278 * that does not exist in the relation type
279 */
280 public void addRelation(ObjectName relationObjectName)
281 throws IllegalArgumentException,
282 RelationServiceNotRegisteredException,
283 NoSuchMethodException,
284 InvalidRelationIdException,
285 InstanceNotFoundException,
286 InvalidRelationServiceException,
287 RelationTypeNotFoundException,
288 RoleNotFoundException,
289 InvalidRoleValueException;
290
291 /**
292 * If the relation is represented by an MBean (created by the user and
293 * added as a relation in the Relation Service), returns the ObjectName of
294 * the MBean.
295 *
296 * @param relationId relation id identifying the relation
297 *
298 * @return ObjectName of the corresponding relation MBean, or null if
299 * the relation is not an MBean.
300 *
301 * @exception IllegalArgumentException if null parameter
302 * @exception RelationNotFoundException there is no relation associated
303 * to that id
304 */
305 public ObjectName isRelationMBean(String relationId)
306 throws IllegalArgumentException,
307 RelationNotFoundException;
308
309 /**
310 * Returns the relation id associated to the given ObjectName if the
311 * MBean has been added as a relation in the Relation Service.
312 *
313 * @param objectName ObjectName of supposed relation
314 *
315 * @return relation id (String) or null (if the ObjectName is not a
316 * relation handled by the Relation Service)
317 *
318 * @exception IllegalArgumentException if null parameter
319 */
320 public String isRelation(ObjectName objectName)
321 throws IllegalArgumentException;
322
323 /**
324 * Checks if there is a relation identified in Relation Service with given
325 * relation id.
326 *
327 * @param relationId relation id identifying the relation
328 *
329 * @return boolean: true if there is a relation, false else
330 *
331 * @exception IllegalArgumentException if null parameter
332 */
333 public Boolean hasRelation(String relationId)
334 throws IllegalArgumentException;
335
336 /**
337 * Returns all the relation ids for all the relations handled by the
338 * Relation Service.
339 *
340 * @return ArrayList of String
341 */
342 public List<String> getAllRelationIds();
343
344 /**
345 * Checks if given Role can be read in a relation of the given type.
346 *
347 * @param roleName name of role to be checked
348 * @param relationTypeName name of the relation type
349 *
350 * @return an Integer wrapping an integer corresponding to possible
351 * problems represented as constants in RoleUnresolved:
352 * <P>- 0 if role can be read
353 * <P>- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME
354 * <P>- integer corresponding to RoleStatus.ROLE_NOT_READABLE
355 *
356 * @exception IllegalArgumentException if null parameter
357 * @exception RelationTypeNotFoundException if the relation type is not
358 * known in the Relation Service
359 */
360 public Integer checkRoleReading(String roleName,
361 String relationTypeName)
362 throws IllegalArgumentException,
363 RelationTypeNotFoundException;
364
365 /**
366 * Checks if given Role can be set in a relation of given type.
367 *
368 * @param role role to be checked
369 * @param relationTypeName name of relation type
370 * @param initFlag flag to specify that the checking is done for the
371 * initialization of a role, write access shall not be verified.
372 *
373 * @return an Integer wrapping an integer corresponding to possible
374 * problems represented as constants in RoleUnresolved:
375 * <P>- 0 if role can be set
376 * <P>- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME
377 * <P>- integer for RoleStatus.ROLE_NOT_WRITABLE
378 * <P>- integer for RoleStatus.LESS_THAN_MIN_ROLE_DEGREE
379 * <P>- integer for RoleStatus.MORE_THAN_MAX_ROLE_DEGREE
380 * <P>- integer for RoleStatus.REF_MBEAN_OF_INCORRECT_CLASS
381 * <P>- integer for RoleStatus.REF_MBEAN_NOT_REGISTERED
382 *
383 * @exception IllegalArgumentException if null parameter
384 * @exception RelationTypeNotFoundException if unknown relation type
385 */
386 public Integer checkRoleWriting(Role role,
387 String relationTypeName,
388 Boolean initFlag)
389 throws IllegalArgumentException,
390 RelationTypeNotFoundException;
391
392 /**
393 * Sends a notification (RelationNotification) for a relation creation.
394 * The notification type is:
395 * <P>- RelationNotification.RELATION_BASIC_CREATION if the relation is an
396 * object internal to the Relation Service
397 * <P>- RelationNotification.RELATION_MBEAN_CREATION if the relation is a
398 * MBean added as a relation.
399 * <P>The source object is the Relation Service itself.
400 * <P>It is called in Relation Service createRelation() and
401 * addRelation() methods.
402 *
403 * @param relationId relation identifier of the updated relation
404 *
405 * @exception IllegalArgumentException if null parameter
406 * @exception RelationNotFoundException if there is no relation for given
407 * relation id
408 */
409 public void sendRelationCreationNotification(String relationId)
410 throws IllegalArgumentException,
411 RelationNotFoundException;
412
413 /**
414 * Sends a notification (RelationNotification) for a role update in the
415 * given relation. The notification type is:
416 * <P>- RelationNotification.RELATION_BASIC_UPDATE if the relation is an
417 * object internal to the Relation Service
418 * <P>- RelationNotification.RELATION_MBEAN_UPDATE if the relation is a
419 * MBean added as a relation.
420 * <P>The source object is the Relation Service itself.
421 * <P>It is called in relation MBean setRole() (for given role) and
422 * setRoles() (for each role) methods (implementation provided in
423 * RelationSupport class).
424 * <P>It is also called in Relation Service setRole() (for given role) and
425 * setRoles() (for each role) methods.
426 *
427 * @param relationId relation identifier of the updated relation
428 * @param newRole new role (name and new value)
429 * @param oldRoleValue old role value (List of ObjectName objects)
430 *
431 * @exception IllegalArgumentException if null parameter
432 * @exception RelationNotFoundException if there is no relation for given
433 * relation id
434 */
435 public void sendRoleUpdateNotification(String relationId,
436 Role newRole,
437 List<ObjectName> oldRoleValue)
438 throws IllegalArgumentException,
439 RelationNotFoundException;
440
441 /**
442 * Sends a notification (RelationNotification) for a relation removal.
443 * The notification type is:
444 * <P>- RelationNotification.RELATION_BASIC_REMOVAL if the relation is an
445 * object internal to the Relation Service
446 * <P>- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is a
447 * MBean added as a relation.
448 * <P>The source object is the Relation Service itself.
449 * <P>It is called in Relation Service removeRelation() method.
450 *
451 * @param relationId relation identifier of the updated relation
452 * @param unregMBeanList List of ObjectNames of MBeans expected
453 * to be unregistered due to relation removal (can be null)
454 *
455 * @exception IllegalArgumentException if null parameter
456 * @exception RelationNotFoundException if there is no relation for given
457 * relation id
458 */
459 public void sendRelationRemovalNotification(String relationId,
460 List<ObjectName> unregMBeanList)
461 throws IllegalArgumentException,
462 RelationNotFoundException;
463
464 /**
465 * Handles update of the Relation Service role map for the update of given
466 * role in given relation.
467 * <P>It is called in relation MBean setRole() (for given role) and
468 * setRoles() (for each role) methods (implementation provided in
469 * RelationSupport class).
470 * <P>It is also called in Relation Service setRole() (for given role) and
471 * setRoles() (for each role) methods.
472 * <P>To allow the Relation Service to maintain the consistency (in case
473 * of MBean unregistration) and to be able to perform queries, this method
474 * must be called when a role is updated.
475 *
476 * @param relationId relation identifier of the updated relation
477 * @param newRole new role (name and new value)
478 * @param oldRoleValue old role value (List of ObjectName objects)
479 *
480 * @exception IllegalArgumentException if null parameter
481 * @exception RelationServiceNotRegisteredException if the Relation
482 * Service is not registered in the MBean Server
483 * @exception RelationNotFoundException if no relation for given id.
484 */
485 public void updateRoleMap(String relationId,
486 Role newRole,
487 List<ObjectName> oldRoleValue)
488 throws IllegalArgumentException,
489 RelationServiceNotRegisteredException,
490 RelationNotFoundException;
491
492 /**
493 * Removes given relation from the Relation Service.
494 * <P>A RelationNotification notification is sent, its type being:
495 * <P>- RelationNotification.RELATION_BASIC_REMOVAL if the relation was
496 * only internal to the Relation Service
497 * <P>- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is
498 * registered as an MBean.
499 * <P>For MBeans referenced in such relation, nothing will be done,
500 *
501 * @param relationId relation id of the relation to be removed
502 *
503 * @exception RelationServiceNotRegisteredException if the Relation
504 * Service is not registered in the MBean Server
505 * @exception IllegalArgumentException if null parameter
506 * @exception RelationNotFoundException if no relation corresponding to
507 * given relation id
508 */
509 public void removeRelation(String relationId)
510 throws RelationServiceNotRegisteredException,
511 IllegalArgumentException,
512 RelationNotFoundException;
513
514 /**
515 * Purges the relations.
516 *
517 * <P>Depending on the purgeFlag value, this method is either called
518 * automatically when a notification is received for the unregistration of
519 * an MBean referenced in a relation (if the flag is set to true), or not
520 * (if the flag is set to false).
521 * <P>In that case it is up to the user to call it to maintain the
522 * consistency of the relations. To be kept in mind that if an MBean is
523 * unregistered and the purge not done immediately, if the ObjectName is
524 * reused and assigned to another MBean referenced in a relation, calling
525 * manually this purgeRelations() method will cause trouble, as will
526 * consider the ObjectName as corresponding to the unregistered MBean, not
527 * seeing the new one.
528 *
529 * <P>The behavior depends on the cardinality of the role where the
530 * unregistered MBean is referenced:
531 * <P>- if removing one MBean reference in the role makes its number of
532 * references less than the minimum degree, the relation has to be removed.
533 * <P>- if the remaining number of references after removing the MBean
534 * reference is still in the cardinality range, keep the relation and
535 * update it calling its handleMBeanUnregistration() callback.
536 *
537 * @exception RelationServiceNotRegisteredException if the Relation
538 * Service is not registered in the MBean Server.
539 */
540 public void purgeRelations()
541 throws RelationServiceNotRegisteredException;
542
543 /**
544 * Retrieves the relations where a given MBean is referenced.
545 * <P>This corresponds to the CIM "References" and "ReferenceNames"
546 * operations.
547 *
548 * @param mbeanName ObjectName of MBean
549 * @param relationTypeName can be null; if specified, only the relations
550 * of that type will be considered in the search. Else all relation types
551 * are considered.
552 * @param roleName can be null; if specified, only the relations
553 * where the MBean is referenced in that role will be returned. Else all
554 * roles are considered.
555 *
556 * @return an HashMap, where the keys are the relation ids of the relations
557 * where the MBean is referenced, and the value is, for each key,
558 * an ArrayList of role names (as an MBean can be referenced in several
559 * roles in the same relation).
560 *
561 * @exception IllegalArgumentException if null parameter
562 */
563 public Map<String,List<String>>
564 findReferencingRelations(ObjectName mbeanName,
565 String relationTypeName,
566 String roleName)
567 throws IllegalArgumentException;
568
569 /**
570 * Retrieves the MBeans associated to given one in a relation.
571 * <P>This corresponds to CIM Associators and AssociatorNames operations.
572 *
573 * @param mbeanName ObjectName of MBean
574 * @param relationTypeName can be null; if specified, only the relations
575 * of that type will be considered in the search. Else all
576 * relation types are considered.
577 * @param roleName can be null; if specified, only the relations
578 * where the MBean is referenced in that role will be considered. Else all
579 * roles are considered.
580 *
581 * @return an HashMap, where the keys are the ObjectNames of the MBeans
582 * associated to given MBean, and the value is, for each key, an ArrayList
583 * of the relation ids of the relations where the key MBean is
584 * associated to given one (as they can be associated in several different
585 * relations).
586 *
587 * @exception IllegalArgumentException if null parameter
588 */
589 public Map<ObjectName,List<String>>
590 findAssociatedMBeans(ObjectName mbeanName,
591 String relationTypeName,
592 String roleName)
593 throws IllegalArgumentException;
594
595 /**
596 * Returns the relation ids for relations of the given type.
597 *
598 * @param relationTypeName relation type name
599 *
600 * @return an ArrayList of relation ids.
601 *
602 * @exception IllegalArgumentException if null parameter
603 * @exception RelationTypeNotFoundException if there is no relation type
604 * with that name.
605 */
606 public List<String> findRelationsOfType(String relationTypeName)
607 throws IllegalArgumentException,
608 RelationTypeNotFoundException;
609
610 /**
611 * Retrieves role value for given role name in given relation.
612 *
613 * @param relationId relation id
614 * @param roleName name of role
615 *
616 * @return the ArrayList of ObjectName objects being the role value
617 *
618 * @exception RelationServiceNotRegisteredException if the Relation
619 * Service is not registered
620 * @exception IllegalArgumentException if null parameter
621 * @exception RelationNotFoundException if no relation with given id
622 * @exception RoleNotFoundException if:
623 * <P>- there is no role with given name
624 * <P>or
625 * <P>- the role is not readable.
626 *
627 * @see #setRole
628 */
629 public List<ObjectName> getRole(String relationId,
630 String roleName)
631 throws RelationServiceNotRegisteredException,
632 IllegalArgumentException,
633 RelationNotFoundException,
634 RoleNotFoundException;
635
636 /**
637 * Retrieves values of roles with given names in given relation.
638 *
639 * @param relationId relation id
640 * @param roleNameArray array of names of roles to be retrieved
641 *
642 * @return a RoleResult object, including a RoleList (for roles
643 * successfully retrieved) and a RoleUnresolvedList (for roles not
644 * retrieved).
645 *
646 * @exception RelationServiceNotRegisteredException if the Relation
647 * Service is not registered in the MBean Server
648 * @exception IllegalArgumentException if null parameter
649 * @exception RelationNotFoundException if no relation with given id
650 *
651 * @see #setRoles
652 */
653 public RoleResult getRoles(String relationId,
654 String[] roleNameArray)
655 throws RelationServiceNotRegisteredException,
656 IllegalArgumentException,
657 RelationNotFoundException;
658
659 /**
660 * Returns all roles present in the relation.
661 *
662 * @param relationId relation id
663 *
664 * @return a RoleResult object, including a RoleList (for roles
665 * successfully retrieved) and a RoleUnresolvedList (for roles not
666 * readable).
667 *
668 * @exception IllegalArgumentException if null parameter
669 * @exception RelationNotFoundException if no relation for given id
670 * @exception RelationServiceNotRegisteredException if the Relation
671 * Service is not registered in the MBean Server
672 */
673 public RoleResult getAllRoles(String relationId)
674 throws IllegalArgumentException,
675 RelationNotFoundException,
676 RelationServiceNotRegisteredException;
677
678 /**
679 * Retrieves the number of MBeans currently referenced in the
680 * given role.
681 *
682 * @param relationId relation id
683 * @param roleName name of role
684 *
685 * @return the number of currently referenced MBeans in that role
686 *
687 * @exception IllegalArgumentException if null parameter
688 * @exception RelationNotFoundException if no relation with given id
689 * @exception RoleNotFoundException if there is no role with given name
690 */
691 public Integer getRoleCardinality(String relationId,
692 String roleName)
693 throws IllegalArgumentException,
694 RelationNotFoundException,
695 RoleNotFoundException;
696
697 /**
698 * Sets the given role in given relation.
699 * <P>Will check the role according to its corresponding role definition
700 * provided in relation's relation type
701 * <P>The Relation Service will keep track of the change to keep the
702 * consistency of relations by handling referenced MBean unregistrations.
703 *
704 * @param relationId relation id
705 * @param role role to be set (name and new value)
706 *
707 * @exception RelationServiceNotRegisteredException if the Relation
708 * Service is not registered in the MBean Server
709 * @exception IllegalArgumentException if null parameter
710 * @exception RelationNotFoundException if no relation with given id
711 * @exception RoleNotFoundException if:
712 * <P>- internal relation
713 * <P>and
714 * <P>- the role does not exist or is not writable
715 * @exception InvalidRoleValueException if internal relation and value
716 * provided for role is not valid:
717 * <P>- the number of referenced MBeans in given value is less than
718 * expected minimum degree
719 * <P>or
720 * <P>- the number of referenced MBeans in provided value exceeds expected
721 * maximum degree
722 * <P>or
723 * <P>- one referenced MBean in the value is not an Object of the MBean
724 * class expected for that role
725 * <P>or
726 * <P>- an MBean provided for that role does not exist
727 * @exception RelationTypeNotFoundException if unknown relation type
728 *
729 * @see #getRole
730 */
731 public void setRole(String relationId,
732 Role role)
733 throws RelationServiceNotRegisteredException,
734 IllegalArgumentException,
735 RelationNotFoundException,
736 RoleNotFoundException,
737 InvalidRoleValueException,
738 RelationTypeNotFoundException;
739
740 /**
741 * Sets the given roles in given relation.
742 * <P>Will check the role according to its corresponding role definition
743 * provided in relation's relation type
744 * <P>The Relation Service keeps track of the changes to keep the
745 * consistency of relations by handling referenced MBean unregistrations.
746 *
747 * @param relationId relation id
748 * @param roleList list of roles to be set
749 *
750 * @return a RoleResult object, including a RoleList (for roles
751 * successfully set) and a RoleUnresolvedList (for roles not
752 * set).
753 *
754 * @exception RelationServiceNotRegisteredException if the Relation
755 * Service is not registered in the MBean Server
756 * @exception IllegalArgumentException if null parameter
757 * @exception RelationNotFoundException if no relation with given id
758 *
759 * @see #getRoles
760 */
761 public RoleResult setRoles(String relationId,
762 RoleList roleList)
763 throws RelationServiceNotRegisteredException,
764 IllegalArgumentException,
765 RelationNotFoundException;
766
767 /**
768 * Retrieves MBeans referenced in the various roles of the relation.
769 *
770 * @param relationId relation id
771 *
772 * @return a HashMap mapping:
773 * <P> ObjectName -> ArrayList of String (role
774 * names)
775 *
776 * @exception IllegalArgumentException if null parameter
777 * @exception RelationNotFoundException if no relation for given
778 * relation id
779 */
780 public Map<ObjectName,List<String>> getReferencedMBeans(String relationId)
781 throws IllegalArgumentException,
782 RelationNotFoundException;
783
784 /**
785 * Returns name of associated relation type for given relation.
786 *
787 * @param relationId relation id
788 *
789 * @return the name of the associated relation type.
790 *
791 * @exception IllegalArgumentException if null parameter
792 * @exception RelationNotFoundException if no relation for given
793 * relation id
794 */
795 public String getRelationTypeName(String relationId)
796 throws IllegalArgumentException,
797 RelationNotFoundException;
798 }
Save This Page