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