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