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