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