00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Naming_Context_Interface.h 00006 * 00007 * Naming_Context_Interface.h,v 1.19 2006/03/14 06:14:33 jtc Exp 00008 * 00009 * @author Marina Spivak <marina@cs.wustl.edu> 00010 */ 00011 //============================================================================= 00012 00013 #ifndef TAO_NAMING_CONTEXT_INTERFACE_H 00014 #define TAO_NAMING_CONTEXT_INTERFACE_H 00015 00016 #include /**/ "ace/pre.h" 00017 00018 #include "orbsvcs/CosNamingS.h" 00019 00020 #include "orbsvcs/Naming/naming_serv_export.h" 00021 #include "ace/Null_Mutex.h" 00022 00023 TAO_BEGIN_VERSIONED_NAMESPACE_DECL 00024 00025 class TAO_Naming_Context_Impl; 00026 00027 // This is to remove "inherits via dominance" warnings from MSVC. 00028 #if defined (_MSC_VER) 00029 # pragma warning (disable : 4250) 00030 #endif /* _MSC_VER */ 00031 00032 /** 00033 * @class TAO_Naming_Context 00034 * 00035 * @brief This class plays a role of the 'Abstraction' (aka 'Interface') 00036 * in the Bridge pattern architecture of the CosNaming::NamingContext 00037 * implementation. 00038 * 00039 * This class simply forwards all client requests to a concrete 00040 * NamingContext implementation through its <impl_> pointer. See 00041 * README file for more info. Comments for the idl methods 00042 * describe methods semantics - actual actions are carried out by 00043 * concrete implementors. 00044 */ 00045 00046 class TAO_Naming_Serv_Export TAO_Naming_Context : 00047 public virtual POA_CosNaming::NamingContextExt 00048 { 00049 public: 00050 00051 // = Initialization and termination methods. 00052 /// Constructor. Initializes <impl_> with a concrete implementation. 00053 TAO_Naming_Context (TAO_Naming_Context_Impl *impl); 00054 00055 /// Destructor. 00056 ~TAO_Naming_Context (void); 00057 00058 // = CosNaming::NamingContext idl interface methods. 00059 00060 /** 00061 * Create a binding for name <n> and object <obj> in the naming 00062 * context. Compound names are treated as follows: ctx->bind (<c1; 00063 * c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, 00064 * obj) if the there already exists a binding for the specified 00065 * name, <AlreadyBound> exception is thrown. Naming contexts should 00066 * be bound using <bind_context> and <rebind_context> in order to 00067 * participate in name resolution later. 00068 */ 00069 virtual void bind (const CosNaming::Name &n, 00070 CORBA::Object_ptr obj 00071 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00072 ACE_THROW_SPEC ((CORBA::SystemException, 00073 CosNaming::NamingContext::NotFound, 00074 CosNaming::NamingContext::CannotProceed, 00075 CosNaming::NamingContext::InvalidName, 00076 CosNaming::NamingContext::AlreadyBound)); 00077 00078 /** 00079 * This is similar to <bind> operation above, except for when the 00080 * binding for the specified name already exists in the specified 00081 * context. In that case, the existing binding is replaced with the 00082 * new one. 00083 */ 00084 virtual void rebind (const CosNaming::Name &n, 00085 CORBA::Object_ptr obj 00086 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00087 ACE_THROW_SPEC ((CORBA::SystemException, 00088 CosNaming::NamingContext::NotFound, 00089 CosNaming::NamingContext::CannotProceed, 00090 CosNaming::NamingContext::InvalidName)); 00091 00092 /** 00093 * This is the version of <bind> specifically for binding naming 00094 * contexts, so that they will participate in name resolution when 00095 * compound names are passed to be resolved. 00096 */ 00097 virtual void bind_context (const CosNaming::Name &n, 00098 CosNaming::NamingContext_ptr nc 00099 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00100 ACE_THROW_SPEC ((CORBA::SystemException, 00101 CosNaming::NamingContext::NotFound, 00102 CosNaming::NamingContext::CannotProceed, 00103 CosNaming::NamingContext::InvalidName, 00104 CosNaming::NamingContext::AlreadyBound)); 00105 00106 /** 00107 * This is a version of <rebind> specifically for naming contexts, 00108 * so that they can participate in name resolution when compound 00109 * names are passed. 00110 */ 00111 virtual void rebind_context (const CosNaming::Name &n, 00112 CosNaming::NamingContext_ptr nc 00113 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00114 ACE_THROW_SPEC ((CORBA::SystemException, 00115 CosNaming::NamingContext::NotFound, 00116 CosNaming::NamingContext::CannotProceed, 00117 CosNaming::NamingContext::InvalidName)); 00118 00119 /** 00120 * Return object reference that is bound to the name. Compound name 00121 * resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = 00122 * ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service 00123 * does not return the type of the object. Clients are responsible 00124 * for "narrowing" the object to the appropriate type. 00125 */ 00126 virtual CORBA::Object_ptr resolve (const CosNaming::Name &n 00127 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00128 ACE_THROW_SPEC ((CORBA::SystemException, 00129 CosNaming::NamingContext::NotFound, 00130 CosNaming::NamingContext::CannotProceed, 00131 CosNaming::NamingContext::InvalidName)); 00132 00133 /** 00134 * Remove the name binding from the context. When compound names 00135 * are used, unbind is defined as follows: ctx->unbind (<c1; c2; 00136 * cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) 00137 */ 00138 virtual void unbind (const CosNaming::Name &n 00139 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00140 ACE_THROW_SPEC ((CORBA::SystemException, 00141 CosNaming::NamingContext::NotFound, 00142 CosNaming::NamingContext::CannotProceed, 00143 CosNaming::NamingContext::InvalidName)); 00144 00145 00146 /** 00147 * This operation returns a new naming context implemented by the 00148 * same naming server in which the operation was invoked. The 00149 * context is not bound. 00150 */ 00151 virtual CosNaming::NamingContext_ptr new_context ( 00152 ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS) 00153 ACE_THROW_SPEC ((CORBA::SystemException)); 00154 00155 /** 00156 * This operation creates a new context and binds it to the name 00157 * supplied as an argument. The newly-created context is 00158 * implemented by the same server as the context in which it was 00159 * bound (the name argument excluding the last component). 00160 */ 00161 virtual CosNaming::NamingContext_ptr bind_new_context ( 00162 const CosNaming::Name &n 00163 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00164 ACE_THROW_SPEC ((CORBA::SystemException, 00165 CosNaming::NamingContext::NotFound, 00166 CosNaming::NamingContext::AlreadyBound, 00167 CosNaming::NamingContext::CannotProceed, 00168 CosNaming::NamingContext::InvalidName)); 00169 00170 /** 00171 * Delete the naming context. The user should take care to <unbind> any 00172 * bindings in which the given context is bound to some names, to 00173 * avoid dangling references when invoking <destroy> operation. 00174 * NOTE: <destory> is a no-op on the root context. 00175 * NOTE: after <destroy> is invoked on a Naming Context, all 00176 * BindingIterators associated with that Naming Context are also destroyed. 00177 */ 00178 virtual void destroy (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS) 00179 ACE_THROW_SPEC ((CORBA::SystemException, 00180 CosNaming::NamingContext::NotEmpty)); 00181 00182 /** 00183 * Returns at most the requested number of bindings <how_many> in 00184 * <bl>. If the naming context contains additional bindings, they 00185 * are returned with a BindingIterator. In the naming context does 00186 * not contain any additional bindings <bi> returned as null. 00187 */ 00188 virtual void list (CORBA::ULong how_many, 00189 CosNaming::BindingList_out bl, 00190 CosNaming::BindingIterator_out bi 00191 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00192 ACE_THROW_SPEC ((CORBA::SystemException)); 00193 00194 /** 00195 * Stringify the name using '\' as the escape character. The 00196 * characters '.' , '/' and '\' are to be escaped. If the input name 00197 * is invalid i.e. if the number of characters in the name is zero, 00198 * an InvalidName exception is to be raised. 00199 */ 00200 virtual char * to_string (const CosNaming::Name &n 00201 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00202 ACE_THROW_SPEC ((CORBA::SystemException, 00203 CosNaming::NamingContext::InvalidName)); 00204 00205 /** 00206 * The in parameter is an stringified name. This function removes the 00207 * escape character '\' and destringifies the stringified name and returns 00208 * it. 00209 */ 00210 virtual CosNaming::Name * to_name (const char *sn 00211 ACE_ENV_ARG_DECL_WITH_DEFAULTS) 00212 ACE_THROW_SPEC ((CORBA::SystemException, 00213 CosNaming::NamingContext::InvalidName)); 00214 00215 /** 00216 * The in parameter addr refers to the address of the naming context 00217 * and sn refers to the strigified name of the object in that 00218 * context. This function returns a fully formed URL string like 00219 * iiopname://1.1@myhost.555xyz.com:9999/a/b/c 00220 */ 00221 virtual char * to_url ( const char * addr, 00222 const char * sn 00223 ACE_ENV_ARG_DECL_WITH_DEFAULTS 00224 ) 00225 ACE_THROW_SPEC (( 00226 CORBA::SystemException, 00227 CosNaming::NamingContextExt::InvalidAddress, 00228 CosNaming::NamingContext::InvalidName 00229 )); 00230 00231 /** 00232 * Similar to <resolve> as in the CosNaming::NamingContext interface. 00233 * It accepts a strigified name as an argument instead of a Name. 00234 */ 00235 virtual CORBA::Object_ptr resolve_str (const char * n 00236 ACE_ENV_ARG_DECL_WITH_DEFAULTS 00237 ) 00238 ACE_THROW_SPEC (( 00239 CORBA::SystemException, 00240 CosNaming::NamingContext::NotFound, 00241 CosNaming::NamingContext::CannotProceed, 00242 CosNaming::NamingContext::InvalidName 00243 )); 00244 00245 /// Returns the Default POA of this Servant object 00246 virtual PortableServer::POA_ptr _default_POA (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS); 00247 00248 private: 00249 00250 enum Hint 00251 { 00252 HINT_ID, 00253 HINT_KIND 00254 }; 00255 00256 /** 00257 * This private function is used as a helper to <to_name>. It reads 00258 * character by character from 'src' and depending on the character, 00259 * either assigns it to 'dest' or returns back to the calling 00260 * function. If the character is a seperator between the 'id' and 00261 * 'kind' fields or a seperator between two name components, the 00262 * control is returned back to the calling function <to_name>. 00263 */ 00264 void to_name_helper (char *dest, const char*& src, Hint hint); 00265 00266 /** 00267 * This method functions similar to <to_name_helper>. If the 00268 * character read is '.' or '/' or '\', an escape character '\' is 00269 * prepended before the character. 00270 */ 00271 void to_string_helper_assign (char * &k, const char * &src); 00272 00273 /** 00274 * This method helps count the number of characters in 'src' so 00275 * that memory can be allocated for the return parameter. For 00276 * all '.' , '/' and '\', the count is incremented by 'one' to 00277 * account for the escape character that needs to be 00278 * added. Seperators between 'id' and 'kind' as well as seperators 00279 * between the name components are also counted. 00280 */ 00281 void to_string_helper_length (CORBA::ULong &len, const char * &src); 00282 00283 /// Return 1 if the character is alphanumeric or a non-scaped 00284 /// punctuation. 00285 static int to_url_is_alnum_or_punctuation (char c); 00286 00287 /// Validate the to_url() method input, and compute the size of the 00288 /// returned URL address. 00289 static size_t to_url_validate_and_compute_size (const char *add, 00290 const char *sn 00291 ACE_ENV_ARG_DECL); 00292 00293 protected: 00294 00295 /// A concrete implementor of the NamingContext functions. 00296 TAO_Naming_Context_Impl *impl_; 00297 }; 00298 00299 /** 00300 * @class TAO_Naming_Context_Impl 00301 * 00302 * @brief This abstract base class plays a role of the 'Implementor' in the Bridge 00303 * pattern architecture of the NamingContext implementation. 00304 * 00305 * Subclasses of TAO_Naming_Context_Impl provide concrete 00306 * implementations of the NamingContext functionality. 00307 */ 00308 class TAO_Naming_Serv_Export TAO_Naming_Context_Impl 00309 { 00310 00311 public: 00312 00313 /// Destructor. 00314 virtual ~TAO_Naming_Context_Impl (void); 00315 00316 // = CosNaming::NamingContext idl interface methods. 00317 00318 /** 00319 * Create a binding for name <n> and object <obj> in the naming 00320 * context. Compound names are treated as follows: ctx->bind (<c1; 00321 * c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, 00322 * obj) if the there already exists a binding for the specified 00323 * name, <AlreadyBound> exception is thrown. Naming contexts should 00324 * be bound using <bind_context> and <rebind_context> in order to 00325 * participate in name resolution later. 00326 */ 00327 virtual void bind (const CosNaming::Name &n, 00328 CORBA::Object_ptr obj 00329 ACE_ENV_ARG_DECL) = 0; 00330 00331 /** 00332 * This is similar to <bind> operation above, except for when the 00333 * binding for the specified name already exists in the specified 00334 * context. In that case, the existing binding is replaced with the 00335 * new one. 00336 */ 00337 virtual void rebind (const CosNaming::Name &n, 00338 CORBA::Object_ptr obj 00339 ACE_ENV_ARG_DECL) = 0; 00340 00341 /** 00342 * This is the version of <bind> specifically for binding naming 00343 * contexts, so that they will participate in name resolution when 00344 * compound names are passed to be resolved. 00345 */ 00346 virtual void bind_context (const CosNaming::Name &n, 00347 CosNaming::NamingContext_ptr nc 00348 ACE_ENV_ARG_DECL) = 0; 00349 00350 /** 00351 * This is a version of <rebind> specifically for naming contexts, 00352 * so that they can participate in name resolution when compound 00353 * names are passed. 00354 */ 00355 virtual void rebind_context (const CosNaming::Name &n, 00356 CosNaming::NamingContext_ptr nc 00357 ACE_ENV_ARG_DECL) = 0; 00358 00359 /** 00360 * Return object reference that is bound to the name. Compound name 00361 * resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = 00362 * ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service 00363 * does not return the type of the object. Clients are responsible 00364 * for "narrowing" the object to the appropriate type. 00365 */ 00366 virtual CORBA::Object_ptr resolve (const CosNaming::Name &n 00367 ACE_ENV_ARG_DECL) = 0; 00368 00369 /** 00370 * Remove the name binding from the context. When compound names 00371 * are used, unbind is defined as follows: ctx->unbind (<c1; c2; 00372 * cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) 00373 */ 00374 virtual void unbind (const CosNaming::Name &n 00375 ACE_ENV_ARG_DECL) = 0; 00376 00377 /** 00378 * This operation returns a new naming context implemented by the 00379 * same naming server in which the operation was invoked. The 00380 * context is not bound. 00381 */ 00382 virtual CosNaming::NamingContext_ptr new_context (ACE_ENV_SINGLE_ARG_DECL) = 0; 00383 00384 /** 00385 * This operation creates a new context and binds it to the name 00386 * supplied as an argument. The newly-created context is 00387 * implemented by the same server as the context in which it was 00388 * bound (the name argument excluding the last component). 00389 */ 00390 virtual CosNaming::NamingContext_ptr bind_new_context (const CosNaming::Name &n 00391 ACE_ENV_ARG_DECL) = 0; 00392 00393 /** 00394 * Delete the naming context. The user should take care to <unbind> any 00395 * bindings in which the given context is bound to some names, to 00396 * avoid dangling references when invoking <destroy> operation. 00397 * NOTE: <destory> is a no-op on the root context. 00398 * NOTE: after <destroy> is invoked on a Naming Context, all 00399 * BindingIterators associated with that Naming Context are also destroyed. 00400 */ 00401 virtual void destroy (ACE_ENV_SINGLE_ARG_DECL) = 0; 00402 00403 /** 00404 * Returns at most the requested number of bindings <how_many> in 00405 * <bl>. If the naming context contains additional bindings, they 00406 * are returned with a BindingIterator. In the naming context does 00407 * not contain any additional bindings <bi> returned as null. 00408 */ 00409 virtual void list (CORBA::ULong how_many, 00410 CosNaming::BindingList_out &bl, 00411 CosNaming::BindingIterator_out &bi 00412 ACE_ENV_ARG_DECL) = 0; 00413 00414 /// Returns the Default POA of this Servant object 00415 virtual PortableServer::POA_ptr _default_POA (void) = 0; 00416 }; 00417 00418 TAO_END_VERSIONED_NAMESPACE_DECL 00419 00420 #include /**/ "ace/post.h" 00421 00422 #endif /* TAO_NAMING_CONTEXT_INTERFACE_H */