Naming_Context_Interface.h

Go to the documentation of this file.
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 */

Generated on Thu Nov 9 13:57:02 2006 for TAO_CosNaming by doxygen 1.3.6