001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.management.relation;
023:
024: import java.util.List;
025: import java.util.Map;
026:
027: import javax.management.InstanceNotFoundException;
028: import javax.management.ObjectName;
029:
030: /**
031: * This interface defines the management interface for a relation
032: * service. <p>
033: * <p/>
034: * The relation service performs the following functions:<br>
035: * Creating and deleting relation types and relations.<br>
036: * Making sure relations are consistent as defined by information
037: * in their relation types/roles.<br>
038: * Allowing relations to be queried.
039: * <p/>
040: * <p><b>Revisions:</b>
041: * <p><b>20020312 Adrian Brock:</b>
042: * <ul>
043: * <li>Fixed wrong exception types thrown
044: * <li>Add missing method getRoles(String, String[])
045: * </ul>
046: *
047: * @author <a href="mailto:Adrian.Brock@HappeningTimes.com">Adrian Brock</a>.
048: * @version $Revision: 57200 $
049: */
050: public interface RelationServiceMBean {
051: // Constants ---------------------------------------------------
052:
053: // Public ------------------------------------------------------
054:
055: /**
056: * Checks whether the relation service is active, i.e. it is registered
057: * with an MBeanServer.
058: *
059: * @throws RelationServiceNotRegisteredException
060: * when the relation
061: * service is not registered with an MBeanServer.
062: */
063: public void isActive() throws RelationServiceNotRegisteredException;
064:
065: /**
066: * Retrieves the purge flag. This flag controls whether all relations
067: * have to validated when notification is received of an MBeans
068: * unregistration or whether the purgeRelations() method has to be
069: * called.
070: *
071: * @return true for an immediate purge on unregistration, false otherwise.
072: */
073: public boolean getPurgeFlag();
074:
075: /**
076: * Sets the purge flag. This flag controls whether all relations
077: * have to validated when notification is received of an MBeans
078: * unregistration or whether the purgeRelations() method has to be
079: * called.
080: *
081: * @param value true for an immediate purge on unregistration, false
082: * otherwise.
083: */
084: public void setPurgeFlag(boolean value);
085:
086: /**
087: * Create a relation type within the relation service.
088: *
089: * @param relationTypeName the relation type name.
090: * @param roleInfos an array of role infos.
091: * @throws IllegalArgumentException for a null relation type.
092: * @throws InvalidRelationTypeException if a relation type already
093: * exists in the relation service with the given name, there
094: * are problems with the role infos.
095: */
096: public void createRelationType(String relationTypeName,
097: RoleInfo[] roleInfos) throws IllegalArgumentException,
098: InvalidRelationTypeException;
099:
100: /**
101: * Add a relation type to the relation service.
102: *
103: * @param relationType the relation type.
104: * @throws IllegalArgumentException for a null relation type.
105: * @throws InvalidRelationTypeException if a relation type already
106: * exists in the relation service with the given name.
107: */
108: public void addRelationType(RelationType relationType)
109: throws IllegalArgumentException,
110: InvalidRelationTypeException;
111:
112: /**
113: * Retrieves all the relation type names.
114: *
115: * @return an ArrayList of relation type names
116: */
117: public List getAllRelationTypeNames();
118:
119: /**
120: * Retrieves all the role information for a given relation type.
121: *
122: * @param relationTypeName the relation type name
123: * @return an ArrayList of role information.
124: * @throws IllegalArgumentException for a null parameter.
125: * @throws RelationTypeNotFoundException when the relation id does not
126: * exist.
127: */
128: public List getRoleInfos(String relationTypeName)
129: throws IllegalArgumentException,
130: RelationTypeNotFoundException;
131:
132: /**
133: * Retrieves the role information for a given relation type.
134: *
135: * @param relationTypeName the relation type name
136: * @param roleInfoName the role information name
137: * @return the role information.
138: * @throws IllegalArgumentException for a null parameter.
139: * @throws RelationTypeNotFoundException when the relation type does not
140: * exist.
141: * @throws RoleInfoNotFoundException when the role information does not
142: * exist for the relation type.
143: */
144: public RoleInfo getRoleInfo(String relationTypeName,
145: String roleInfoName) throws IllegalArgumentException,
146: RelationTypeNotFoundException, RoleInfoNotFoundException;
147:
148: /**
149: * Removes a relation type from the relation service.<p>
150: * <p/>
151: * Any relations using this relation type are also removed.
152: *
153: * @param relationTypeName the relation type name
154: * @throws IllegalArgumentException for a null parameter.
155: * @throws RelationTypeNotFoundException when the relation type does not
156: * exist.
157: * @throws RelationServiceNotRegisteredException
158: * when the relation
159: * service is not registered with an MBeanServer.
160: */
161: public void removeRelationType(String relationTypeName)
162: throws RelationServiceNotRegisteredException,
163: IllegalArgumentException, RelationTypeNotFoundException;
164:
165: /**
166: * Create a simple relation using {@link RelationSupport} for a relation
167: * type within the relation service.<p>
168: * <p/>
169: * Roles not initialised are set to an empty ArrayList.<p>
170: * <p/>
171: * A RELATION_BASIC_CREATION notification is sent.
172: *
173: * @param relationId the relation id of the relation
174: * @param relationTypeName the relation type of the relation
175: * @param roleList the roles to initialise in the relation (can be null)
176: * @throws IllegalArgumentException for a null parameter.
177: * @throws RelationServiceNotRegisteredException
178: * when the relation
179: * service is not registered with the MBeanServer.
180: * @throws InvalidRelationIdException if the relation id
181: * is already used by another relation.
182: * @throws RelationTypeNotFoundException if there is no relation type in
183: * the relation or the relation type has not been registered
184: * with the relation service.
185: * @throws InvalidRoleValueException if the number of MBeans in a
186: * role is outside the bounds of the RoleInfo defined in the
187: * relation type, one of the MBeans is not of the correct
188: * class, an MBean does not exist, the same role name is
189: * used in two different relations.
190: * @throws RoleNotFoundException if a role in the relation is not
191: * in the relation type.
192: */
193: public void createRelation(String relationId,
194: String relationTypeName, RoleList roleList)
195: throws RelationServiceNotRegisteredException,
196: IllegalArgumentException, RoleNotFoundException,
197: InvalidRelationIdException, RelationTypeNotFoundException,
198: InvalidRoleValueException;
199:
200: /**
201: * Add a manually created relation to the relation service. It must
202: * be registered with the same MBeanService as the relation service.
203: * <p/>
204: * A RELATION_MBEAN_CREATION notification is sent.
205: *
206: * @param relation the object name of the relation
207: * @throws IllegalArgumentException for a null object name.
208: * @throws NoSuchMethodException if the mbean does not implement the
209: * Relation interface.
210: * @throws RelationServiceNotRegisteredException
211: * when the relation
212: * service is not registered with the MBeanServer.
213: * @throws InstanceNotFoundException when the relation is not
214: * registered in the MBeanServer.
215: * @throws InvalidRelationIdException if the relation id
216: * is already used by another relation.
217: * @throws InvalidRelationServiceException
218: * if the relation service in
219: * the relation is null or is not the relation service to which
220: * it is being added.
221: * @throws RelationTypeNotFoundException if there is no relation type in
222: * the relation or the relation type has not been registered
223: * with the relation service.
224: * @throws InvalidRoleValueException if the number of MBeans in a
225: * role is outside the bounds of the RoleInfo defined in the
226: * relation type, one of the MBeans is not of the correct
227: * class or an MBean does not exist.
228: * @throws RoleNotFoundException if a role in the relation is not
229: * in the relation type.
230: */
231: public void addRelation(ObjectName relation)
232: throws IllegalArgumentException,
233: RelationServiceNotRegisteredException,
234: NoSuchMethodException, InvalidRelationIdException,
235: InstanceNotFoundException, InvalidRelationServiceException,
236: RelationTypeNotFoundException, RoleNotFoundException,
237: InvalidRoleValueException;
238:
239: /**
240: * Checks whether the passed relation id is an MBean created by a user
241: * or has been internally created by the relation service.
242: *
243: * @param relationId the relation id to check
244: * @return the object name of the MBean when it is externally created,
245: * null otherwise.
246: * @throws IllegalArgumentException for a null object name.
247: * @throws RelationNotFoundException when the relation id does not
248: * exist.
249: */
250: public ObjectName isRelationMBean(String relationId)
251: throws IllegalArgumentException, RelationNotFoundException;
252:
253: /**
254: * Checks whether the passed object name is a relation in this relation
255: * service.
256: *
257: * @param objectName the name of the MBean to check
258: * @return the relation id the MBean is registered as, or null
259: * when not registered.
260: * @throws IllegalArgumentException for a null object name.
261: */
262: public String isRelation(ObjectName objectName)
263: throws IllegalArgumentException;
264:
265: /**
266: * Checks whether the relation service has the passed relation id.
267: *
268: * @param relationId the relation id
269: * @return true when it has the relationId, false otherwise.
270: * @throws IllegalArgumentException for a null parameter.
271: */
272: public Boolean hasRelation(String relationId)
273: throws IllegalArgumentException;
274:
275: /**
276: * Retrieves all the relation ids.
277: *
278: * @return an ArrayList of relation ids.
279: */
280: public List getAllRelationIds();
281:
282: /**
283: * Checks whether the passed role can be read in the given
284: * relation type.<p>
285: * <p/>
286: * The return value is either zero when readable or a value from
287: * {@link RoleStatus}.
288: *
289: * @param roleName the name of the role to check.
290: * @param relationTypeName the relation type to check.
291: * @return the result described above.
292: * @throws IllegalArgumentException for a null parameters.
293: * @throws RelationTypeNotFoundException if the relation type does
294: * exist in the relation service.
295: */
296: public Integer checkRoleReading(String roleName,
297: String relationTypeName) throws IllegalArgumentException,
298: RelationTypeNotFoundException;
299:
300: /**
301: * Checks whether the passed role can be written in the given
302: * relation type.<p>
303: * <p/>
304: * The return value is either zero when writable or a value from
305: * {@link RoleStatus}.
306: *
307: * @param role the role to check.
308: * @param relationTypeName the relation type to check.
309: * @param initFlag write access is not check when this flag is true.
310: * @return the result described above.
311: * @throws IllegalArgumentException for a null parameters.
312: * @throws RelationTypeNotFoundException if the relation type does
313: * exist in the relation service.
314: */
315: public Integer checkRoleWriting(Role role, String relationTypeName,
316: Boolean initFlag) throws IllegalArgumentException,
317: RelationTypeNotFoundException;
318:
319: /**
320: * Sends a relation creation notification
321: * <p/>
322: * For internally created relations, a RELATION_BASIC_CREATION
323: * notification is sent.<p>
324: * <p/>
325: * For externally created relations, a RELATION_MBEAN_CREATION
326: * notification is sent.<p>
327: * <p/>
328: * The source is this relation service.<p>
329: * <p/>
330: * This method is called by addRelation() and createRelation()
331: *
332: * @param relationId the relation id
333: * @throws IllegalArgumentException for a null parameter.
334: * @throws RelationNotFoundException when the relation id does not
335: * exist.
336: */
337: public void sendRelationCreationNotification(String relationId)
338: throws IllegalArgumentException, RelationNotFoundException;
339:
340: /**
341: * Sends a relation update notification
342: * <p/>
343: * For internally created relations, a RELATION_BASIC_UPDATE
344: * notification is sent.<p>
345: * <p/>
346: * For externally created relations, a RELATION_MBEAN_UPDATE
347: * notification is sent.<p>
348: * <p/>
349: * The source is this relation service.<p>
350: * <p/>
351: * This method is called from the RelationSupport setRole() and
352: * setRoles() methods.
353: *
354: * @param relationId the relation id
355: * @param newRole the new role
356: * @param oldRoleValue a list of MBeans in the old role
357: * @throws IllegalArgumentException for a null parameter.
358: * @throws RelationNotFoundException when the relation id does not
359: * exist.
360: */
361: public void sendRoleUpdateNotification(String relationId,
362: Role newRole, List oldRoleValue)
363: throws IllegalArgumentException, RelationNotFoundException;
364:
365: /**
366: * Sends a relation removal notification
367: * <p/>
368: * For internally created relations, a RELATION_BASIC_REMOVAL
369: * notification is sent.<p>
370: * <p/>
371: * For externally created relations, a RELATION_MBEAN_REMOVAL
372: * notification is sent.<p>
373: * <p/>
374: * The source is this relation service.<p>
375: * <p/>
376: * This method is called by removeRelation()
377: *
378: * @param relationId the relation id
379: * @param unregMBeans a list of MBeans to be unregistered due to this
380: * removal (can be null)
381: * @throws IllegalArgumentException for a null parameter.
382: * @throws RelationNotFoundException when the relation id does not
383: * exist.
384: */
385: public void sendRelationRemovalNotification(String relationId,
386: List unregMBeans) throws IllegalArgumentException,
387: RelationNotFoundException;
388:
389: /**
390: * Handles the update of the relation service role map when a role
391: * is changed.<p>
392: * <p/>
393: * It is called from RelationSupport setRole() and setRoles() and
394: * the relation service's setRole() and setRoles() methods.<p>
395: * <p/>
396: * The relation service will keep track the MBeans unregistration
397: * to maintain the consistency of the relation.
398: *
399: * @param relationId the relation id
400: * @param newRole the new role
401: * @param oldRoleValue a list of MBeans in the old role
402: * @throws IllegalArgumentException for a null parameter.
403: * @throws RelationNotFoundException when the relation id does not
404: * exist.
405: * @throws RelationServiceNotRegisteredException
406: * when the relation
407: * service has not been registered with an MBeanServer
408: */
409: public void updateRoleMap(String relationId, Role newRole,
410: List oldRoleValue) throws IllegalArgumentException,
411: RelationServiceNotRegisteredException,
412: RelationNotFoundException;
413:
414: /**
415: * Removes a relation from the relation service.<p>
416: * <p/>
417: * For internally created relations, a RELATION_BASIC_REMOVAL
418: * notification is sent.<p>
419: * <p/>
420: * For externally created relations, a RELATION_MBEAN_REMOVAL
421: * notification is sent.<p>
422: * <p/>
423: * The MBeans referenced in the relation are unaffected.
424: *
425: * @param relationId the relation id
426: * @throws IllegalArgumentException for a null parameter.
427: * @throws RelationNotFoundException when the relation id does not
428: * exist.
429: * @throws RelationServiceNotRegisteredException
430: * when the relation
431: * service is not registered with an MBeanServer.
432: */
433: public void removeRelation(String relationId)
434: throws RelationServiceNotRegisteredException,
435: IllegalArgumentException, RelationNotFoundException;
436:
437: /**
438: * Purge relations. This method is called automatically when the purge
439: * flag is true and an MBean in a relation is unregistered.<p>
440: * <p/>
441: * Not purging relations automatically can lead to problems when the
442: * same object name is reused.<p>
443: * <p/>
444: * If the unregistration causes a role to go below its minimal cardinality,
445: * the relation is removed. Otherwise the relation's
446: * handleMBeanUnregistration() is called.
447: *
448: * @throws RelationServiceNotRegisteredException
449: * when the relation
450: * service is not registered with an MBeanServer.
451: */
452: public void purgeRelations()
453: throws RelationServiceNotRegisteredException;
454:
455: /**
456: * Retrieves MBeans referencing the passed MBean in the passed
457: * relation type and role.
458: *
459: * @param mbeanName the name of the referenced MBean
460: * @param relationTypeName the relation type, null means check all
461: * relation types.
462: * @param roleName the role, null means check all roles.
463: * @return a HashMap with keys of the referencing MBeans with the
464: * value for each MBean an ArrayList of Relation Types.
465: * @throws IllegalArgumentException for a null object name.
466: */
467: public Map findReferencingRelations(ObjectName mbeanName,
468: String relationTypeName, String roleName)
469: throws IllegalArgumentException;
470:
471: /**
472: * Retrieves MBeans associated with the passed MBean in the passed
473: * relation type and role.
474: *
475: * @param mbeanName the name of the reference MBean
476: * @param relationTypeName the relation type, null means check all
477: * relation types.
478: * @param roleName the role, null means check all roles.
479: * @return a HashMap with keys of the related MBeans with the
480: * value for each MBean an ArrayList of Relation Types.
481: * @throws IllegalArgumentException for a null object name.
482: */
483: public Map findAssociatedMBeans(ObjectName mbeanName,
484: String relationTypeName, String roleName)
485: throws IllegalArgumentException;
486:
487: /**
488: * Retrieves the relation ids for relations of the passed type.
489: *
490: * @param relationTypeName the relation type.
491: * @return an ArrayList of relation ids.
492: * @throws IllegalArgumentException for a null relation type name.
493: * @throws RelationTypeNotFoundException if there is no relation type
494: * with the passed name.
495: */
496: public List findRelationsOfType(String relationTypeName)
497: throws IllegalArgumentException,
498: RelationTypeNotFoundException;
499:
500: /**
501: * Retrieves MBeans in a role for a given relation id.
502: *
503: * @param relationId the relation id
504: * @param roleName the role name
505: * @return an ArrayList of object names for mbeans in the role.
506: * @throws IllegalArgumentException for a null parameter.
507: * @throws RelationNotFoundException when the relation id does not
508: * exist.
509: * @throws RelationServiceNotRegisteredException
510: * when the relation
511: * service is not registered with an MBeanServer.
512: * @throws RoleNotFoundException when the role does not exist or
513: * is not readable.
514: */
515: public List getRole(String relationId, String roleName)
516: throws RelationServiceNotRegisteredException,
517: IllegalArgumentException, RelationNotFoundException,
518: RoleNotFoundException;
519:
520: /**
521: * Retrieves selected roles for a relation.
522: *
523: * @param relationId the relation id
524: * @param roleNames an array of role name
525: * @return a RoleResult containing resolved and unresolved roles.
526: * @throws IllegalArgumentException for a null parameter.
527: * @throws RelationNotFoundException when the relation id does not
528: * exist.
529: * @throws RelationServiceNotRegisteredException
530: * when the relation
531: * service is not registered with an MBeanServer.
532: */
533: public RoleResult getRoles(String relationId, String[] roleNames)
534: throws RelationServiceNotRegisteredException,
535: IllegalArgumentException, RelationNotFoundException;
536:
537: /**
538: * Retrieves all the roles for a given relation id.
539: *
540: * @param relationId the relation id
541: * @return a RoleResult with a RoleList for readable roles and a
542: * RoleUnresolvedList for roles that are not readable.
543: * @throws IllegalArgumentException for a null relation id.
544: * @throws RelationNotFoundException when the relation id does not
545: * exist.
546: * @throws RelationServiceNotRegisteredException
547: * when the relation
548: * service is not registered with an MBeanServer.
549: */
550: public RoleResult getAllRoles(String relationId)
551: throws IllegalArgumentException, RelationNotFoundException,
552: RelationServiceNotRegisteredException;
553:
554: /**
555: * Retrieves the number of MBeans in a role for a given relation id.
556: *
557: * @param relationId the relation id
558: * @param roleName the role name
559: * @return the number of mbeans in the role
560: * @throws IllegalArgumentException for a null parameter.
561: * @throws RelationNotFoundException when the relation id does not
562: * exist.
563: * @throws RoleNotFoundException when the role does not exist or
564: * is not readable.
565: */
566: public Integer getRoleCardinality(String relationId, String roleName)
567: throws IllegalArgumentException, RelationNotFoundException,
568: RoleNotFoundException;
569:
570: /**
571: * Sets the role in the passed relation.<p>
572: * <p/>
573: * The role will be validated according to information in the relation
574: * type.<p>
575: * <p/>
576: * The relation service will keep track the MBeans unregistration
577: * to maintain the consistency of the relation.
578: *
579: * @param relationId the relation to change the role for.
580: * @param role the new role
581: * @throws IllegalArgumentException for null parameters
582: * @throws RelationServiceNotRegisteredException
583: * when the relation service
584: * has not been registered with an MBeanServer
585: * @throws RelationNotFoundException when the relation does not exist in
586: * the relation service.
587: * @throws RoleNotFoundException when this is an internal relation or
588: * the role does not exist or it is not writable.
589: * @throws InvalidRoleValueException when the role is not valid according
590: * to information in the relation type.
591: * @throws RelationTypeNotFoundException if the relation type is not known.
592: */
593: public void setRole(String relationId, Role role)
594: throws RelationServiceNotRegisteredException,
595: IllegalArgumentException, RelationNotFoundException,
596: RoleNotFoundException, InvalidRoleValueException,
597: RelationTypeNotFoundException;
598:
599: /**
600: * Sets the roles in the passed relation.<p>
601: * <p/>
602: * The roles will be validated according to information in the relation
603: * type.<p>
604: * <p/>
605: * The relation service will keep track the MBeans unregistration
606: * to maintain the consistency of the relation.
607: *
608: * @param relationId the relation to change the role for.
609: * @param roles the list of roles
610: * @throws IllegalArgumentException for null parameters
611: * @throws RelationServiceNotRegisteredException
612: * when the relation service
613: * has not been registered with an MBeanServer
614: * @throws RelationNotFoundException when the relation does not exist in
615: * the relation service.
616: */
617: public RoleResult setRoles(String relationId, RoleList roles)
618: throws RelationServiceNotRegisteredException,
619: IllegalArgumentException, RelationNotFoundException;
620:
621: /**
622: * Retrieves all the MBeans referenced in all the roles of a
623: * relation.
624: *
625: * @param relationId the relation id
626: * @return a HashMap with a key of the MBeans and the values an
627: * array list of the role names for each MBean.
628: * @throws IllegalArgumentException for a null relation id.
629: * @throws RelationNotFoundException when the relation id does not
630: * exist.
631: */
632: public Map getReferencedMBeans(String relationId)
633: throws IllegalArgumentException, RelationNotFoundException;
634:
635: /**
636: * Retrieves the relation type name for the passed relation.
637: *
638: * @param relationId the relation id
639: * @return the relation type name.
640: * @throws IllegalArgumentException for a null relation id.
641: * @throws RelationNotFoundException when the relation id does not
642: * exist.
643: */
644: public String getRelationTypeName(String relationId)
645: throws IllegalArgumentException, RelationNotFoundException;
646:
647: }
|