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.
858 result = (ArrayList )
859             (((ArrayList )(role.getRoleValue())).clone());
860
861         } else {
862         // Role retrieved during multi-role retrieval: returns the
863 // role
864 result = (Role )(role.clone());
865         }
866
867     } else {
868         // Role not retrieved
869
870         if (!(theMultiRoleFlg)) {
871         // Problem when retrieving a simple role: either role not
872 // found or not readable, so raises a RoleNotFoundException.
873 try {
874             RelationService.throwRoleProblemException(pbType,
875                                   theRoleName);
876             // To keep compiler happy :)
877 return null;
878         } catch (InvalidRoleValueException exc) {
879             throw new RuntimeException (exc.getMessage());
880         }
881
882         } else {
883         // Problem when retrieving a role in a multi-role retrieval:
884 // returns a RoleUnresolved object
885 result = new RoleUnresolved (theRoleName, null, pbType);
886         }
887     }
888
889     if (isDebugOn())
890         debug("getRoleInt: exiting", null);
891     return result;
892     }
893
894     // Gets the given roles
895 // For each role, verifies if the role exists and is readable according to
896 // the relation type.
897 //
898 // This method is called in getRoles() above and in Relation Service
899 // getRoles() method.
900 //
901 // -param theRoleNameArray array of names of roles to be retrieved
902 // -param theRelServCallFlg true if call from the Relation Service; this
903 // will happen if the current RelationSupport object has been created by
904 // the Relation Service (via createRelation()) method, so direct access is
905 // possible.
906 // -param theRelServ reference to Relation Service object, if object
907 // created by Relation Service.
908 //
909 // -return a RoleResult object
910 //
911 // -exception IllegalArgumentException if null parameter
912 // -exception RelationServiceNotRegisteredException if the Relation
913 // Service is not registered in the MBean Server
914 RoleResult getRolesInt(String [] theRoleNameArray,
915                boolean theRelServCallFlg,
916                RelationService theRelServ)
917     throws IllegalArgumentException ,
918            RelationServiceNotRegisteredException {
919
920     if (theRoleNameArray == null ||
921         (theRelServCallFlg && theRelServ == null)) {
922         // Revisit [cebro] Localize message
923 String excMsg = "Invalid parameter.";
924         throw new IllegalArgumentException (excMsg);
925     }
926
927     if (isDebugOn())
928         debug("getRolesInt: entering", null);
929
930     RoleList roleList = new RoleList ();
931     RoleUnresolvedList roleUnresList = new RoleUnresolvedList ();
932
933     for (int i = 0; i < theRoleNameArray.length; i++) {
934         String currRoleName = theRoleNameArray[i];
935
936         Object currResult = null;
937
938         // Can throw RelationServiceNotRegisteredException
939 //
940 // RoleNotFoundException: not possible but catch it for compiler :)
941 try {
942         currResult = getRoleInt(currRoleName,
943                     theRelServCallFlg,
944                     theRelServ,
945                     true);
946
947         } catch (RoleNotFoundException exc) {
948         return null; // :)
949 }
950
951         if (currResult instanceof Role ) {
952         // Can throw IllegalArgumentException if role is null
953 // (normally should not happen :(
954 try {
955             roleList.add((Role )currResult);
956         } catch (IllegalArgumentException exc) {
957             throw new RuntimeException (exc.getMessage());
958         }
959
960         } else if (currResult instanceof RoleUnresolved ) {
961         // Can throw IllegalArgumentException if role is null
962 // (normally should not happen :(
963 try {
964             roleUnresList.add((RoleUnresolved )currResult);
965         } catch (IllegalArgumentException exc) {
966             throw new RuntimeException (exc.getMessage());
967         }
968         }
969     }
970
971     RoleResult result = new RoleResult (roleList, roleUnresList);
972     if (isDebugOn())
973         debug("getRolesInt: exiting", null);
974     return result;
975     }
976
977     // Returns all roles present in the relation
978 //
979 // -return a RoleResult object, including a RoleList (for roles
980 // successfully retrieved) and a RoleUnresolvedList (for roles not
981 // readable).
982 //
983 // -exception IllegalArgumentException if null parameter
984 // -exception RelationServiceNotRegisteredException if the Relation
985 // Service is not registered in the MBean Server
986 //
987 RoleResult getAllRolesInt(boolean theRelServCallFlg,
988                   RelationService theRelServ)
989     throws IllegalArgumentException ,
990            RelationServiceNotRegisteredException {
991
992     if (theRelServCallFlg && theRelServ == null) {
993         // Revisit [cebro] Localize message
994 String excMsg = "Invalid parameter.";
995         throw new IllegalArgumentException (excMsg);
996     }
997
998     if (isDebugOn())
999         debug("getAllRolesInt: entering", null);
1000
1001    ArrayList roleNameList = null;
1002    synchronized(myRoleName2ValueMap) {
1003        roleNameList =
1004        new ArrayList (myRoleName2ValueMap.keySet());
1005    }
1006    String [] roleNames = new String [roleNameList.size()];
1007    int i = 0;
1008    for (Iterator roleNameIter = roleNameList.iterator();
1009         roleNameIter.hasNext();) {
1010        String currRoleName = (String )(roleNameIter.next());
1011        roleNames[i] = currRoleName;
1012        i++;
1013    }
1014
1015    RoleResult result = getRolesInt(roleNames,
1016                    theRelServCallFlg,
1017                    theRelServ);
1018
1019    if (isDebugOn())
1020        debug("getAllRolesInt: exiting", null);
1021    return result;
1022    }
1023
1024    // Sets the role with given value
1025 //
1026 // This method is called in setRole() above.
1027 // It is also called by the Relation Service setRole() method.
1028 // It is also called in setRolesInt() method below (used in setRoles()
1029 // above and in RelationService setRoles() method).
1030 //
1031 // Will check the role according to its corresponding role definition
1032 // provided in relation's relation type
1033 // Will send a notification (RelationNotification with type
1034 // RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
1035 // relation is a MBean or not) if not initialisation of role.
1036 //
1037 // -param theRole role to be set (name and new value)
1038 // -param theRelServCallFlg true if call from the Relation Service; this
1039 // will happen if the current RelationSupport object has been created by
1040 // the Relation Service (via createRelation()) method, so direct access is
1041 // possible.
1042 // -param theRelServ reference to Relation Service object, if internal
1043 // relation
1044 // -param theMultiRoleFlg true if getting the role in the scope of a
1045 // multiple retrieval.
1046 //
1047 // -return (except other "critical" exceptions):
1048 // - for single role retrieval (theMultiRoleFlg false):
1049 // - null if the role has been set
1050 // - raise an InvalidRoleValueException
1051 // else
1052 // - for multi-role retrieval (theMultiRoleFlg true):
1053 // - the Role object for given role name if role has been set
1054 // - a RoleUnresolved object with problem else.
1055 //
1056 // -exception IllegalArgumentException if null parameter
1057 // -exception RoleNotFoundException if theMultiRoleFlg is false and:
1058 // - internal relation and the role does not exist
1059 // or
1060 // - existing role (i.e. not initialising it) and the role is not
1061 // writable.
1062 // -exception InvalidRoleValueException iftheMultiRoleFlg is false and
1063 // value provided for:
1064 // - the number of referenced MBeans in given value is less than
1065 // expected minimum degree
1066 // or
1067 // - the number of referenced MBeans in provided value exceeds expected
1068 // maximum degree
1069 // or
1070 // - one referenced MBean in the value is not an Object of the MBean
1071 // class expected for that role
1072 // or
1073 // - a MBean provided for that role does not exist
1074 // -exception RelationServiceNotRegisteredException if the Relation
1075 // Service is not registered in the MBean Server
1076 // -exception RelationTypeNotFoundException if relation type unknown
1077 // -exception RelationNotFoundException if a relation MBean has not been
1078 // added in the Relation Service
1079 Object setRoleInt(Role theRole,
1080              boolean theRelServCallFlg,
1081              RelationService theRelServ,
1082              boolean theMultiRoleFlg)
1083    throws IllegalArgumentException ,
1084           RoleNotFoundException ,
1085           InvalidRoleValueException ,
1086           RelationServiceNotRegisteredException ,
1087           RelationTypeNotFoundException ,
1088               RelationNotFoundException {
1089
1090    if (theRole == null ||
1091        (theRelServCallFlg && theRelServ == null)) {
1092        // Revisit [cebro] Localize message
1093 String excMsg = "Invalid parameter.";
1094        throw new IllegalArgumentException (excMsg);
1095    }
1096
1097    if (isDebugOn()) {
1098        String str =
1099        "theRole " + theRole
1100        + ", theRelServCallFlg " + theRelServCallFlg
1101        + ", theMultiRoleFlg " + theMultiRoleFlg;
1102        debug("setRoleInt: entering" , str);
1103    }
1104
1105    String roleName = theRole.getRoleName();
1106    int pbType = 0;
1107
1108    // Checks if role exists in the relation
1109 // No error if the role does not exist in the relation, to be able to
1110 // handle initialisation of role when creating the relation
1111 // (roles provided in the RoleList parameter are directly set but
1112 // roles automatically initialised are set using setRole())
1113 Role role = null;
1114    synchronized(myRoleName2ValueMap) {
1115        role = (Role )(myRoleName2ValueMap.get(roleName));
1116    }
1117
1118    ArrayList oldRoleValue = null;
1119    Boolean initFlg = null;
1120
1121    if (role == null) {
1122        initFlg = new Boolean (true);
1123        oldRoleValue = new ArrayList ();
1124
1125    } else {
1126        initFlg = new Boolean (false);
1127        oldRoleValue = (ArrayList )(role.getRoleValue());
1128    }
1129
1130    // Checks if the role can be set: is writable (except if
1131 // initialisation) and correct value
1132 try {
1133        Integer status = null;
1134
1135        if (theRelServCallFlg) {
1136
1137        // Call from the Relation Service, so direct access to it,
1138 // avoiding MBean Server
1139 //
1140 // Shall not raise a RelationTypeNotFoundException
1141 status = theRelServ.checkRoleWriting(theRole,
1142                             myRelTypeName,
1143                             initFlg);
1144
1145        } else {
1146
1147        // Call from setRole() method above
1148 // So we have a MBean. We must access the Relation Service
1149 // via the MBean Server.
1150 Object [] params = new Object [3];
1151        params[0] = theRole;
1152        params[1] = myRelTypeName;
1153        params[2] = initFlg;
1154        String [] signature = new String [3];
1155        signature[0] = "javax.management.relation.Role";
1156        signature[1] = "java.lang.String";
1157        signature[2] = "java.lang.Boolean";
1158        // Can throw InstanceNotFoundException if the Relation Service
1159 // is not registered (to be transformed into
1160 // RelationServiceNotRegisteredException in any case).
1161 //
1162 // Can throw a MBeanException wrapping a
1163 // RelationTypeNotFoundException:
1164 // throw wrapped exception.
1165 //
1166 // Shall not throw a ReflectionException
1167 status = (Integer )
1168            (myRelServiceMBeanServer.invoke(myRelServiceName,
1169                            "checkRoleWriting",
1170                            params,
1171                            signature));
1172        }
1173
1174        pbType = status.intValue();
1175
1176    } catch (MBeanException exc2) {
1177
1178        // Retrieves underlying exception
1179 Exception wrappedExc = exc2.getTargetException();
1180        if (wrappedExc instanceof RelationTypeNotFoundException ) {
1181        throw ((RelationTypeNotFoundException )wrappedExc);
1182
1183        } else {
1184        throw new RuntimeException (wrappedExc.getMessage());
1185        }
1186
1187    } catch (ReflectionException exc3) {
1188        throw new RuntimeException (exc3.getMessage());
1189
1190    } catch (RelationTypeNotFoundException exc4) {
1191        throw new RuntimeException (exc4.getMessage());
1192
1193    } catch (InstanceNotFoundException exc5) {
1194        throw new RelationServiceNotRegisteredException (exc5.getMessage());
1195    }
1196
1197    Object result = null;
1198
1199    if (pbType == 0) {
1200        // Role can be set
1201 if (!(initFlg.booleanValue())) {
1202
1203        // Not initialising the role
1204 // If role being initialised:
1205 // - do not send an update notification
1206 // - do not try to update internal map of Relation Service
1207 // listing referenced MBeans, as role is initialised to an
1208 // empty list
1209
1210        // Sends a notification (RelationNotification)
1211 // Can throw a RelationNotFoundException
1212 sendRoleUpdateNotification(theRole,
1213                       oldRoleValue,
1214                       theRelServCallFlg,
1215                       theRelServ);
1216
1217        // Updates the role map of the Relation Service
1218 // Can throw RelationNotFoundException
1219 updateRelationServiceMap(theRole,
1220                     oldRoleValue,
1221                     theRelServCallFlg,
1222                     theRelServ);
1223
1224        }
1225
1226        // Sets the role
1227 synchronized(myRoleName2ValueMap) {
1228        myRoleName2ValueMap.put(roleName,
1229                    (Role )(theRole.clone()));
1230        }
1231
1232        // Single role set: returns null: nothing to set in result
1233
1234        if (theMultiRoleFlg) {
1235        // Multi-roles retrieval: returns the role
1236 result = theRole;
1237        }
1238
1239    } else {
1240
1241        // Role not set
1242
1243        if (!(theMultiRoleFlg)) {
1244        // Problem when setting a simple role: either role not
1245 // found, not writable, or incorrect value:
1246 // raises appropriate exception, RoleNotFoundException or
1247 // InvalidRoleValueException
1248 RelationService.throwRoleProblemException(pbType,
1249                              roleName);
1250        // To keep compiler happy :)
1251 return null;
1252
1253        } else {
1254        // Problem when retrieving a role in a multi-role retrieval:
1255 // returns a RoleUnresolved object
1256 result = new RoleUnresolved (roleName,
1257                        theRole.getRoleValue(),
1258                        pbType);
1259        }
1260    }
1261
1262    if (isDebugOn())
1263        debug("setRoleInt: exiting", null);
1264    return result;
1265    }
1266
1267    // Requires the Relation Service to send a notification
1268 // RelationNotification, with type being either:
1269 // - RelationNotification.RELATION_BASIC_UPDATE if the updated relation is
1270 // a relation internal to the Relation Service
1271 // - RelationNotification.RELATION_MBEAN_UPDATE if the updated relation is
1272 // a relation MBean.
1273 //
1274 // -param theNewRole new role
1275 // -param theOldRoleValue old role value (ArrayList of ObjectNames)
1276 // -param theRelServCallFlg true if call from the Relation Service; this
1277 // will happen if the current RelationSupport object has been created by
1278 // the Relation Service (via createRelation()) method, so direct access is
1279 // possible.
1280 // -param theRelServ reference to Relation Service object, if object
1281 // created by Relation Service.
1282 //
1283 // -exception IllegalArgumentException if null parameter provided
1284 // -exception RelationServiceNotRegisteredException if the Relation
1285 // Service is not registered in the MBean Server
1286 // -exception RelationNotFoundException if:
1287 // - relation MBean
1288 // and
1289 // - it has not been added into the Relation Service
1290 private void sendRoleUpdateNotification(Role theNewRole,
1291                        List theOldRoleValue,
1292                        boolean theRelServCallFlg,
1293                        RelationService theRelServ)
1294    throws IllegalArgumentException ,
1295           RelationServiceNotRegisteredException ,
1296           RelationNotFoundException {
1297
1298    if (theNewRole == null ||
1299        theOldRoleValue == null ||
1300        (theRelServCallFlg && theRelServ == null)) {
1301        // Revisit [cebro] Localize message
1302 String excMsg = "Invalid parameter.";
1303        throw new IllegalArgumentException (excMsg);
1304    }
1305
1306    if (isDebugOn()) {
1307        String str =
1308        "theNewRole " + theNewRole
1309        + ", theOldRoleValue " + theOldRoleValue
1310        + ", theRelServCallFlg " + theRelServCallFlg;
1311        debug("sendRoleUpdateNotification: entering", str);
1312    }
1313
1314    if (theRelServCallFlg) {
1315        // Direct call to the Relation Service
1316 // Shall not throw a RelationNotFoundException for an internal
1317 // relation
1318 try {
1319        theRelServ.sendRoleUpdateNotification(myRelId,
1320                              theNewRole,
1321                              theOldRoleValue);
1322        } catch (RelationNotFoundException exc) {
1323        throw new RuntimeException (exc.getMessage());
1324        }
1325
1326    } else {
1327
1328        Object [] params = new Object [3];
1329        params[0] = myRelId;
1330        params[1] = theNewRole;
1331        params[2] = ((ArrayList )theOldRoleValue);
1332        String [] signature = new String [3];
1333        signature[0] = "java.lang.String";
1334        signature[1] = "javax.management.relation.Role";
1335        signature[2] = "java.util.List";
1336
1337        // Can throw InstanceNotFoundException if the Relation Service
1338 // is not registered (to be transformed).
1339 //
1340 // Can throw a MBeanException wrapping a
1341 // RelationNotFoundException (to be raised in any case): wrapped
1342 // exception to be thrown
1343 //
1344 // Shall not throw a ReflectionException
1345 try {
1346        myRelServiceMBeanServer.invoke(myRelServiceName,
1347                           "sendRoleUpdateNotification",
1348                           params,
1349                           signature);
1350        } catch (ReflectionException exc1) {
1351        throw new RuntimeException (exc1.getMessage());
1352        } catch (InstanceNotFoundException exc2) {
1353        throw new RelationServiceNotRegisteredException (
1354                                exc2.getMessage());
1355        } catch (MBeanException exc3) {
1356        Exception wrappedExc = exc3.getTargetException();
1357        if (wrappedExc instanceof RelationNotFoundException ) {
1358            throw ((RelationNotFoundException )wrappedExc);
1359        } else {
1360            throw new RuntimeException (wrappedExc.getMessage());
1361        }
1362        }
1363    }
1364
1365    if (isDebugOn())
1366        debug("sendRoleUpdateNotification: exiting", null);
1367    return;
1368    }
1369
1370    // Requires the Relation Service to update its internal map handling
1371 // MBeans referenced in relations.
1372 // The Relation Service will also update its recording as a listener to
1373 // be informed about unregistration of new referenced MBeans, and no longer
1374 // informed of MBeans no longer referenced.
1375 //
1376 // -param theNewRole new role
1377 // -param theOldRoleValue old role value (ArrayList of ObjectNames)
1378 // -param theRelServCallFlg true if call from the Relation Service; this
1379 // will happen if the current RelationSupport object has been created by
1380 // the Relation Service (via createRelation()) method, so direct access is
1381 // possible.
1382 // -param theRelServ reference to Relation Service object, if object
1383 // created by Relation Service.
1384 //
1385 // -exception IllegalArgumentException if null parameter
1386 // -exception RelationServiceNotRegisteredException if the Relation
1387 // Service is not registered in the MBean Server
1388 // -exception RelationNotFoundException if:
1389 // - relation MBean
1390 // and
1391 // - the relation is not added in the Relation Service
1392 private void updateRelationServiceMap(Role theNewRole,
1393                      List theOldRoleValue,
1394                      boolean theRelServCallFlg,
1395                      RelationService theRelServ)
1396    throws IllegalArgumentException ,
1397           RelationServiceNotRegisteredException ,
1398           RelationNotFoundException {
1399
1400    if (theNewRole == null ||
1401        theOldRoleValue == null ||
1402        (theRelServCallFlg && theRelServ == null)) {
1403        // Revisit [cebro] Localize message
1404 String excMsg = "Invalid parameter.";
1405        throw new IllegalArgumentException (excMsg);
1406    }
1407
1408    if (isDebugOn()) {
1409        String str =
1410        "theNewRole " + theNewRole
1411        + ", theOldRoleValue " + theOldRoleValue
1412        + ", theRelServCallFlg " + theRelServCallFlg;
1413        debug("updateRelationServiceMap: entering", str);
1414    }
1415
1416    if (theRelServCallFlg) {
1417        // Direct call to the Relation Service
1418 // Shall not throw a RelationNotFoundException
1419 try {
1420        theRelServ.updateRoleMap(myRelId,
1421                     theNewRole,
1422                     theOldRoleValue);
1423        } catch (RelationNotFoundException exc) {
1424        throw new RuntimeException (exc.getMessage());
1425        }
1426
1427    } else {
1428        Object [] params = new Object [3];
1429        params[0] = myRelId;
1430        params[1] = theNewRole;
1431        params[2] = theOldRoleValue;
1432        String [] signature = new String [3];
1433        signature[0] = "java.lang.String";
1434        signature[1] = "javax.management.relation.Role";
1435        signature[2] = "java.util.List";
1436        // Can throw InstanceNotFoundException if the Relation Service
1437 // is not registered (to be transformed).
1438 // Can throw a MBeanException wrapping a RelationNotFoundException:
1439 // wrapped exception to be thrown
1440 //
1441 // Shall not throw a ReflectionException
1442 try {
1443        myRelServiceMBeanServer.invoke(myRelServiceName,
1444                           "updateRoleMap",
1445                           params,
1446                           signature);
1447        } catch (ReflectionException exc1) {
1448        throw new RuntimeException (exc1.getMessage());
1449        } catch (InstanceNotFoundException exc2) {
1450        throw new
1451             RelationServiceNotRegisteredException (exc2.getMessage());
1452        } catch (MBeanException exc3) {
1453        Exception wrappedExc = exc3.getTargetException();
1454        if (wrappedExc instanceof RelationNotFoundException ) {
1455            throw ((RelationNotFoundException )wrappedExc);
1456        } else {
1457            throw new RuntimeException (wrappedExc.getMessage());
1458        }
1459        }
1460    }
1461
1462    if (isDebugOn())
1463        debug("updateRelationServiceMap: exiting", null);
1464    return;
1465    }
1466
1467    // Sets the given roles
1468 // For each role:
1469 // - will check the role according to its corresponding role definition
1470 // provided in relation's relation type
1471 // - will send a notification (RelationNotification with type
1472 // RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the
1473 // relation is a MBean or not) for each updated role.
1474 //
1475 // This method is called in setRoles() above and in Relation Service
1476 // setRoles() method.
1477 //
1478 // -param theRoleList list of roles to be set
1479 // -param theRelServCallFlg true if call from the Relation Service; this
1480 // will happen if the current RelationSupport object has been created by
1481 // the Relation Service (via createRelation()) method, so direct access is
1482 // possible.
1483 // -param theRelServ reference to Relation Service object, if object
1484 // created by Relation Service.
1485 //
1486 // -return a RoleResult object
1487 //
1488 // -exception IllegalArgumentException if null parameter
1489 // -exception RelationServiceNotRegisteredException if the Relation
1490 // Service is not registered in the MBean Server
1491 // -exception RelationTypeNotFoundException if:
1492 // - relation MBean
1493 // and
1494 // - unknown relation type
1495 // -exception RelationNotFoundException if:
1496 // - relation MBean
1497 // and
1498 // - not added in the RS
1499 RoleResult setRolesInt(RoleList theRoleList,
1500               boolean theRelServCallFlg,
1501               RelationService theRelServ)
1502    throws IllegalArgumentException ,
1503           RelationServiceNotRegisteredException ,
1504           RelationTypeNotFoundException ,
1505               RelationNotFoundException {
1506
1507    if (theRoleList == null ||
1508        (theRelServCallFlg && theRelServ == null)) {
1509        // Revisit [cebro] Localize message
1510 String excMsg = "Invalid parameter.";
1511        throw new IllegalArgumentException (excMsg);
1512    }
1513
1514    if (isDebugOn()) {
1515        String str =
1516        "theRoleList " + theRoleList
1517        + ", theRelServCallFlg " + theRelServCallFlg;
1518        debug("setRolesInt: entering", str);
1519    }
1520
1521    RoleList roleList = new RoleList ();
1522    RoleUnresolvedList roleUnresList = new RoleUnresolvedList ();
1523
1524    for (Iterator roleIter = theRoleList.iterator();
1525         roleIter.hasNext();) {
1526
1527        Role currRole = (Role )(roleIter.next());
1528
1529        Object currResult = null;
1530        // Can throw:
1531 // RelationServiceNotRegisteredException,
1532 // RelationTypeNotFoundException
1533 //
1534 // Will not throw, due to parameters, RoleNotFoundException or
1535 // InvalidRoleValueException, but catch them to keep compiler
1536 // happy
1537 try {
1538        currResult = setRoleInt(currRole,
1539                    theRelServCallFlg,
1540                    theRelServ,
1541                    true);
1542        } catch (RoleNotFoundException exc1) {
1543        // OK : Do not throw a RoleNotFoundException.
1544 } catch (InvalidRoleValueException exc2) {
1545        // OK : Do not throw an InvalidRoleValueException.
1546 }
1547
1548        if (currResult instanceof Role ) {
1549        // Can throw IllegalArgumentException if role is null
1550 // (normally should not happen :(
1551 try {
1552            roleList.add((Role )currResult);
1553        } catch (IllegalArgumentException exc) {
1554            throw new RuntimeException (exc.getMessage());
1555        }
1556
1557        } else if (currResult instanceof RoleUnresolved ) {
1558        // Can throw IllegalArgumentException if role is null
1559 // (normally should not happen :(
1560 try {
1561            roleUnresList.add((RoleUnresolved )currResult);
1562        } catch (IllegalArgumentException exc) {
1563            throw new RuntimeException (exc.getMessage());
1564        }
1565        }
1566    }
1567
1568    RoleResult result = new RoleResult (roleList, roleUnresList);
1569
1570    if (isDebugOn())
1571        debug("setRolesInt: exiting", null);
1572    return result;
1573    }
1574
1575    // Initialises all members
1576 //
1577 // -param theRelId relation identifier, to identify the relation in the
1578 // Relation Service.
1579 // Expected to be unique in the given Relation Service.
1580 // -param theRelServiceName ObjectName of the Relation Service where
1581 // the relation will be registered.
1582 // It is required as this is the Relation Service that is aware of the
1583 // definition of the relation type of given relation, so that will be able
1584 // to check update operations (set). Direct access via the Relation
1585 // Service (RelationService.setRole()) do not need this information but
1586 // as any user relation is a MBean, setRole() is part of its management
1587 // interface and can be called directly on the user relation MBean. So the
1588 // user relation MBean must be aware of the Relation Service where it will
1589 // be added.
1590 // -param theRelTypeName Name of relation type.
1591 // Expected to have been created in given Relation Service.
1592 // -param theRoleList list of roles (Role objects) to initialised the
1593 // relation. Can be null.
1594 // Expected to conform to relation info in associated relation type.
1595 //
1596 // -exception InvalidRoleValueException if the same name is used for two
1597 // roles.
1598 // -exception IllegalArgumentException if a required value (Relation
1599 // Service Object Name, etc.) is not provided as parameter.
1600 private void initMembers(String theRelId,
1601                 ObjectName theRelServiceName,
1602                 MBeanServer theRelServiceMBeanServer,
1603                 String theRelTypeName,
1604                 RoleList theRoleList)
1605    throws InvalidRoleValueException ,
1606               IllegalArgumentException {
1607
1608    if (theRelId == null ||
1609        theRelServiceName == null ||
1610        theRelTypeName == null) {
1611        // Revisit [cebro] Localize message
1612 String excMsg = "Invalid parameter.";
1613        throw new IllegalArgumentException (excMsg);
1614    }
1615
1616    if (isDebugOn()) {
1617        StringBuffer strB =
1618        new StringBuffer ("theRelId " + theRelId
1619                 + ", theRelServiceName "
1620                 + theRelServiceName.toString()
1621                 + ", theRelTypeName " + theRelTypeName);
1622        if (theRoleList != null) {
1623        strB.append(", theRoleList " + theRoleList.toString());
1624        }
1625        debug("initMembers: entering", strB.toString());
1626    }
1627
1628    myRelId = theRelId;
1629    myRelServiceName = theRelServiceName;
1630    myRelServiceMBeanServer = theRelServiceMBeanServer;
1631    myRelTypeName = theRelTypeName;
1632    // Can throw InvalidRoleValueException
1633 initRoleMap(theRoleList);
1634    myInRelServFlg = new Boolean (false);
1635
1636    if (isDebugOn())
1637        debug("initMembers: exiting", null);
1638    return;
1639    }
1640
1641    // Initialise the internal role map from given RoleList parameter
1642 //
1643 // -param theRoleList role list. Can be null.
1644 // As it is a RoleList object, it cannot include null (rejected).
1645 //
1646 // -exception InvalidRoleValueException if the same role name is used for
1647 // several roles.
1648 //
1649 private void initRoleMap(RoleList theRoleList)
1650    throws InvalidRoleValueException {
1651
1652    if (theRoleList == null) {
1653        return;
1654    }
1655
1656    if (isDebugOn())
1657        debug("initRoleMap: entering", theRoleList.toString());
1658
1659    synchronized(myRoleName2ValueMap) {
1660
1661        for (Iterator roleIter = theRoleList.iterator();
1662         roleIter.hasNext();) {
1663
1664        // No need to check if role is null, it is not allowed to store
1665 // a null role in a RoleList :)
1666 Role currRole = (Role )(roleIter.next());
1667        String currRoleName = currRole.getRoleName();
1668
1669        if (myRoleName2ValueMap.containsKey(currRoleName)) {
1670            // Role already provided in current list
1671 // Revisit [cebro] Localize message
1672 StringBuffer excMsgStrB = new StringBuffer ("Role name ");
1673            excMsgStrB.append(currRoleName);
1674            excMsgStrB.append(" used for two roles.");
1675            throw new InvalidRoleValueException (excMsgStrB.toString());
1676        }
1677
1678        myRoleName2ValueMap.put(currRoleName,
1679                    (Role )(currRole.clone()));
1680        }
1681    }
1682
1683    if (isDebugOn())
1684        debug("initRoleMap: exiting", null);
1685    return;
1686    }
1687
1688    // Callback used by the Relation Service when a MBean referenced in a role
1689 // is unregistered.
1690 // The Relation Service will call this method to let the relation
1691 // take action to reflect the impact of such unregistration.
1692 // Current implementation is to set the role with its current value
1693 // (list of ObjectNames of referenced MBeans) without the unregistered
1694 // one.
1695 //
1696 // -param theObjName ObjectName of unregistered MBean
1697 // -param theRoleName name of role where the MBean is referenced
1698 // -param theRelServCallFlg true if call from the Relation Service; this
1699 // will happen if the current RelationSupport object has been created by
1700 // the Relation Service (via createRelation()) method, so direct access is
1701 // possible.
1702 // -param theRelServ reference to Relation Service object, if internal
1703 // relation
1704 //
1705 // -exception IllegalArgumentException if null parameter
1706 // -exception RoleNotFoundException if:
1707 // - the role does not exist
1708 // or
1709 // - role not writable.
1710 // -exception InvalidRoleValueException if value provided for:
1711 // - the number of referenced MBeans in given value is less than
1712 // expected minimum degree
1713 // or
1714 // - the number of referenced MBeans in provided value exceeds expected
1715 // maximum degree
1716 // or
1717 // - one referenced MBean in the value is not an Object of the MBean
1718 // class expected for that role
1719 // or
1720 // - a MBean provided for that role does not exist
1721 // -exception RelationServiceNotRegisteredException if the Relation
1722 // Service is not registered in the MBean Server
1723 // -exception RelationTypeNotFoundException if unknown relation type
1724 // -exception RelationNotFoundException if current relation has not been
1725 // added in the RS
1726 void handleMBeanUnregistrationInt(ObjectName theObjName,
1727                      String theRoleName,
1728                      boolean theRelServCallFlg,
1729                      RelationService theRelServ)
1730    throws IllegalArgumentException ,
1731               RoleNotFoundException ,
1732               InvalidRoleValueException ,
1733           RelationServiceNotRegisteredException ,
1734           RelationTypeNotFoundException ,
1735               RelationNotFoundException {
1736
1737    if (theObjName == null ||
1738        theRoleName == null ||
1739        (theRelServCallFlg && theRelServ == null)) {
1740        // Revisit [cebro] Localize message
1741 String excMsg = "Invalid parameter.";
1742        throw new IllegalArgumentException (excMsg);
1743    }
1744
1745    if (isDebugOn()) {
1746        String str =
1747        "theObjName " + theObjName
1748        + ", theRoleName " + theRoleName
1749        + ", theRelServCallFlg " + theRelServCallFlg;
1750        debug("handleMBeanUnregistrationInt: entering", str);
1751    }
1752
1753    // Retrieves current role value
1754 Role role = null;
1755    synchronized(myRoleName2ValueMap) {
1756        role = (Role )(myRoleName2ValueMap.get(theRoleName));
1757    }
1758
1759    if (role == null) {
1760        StringBuffer excMsgStrB = new StringBuffer ();
1761        // Revisit [cebro] Localize message
1762 String excMsg = "No role with name ";
1763        excMsgStrB.append(excMsg);
1764        excMsgStrB.append(theRoleName);
1765        throw new RoleNotFoundException (excMsgStrB.toString());
1766    }
1767    ArrayList currRoleValue = (ArrayList )(role.getRoleValue());
1768
1769    // Note: no need to test if list not null before cloning, null value
1770 // not allowed for role value.
1771 ArrayList newRoleValue = (ArrayList )(currRoleValue.clone());
1772    newRoleValue.remove(theObjName);
1773    Role newRole = new Role (theRoleName, newRoleValue);
1774
1775    // Can throw InvalidRoleValueException,
1776 // RelationTypeNotFoundException
1777 // (RoleNotFoundException already detected)
1778 Object result =
1779        setRoleInt(newRole, theRelServCallFlg, theRelServ, false);
1780
1781    if (isDebugOn())
1782        debug("handleMBeanUnregistrationInt: exiting", null);
1783    return;
1784    }
1785
1786    // stuff for Tracing
1787
1788    private static String localClassName = "RelationSupport";
1789
1790    // trace level
1791 private boolean isTraceOn() {
1792        return Trace.isSelected(Trace.LEVEL_TRACE, Trace.INFO_RELATION);
1793    }
1794
1795// private void trace(String className, String methodName, String info) {
1796// Trace.send(Trace.LEVEL_TRACE, Trace.INFO_RELATION, className, methodName, info);
1797// }
1798
1799    private void trace(String methodName, String info) {
1800        Trace.send(Trace.LEVEL_TRACE, Trace.INFO_RELATION, localClassName, methodName, info);
1801    Trace.send(Trace.LEVEL_TRACE, Trace.INFO_RELATION, "", "", "\n");
1802    }
1803
1804// private void trace(String className, String methodName, Exception e) {
1805// Trace.send(Trace.LEVEL_TRACE, Trace.INFO_RELATION, className, methodName, e);
1806// }
1807
1808// private void trace(String methodName, Exception e) {
1809// Trace.send(Trace.LEVEL_TRACE, Trace.INFO_RELATION, localClassName, methodName, e);
1810// }
1811
1812    // debug level
1813 private boolean isDebugOn() {
1814        return Trace.isSelected(Trace.LEVEL_DEBUG, Trace.INFO_RELATION);
1815    }
1816
1817// private void debug(String className, String methodName, String info) {
1818// Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_RELATION, className, methodName, info);
1819// }
1820
1821    private void debug(String methodName, String info) {
1822        Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_RELATION, localClassName, methodName, info);
1823    Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_RELATION, "", "", "\n");
1824    }
1825
1826// private void debug(String className, String methodName, Exception e) {
1827// Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_RELATION, className, methodName, e);
1828// }
1829
1830// private void debug(String methodName, Exception e) {
1831// Trace.send(Trace.LEVEL_DEBUG, Trace.INFO_RELATION, localClassName, methodName, e);
1832// }
1833}
1834

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags