Java > Open Source Codes > javax > management > relation > RelationSupport


1 /*
2  * @(#)RelationSupport.java 1.31 04/02/10
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.management.relation;
9
10 import javax.management.ObjectName ;
11 import javax.management.MBeanRegistration ;
12 import javax.management.MBeanServer ;
13 import javax.management.InstanceNotFoundException ;
14 import javax.management.ReflectionException ;
15 import javax.management.MBeanException ;
16
17 import java.util.HashMap ;
18 import java.util.ArrayList ;
19 import java.util.Iterator ;
20 import java.util.Map ;
21 import java.util.List ;
22
23 import com.sun.jmx.trace.Trace;
24
25 /**
26  * A RelationSupport object is used internally by the Relation Service to
27  * represent simple relations (only roles, no properties or methods), with an
28  * unlimited number of roles, of any relation type. As internal representation,
29  * it is not exposed to the user.
30  * <P>RelationSupport class conforms to the design patterns of standard MBean. So
31  * the user can decide to instantiate a RelationSupport object himself as
32  * a MBean (as it follows the MBean design patterns), to register it in the
33  * MBean Server, and then to add it in the Relation Service.
34  * <P>The user can also, when creating his own MBean relation class, have it
35  * extending RelationSupport, to retrieve the implementations of required
36  * interfaces (see below).
37  * <P>It is also possible to have in a user relation MBean class a member
38  * being a RelationSupport object, and to implement the required interfaces by
39  * delegating all to this member.
40  * <P> RelationSupport implements the Relation interface (to be handled by the
41  * Relation Service).
42  * <P>It implements also the MBeanRegistration interface to be able to retrieve
43  * the MBean Server where it is registered (if registered as a MBean) to access
44  * to its Relation Service.
45  *
46  * @since 1.5
47  */
48 public class RelationSupport
49     implements RelationSupportMBean , MBeanRegistration {
50
51     //
52 // Private members
53 //
54
55     // Relation identifier (expected to be unique in the Relation Service where
56 // the RelationSupport object will be added)
57 private String myRelId = null;
58
59     // ObjectName of the Relation Service where the relation will be added
60 // REQUIRED if the RelationSupport is created by the user to be registered as
61 // a MBean, as it will have to access the Relation Service via the MBean
62 // Server to perform the check regarding the relation type.
63 // Is null if current object is directly created by the Relation Service,
64 // as the object will directly access it.
65 private ObjectName myRelServiceName = null;
66
67     // Reference to the MBean Server where the Relation Service is
68 // registered
69 // REQUIRED if the RelationSupport is created by the user to be registered as
70 // a MBean, as it will have to access the Relation Service via the MBean
71 // Server to perform the check regarding the relation type.
72 // If the Relationbase object is created by the Relation Service (use of
73 // createRelation() method), this is null as not needed, direct access to
74 // the Relation Service.
75 // If the Relationbase object is created by the user and registered as a
76 // MBean, this is set by the preRegister() method below.
77 private MBeanServer myRelServiceMBeanServer = null;
78
79     // Relation type name (must be known in the Relation Service where the
80 // relation will be added)
81 private String myRelTypeName = null;
82
83     // Role map, mapping <role-name> -> <Role>
84 // Initialised by role list in the constructor, then updated:
85 // - if the relation is a MBean, via setRole() and setRoles() methods, or
86 // via Relation Service setRole() and setRoles() methods
87 // - if the relation is internal to the Relation Service, via
88 // setRoleInt() and setRolesInt() methods.
89 private HashMap myRoleName2ValueMap = new HashMap ();
90
91     // Flag to indicate if the object has been added in the Relation Service
92 private Boolean myInRelServFlg = null;
93
94     //
95 // Constructors
96 //
97
98     /**
99      * Creates object.
100      * <P>This constructor has to be used when the RelationSupport object will be
101      * registered as a MBean by the user, or when creating a user relation
102      * MBean those class extends RelationSupport.
103      * <P>Nothing is done at the Relation Service level, i.e. the RelationSupport
104      * object is not added, and no check if the provided values are correct.
105      * The object is always created, EXCEPT if:
106      * <P>- one mandatory parameter is not provided
107      * <P>- the same name is used for two roles.
108      * <P>To be handled as a relation, the object has then to be added in the
109      * Relation Service using Relation Service method addRelation().
110      *
111      * @param theRelId relation identifier, to identify the relation in the
112      * Relation Service.
113      * <P>Expected to be unique in the given Relation Service.
114      * @param theRelServiceName ObjectName of the Relation Service where
115      * the relation will be registered.
116      * <P>It is required as this is the Relation Service that is aware of the
117      * definition of the relation type of given relation, so that will be able
118      * to check update operations (set).
119      * @param theRelTypeName Name of relation type.
120      * <P>Expected to have been created in given Relation Service.
121      * @param theRoleList list of roles (Role objects) to initialised the
122      * relation. Can be null.
123      * <P>Expected to conform to relation info in associated relation type.
124      *
125      * @exception InvalidRoleValueException if the same name is used for two
126      * roles.
127      * @exception IllegalArgumentException if a required value (Relation
128      * Service Object Name, etc.) is not provided as parameter.
129      */
130     public RelationSupport(String theRelId,
131             ObjectName theRelServiceName,
132             String theRelTypeName,
133             RoleList theRoleList)
134     throws InvalidRoleValueException ,
135                IllegalArgumentException {
136
137     super();
138
139     if (isTraceOn())
140             trace("Constructor: entering", null);
141
142     // Can throw InvalidRoleValueException and IllegalArgumentException
143 initMembers(theRelId,
144             theRelServiceName,
145             null,
146             theRelTypeName,
147             theRoleList);
148
149     if (isTraceOn())
150         trace("Constructor: exiting", null);
151     }
152
153     /**
154      * Creates object.
155      * <P>This constructor has to be used when the user relation MBean
156      * implements the interfaces expected to be supported by a relation by
157      * delegating to a RelationSupport object.
158      * <P>This object needs to know the Relation Service expected to handle the
159      * relation. So it has to know the MBean Server where the Relation Service
160      * is registered.
161      * <P>According to a limitation, a relation MBean must be registered in the
162      * same MBean Server as the Relation Service expected to handle it. So the
163      * user relation MBean has to be created and registered, and then the
164      * wrapped RelationSupport object can be created with identified MBean
165      * Server.
166      * <P>Nothing is done at the Relation Service level, i.e. the RelationSupport
167      * object is not added, and no check if the provided values are correct.
168      * The object is always created, EXCEPT if:
169      * <P>- one required parameter is not provided
170      * <P>- the same name is used for two roles.
171      * <P>To be handled as a relation, the object has then to be added in the
172      * Relation Service using the Relation Service method addRelation().
173      *
174      * @param theRelId relation identifier, to identify the relation in the
175      * Relation Service.
176      * <P>Expected to be unique in the given Relation Service.
177      * @param theRelServiceName ObjectName of the Relation Service where
178      * the relation will be registered.
179      * <P>It is required as this is the Relation Service that is aware of the
180      * definition of the relation type of given relation, so that will be able
181      * to check update operations (set).
182      * @param theRelServiceMBeanServer MBean Server where the wrapping MBean
183      * is or will be registered.
184      * <P>Expected to be the MBean Server where the Relation Service is or will
185      * be registered.
186      * @param theRelTypeName Name of relation type.
187      * <P>Expected to have been created in given Relation Service.
188      * @param theRoleList list of roles (Role objects) to initialised the
189      * relation. Can be null.
190      * <P>Expected to conform to relation info in associated relation type.
191      *
192      * @exception InvalidRoleValueException if the same name is used for two
193      * roles.
194      * @exception IllegalArgumentException if a required value (Relation
195      * Service Object Name, etc.) is not provided as parameter.
196      */
197     public RelationSupport(String theRelId,
198             ObjectName theRelServiceName,
199             MBeanServer theRelServiceMBeanServer,
200             String theRelTypeName,
201             RoleList theRoleList)
202     throws InvalidRoleValueException ,
203                IllegalArgumentException {
204
205     super();
206
207     if (theRelServiceMBeanServer == null) {
208         // Revisit [cebro] Localize message
209 String excMsg = "Invalid parameter.";
210         throw new IllegalArgumentException (excMsg);
211     }
212
213     if (isTraceOn())
214             trace("Constructor: entering", null);
215
216     // Can throw InvalidRoleValueException and
217 // IllegalArgumentException
218 initMembers(theRelId,
219             theRelServiceName,
220             theRelServiceMBeanServer,
221             theRelTypeName,
222             theRoleList);
223
224     if (isTraceOn())
225         trace("Constructor: exiting", null);
226     }
227
228     //
229 // Relation Interface
230 //
231
232     /**
233      * Retrieves role value for given role name.
234      * <P>Checks if the role exists and is readable according to the relation
235      * type.
236      *
237      * @param theRoleName name of role
238      *
239      * @return the ArrayList of ObjectName objects being the role value
240      *
241      * @exception IllegalArgumentException if null role name
242      * @exception RoleNotFoundException if:
243      * <P>- there is no role with given name
244      * <P>- the role is not readable.
245      * @exception RelationServiceNotRegisteredException if the Relation
246      * Service is not registered in the MBean Server
247      *
248      * @see #setRole
249      */
250     public List getRole(String theRoleName)
251     throws IllegalArgumentException ,
252            RoleNotFoundException ,
253            RelationServiceNotRegisteredException {
254
255     if (theRoleName == null) {
256         // Revisit [cebro] Localize message
257 String excMsg = "Invalid parameter.";
258         throw new IllegalArgumentException (excMsg);
259     }
260
261     if (isTraceOn())
262         trace("getRole: entering", theRoleName);
263
264     // Can throw RoleNotFoundException and
265 // RelationServiceNotRegisteredException
266 ArrayList result = (ArrayList )
267         (getRoleInt(theRoleName, false, null, false));
268
269     if (isTraceOn())
270         trace("getRole: exiting", null);
271     return result;
272     }
273
274     /**
275      * Retrieves values of roles with given names.
276      * <P>Checks for each role if it exists and is readable according to the
277      * relation type.
278      *
279      * @param theRoleNameArray array of names of roles to be retrieved
280      *
281      * @return a RoleResult object, including a RoleList (for roles
282      * successfully retrieved) and a RoleUnresolvedList (for roles not
283      * retrieved).
284      *
285      * @exception IllegalArgumentException if null role name
286      * @exception RelationServiceNotRegisteredException if the Relation
287      * Service is not registered in the MBean Server
288      *
289      * @see #setRoles
290      */
291     public RoleResult getRoles(String [] theRoleNameArray)
292     throws IllegalArgumentException ,
293            RelationServiceNotRegisteredException {
294
295     if (theRoleNameArray == null) {
296         // Revisit [cebro] Localize message
297 String excMsg = "Invalid parameter.";
298         throw new IllegalArgumentException (excMsg);
299     }
300
301     if (isTraceOn())
302             trace("getRoles: entering", null);
303
304     // Can throw RelationServiceNotRegisteredException
305 RoleResult result = getRolesInt(theRoleNameArray, false, null);
306
307     if (isTraceOn())
308             trace("getRoles: exiting", null);
309     return result;
310     }
311
312     /**
313      * Returns all roles present in the relation.
314      *
315      * @return a RoleResult object, including a RoleList (for roles
316      * successfully retrieved) and a RoleUnresolvedList (for roles not
317      * readable).
318      *
319      * @exception RelationServiceNotRegisteredException if the Relation
320      * Service is not registered in the MBean Server
321      */
322     public RoleResult getAllRoles()
323         throws RelationServiceNotRegisteredException {
324
325     if (isTraceOn())
326             trace("getAllRoles: entering", null);
327
328     RoleResult result = null;
329     try {
330         result = getAllRolesInt(false, null);
331     } catch (IllegalArgumentException exc) {
332         // OK : Invalid parameters, ignore...
333 }
334
335     if (isTraceOn())
336             trace("getAllRoles: exiting", null);
337     return result;
338     }
339
340     /**
341      * Returns all roles in the relation without checking read mode.
342      *
343      * @return a RoleList
344      */
345     public RoleList retrieveAllRoles() {
346
347     if (isTraceOn())
348             trace("retrieveAllRoles: entering", null);
349
350     RoleList result = null;
351     synchronized(myRoleName2ValueMap) {
352         result =
353         new RoleList (new ArrayList (myRoleName2ValueMap.values()));
354     }
355
356     if (isTraceOn())
357             trace("retrieveAllRoles: exiting", null);
358     return result;
359     }
360
361     /**
362      * Returns the number of MBeans currently referenced in the given role.
363      *
364      * @param theRoleName name of role
365      *
366      * @return the number of currently referenced MBeans in that role
367      *
368      * @exception IllegalArgumentException if null role name
369      * @exception RoleNotFoundException if there is no role with given name
370      */
371     public Integer getRoleCardinality(String theRoleName)
372     throws IllegalArgumentException ,
373            RoleNotFoundException {
374
375     if (theRoleName == null) {
376         // Revisit [cebro] Localize message
377 String excMsg = "Invalid parameter.";
378         throw new IllegalArgumentException (excMsg);
379     }
380
381     if (isTraceOn())
382             trace("getRoleCardinality: entering", theRoleName);
383
384     // Try to retrieve the role
385 Role role = null;
386     synchronized(myRoleName2ValueMap) {
387         // No null Role is allowed, so direct use of get()
388 role = (Role )(myRoleName2ValueMap.get(theRoleName));
389     }
390     if (role == null) {
391         int pbType = RoleStatus.NO_ROLE_WITH_NAME;
392         // Will throw a RoleNotFoundException
393 //
394 // Will not throw InvalidRoleValueException, so catch it for the
395 // compiler
396 try {
397         RelationService.throwRoleProblemException(pbType,
398                               theRoleName);
399         } catch (InvalidRoleValueException exc) {
400         // OK : Do not throw InvalidRoleValueException as
401 // a RoleNotFoundException will be thrown.
402 }
403     }
404
405     ArrayList roleValue = (ArrayList )(role.getRoleValue());
406
407     if (isTraceOn())
408             trace("getRoleCardinality: exiting", null);
409     return new Integer (roleValue.size());
410     }
411
412     /**
413      * Sets the given role.
414      * <P>Will check the role according to its corresponding role definition
415      * provided in relation's relation type
416      * <P>Will send a notification (RelationNotification with type
417      * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
418      * relation is a MBean or not).
419      *
420      * @param theRole role to be set (name and new value)
421      *
422      * @exception IllegalArgumentException if null role
423      * @exception RoleNotFoundException if the role is not writable (no
424      * test on the write access mode performed when initialising the role)
425      * @exception InvalidRoleValueException if value provided for
426      * role is not valid, i.e.:
427      * <P>- the number of referenced MBeans in given value is less than
428      * expected minimum degree
429      * <P>- the number of referenced MBeans in provided value exceeds expected
430      * maximum degree
431      * <P>- one referenced MBean in the value is not an Object of the MBean
432      * class expected for that role
433      * <P>- a MBean provided for that role does not exist
434      * @exception RelationServiceNotRegisteredException if the Relation
435      * Service is not registered in the MBean Server
436      * @exception RelationTypeNotFoundException if the relation type has not
437      * been declared in the Relation Service
438      * @exception RelationNotFoundException if the relation has not been
439      * added in the Relation Service.
440      *
441      * @see #getRole
442      */
443     public void setRole(Role theRole)
444     throws IllegalArgumentException ,
445            RoleNotFoundException ,
446            RelationTypeNotFoundException ,
447            InvalidRoleValueException ,
448            RelationServiceNotRegisteredException ,
449                RelationNotFoundException {
450
451     if (theRole == null) {
452         // Revisit [cebro] Localize message
453 String excMsg = "Invalid parameter.";
454         throw new IllegalArgumentException (excMsg);
455     }
456
457     if (isTraceOn())
458             trace("setRole: entering", theRole.toString());
459
460     // Will return null :)
461 Object result = setRoleInt(theRole, false, null, false);
462
463     if (isTraceOn())
464             trace("setRole: exiting", null);
465     return;
466     }
467
468     /**
469      * Sets the given roles.
470      * <P>Will check the role according to its corresponding role definition
471      * provided in relation's relation type
472      * <P>Will send one notification (RelationNotification with type
473      * RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
474      * relation is a MBean or not) per updated role.
475      *
476      * @param theRoleList list of roles to be set
477      *
478      * @return a RoleResult object, including a RoleList (for roles
479      * successfully set) and a RoleUnresolvedList (for roles not
480      * set).
481      *
482      * @exception IllegalArgumentException if null role name
483      * @exception RelationServiceNotRegisteredException if the Relation
484      * Service is not registered in the MBean Server
485      * @exception RelationTypeNotFoundException if the relation type has not
486      * been declared in the Relation Service.
487      * @exception RelationNotFoundException if the relation MBean has not been
488      * added in the Relation Service.
489      *
490      * @see #getRoles
491      */
492     public RoleResult setRoles(RoleList theRoleList)
493     throws IllegalArgumentException ,
494            RelationServiceNotRegisteredException ,
495                RelationTypeNotFoundException ,
496                RelationNotFoundException {
497
498     if (theRoleList == null) {
499         // Revisit [cebro] Localize message
500 String excMsg = "Invalid parameter.";
501         throw new IllegalArgumentException (excMsg);
502     }
503
504     if (isTraceOn())
505             trace("setRoles: entering", theRoleList.toString());
506
507     RoleResult result = setRolesInt(theRoleList, false, null);
508
509     if (isTraceOn())
510             trace("setRoles: exiting", null);
511     return result;
512     }
513
514     /**
515      * Callback used by the Relation Service when a MBean referenced in a role
516      * is unregistered.
517      * <P>The Relation Service will call this method to let the relation
518      * take action to reflect the impact of such unregistration.
519      * <P>BEWARE. the user is not expected to call this method.
520      * <P>Current implementation is to set the role with its current value
521      * (list of ObjectNames of referenced MBeans) without the unregistered
522      * one.
523      *
524      * @param theObjName ObjectName of unregistered MBean
525      * @param theRoleName name of role where the MBean is referenced
526      *
527      * @exception IllegalArgumentException if null parameter
528      * @exception RoleNotFoundException if role does not exist in the
529      * relation or is not writable
530      * @exception InvalidRoleValueException if role value does not conform to
531      * the associated role info (this will never happen when called from the
532      * Relation Service)
533      * @exception RelationServiceNotRegisteredException if the Relation
534      * Service is not registered in the MBean Server
535      * @exception RelationTypeNotFoundException if the relation type has not
536      * been declared in the Relation Service.
537      * @exception RelationNotFoundException if this method is called for a
538      * relation MBean not added in the Relation Service.
539      */
540     public void handleMBeanUnregistration(ObjectName theObjName,
541                       String theRoleName)
542     throws IllegalArgumentException ,
543                RoleNotFoundException ,
544                InvalidRoleValueException ,
545                RelationServiceNotRegisteredException ,
546                RelationTypeNotFoundException ,
547                RelationNotFoundException {
548
549     if (theObjName == null || theRoleName == null) {
550         // Revisit [cebro] Localize message
551 String excMsg = "Invalid parameter.";
552         throw new IllegalArgumentException (excMsg);
553     }
554
555     if (isTraceOn())
556             trace("handleMBeanUnregistration: entering",
557           "theObjName " + theObjName + ", theRoleName " + theRoleName);
558
559     // Can throw RoleNotFoundException, InvalidRoleValueException,
560 // or RelationTypeNotFoundException
561 handleMBeanUnregistrationInt(theObjName,
562                      theRoleName,
563                      false,
564                      null);
565
566     if (isTraceOn())
567             trace("handleMBeanUnregistration: exiting", null);
568     return;
569     }
570
571     /**
572      * Retrieves MBeans referenced in the various roles of the relation.
573      *
574      * @return a HashMap mapping:
575      * <P> ObjectName -> ArrayList of String (role names)
576      */
577     public Map getReferencedMBeans() {
578
579     if (isTraceOn())
580             trace("getReferencedMBeans: entering", null);
581
582     HashMap refMBeanMap = new HashMap ();
583
584     synchronized(myRoleName2ValueMap) {
585
586         for (Iterator roleIter = (myRoleName2ValueMap.values()).iterator();
587          roleIter.hasNext();) {
588
589         Role currRole = (Role )(roleIter.next());
590
591         String currRoleName = currRole.getRoleName();
592         // Retrieves ObjectNames of MBeans referenced in current role
593 ArrayList currRefMBeanList = (ArrayList )
594             (currRole.getRoleValue());
595
596         for (Iterator mbeanIter = currRefMBeanList.iterator();
597              mbeanIter.hasNext();) {
598
599             ObjectName currRoleObjName =
600             (ObjectName )(mbeanIter.next());
601
602             // Sees if current MBean has been already referenced in
603 // roles already seen
604 ArrayList mbeanRoleNameList =
605             (ArrayList )(refMBeanMap.get(currRoleObjName));
606
607             boolean newRefFlg = false;
608             if (mbeanRoleNameList == null) {
609             newRefFlg = true;
610             mbeanRoleNameList = new ArrayList ();
611             }
612             mbeanRoleNameList.add(currRoleName);
613             if (newRefFlg) {
614             refMBeanMap.put(currRoleObjName, mbeanRoleNameList);
615             }
616         }
617         }
618     }
619
620     if (isTraceOn())
621             trace("getReferencedMBeans: exiting", null);
622     return refMBeanMap;
623     }
624
625     /**
626      * Returns name of associated relation type.
627      */
628     public String getRelationTypeName() {
629     return myRelTypeName;
630     }
631
632     /**
633      * Returns ObjectName of the Relation Service handling the relation.
634      *
635      * @return the ObjectName of the Relation Service.
636      */
637     public ObjectName getRelationServiceName() {
638     return myRelServiceName;
639     }
640
641     /**
642      * Returns relation identifier (used to uniquely identify the relation
643      * inside the Relation Service).
644      *
645      * @return the relation id.
646      */
647     public String getRelationId() {
648     return myRelId;
649     }
650
651     //
652 // MBeanRegistration interface
653 //
654
655     // Pre-registration: retrieves the MBean Server (useful to access to the
656 // Relation Service)
657 // This is the way to retrieve the MBean Server when the relation object is
658 // a MBean created by the user outside of the Relation Service.
659 //
660 // No exception thrown.
661 public ObjectName preRegister(MBeanServer server,
662                   ObjectName name)
663     throws Exception {
664
665     myRelServiceMBeanServer = server;
666     return name;
667     }
668
669     // Post-registration: does nothing
670 public void postRegister(Boolean registrationDone) {
671     return;
672     }
673
674     // Pre-unregistration: does nothing
675 public void preDeregister()
676     throws Exception {
677     return;
678     }
679
680     // Post-unregistration: does nothing
681 public void postDeregister() {
682     return;
683     }
684
685     //
686 // Others
687 //
688
689     /**
690      * Returns an internal flag specifying if the object is still handled by
691      * the Relation Service.
692      */
693     public Boolean isInRelationService() {
694     Boolean result = null;
695     synchronized(myInRelServFlg) {
696         result = new Boolean (myInRelServFlg.booleanValue());
697     }
698     return result;
699     }
700
701     public void setRelationServiceManagementFlag(Boolean theFlg)
702     throws IllegalArgumentException {
703
704     if (theFlg == null) {
705         // Revisit [cebro] Localize message
706 String excMsg = "Invalid parameter.";
707         throw new IllegalArgumentException (excMsg);
708     }
709     synchronized(myInRelServFlg) {
710         myInRelServFlg = new Boolean (theFlg.booleanValue());
711     }
712     return;
713     }
714
715     //
716 // Misc
717 //
718
719     // Gets the role with given name
720 // Checks if the role exists and is readable according to the relation
721 // type.
722 //
723 // This method is called in getRole() above.
724 // It is also called in the Relation Service getRole() method.
725 // It is also called in getRolesInt() below (used for getRoles() above
726 // and for Relation Service getRoles() method).
727 //
728 // Depending on parameters reflecting its use (either in the scope of
729 // getting a single role or of getting several roles), will return:
730 // - in case of success:
731 // - for single role retrieval, the ArrayList of ObjectNames being the
732 // role value
733 // - for multi-role retrieval, the Role object itself
734 // - in case of failure (except critical exceptions):
735 // - for single role retrieval, if role does not exist or is not
736 // readable, an RoleNotFoundException exception is raised
737 // - for multi-role retrieval, a RoleUnresolved object
738 //
739 // -param theRoleName name of role to be retrieved
740 // -param theRelServCallFlg true if call from the Relation Service; this
741 // will happen if the current RelationSupport object has been created by
742 // the Relation Service (via createRelation()) method, so direct access is
743 // possible.
744 // -param theRelServ reference to Relation Service object, if object
745 // created by Relation Service.
746 // -param theMultiRoleFlg true if getting the role in the scope of a
747 // multiple retrieval.
748 //
749 // -return:
750 // - for single role retrieval (theMultiRoleFlg false):
751 // - ArrayList of ObjectName objects, value of role with given name, if
752 // the role can be retrieved
753 // - raise a RoleNotFoundException exception else
754 // - for multi-role retrieval (theMultiRoleFlg true):
755 // - the Role object for given role name if role can be retrieved
756 // - a RoleUnresolved object with problem.
757 //
758 // -exception IllegalArgumentException if null parameter
759 // -exception RoleNotFoundException if theMultiRoleFlg is false and:
760 // - there is no role with given name
761 // or
762 // - the role is not readable.
763 // -exception RelationServiceNotRegisteredException if the Relation
764 // Service is not registered in the MBean Server
765 Object getRoleInt(String theRoleName,
766               boolean theRelServCallFlg,
767               RelationService theRelServ,
768               boolean theMultiRoleFlg)
769     throws IllegalArgumentException ,
770            RoleNotFoundException ,
771            RelationServiceNotRegisteredException {
772
773     if (theRoleName == null ||
774         (theRelServCallFlg && theRelServ == null)) {
775         // Revisit [cebro] Localize message
776 String excMsg = "Invalid parameter.";
777         throw new IllegalArgumentException (excMsg);
778     }
779
780     if (isDebugOn()) {
781         String str = "theRoleName " + theRoleName;
782         debug("getRoleInt: entering", str);
783     }
784
785     int pbType = 0;
786
787     Role role = null;
788     synchronized(myRoleName2ValueMap) {
789         // No null Role is allowed, so direct use of get()
790 role = (Role )(myRoleName2ValueMap.get(theRoleName));
791     }
792
793     if (role == null) {
794         pbType = RoleStatus.NO_ROLE_WITH_NAME;
795
796     } else {
797         // Checks if the role is readable
798 Integer status = null;
799
800         if (theRelServCallFlg) {
801
802         // Call from the Relation Service, so direct access to it,
803 // avoiding MBean Server
804 // Shall not throw a RelationTypeNotFoundException
805 try {
806             status = theRelServ.checkRoleReading(theRoleName,
807                              myRelTypeName);
808         } catch (RelationTypeNotFoundException exc) {
809             throw new RuntimeException (exc.getMessage());
810         }
811
812         } else {
813
814         // Call from getRole() method above
815 // So we have a MBean. We must access the Relation Service
816 // via the MBean Server.
817 Object [] params = new Object [2];
818         params[0] = theRoleName;
819         params[1] = myRelTypeName;
820         String [] signature = new String [2];
821         signature[0] = "java.lang.String";
822         signature[1] = "java.lang.String";
823         // Can throw InstanceNotFoundException if the Relation
824 // Service is not registered (to be catched in any case and
825 // transformed into RelationServiceNotRegisteredException).
826 //
827 // Shall not throw a MBeanException, or a ReflectionException
828 // or an InstanceNotFoundException
829 try {
830             status = (Integer )
831             (myRelServiceMBeanServer.invoke(myRelServiceName,
832                             "checkRoleReading",
833                             params,
834                             signature));
835         } catch (MBeanException exc1) {
836             throw new RuntimeException ("incorrect relation type");
837         } catch (ReflectionException exc2) {
838             throw new RuntimeException (exc2.getMessage());
839         } catch (InstanceNotFoundException exc3) {
840             throw new RelationServiceNotRegisteredException (
841                                 exc3.getMessage());
842         }
843         }
844
845         pbType = status.intValue();
846     }
847
848     Object result = null;
849
850     if (pbType == 0) {
851         // Role can be retrieved
852
853         if (!(theMultiRoleFlg)) {
854         // Single role retrieved: returns its value
855 // Note: no need to test if role value (list) not null before
856 // cloning, null value not allowed, empty list if
857 // nothing.