TAO/tao/IORManipulation/IOR.pidl

   1 /**
   2  * @file IOR.pidl
   3  *
   4  * @brief Pre-compiled IDL source for the TAO_IOP namespace.
   5  */
   6
   7 #ifndef TAO_IOR_PIDL
   8 #define TAO_IOR_PIDL
   9
  10 module TAO_IOP
  11 {
  12   /**
  13    * @exception EmptyProfileList
  14    *
  15    * @brief @@ Bala, please describe this exception
  16    */
  17   exception EmptyProfileList {};
  18
  19   /**
  20    * @exception NotFound
  21    *
  22    * @brief @@ Bala, please describe this exception
  23    */
  24   exception NotFound {};
  25
  26   /**
  27    * @exception Duplicate
  28    *
  29    * @brief @@ Bala, please describe this exception
  30    */
  31   exception Duplicate {};
  32
  33   /**
  34    * @exception Invalid_IOR
  35    *
  36    * @brief @@ Bala, please describe this exception
  37    */
  38   exception Invalid_IOR {};
  39
  40   /**
  41    * @exception MultiProfileList
  42    *
  43    * @brief @@ Bala, please describe this exception
  44    */
  45   exception MultiProfileList {};
  46
  47   /**
  48    * @interface TAO_IOR_Property
  49    *
  50    * Allows setting properties  by the different services in the
  51    * IOR. The implementations of this interface would reside in the
  52    * services. This interface essentially performs a role of a
  53    * callback object.
  54    *
  55    * @todo This interface seems redundant in the face of the
  56    * PortableInterceptor::IORInterceptor and the
  57    * ObjectReferenceTemplate.  If that is the case we should deprecate
  58    * it and remove it.
  59    */
  60   local interface TAO_IOR_Property
  61   {
  62     /// Operation that would set the required properties in the @a ior
  63     /// as needed by the service.
  64     boolean set_property (inout Object ior)
  65       raises (Invalid_IOR);
  66
  67     /// Sets the profile ior1, in the profile ior2 to be a
  68     /// primary.
  69     boolean set_primary (inout Object ior1,
  70                          in Object ior2)
  71       raises (Duplicate, NotFound);
  72
  73     /// Returns the ior of the primary from @a ior if it has been
  74     /// set. Else returns a NotFound exception
  75     Object get_primary (in Object ior)
  76       raises (NotFound);
  77
  78     /// Returns a true or false depending on whether a primary member
  79     /// has been set in @a ior
  80     boolean is_primary_set (in Object ior);
  81
  82     /// If any of the IOR's within the IOGR has a primary tag, just
  83     /// remove it. Returns zero if no primary was found.
  84     boolean remove_primary_tag (inout Object iogr)
  85       raises (NotFound);
  86   };
  87
  88   /**
  89    * @interface TAO_IOR_Manipulation
  90    *
  91    * @brief Allows applications to manipulate object references.
  92    *
  93    * Manipulating Object References.  While this interface does not
  94    * assume the use of CORBA complaint IOPs, the IOP terminology is
  95    * used throughout.
  96    * Object references (Object) are used since they encapsulate the
  97    * notion of object references and IORs.
  98    * Note, an IOR contains one or more profiles and a profile can be
  99    * considered to represent the location or route to a specific instance
 100    * of an object.
 101    * A profile may also contain supplementary information useful for
 102    * different services such as security.
 103    * All Object references may have multiple profiles
 104    */
 105   local interface TAO_IOR_Manipulation
 106   {
 107       typedef sequence <Object> IORList;
 108
 109       /// Create a new object reference by merging the profiles lists in the
 110       /// supplied list of one or more object references.
 111       Object merge_iors (in IORList iors)
 112         raises (EmptyProfileList,Duplicate,Invalid_IOR);
 113
 114       /// copy the profile list from "ior2" to "ior1".
 115       /// Note on ordering, while the current implementation will place
 116       /// the profiles from ior2 (which are not already in ior1) on the
 117       /// end of the profile list in ior1, there is no guarantee this ordering
 118       /// will be maintained.  For example, string_to_object or object_to_string
 119       /// may reorder the profile lists.  So, if it is important to use one
 120       /// profile before another then policies should be used along with tagged
 121       /// components/tagged profiles.
 122       Object add_profiles (in Object ior1,
 123                            in Object ior2)
 124         raises (EmptyProfileList, Duplicate, Invalid_IOR);
 125
 126       // Any profile in @a ior1 which matches at least one profile in @a ior2
 127       // will be removed.  Returns a new object reference
 128       Object remove_profiles (in Object ior1,
 129                               in Object ior2)
 130         raises (Invalid_IOR, EmptyProfileList, NotFound);
 131
 132       /// Allows setting of properties as defined by the @a prop object
 133       /// in the @a ior list
 134       boolean set_property (in TAO_IOR_Property prop,
 135                             in Object ior)
 136         raises (Invalid_IOR, Duplicate);
 137
 138       // @@ Primary is specific to FT.. But let us have these
 139       // @@ operations around. Further, as we pass the property object
 140       // @@ around the implementation will not be tied with the FT
 141       // @@ service. Any service can use their own ways of defining a
 142       // @@ primary. For example FT service uses IOP::TAG_FT_PRIMARY
 143       // @@ to identify a primary and some other service could use
 144       // @@ something else. But the actual implementation of the
 145       // @@ property object would take care of that.
 146       // Sets the profile ior1, in the profile ior2 to be a
 147       // primary. If ior1 is a multi-profile IOR then the operation
 148       // raises the MultiProfileList exception. If ior1 is not found
 149       // in ior2, it raises an Invalid_IOR exception. If ior2 has a
 150       // primary already defined then it raises a Duplicate
 151       // exception.
 152       boolean set_primary (in TAO_IOR_Property prop,
 153                            in Object ior1,
 154                            in Object ior2)
 155         raises (Invalid_IOR, Duplicate, MultiProfileList, NotFound);
 156
 157       /// If any of the IOR's within the IOGR has a primary tag, just remove
 158       /// it. Return zero if no primary found.
 159       boolean remove_primary_tag (in TAO_IOR_Property prop,
 160                                   in Object ior);
 161
 162
 163       /// Returns the ior of the primary from @a ior if it has been
 164       /// set. Else returns a NotFound exception
 165       Object get_primary (in TAO_IOR_Property prop,
 166                           in Object ior)
 167         raises (NotFound);
 168
 169       /// Returns a true or false depending on whether a primary member
 170       /// has been set in @a ior
 171       boolean is_primary_set (in TAO_IOR_Property prop,
 172                               in Object ior);
 173
 174       /// Returns number of profiles which are in both @a ior1 and @a ior2.
 175       unsigned long is_in_ior(in Object ior1, in Object ior2)
 176         raises (NotFound);
 177
 178       /// This will return the number of profiles contained in the
 179       /// corresponding object reference for this object.
 180       unsigned long get_profile_count (in Object ior)
 181         raises (EmptyProfileList);
 182   };
 183 };
 184
 185 #endif /* TAO_IOR_PIDL */