diff options
Diffstat (limited to 'TAO/orbsvcs/orbsvcs/Naming')
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.h | 142 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Entries.h | 116 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Flat_File_Persistence.h | 23 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h | 264 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Naming_Context_Interface.h | 372 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Naming_Loader.h | 23 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Naming_Service_Container.h | 141 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.h | 269 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h | 159 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.h | 205 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h | 252 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Storable.h | 28 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Storable_Naming_Context.h | 249 | ||||
-rw-r--r-- | TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h | 169 |
14 files changed, 1300 insertions, 1112 deletions
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.h b/TAO/orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.h index 887fc9c034d..64cd9fa5c12 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.h @@ -1,17 +1,14 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Hash_Binding_Iterator_T.h -// -// = AUTHOR -// Marina Spivak <marina@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Bindings_Iterator_T.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + */ +//============================================================================= + #ifndef TAO_BINDINGS_ITERATOR_T_H #define TAO_BINDINGS_ITERATOR_T_H @@ -19,105 +16,116 @@ #include "Hash_Naming_Context.h" +/** + * @class TAO_Bindings_Iterator + * + * @brief This class implements the <BindingIterator> interface that is + * part of the <CosNaming> idl module. This class works with Hash_Map-based + * implementations of CosNaming::NamingContext. + * + * This class is templatized by the types of the underlying + * hash table iterator and hash table entry, so that it can be + * used for both TAO_Transient_Naming_Context and + * TAO_Persistent_Naming_Context (and any other classes with + * underlying data structures supporting + * ACE_Hash_Map_Manager/Iterator - like interfaces). + * + * Instances of <TAO_Bindings_Iterator>s affect reference counts + * of corresponding Naming Contexts. Reference count on a + * Naming Context is incremented by one for a lifetime of each + * instance of <TAO_Bindings_Iterator> created for that + * context, i.e., a Naming Context cannot + * be cleaned up (but, of course, it can be invalidated) before + * all of its iterators have been cleaned up. When <destroy> + * method is invoked on a Naming Context, all of its iterators are + * destroyed in a "lazy evaluation" fashion, i.e., whenever a next + * operation is invoked on an iterator, and it can detect that + * the corresponding Naming Context has been invalidated, the + * iterator is destroyed. + */ template <class ITERATOR, class TABLE_ENTRY> class TAO_Bindings_Iterator : public virtual PortableServer::RefCountServantBase, public virtual POA_CosNaming::BindingIterator { - // = TITLE - // This class implements the <BindingIterator> interface that is - // part of the <CosNaming> idl module. This class works with Hash_Map-based - // implementations of CosNaming::NamingContext. - // - // = DESCRIPTION - // This class is templatized by the types of the underlying - // hash table iterator and hash table entry, so that it can be - // used for both TAO_Transient_Naming_Context and - // TAO_Persistent_Naming_Context (and any other classes with - // underlying data structures supporting - // ACE_Hash_Map_Manager/Iterator - like interfaces). - // - // Instances of <TAO_Bindings_Iterator>s affect reference counts - // of corresponding Naming Contexts. Reference count on a - // Naming Context is incremented by one for a lifetime of each - // instance of <TAO_Bindings_Iterator> created for that - // context, i.e., a Naming Context cannot - // be cleaned up (but, of course, it can be invalidated) before - // all of its iterators have been cleaned up. When <destroy> - // method is invoked on a Naming Context, all of its iterators are - // destroyed in a "lazy evaluation" fashion, i.e., whenever a next - // operation is invoked on an iterator, and it can detect that - // the corresponding Naming Context has been invalidated, the - // iterator is destroyed. - // public: // = Intialization and termination methods. + /** + * Constructor expects a pointer to a + * dynamically allocated hash map iterator (destructor + * deallocates hash map iterator). + */ TAO_Bindings_Iterator (TAO_Hash_Naming_Context *context, ITERATOR *hash_iter, PortableServer::POA_ptr poa, TAO_SYNCH_RECURSIVE_MUTEX &lock); - // Constructor expects a pointer to a - // dynamically allocated hash map iterator (destructor - // deallocates hash map iterator). + /// Destructor. ~TAO_Bindings_Iterator (void); - // Destructor. + /// Returns the Default POA of this Servant object virtual PortableServer::POA_ptr _default_POA (ACE_ENV_SINGLE_ARG_DECL); - // Returns the Default POA of this Servant object // = Idl methods. + /// This operation passes back the next unseen binding. True is + /// returned if a binding is passed back, and false is returned otherwise. CORBA::Boolean next_one (CosNaming::Binding_out b ACE_ENV_ARG_DECL) ACE_THROW_SPEC ((CORBA::SystemException)); - // This operation passes back the next unseen binding. True is - // returned if a binding is passed back, and false is returned otherwise. + /** + * This operation passes back at most <how_many> unseen bindings. + * True is returned if bindings were passed back, and false is + * returned if no bindings were passed back. + */ CORBA::Boolean next_n (CORBA::ULong how_many, CosNaming::BindingList_out bl ACE_ENV_ARG_DECL) ACE_THROW_SPEC ((CORBA::SystemException)); - // This operation passes back at most <how_many> unseen bindings. - // True is returned if bindings were passed back, and false is - // returned if no bindings were passed back. + /// This operation destroys the iterator. void destroy (ACE_ENV_SINGLE_ARG_DECL) ACE_THROW_SPEC ((CORBA::SystemException)); - // This operation destroys the iterator. // = Helper method. + /** + * Helper function used by TAO_*_Naming_Context and + * TAO_BindingIterator: populate a binding <b> with info contained + * in <hash_entry>. Return 1 if everything went smoothly, 0 if an + * allocation failed. + */ static int populate_binding (TABLE_ENTRY *hash_entry, CosNaming::Binding &b); - // Helper function used by TAO_*_Naming_Context and - // TAO_BindingIterator: populate a binding <b> with info contained - // in <hash_entry>. Return 1 if everything went smoothly, 0 if an - // allocation failed. private: + /** + * Flag indicating whether this iterator is still valid. (The + * iterator becomes invalid when <destroy> method has been invoked + * on it, or when <destroy> method has been invoked on the + * corresponding Naming Context.) This flag is necessary + * because immediate destruction of this servant might not be possible + * due to pending requests in the POA. + */ int destroyed_; - // Flag indicating whether this iterator is still valid. (The - // iterator becomes invalid when <destroy> method has been invoked - // on it, or when <destroy> method has been invoked on the - // corresponding Naming Context.) This flag is necessary - // because immediate destruction of this servant might not be possible - // due to pending requests in the POA. + /** + * Pointer to the Naming Context we are iterating over. We need + * this pointer to make sure the context is still valid before + * each iteration, and to decrement its reference count once we are <destroyed>. + */ TAO_Hash_Naming_Context *context_; - // Pointer to the Naming Context we are iterating over. We need - // this pointer to make sure the context is still valid before - // each iteration, and to decrement its reference count once we are <destroyed>. + /// A pointer to the hash map iterator. ITERATOR *hash_iter_; - // A pointer to the hash map iterator. + /// Lock passed on from Naming Context to serialize access to the + /// internal data structure. TAO_SYNCH_RECURSIVE_MUTEX &lock_; - // Lock passed on from Naming Context to serialize access to the - // internal data structure. + /// Implement a different _default_POA(). PortableServer::POA_var poa_; - // Implement a different _default_POA(). }; #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) diff --git a/TAO/orbsvcs/orbsvcs/Naming/Entries.h b/TAO/orbsvcs/orbsvcs/Naming/Entries.h index 958eb7a62a7..5dcf2f6f97d 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Entries.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Entries.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Entries.h -// -// = AUTHOR -// Marina Spivak <marina@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Entries.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + */ +//============================================================================= + #ifndef TAO_ENTRIES_H #define TAO_ENTRIES_H @@ -31,103 +28,108 @@ #include "orbsvcs/CosNamingC.h" #include "naming_export.h" +/** + * @class TAO_IntId + * + * @brief Helper class for TAO_Transient_Bindings_Map: unifies several + * data items, so they can be stored together as a <value> + * for a <key> in a hash table holding the state of a Transient + * Naming Context. + * + * This class holds CORBA Object pointer and a binding type, so + * they can be stored together as a <value> for a <key> in a + * hash table holding the state of a Transient Naming Context. + */ class TAO_Naming_Export TAO_IntId { - // = TITLE - // Helper class for TAO_Transient_Bindings_Map: unifies several - // data items, so they can be stored together as a <value> - // for a <key> in a hash table holding the state of a Transient - // Naming Context. - // - // = DESCRIPTION - // This class holds CORBA Object pointer and a binding type, so - // they can be stored together as a <value> for a <key> in a - // hash table holding the state of a Transient Naming Context. - // public: // = Initialization and termination methods. + /// Constructor. TAO_IntId (void); - // Constructor. + /// Constructor. TAO_IntId (CORBA::Object_ptr obj, CosNaming::BindingType type /* = CosNaming::nobject */); - // Constructor. + /// Copy constructor. TAO_IntId (const TAO_IntId & rhs); - // Copy constructor. + /// Destructor. ~TAO_IntId (void); - // Destructor. + /// Assignment operator (does copy memory). void operator= (const TAO_IntId & rhs); - // Assignment operator (does copy memory). // = Data members. + /// Object reference to be stored in a Transient Naming Context. CORBA::Object_ptr ref_; - // Object reference to be stored in a Transient Naming Context. + /// Binding type for <ref_>. CosNaming::BindingType type_; - // Binding type for <ref_>. }; +/** + * @class TAO_ExtId + * + * @brief Helper class for TAO_Transient_Bindings_Map: unifies several + * data items, so they can be stored together as a <key> + * for a <value> in a hash table holding the state of a Transient + * Naming Context. + * + * This class holds id and kind strings, so + * they can be stored together as a <key> for a <value> in a + * hash table holding the state of a Transient Naming Context. + */ class TAO_Naming_Export TAO_ExtId { - // = TITLE - // Helper class for TAO_Transient_Bindings_Map: unifies several - // data items, so they can be stored together as a <key> - // for a <value> in a hash table holding the state of a Transient - // Naming Context. - // - // = DESCRIPTION - // This class holds id and kind strings, so - // they can be stored together as a <key> for a <value> in a - // hash table holding the state of a Transient Naming Context. - // public: // = Initialization and termination methods. + /// Constructor. TAO_ExtId (void); - // Constructor. + /// Constructor. TAO_ExtId (const char *id, const char *kind); - // Constructor. + /// Copy constructor. TAO_ExtId (const TAO_ExtId & rhs); - // Copy constructor. + /// Destructor. ~TAO_ExtId (void); - // Destructor. // = Assignment and comparison operators. + /// Assignment operator (does copy memory). void operator= (const TAO_ExtId & rhs); - // Assignment operator (does copy memory). + /// Equality comparison operator (must match both id_ and kind_). int operator== (const TAO_ExtId &rhs) const; - // Equality comparison operator (must match both id_ and kind_). + /// Inequality comparison operator. int operator!= (const TAO_ExtId &rhs) const; - // Inequality comparison operator. + /// <hash> function is required in order for this class to be usable by + /// ACE_Hash_Map_Manager. u_long hash (void) const; - // <hash> function is required in order for this class to be usable by - // ACE_Hash_Map_Manager. // = Data members. + /// <kind> portion of the name to be associated with some object + /// reference in a Transient Naming Context. ACE_CString kind_; - // <kind> portion of the name to be associated with some object - // reference in a Transient Naming Context. + /// <id> portion of the name to be associated with some object + /// reference in a Transient Naming Context. ACE_CString id_; - // <id> portion of the name to be associated with some object - // reference in a Transient Naming Context. - // = Accessors: return <id_> and <kind_> in a const char * format. + // = Accessors + /// Return <id_> in a const char * format. const char * id (void); + + /// Return <kind_> in a const char * format. const char * kind (void); }; diff --git a/TAO/orbsvcs/orbsvcs/Naming/Flat_File_Persistence.h b/TAO/orbsvcs/orbsvcs/Naming/Flat_File_Persistence.h index 36b2adb5f9c..2aaab3451db 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Flat_File_Persistence.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Flat_File_Persistence.h @@ -1,16 +1,13 @@ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// -// -// = AUTHOR -// -// -// ============================================================================ +/* -*- C++ -*- */ +//============================================================================= +/** + * @file Flat_File_Persistence.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + */ +//============================================================================= #ifndef TAO_FLAT_FILE_PERSISTENCE_H #define TAO_FLAT_FILE_PERSISTENCE_H diff --git a/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h b/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h index f0c493f66a3..0b7e89004bb 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h @@ -1,17 +1,14 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Hash_Naming_Context.h -// -// = AUTHOR -// Marina Spivak <marina@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Hash_Naming_Context.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + */ +//============================================================================= + #ifndef TAO_HASH_NAMING_CONTEXT_H #define TAO_HASH_NAMING_CONTEXT_H @@ -33,205 +30,240 @@ #undef interface #endif // interface +/** + * @class TAO_Bindings_Map + * + * @brief This abstract base class defines an interface for hash-based + * data structures used in implementations of NamingContext + * (i.e., TAO_Transient_Naming_Context and TAO_Persistent_Naming_Context) + * + * Define an interface for several hash-based data structures, so + * that we can write some code that would work with any of them, + * i.e., TAO_Hash_Naming_Context. + */ class TAO_Naming_Export TAO_Bindings_Map { - // = TITLE - // This abstract base class defines an interface for hash-based - // data structures used in implementations of NamingContext - // (i.e., TAO_Transient_Naming_Context and TAO_Persistent_Naming_Context) - // - // = DESCRIPTION - // Define an interface for several hash-based data structures, so - // that we can write some code that would work with any of them, - // i.e., TAO_Hash_Naming_Context. public: + /// Destructor. virtual ~TAO_Bindings_Map (void); - // Destructor. + /// Return current number of entries (name bindings) in the + /// underlying hash map. virtual size_t current_size (void) = 0; - // Return current number of entries (name bindings) in the - // underlying hash map. + /** + * Add a binding with the specified parameters to the table. + * Return 0 on success and -1 on failure, 1 if there already is a + * binding with <id> and <kind>. + */ virtual int bind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type) = 0; - // Add a binding with the specified parameters to the table. - // Return 0 on success and -1 on failure, 1 if there already is a - // binding with <id> and <kind>. + /** + * Overwrite a binding containing <id> and <kind> (or create a new + * one if one doesn't exist) with the specified parameters. Returns + * -1 on failure. + */ virtual int rebind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type) = 0; - // Overwrite a binding containing <id> and <kind> (or create a new - // one if one doesn't exist) with the specified parameters. Returns - // -1 on failure. + /// Remove a binding containing <id> and <kind> from the table. + /// Return 0 on success and -1 on failure. virtual int unbind (const char * id, const char * kind) = 0; - // Remove a binding containing <id> and <kind> from the table. - // Return 0 on success and -1 on failure. + /** + * Find the binding containing <id> and <kind> in the table, and + * pass binding's type and object back to the caller by reference. + * Return 0 on success and -1 on failure. Note: a 'duplicated' object + * reference is assigned to <obj>, so the caller is responsible for + * its deallocation. + */ virtual int find (const char * id, const char * kind, CORBA::Object_ptr & obj, CosNaming::BindingType &type) = 0; - // Find the binding containing <id> and <kind> in the table, and - // pass binding's type and object back to the caller by reference. - // Return 0 on success and -1 on failure. Note: a 'duplicated' object - // reference is assigned to <obj>, so the caller is responsible for - // its deallocation. }; +/** + * @class TAO_Hash_Naming_Context + * + * @brief This class factors out common code for two 'ConcreteImplementors' + * in the Bridge pattern architecture of the CosNaming::NamingContext + * implementation. + * + * This class contains 'algorithm' code that is common to two + * hash-table-based implementations of the NamingContext: + * TAO_Transient_Naming_Context and TAO_Persistent_Naming_Context. + * To help achieve this 'templatization', we use the abstract base + * class TAO_Bindings_Map, which provides a common interface to the data structures + * used in TAO_Persistent_Namng_Context and TAO_Transient_Naming_Context. + */ class TAO_Naming_Export TAO_Hash_Naming_Context :public TAO_Naming_Context_Impl { - // = TITLE - // This class factors out common code for two 'ConcreteImplementors' - // in the Bridge pattern architecture of the CosNaming::NamingContext - // implementation. - // - // = DESCRIPTION - // This class contains 'algorithm' code that is common to two - // hash-table-based implementations of the NamingContext: - // TAO_Transient_Naming_Context and TAO_Persistent_Naming_Context. - // To help achieve this 'templatization', we use the abstract base - // class TAO_Bindings_Map, which provides a common interface to the data structures - // used in TAO_Persistent_Namng_Context and TAO_Transient_Naming_Context. - // public: // = Initialization and termination methods. + /// Constructor. TAO_Hash_Naming_Context (PortableServer::POA_ptr poa, const char *poa_id); - // Constructor. + /// Set our <interface_> pointer. void interface (TAO_Naming_Context *i); - // Set our <interface_> pointer. + /// Destructor. virtual ~TAO_Hash_Naming_Context (void); - // Destructor. // = Accessors. + /// Get the pointer to our <interface>. TAO_Naming_Context *interface (void); - // Get the pointer to our <interface>. + /// Returns true if this Naming Context is a root Naming Context for + /// the server, and false otherwise. int root (void); - // Returns true if this Naming Context is a root Naming Context for - // the server, and false otherwise. + /// Returns true if this context had <destroy> operation invoked on + /// it, and false otherwise. int destroyed (void); - // Returns true if this context had <destroy> operation invoked on - // it, and false otherwise. // = CosNaming::NamingContext idl interface methods. + /** + * Create a binding for name <n> and object <obj> in the naming + * context. Compound names are treated as follows: ctx->bind (<c1; + * c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, + * obj) if the there already exists a binding for the specified + * name, <AlreadyBound> exception is thrown. Naming contexts should + * be bound using <bind_context> and <rebind_context> in order to + * participate in name resolution later. + */ virtual void bind (const CosNaming::Name &n, CORBA::Object_ptr obj ACE_ENV_ARG_DECL); - // Create a binding for name <n> and object <obj> in the naming - // context. Compound names are treated as follows: ctx->bind (<c1; - // c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, - // obj) if the there already exists a binding for the specified - // name, <AlreadyBound> exception is thrown. Naming contexts should - // be bound using <bind_context> and <rebind_context> in order to - // participate in name resolution later. + /** + * This is similar to <bind> operation above, except for when the + * binding for the specified name already exists in the specified + * context. In that case, the existing binding is replaced with the + * new one. + */ virtual void rebind (const CosNaming::Name &n, CORBA::Object_ptr obj ACE_ENV_ARG_DECL); - // This is similar to <bind> operation above, except for when the - // binding for the specified name already exists in the specified - // context. In that case, the existing binding is replaced with the - // new one. + /** + * This is the version of <bind> specifically for binding naming + * contexts, so that they will participate in name resolution when + * compound names are passed to be resolved. + */ virtual void bind_context (const CosNaming::Name &n, CosNaming::NamingContext_ptr nc ACE_ENV_ARG_DECL); - // This is the version of <bind> specifically for binding naming - // contexts, so that they will participate in name resolution when - // compound names are passed to be resolved. + /** + * This is a version of <rebind> specifically for naming contexts, + * so that they can participate in name resolution when compound + * names are passed. + */ virtual void rebind_context (const CosNaming::Name &n, CosNaming::NamingContext_ptr nc ACE_ENV_ARG_DECL); - // This is a version of <rebind> specifically for naming contexts, - // so that they can participate in name resolution when compound - // names are passed. + /** + * Return object reference that is bound to the name. Compound name + * resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = + * ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service + * does not return the type of the object. Clients are responsible + * for "narrowing" the object to the appropriate type. + */ virtual CORBA::Object_ptr resolve (const CosNaming::Name &n ACE_ENV_ARG_DECL); - // Return object reference that is bound to the name. Compound name - // resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = - // ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service - // does not return the type of the object. Clients are responsible - // for "narrowing" the object to the appropriate type. + /** + * Remove the name binding from the context. When compound names + * are used, unbind is defined as follows: ctx->unbind (<c1; c2; + * cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) + */ virtual void unbind (const CosNaming::Name &n ACE_ENV_ARG_DECL); - // Remove the name binding from the context. When compound names - // are used, unbind is defined as follows: ctx->unbind (<c1; c2; - // cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) + /** + * This operation creates a new context and binds it to the name + * supplied as an argument. The newly-created context is + * implemented by the same server as the context in which it was + * bound (the name argument excluding the last component). + */ virtual CosNaming::NamingContext_ptr bind_new_context (const CosNaming::Name &n ACE_ENV_ARG_DECL); - // This operation creates a new context and binds it to the name - // supplied as an argument. The newly-created context is - // implemented by the same server as the context in which it was - // bound (the name argument excluding the last component). + /** + * Delete the naming context. The user should take care to <unbind> any + * bindings in which the given context is bound to some names, to + * avoid dangling references when invoking <destroy> operation. + * NOTE: <destory> is a no-op on the root context. + * NOTE: after <destroy> is invoked on a Naming Context, all + * BindingIterators associated with that Naming Context are also destroyed. + */ virtual void destroy (ACE_ENV_SINGLE_ARG_DECL); - // Delete the naming context. The user should take care to <unbind> any - // bindings in which the given context is bound to some names, to - // avoid dangling references when invoking <destroy> operation. - // NOTE: <destory> is a no-op on the root context. - // NOTE: after <destroy> is invoked on a Naming Context, all - // BindingIterators associated with that Naming Context are also destroyed. + /// Returns the Default POA of this Servant object virtual PortableServer::POA_ptr _default_POA (void); - // Returns the Default POA of this Servant object protected: // = Helper method used by other methods. + /** + * <get_context> is used by methods that need to resolve a compound + * name before performing the actual operation (e.g., bind, unbind, + * etc.) <get_context> takes a full name (including the last + * component that doesn't need to be resolved), and returns a + * pointer to the target context. + */ CosNaming::NamingContext_ptr get_context (const CosNaming::Name &name ACE_ENV_ARG_DECL); - // <get_context> is used by methods that need to resolve a compound - // name before performing the actual operation (e.g., bind, unbind, - // etc.) <get_context> takes a full name (including the last - // component that doesn't need to be resolved), and returns a - // pointer to the target context. + /** + * Pointer to the data structure used to store this Naming Context's + * bindings. <context_> is initialized with a concrete data + * structure by subclasses, which know which data structure to use. + */ TAO_Bindings_Map *context_; - // Pointer to the data structure used to store this Naming Context's - // bindings. <context_> is initialized with a concrete data - // structure by subclasses, which know which data structure to use. + /** + * Pointer to the <interface> object for which we serve as a + * <concrete implementation>, i.e., the object that delegates to us + * all client CosNaming::NamingContext CORBA calls. + * We need this pointer for reference counting. + */ TAO_Naming_Context *interface_; - // Pointer to the <interface> object for which we serve as a - // <concrete implementation>, i.e., the object that delegates to us - // all client CosNaming::NamingContext CORBA calls. - // We need this pointer for reference counting. + /// Lock used to serialize access to the underlying data structure. TAO_SYNCH_RECURSIVE_MUTEX lock_; - // Lock used to serialize access to the underlying data structure. + /** + * Flag indicating whether this Naming Context is no longer valid. + * This flag is necessary because immediate destruction + * might not be possible if there are pending requests on this servant + * in the POA. + */ int destroyed_; - // Flag indicating whether this Naming Context is no longer valid. - // This flag is necessary because immediate destruction - // might not be possible if there are pending requests on this servant - // in the POA. + /// POA we are registered with. PortableServer::POA_var poa_; - // POA we are registered with. + /** + * ID with which we are registered with <poa_>. + * Note, if <poa_id_> is equivalent to TAO_ROOT_NAMING_CONTEXT, then this Naming Context + * is the root Naming Context for the server, i.e., it is un<destroy>able. + */ ACE_CString poa_id_; - // ID with which we are registered with <poa_>. - // Note, if <poa_id_> is equivalent to TAO_ROOT_NAMING_CONTEXT, then this Naming Context - // is the root Naming Context for the server, i.e., it is un<destroy>able. }; #include "ace/post.h" diff --git a/TAO/orbsvcs/orbsvcs/Naming/Naming_Context_Interface.h b/TAO/orbsvcs/orbsvcs/Naming/Naming_Context_Interface.h index e7ffff27984..87311dac912 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Naming_Context_Interface.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Naming_Context_Interface.h @@ -1,17 +1,14 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Naming_Context_Interface.h -// -// = AUTHOR -// Marina Spivak <marina@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Naming_Context_Interface.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + */ +//============================================================================= + #ifndef TAO_NAMING_CONTEXT_INTERFACE_H #define TAO_NAMING_CONTEXT_INTERFACE_H @@ -26,33 +23,44 @@ class TAO_Naming_Context_Impl; # pragma warning (disable : 4250) #endif /* _MSC_VER */ +/** + * @class TAO_Naming_Context + * + * @brief This class plays a role of the 'Abstraction' (aka 'Interface') + * in the Bridge pattern architecture of the CosNaming::NamingContext + * implementation. + * + * This class simply forwards all client requests to a concrete + * NamingContext implementation through its <impl_> pointer. See + * README file for more info. Comments for the idl methods + * describe methods semantics - actual actions are carried out by + * concrete implementors. + */ + class TAO_Naming_Export TAO_Naming_Context : public virtual PortableServer::RefCountServantBase, public virtual POA_CosNaming::NamingContextExt { - // = TITLE - // This class plays a role of the 'Abstraction' (aka 'Interface') - // in the Bridge pattern architecture of the - // CosNaming::NamingContext implementation. - // - // = DESCRIPTION - // This class simply forwards all client requests to a concrete - // NamingContext implementation through its <impl_> pointer. See - // README file for more info. Comments for the idl methods - // describe methods semantics - actual actions are carried out by - // concrete implementors. - public: // = Initialization and termination methods. + /// Constructor. Initializes <impl_> with a concrete implementation. TAO_Naming_Context (TAO_Naming_Context_Impl *impl); - // Constructor. Initializes <impl_> with a concrete implementation. + /// Destructor. ~TAO_Naming_Context (void); - // Destructor. // = CosNaming::NamingContext idl interface methods. + /** + * Create a binding for name <n> and object <obj> in the naming + * context. Compound names are treated as follows: ctx->bind (<c1; + * c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, + * obj) if the there already exists a binding for the specified + * name, <AlreadyBound> exception is thrown. Naming contexts should + * be bound using <bind_context> and <rebind_context> in order to + * participate in name resolution later. + */ virtual void bind (const CosNaming::Name &n, CORBA::Object_ptr obj ACE_ENV_ARG_DECL_WITH_DEFAULTS) @@ -62,14 +70,12 @@ public: CosNaming::NamingContext::InvalidName, CosNaming::NamingContext::AlreadyBound)); - // Create a binding for name <n> and object <obj> in the naming - // context. Compound names are treated as follows: ctx->bind (<c1; - // c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, - // obj) if the there already exists a binding for the specified - // name, <AlreadyBound> exception is thrown. Naming contexts should - // be bound using <bind_context> and <rebind_context> in order to - // participate in name resolution later. - + /** + * This is similar to <bind> operation above, except for when the + * binding for the specified name already exists in the specified + * context. In that case, the existing binding is replaced with the + * new one. + */ virtual void rebind (const CosNaming::Name &n, CORBA::Object_ptr obj ACE_ENV_ARG_DECL_WITH_DEFAULTS) @@ -78,11 +84,11 @@ public: CosNaming::NamingContext::CannotProceed, CosNaming::NamingContext::InvalidName)); - // This is similar to <bind> operation above, except for when the - // binding for the specified name already exists in the specified - // context. In that case, the existing binding is replaced with the - // new one. - + /** + * This is the version of <bind> specifically for binding naming + * contexts, so that they will participate in name resolution when + * compound names are passed to be resolved. + */ virtual void bind_context (const CosNaming::Name &n, CosNaming::NamingContext_ptr nc ACE_ENV_ARG_DECL_WITH_DEFAULTS) @@ -92,10 +98,11 @@ public: CosNaming::NamingContext::InvalidName, CosNaming::NamingContext::AlreadyBound)); - // This is the version of <bind> specifically for binding naming - // contexts, so that they will participate in name resolution when - // compound names are passed to be resolved. - + /** + * This is a version of <rebind> specifically for naming contexts, + * so that they can participate in name resolution when compound + * names are passed. + */ virtual void rebind_context (const CosNaming::Name &n, CosNaming::NamingContext_ptr nc ACE_ENV_ARG_DECL_WITH_DEFAULTS) @@ -103,22 +110,26 @@ public: CosNaming::NamingContext::NotFound, CosNaming::NamingContext::CannotProceed, CosNaming::NamingContext::InvalidName)); - // This is a version of <rebind> specifically for naming contexts, - // so that they can participate in name resolution when compound - // names are passed. + /** + * Return object reference that is bound to the name. Compound name + * resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = + * ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service + * does not return the type of the object. Clients are responsible + * for "narrowing" the object to the appropriate type. + */ virtual CORBA::Object_ptr resolve (const CosNaming::Name &n ACE_ENV_ARG_DECL_WITH_DEFAULTS) ACE_THROW_SPEC ((CORBA::SystemException, CosNaming::NamingContext::NotFound, CosNaming::NamingContext::CannotProceed, CosNaming::NamingContext::InvalidName)); - // Return object reference that is bound to the name. Compound name - // resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = - // ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service - // does not return the type of the object. Clients are responsible - // for "narrowing" the object to the appropriate type. + /** + * Remove the name binding from the context. When compound names + * are used, unbind is defined as follows: ctx->unbind (<c1; c2; + * cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) + */ virtual void unbind (const CosNaming::Name &n ACE_ENV_ARG_DECL_WITH_DEFAULTS) ACE_THROW_SPEC ((CORBA::SystemException, @@ -126,18 +137,22 @@ public: CosNaming::NamingContext::CannotProceed, CosNaming::NamingContext::InvalidName)); - // Remove the name binding from the context. When compound names - // are used, unbind is defined as follows: ctx->unbind (<c1; c2; - // cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) + /** + * This operation returns a new naming context implemented by the + * same naming server in which the operation was invoked. The + * context is not bound. + */ virtual CosNaming::NamingContext_ptr new_context ( ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS) ACE_THROW_SPEC ((CORBA::SystemException)); - // This operation returns a new naming context implemented by the - // same naming server in which the operation was invoked. The - // context is not bound. - + /** + * This operation creates a new context and binds it to the name + * supplied as an argument. The newly-created context is + * implemented by the same server as the context in which it was + * bound (the name argument excluding the last component). + */ virtual CosNaming::NamingContext_ptr bind_new_context ( const CosNaming::Name &n ACE_ENV_ARG_DECL_WITH_DEFAULTS) @@ -147,50 +162,57 @@ public: CosNaming::NamingContext::CannotProceed, CosNaming::NamingContext::InvalidName)); - // This operation creates a new context and binds it to the name - // supplied as an argument. The newly-created context is - // implemented by the same server as the context in which it was - // bound (the name argument excluding the last component). - - + /** + * Delete the naming context. The user should take care to <unbind> any + * bindings in which the given context is bound to some names, to + * avoid dangling references when invoking <destroy> operation. + * NOTE: <destory> is a no-op on the root context. + * NOTE: after <destroy> is invoked on a Naming Context, all + * BindingIterators associated with that Naming Context are also destroyed. + */ virtual void destroy (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS) ACE_THROW_SPEC ((CORBA::SystemException, CosNaming::NamingContext::NotEmpty)); - // Delete the naming context. The user should take care to <unbind> any - // bindings in which the given context is bound to some names, to - // avoid dangling references when invoking <destroy> operation. - // NOTE: <destory> is a no-op on the root context. - // NOTE: after <destroy> is invoked on a Naming Context, all - // BindingIterators associated with that Naming Context are also destroyed. + /** + * Returns at most the requested number of bindings <how_many> in + * <bl>. If the naming context contains additional bindings, they + * are returned with a BindingIterator. In the naming context does + * not contain any additional bindings <bi> returned as null. + */ virtual void list (CORBA::ULong how_many, CosNaming::BindingList_out bl, CosNaming::BindingIterator_out bi ACE_ENV_ARG_DECL_WITH_DEFAULTS) ACE_THROW_SPEC ((CORBA::SystemException)); - // Returns at most the requested number of bindings <how_many> in - // <bl>. If the naming context contains additional bindings, they - // are returned with a BindingIterator. In the naming context does - // not contain any additional bindings <bi> returned as null. - + /** + * Stringify the name using '\' as the escape character. The + * characters '.' , '/' and '\' are to be escaped. If the input name + * is invalid i.e. if the number of characters in the name is zero, + * an InvalidName exception is to be raised. + */ virtual char * to_string (const CosNaming::Name &n ACE_ENV_ARG_DECL_WITH_DEFAULTS) ACE_THROW_SPEC ((CORBA::SystemException, CosNaming::NamingContext::InvalidName)); - // Stringify the name using '\' as the escape character. The - // characters '.' , '/' and '\' are to be escaped. If the input name - // is invalid i.e. if the number of characters in the name is zero, - // an InvalidName exception is to be raised. + /** + * The in parameter is an stringified name. This function removes the + * escape character '\' and destringifies the stringified name and returns + * it. + */ virtual CosNaming::Name * to_name (const char *sn ACE_ENV_ARG_DECL_WITH_DEFAULTS) ACE_THROW_SPEC ((CORBA::SystemException, CosNaming::NamingContext::InvalidName)); - // The in parameter is an stringified name. This function removes the - // escape character '\' and destringifies the stringified name and returns - // it. + /** + * The in parameter addr refers to the address of the naming context + * and sn refers to the strigified name of the object in that + * context. This function returns a fully formed URL string like + * iiopname://1.1@myhost.555xyz.com:9999/a/b/c + */ virtual char * to_url ( const char * addr, const char * sn ACE_ENV_ARG_DECL_WITH_DEFAULTS @@ -200,11 +222,11 @@ public: CosNaming::NamingContextExt::InvalidAddress, CosNaming::NamingContext::InvalidName )); - // The in parameter addr refers to the address of the naming context - // and sn refers to the strigified name of the object in that - // context. This function returns a fully formed URL string like - // iiopname://1.1@myhost.555xyz.com:9999/a/b/c + /** + * Similar to <resolve> as in the CosNaming::NamingContext interface. + * It accepts a strigified name as an argument instead of a Name. + */ virtual CORBA::Object_ptr resolve_str (const char * n ACE_ENV_ARG_DECL_WITH_DEFAULTS ) @@ -216,147 +238,171 @@ public: CosNaming::NamingContext::AlreadyBound )); - // Similar to <resolve> as in the CosNaming::NamingContext interface. - // It accepts a strigified name as an argument instead of a Name. - - + /// Returns the Default POA of this Servant object virtual PortableServer::POA_ptr _default_POA (ACE_ENV_SINGLE_ARG_DECL_WITH_DEFAULTS); - // Returns the Default POA of this Servant object private: + /** + * This private function is used as a helper to <to_name>. It reads + * character by character from 'src' and depending on the character, + * either assigns it to 'dest' or returns back to the calling + * function. If the character is a seperator between the 'id' and + * 'kind' fields or a seperator between two name components, the + * control is returned back to the calling function <to_name>. + */ void to_name_helper (char *dest, const char*& src); - // This private function is used as a helper to <to_name>. It reads - // character by character from 'src' and depending on the character, - // either assigns it to 'dest' or returns back to the calling - // function. If the character is a seperator between the 'id' and - // 'kind' fields or a seperator between two name components, the - // control is returned back to the calling function <to_name>. + /** + * This method functions similar to <to_name_helper>. If the + * character read is '.' or '/' or '\', an escape character '\' is + * prepended before the character. + */ void to_string_helper_assign (char * &k, const char * &src); - // This method functions similar to <to_name_helper>. If the - // character read is '.' or '/' or '\', an escape character '\' is - // prepended before the character. + /** + * This method helps count the number of characters in 'src' so + * that memory can be allocated for the return parameter. For + * all '.' , '/' and '\', the count is incremented by 'one' to + * account for the escape character that needs to be + * added. Seperators between 'id' and 'kind' as well as seperators + * between the name components are also counted. + */ void to_string_helper_length (CORBA::ULong &len, const char * &src); - // This method helps count the number of characters in 'src' so - // that memory can be allocated for the return parameter. For - // all '.' , '/' and '\', the count is incremented by 'one' to - // account for the escape character that needs to be - // added. Seperators between 'id' and 'kind' as well as seperators - // between the name components are also counted. + /// Return 1 if the character is alphanumeric or a non-scaped + /// punctuation. static int to_url_is_alnum_or_punctuation (char c); - // Return 1 if the character is alphanumeric or a non-scaped - // punctuation. + /// Validate the to_url() method input, and compute the size of the + /// returned URL address. static size_t to_url_validate_and_compute_size (const char *add, const char *sn ACE_ENV_ARG_DECL); - // Validate the to_url() method input, and compute the size of the - // returned URL address. protected: + /// A concrete implementor of the NamingContext functions. TAO_Naming_Context_Impl *impl_; - // A concrete implementor of the NamingContext functions. }; +/** + * @class TAO_Naming_Context_Impl + * + * @brief This abstract base class plays a role of the 'Implementor' in the Bridge + * pattern architecture of the NamingContext implementation. + * + * Subclasses of TAO_Naming_Context_Impl provide concrete + * implementations of the NamingContext functionality. + */ class TAO_Naming_Export TAO_Naming_Context_Impl { - // = TITLE - // This abstract base class plays a role of the 'Implementor' in the Bridge - // pattern architecture of the NamingContext implementation. - // - // = DESCRIPTION - // Subclasses of TAO_Naming_Context_Impl provide concrete - // implementations of the NamingContext functionality. public: + /// Destructor. virtual ~TAO_Naming_Context_Impl (void); - // Destructor. // = CosNaming::NamingContext idl interface methods. + /** + * Create a binding for name <n> and object <obj> in the naming + * context. Compound names are treated as follows: ctx->bind (<c1; + * c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, + * obj) if the there already exists a binding for the specified + * name, <AlreadyBound> exception is thrown. Naming contexts should + * be bound using <bind_context> and <rebind_context> in order to + * participate in name resolution later. + */ virtual void bind (const CosNaming::Name &n, CORBA::Object_ptr obj ACE_ENV_ARG_DECL) = 0; - // Create a binding for name <n> and object <obj> in the naming - // context. Compound names are treated as follows: ctx->bind (<c1; - // c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, - // obj) if the there already exists a binding for the specified - // name, <AlreadyBound> exception is thrown. Naming contexts should - // be bound using <bind_context> and <rebind_context> in order to - // participate in name resolution later. + /** + * This is similar to <bind> operation above, except for when the + * binding for the specified name already exists in the specified + * context. In that case, the existing binding is replaced with the + * new one. + */ virtual void rebind (const CosNaming::Name &n, CORBA::Object_ptr obj ACE_ENV_ARG_DECL) = 0; - // This is similar to <bind> operation above, except for when the - // binding for the specified name already exists in the specified - // context. In that case, the existing binding is replaced with the - // new one. + /** + * This is the version of <bind> specifically for binding naming + * contexts, so that they will participate in name resolution when + * compound names are passed to be resolved. + */ virtual void bind_context (const CosNaming::Name &n, CosNaming::NamingContext_ptr nc ACE_ENV_ARG_DECL) = 0; - // This is the version of <bind> specifically for binding naming - // contexts, so that they will participate in name resolution when - // compound names are passed to be resolved. + /** + * This is a version of <rebind> specifically for naming contexts, + * so that they can participate in name resolution when compound + * names are passed. + */ virtual void rebind_context (const CosNaming::Name &n, CosNaming::NamingContext_ptr nc ACE_ENV_ARG_DECL) = 0; - // This is a version of <rebind> specifically for naming contexts, - // so that they can participate in name resolution when compound - // names are passed. + /** + * Return object reference that is bound to the name. Compound name + * resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = + * ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service + * does not return the type of the object. Clients are responsible + * for "narrowing" the object to the appropriate type. + */ virtual CORBA::Object_ptr resolve (const CosNaming::Name &n ACE_ENV_ARG_DECL) = 0; - // Return object reference that is bound to the name. Compound name - // resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = - // ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service - // does not return the type of the object. Clients are responsible - // for "narrowing" the object to the appropriate type. + /** + * Remove the name binding from the context. When compound names + * are used, unbind is defined as follows: ctx->unbind (<c1; c2; + * cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) + */ virtual void unbind (const CosNaming::Name &n ACE_ENV_ARG_DECL) = 0; - // Remove the name binding from the context. When compound names - // are used, unbind is defined as follows: ctx->unbind (<c1; c2; - // cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) + /** + * This operation returns a new naming context implemented by the + * same naming server in which the operation was invoked. The + * context is not bound. + */ virtual CosNaming::NamingContext_ptr new_context (ACE_ENV_SINGLE_ARG_DECL) = 0; - // This operation returns a new naming context implemented by the - // same naming server in which the operation was invoked. The - // context is not bound. + /** + * This operation creates a new context and binds it to the name + * supplied as an argument. The newly-created context is + * implemented by the same server as the context in which it was + * bound (the name argument excluding the last component). + */ virtual CosNaming::NamingContext_ptr bind_new_context (const CosNaming::Name &n ACE_ENV_ARG_DECL) = 0; - // This operation creates a new context and binds it to the name - // supplied as an argument. The newly-created context is - // implemented by the same server as the context in which it was - // bound (the name argument excluding the last component). + /** + * Delete the naming context. The user should take care to <unbind> any + * bindings in which the given context is bound to some names, to + * avoid dangling references when invoking <destroy> operation. + * NOTE: <destory> is a no-op on the root context. + * NOTE: after <destroy> is invoked on a Naming Context, all + * BindingIterators associated with that Naming Context are also destroyed. + */ virtual void destroy (ACE_ENV_SINGLE_ARG_DECL) = 0; - // Delete the naming context. The user should take care to <unbind> any - // bindings in which the given context is bound to some names, to - // avoid dangling references when invoking <destroy> operation. - // NOTE: <destory> is a no-op on the root context. - // NOTE: after <destroy> is invoked on a Naming Context, all - // BindingIterators associated with that Naming Context are also destroyed. + /** + * Returns at most the requested number of bindings <how_many> in + * <bl>. If the naming context contains additional bindings, they + * are returned with a BindingIterator. In the naming context does + * not contain any additional bindings <bi> returned as null. + */ virtual void list (CORBA::ULong how_many, CosNaming::BindingList_out &bl, CosNaming::BindingIterator_out &bi ACE_ENV_ARG_DECL) = 0; - // Returns at most the requested number of bindings <how_many> in - // <bl>. If the naming context contains additional bindings, they - // are returned with a BindingIterator. In the naming context does - // not contain any additional bindings <bi> returned as null. + /// Returns the Default POA of this Servant object virtual PortableServer::POA_ptr _default_POA (void) = 0; - // Returns the Default POA of this Servant object }; diff --git a/TAO/orbsvcs/orbsvcs/Naming/Naming_Loader.h b/TAO/orbsvcs/orbsvcs/Naming/Naming_Loader.h index 0acb7449e54..601ad73e463 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Naming_Loader.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Naming_Loader.h @@ -28,22 +28,22 @@ class TAO_Naming_Export TAO_Naming_Loader : public TAO_Object_Loader { public: - // Constructor + /// Constructor TAO_Naming_Loader (void); - // Destructor + /// Destructor ~TAO_Naming_Loader (void); - // Called by the Service Configurator framework to initialize the - // Event Service. Defined in <ace/Service_Config.h> + /// Called by the Service Configurator framework to initialize the + /// Event Service. Defined in <ace/Service_Config.h> virtual int init (int argc, ACE_TCHAR *argv[]); - // Called by the Service Configurator framework to remove the - // Event Service. Defined in <ace/Service_Config.h> + /// Called by the Service Configurator framework to remove the + /// Event Service. Defined in <ace/Service_Config.h> virtual int fini (void); - // This function call initializes the Naming Service given a reference to the - // ORB and the command line parameters. + /// This function call initializes the Naming Service given a reference to the + /// ORB and the command line parameters. virtual CORBA::Object_ptr create_object (CORBA::ORB_ptr orb, int argc, ACE_TCHAR *argv[] @@ -52,13 +52,12 @@ public: protected: + /// Instance of the TAO_Naming_Server TAO_Naming_Server naming_server_; - // Instance of the TAO_Naming_Server private: - -ACE_UNIMPLEMENTED_FUNC (TAO_Naming_Loader (const TAO_Naming_Loader &)) -ACE_UNIMPLEMENTED_FUNC (TAO_Naming_Loader &operator = (const TAO_Naming_Loader &)) + ACE_UNIMPLEMENTED_FUNC (TAO_Naming_Loader (const TAO_Naming_Loader &)) + ACE_UNIMPLEMENTED_FUNC (TAO_Naming_Loader &operator = (const TAO_Naming_Loader &)) }; ACE_FACTORY_DECLARE (TAO_Naming, TAO_Naming_Loader) diff --git a/TAO/orbsvcs/orbsvcs/Naming/Naming_Service_Container.h b/TAO/orbsvcs/orbsvcs/Naming/Naming_Service_Container.h index c73decb05fd..d5dec5b78db 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Naming_Service_Container.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Naming_Service_Container.h @@ -1,17 +1,14 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Naming_Service_Container.h -// -// = AUTHOR -// Bruce Trask <trask_b@ociweb.com> -// -// ============================================================================ +//============================================================================= +/** + * @file Naming_Service_Container.h + * + * $Id$ + * + * @author Bruce Trask <trask_b@ociweb.com> + */ +//============================================================================= + #ifndef NS_CONTAINER_H @@ -35,11 +32,14 @@ template <class T> class ACE_Unbounded_List; template <class T> class ACE_Unbounded_List_Iterator; +/** + * @class ACE_NS_Node + * + * @brief Implementation element in a Queue, List, and Stack. + */ template<class T> class ACE_NS_Node { - // = TITLE - // Implementation element in a Queue, List, and Stack. public: friend class ACE_Unbounded_List<T>; friend class ACE_Unbounded_List_Iterator<T>; @@ -47,8 +47,8 @@ public: # if ! defined (ACE_HAS_BROKEN_NOOP_DTORS) + /// This isn't necessary, but it keeps some compilers happy. ~ACE_NS_Node (void); - // This isn't necessary, but it keeps some compilers happy. # endif /* ! defined (ACE_HAS_BROKEN_NOOP_DTORS) */ private: @@ -57,83 +57,88 @@ private: ACE_NS_Node (ACE_NS_Node<T> *n = 0, int = 0); ACE_NS_Node (const ACE_NS_Node<T> &n); + /// Pointer to next element in the list of <ACE_NS_Node>s. ACE_NS_Node<T> *next_; - // Pointer to next element in the list of <ACE_NS_Node>s. + /// Current value of the item in this node. T item_; - // Current value of the item in this node. }; +/** + * @class ACE_Unbounded_List_Iterator + * + * @brief Implement an iterator over an unbounded List. + */ template <class T> class ACE_Unbounded_List_Iterator { - // = TITLE - // Implement an iterator over an unbounded List. public: // = Initialization method. ACE_Unbounded_List_Iterator (ACE_Unbounded_List<T> &s, int end = 0); // = Iteration methods. + /// Pass back the <next_item> that hasn't been seen in the List. + /// Returns 0 when all items have been seen, else 1. int next (T *&next_item); - // Pass back the <next_item> that hasn't been seen in the List. - // Returns 0 when all items have been seen, else 1. + /// Move forward by one element in the List. Returns 0 when all the + /// items in the List have been seen, else 1. int advance (void); - // Move forward by one element in the List. Returns 0 when all the - // items in the List have been seen, else 1. + /// Move to the first element in the List. Returns 0 if the + /// List is empty, else 1. int first (void); - // Move to the first element in the List. Returns 0 if the - // List is empty, else 1. + /// Returns 1 when all items have been seen, else 0. int done (void) const; - // Returns 1 when all items have been seen, else 0. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. // = STL styled iteration, compare, and reference functions. + /// Postfix advance. ACE_Unbounded_List_Iterator<T> operator++ (int); - // Postfix advance. + /// Prefix advance. ACE_Unbounded_List_Iterator<T>& operator++ (void); - // Prefix advance. + /// Returns a reference to the interal element <this> is pointing to. T& operator* (void); - // Returns a reference to the interal element <this> is pointing to. + /// Check if two iterators point to the same position int operator== (const ACE_Unbounded_List_Iterator<T> &) const; int operator!= (const ACE_Unbounded_List_Iterator<T> &) const; - // Check if two iterators point to the same position + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Pointer to the current node in the iteration. ACE_NS_Node<T> *current_; - // Pointer to the current node in the iteration. + /// Pointer to the set we're iterating over. ACE_Unbounded_List<T> *set_; - // Pointer to the set we're iterating over. }; +/** + * @class ACE_Unbounded_List + * + * @brief Implement a simple unordered set of <T> of unbounded size. + * + * This implementation of an unordered set uses a circular + * linked list with a dummy node. This implementation does not + * allow duplicates, but it maintains FIFO ordering of insertions. + */ template <class T> class ACE_Unbounded_List { - // = TITLE - // Implement a simple unordered set of <T> of unbounded size. - // - // = DESCRIPTION - // This implementation of an unordered set uses a circular - // linked list with a dummy node. This implementation does not - // allow duplicates, but it maintains FIFO ordering of insertions. public: friend class ACE_Unbounded_List_Iterator<T>; @@ -142,74 +147,78 @@ public: typedef ACE_Unbounded_List_Iterator<T> iterator; // = Initialization and termination methods. + /// Constructor. Use user specified allocation strategy + /// if specified. ACE_Unbounded_List (ACE_Allocator *alloc = 0); - // Constructor. Use user specified allocation strategy - // if specified. + /// Copy constructor. ACE_Unbounded_List (const ACE_Unbounded_List<T> &); - // Copy constructor. + /// Assignment operator. void operator= (const ACE_Unbounded_List<T> &); - // Assignment operator. + /// Destructor. ~ACE_Unbounded_List (void); - // Destructor. // = Check boundary conditions. + /// Returns 1 if the container is empty, otherwise returns 0. int is_empty (void) const; - // Returns 1 if the container is empty, otherwise returns 0. + /// Returns 1 if the container is full, otherwise returns 0. int is_full (void) const; - // Returns 1 if the container is full, otherwise returns 0. // = Classic unordered set operations. + /** + * Insert <new_item> into the set (doesn't allow duplicates). + * Returns -1 if failures occur, 1 if item is already present, else + * 0. + */ int insert (const T &new_item); - // Insert <new_item> into the set (doesn't allow duplicates). - // Returns -1 if failures occur, 1 if item is already present, else - // 0. + /** + * Remove first occurrence of <item> from the set. Returns 0 if + * it removes the item, -1 if it can't find the item, and -1 if a + * failure occurs. + */ int remove (const T &item); - // Remove first occurrence of <item> from the set. Returns 0 if - // it removes the item, -1 if it can't find the item, and -1 if a - // failure occurs. + /// Size of the set. size_t size (void) const; - // Size of the set. + /// Dump the state of an object. void dump (void) const; - // Dump the state of an object. + /// Reset the <ACE_Unbounded_List> to be empty. void reset (void); - // Reset the <ACE_Unbounded_List> to be empty. // = STL-styled unidirectional iterator factory. ACE_Unbounded_List_Iterator<T> begin (void); ACE_Unbounded_List_Iterator<T> end (void); + /// Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - // Declare the dynamic allocation hooks. private: + /// Insert <item> at the tail of the set (doesn't check for + /// duplicates). int insert_tail (const T &item); - // Insert <item> at the tail of the set (doesn't check for - // duplicates). + /// Delete all the nodes in the List. void delete_nodes (void); - // Delete all the nodes in the List. + /// Copy nodes into this set. void copy_nodes (const ACE_Unbounded_List<T> &); - // Copy nodes into this set. + /// Head of the linked list of NS_Nodes. ACE_NS_Node<T> *head_; - // Head of the linked list of NS_Nodes. + /// Current size of the set. size_t cur_size_; - // Current size of the set. + /// Allocation strategy of the set. ACE_Allocator *allocator_; - // Allocation strategy of the set. }; diff --git a/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.h b/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.h index 52799feefdb..87659787e54 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.h @@ -1,22 +1,20 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// TAO/orbsvcs/Naming_Service -// -// = FILENAME -// Naming_Utils.h -// -// = DESCRIPTION -// Implement wrappers useful to Naming Service clients and servers. -// -// = AUTHORS -// Nagarajan Surendran (naga@cs.wustl.edu), Matt Braun -// <mjb2@cs.wustl.edu>, and Douglas C. Schmidt <schmidt@cs.wustl.edu>. -// -// ============================================================================ + +//============================================================================= +/** + * @file Naming_Utils.h + * + * $Id$ + * + * Implement wrappers useful to Naming Service clients and servers. + * + * + * @author Nagarajan Surendran (naga@cs.wustl.edu) + * @author Matt Braun <mjb2@cs.wustl.edu> + * @author and Douglas C. Schmidt <schmidt@cs.wustl.edu>. + */ +//============================================================================= + #ifndef TAO_NAMING_UTILS_H #define TAO_NAMING_UTILS_H @@ -31,38 +29,53 @@ // Forward decl; class TAO_Persistent_Context_Index; +/** + * @class TAO_Naming_Server + * + * @brief Defines a wrapper class that holds the root Naming Context. + * + * This class either finds an existing Naming Service (if the + * <resolve_for_existing_naming_service> flag is set) or creates + * one (if <resolve_for_existing_naming_service> flag isn't set or + * Naming Service was not found). This class also defines the + * operator-> so that <NamingContext> functions like <bind>, + * <unbind> .. can be called directly on a <TAO_Naming_Server> + * object, and be forwareded to the root Naming Context. + * This class is intended to simplify + * programs that want to play the role of a Naming Service + * server. To simplify programs that want to play the role of + * Naming Service clients, use <TAO_Naming_Client>. + * If a Naming Service is created locally, a TAO_IOR_Multicast + * event handler is created and installed on the ORB's reactor. + * This event handler allows other clients on the network to + * discover and use this Naming Service. + * Event handler listens on a multicast port for messages from + * clients looking for a Naming Service, and sends back the ior + * of the root Naming Context. For more information on how this + * bootstraping through a multicast process works, check out + * orbsvcs/orbsvcs/TAO_IOR_Multicast.*, implementation of + * <resolve_initial_references>, and orbsvcs/Naming/README. + */ class TAO_Naming_Export TAO_Naming_Server { - // = TITLE - // Defines a wrapper class that holds the root Naming Context. - // - // = DESCRIPTION - // This class either finds an existing Naming Service (if the - // <resolve_for_existing_naming_service> flag is set) or creates - // one (if <resolve_for_existing_naming_service> flag isn't set or - // Naming Service was not found). This class also defines the - // operator-> so that <NamingContext> functions like <bind>, - // <unbind> .. can be called directly on a <TAO_Naming_Server> - // object, and be forwareded to the root Naming Context. - // This class is intended to simplify - // programs that want to play the role of a Naming Service - // server. To simplify programs that want to play the role of - // Naming Service clients, use <TAO_Naming_Client>. - // - // If a Naming Service is created locally, a TAO_IOR_Multicast - // event handler is created and installed on the ORB's reactor. - // This event handler allows other clients on the network to - // discover and use this Naming Service. - // Event handler listens on a multicast port for messages from - // clients looking for a Naming Service, and sends back the ior - // of the root Naming Context. For more information on how this - // bootstraping through a multicast process works, check out - // orbsvcs/orbsvcs/TAO_IOR_Multicast.*, implementation of - // <resolve_initial_references>, and orbsvcs/Naming/README. public: + /// Default constructor. TAO_Naming_Server (void); - // Default constructor. + /** + * Constructor. Attempts to find an existing Naming Service if + * <resolve_for_existing_naming_service> is set to true. If it is + * false, or no Naming Service was found during a <timeout> period, + * create the Naming Service in this process. If creating the + * Naming Service locally, make the root context of size + * <context_size>, register it under the <poa>, and make the Naming + * Service persistent if <persistence_location> is not 0. + * (<persistence_location> specifies name of the file to use for + * persistent storage, <base_addr> specifies the address used for + * memory mapping <persistent_location> file). + * If <enable_multicast> is not zero then the service will respond + * to multicast location queries. + */ TAO_Naming_Server (CORBA::ORB_ptr orb, PortableServer::POA_ptr poa, size_t context_size = ACE_DEFAULT_MAP_SIZE, @@ -72,19 +85,21 @@ public: void *base_addr = TAO_NAMING_BASE_ADDR, int enable_multicast = 1, int use_storable_context = 0); - // Constructor. Attempts to find an existing Naming Service if - // <resolve_for_existing_naming_service> is set to true. If it is - // false, or no Naming Service was found during a <timeout> period, - // create the Naming Service in this process. If creating the - // Naming Service locally, make the root context of size - // <context_size>, register it under the <poa>, and make the Naming - // Service persistent if <persistence_location> is not 0. - // (<persistence_location> specifies name of the file to use for - // persistent storage, <base_addr> specifies the address used for - // memory mapping <persistent_location> file). - // If <enable_multicast> is not zero then the service will respond - // to multicast location queries. + /** + * Initializer. Attempts to find an existing Naming Service if + * <resolve_for_existing_naming_service> is set to true. If it is + * false, or no Naming Service was found during a <timeout> period, + * create the Naming Service in this process. If creating the + * Naming Service locally, make the root context of size + * <context_size>, register it under the <poa>, and make the Naming + * Service persistent if <persistence_location> is not 0. + * (<persistence_location> specifies name of the file to use for + * persistent storage, <base_addr> specifies the address used for + * memory mapping <persistent_location> file). + * If <enable_multicast> is not zero then the service will respond + * to multicast location queries. + */ int init (CORBA::ORB_ptr orb, PortableServer::POA_ptr poa, size_t context_size = ACE_DEFAULT_MAP_SIZE, @@ -94,38 +109,36 @@ public: void *base_addr = TAO_NAMING_BASE_ADDR, int enable_multicast = 1, int use_storable_context = 0); - // Initializer. Attempts to find an existing Naming Service if - // <resolve_for_existing_naming_service> is set to true. If it is - // false, or no Naming Service was found during a <timeout> period, - // create the Naming Service in this process. If creating the - // Naming Service locally, make the root context of size - // <context_size>, register it under the <poa>, and make the Naming - // Service persistent if <persistence_location> is not 0. - // (<persistence_location> specifies name of the file to use for - // persistent storage, <base_addr> specifies the address used for - // memory mapping <persistent_location> file). - // If <enable_multicast> is not zero then the service will respond - // to multicast location queries. + /// Initialize the Naming Service with the command line arguments and + /// the ORB. int init_with_orb (int argc, ACE_TCHAR *argv [], CORBA::ORB_ptr orb); - // Initialize the Naming Service with the command line arguments and - // the ORB. + /// Destroy the child POA created in <init_with_orb> int fini (void); - // Destroy the child POA created in <init_with_orb> + /// Destructor. ~TAO_Naming_Server (void); - // Destructor. + /// Returns the IOR of the naming service. char * naming_service_ior (void); - // Returns the IOR of the naming service. + /// Returns a <NamingContext_ptr> for the root Naming Context. CosNaming::NamingContext_ptr operator-> (void) const; - // Returns a <NamingContext_ptr> for the root Naming Context. protected: + /** + * Helper method: create Naming Service locally. + * Make the root context of size + * <context_size>, register it under the <root_poa>, and make the Naming + * Service persistent if <persistence_location> is not 0. + * (<persistence_location> specifies name of the file to use for + * persistent storage). + * If <enable_multicast> is not zero then the service will respond + * to multicast location queries. + */ int init_new_naming (CORBA::ORB_ptr orb, PortableServer::POA_ptr root_poa, const ACE_TCHAR *persistence_location, @@ -133,110 +146,112 @@ protected: size_t context_size, int enable_multicast, int use_storable_context); - // Helper method: create Naming Service locally. - // Make the root context of size - // <context_size>, register it under the <root_poa>, and make the Naming - // Service persistent if <persistence_location> is not 0. - // (<persistence_location> specifies name of the file to use for - // persistent storage). - // If <enable_multicast> is not zero then the service will respond - // to multicast location queries. + /// parses the arguments. int parse_args (int argc, ACE_TCHAR *argv[]); - // parses the arguments. + /// Root NamingContext_ptr. CosNaming::NamingContext_var naming_context_; - // Root NamingContext_ptr. + /// The ior_multicast event handler. TAO_IOR_Multicast *ior_multicast_; - // The ior_multicast event handler. + /// The IOR string of the root naming context. CORBA::String_var naming_service_ior_; - // The IOR string of the root naming context. + /** + * Pointer to the object used to create/initialize + * the Naming Service when local persistent Naming Service is + * desired. + */ TAO_Persistent_Context_Index *context_index_; - // Pointer to the object used to create/initialize - // the Naming Service when local persistent Naming Service is - // desired. + /// The ORB CORBA::ORB_var orb_; - // The ORB + /// The Root POA. PortableServer::POA_var root_poa_; - // The Root POA. + /// The Naming Service POA. PortableServer::POA_var ns_poa_; - // The Naming Service POA. + /// File to output the Naming Service IOR. FILE *ior_output_file_; - // File to output the Naming Service IOR. + /// File to output the process id. const ACE_TCHAR *pid_file_name_; - // File to output the process id. + /** + * Size of the hash_table allocated upon the creation of the Naming + * Service context (if one is created). Note: all the contexts + * created under the given context will use the same size for their + * initial hash table allocations. + */ size_t context_size_; - // Size of the hash_table allocated upon the creation of the Naming - // Service context (if one is created). Note: all the contexts - // created under the given context will use the same size for their - // initial hash table allocations. + /// Path to the file to be used to store/read in Naming Service + /// persistent state. const ACE_TCHAR *persistence_file_name_; - // Path to the file to be used to store/read in Naming Service - // persistent state. + /// Address to be used for memory mapping Naming Service state file, + /// identified by the <persistence_file_name_>. void *base_address_; - // Address to be used for memory mapping Naming Service state file, - // identified by the <persistence_file_name_>. + /// After how long the server should stop listening to requests (in + /// seconds). size_t time_; - // After how long the server should stop listening to requests (in - // seconds). + /// If not zero multicast is enabled. int multicast_; - // If not zero multicast is enabled. + /// If not zero use flat file persistence int use_storable_context_; - // If not zero use flat file persistence }; +/** + * @class TAO_Naming_Client + * + * @brief This class is intended to simplify programs that want to play + * the role of Naming Service clients. + * + * Wrapper class that locates the root Naming Context. It also + * defines the operator-> so that <NamingContext> functions like + * <resolve>, etc. can be directly called on a + * <TAO_Naming_Client> object, and will be forwarded to the root + * Naming Context. + */ class TAO_Naming_Export TAO_Naming_Client { - // = TITLE - // This class is intended to simplify programs that want to play - // the role of Naming Service clients. - // - // = DESCRIPTION - // Wrapper class that locates the root Naming Context. It also - // defines the operator-> so that <NamingContext> functions like - // <resolve>, etc. can be directly called on a - // <TAO_Naming_Client> object, and will be forwarded to the root - // Naming Context. public: // = Initialization and termination methods. + /// Default constructor. TAO_Naming_Client (void); - // Default constructor. + /** + * Look for a Naming Service for a period of <timeout> using + * <resolve_initial_references>. Return 0 if Naming Service is + * successfully located, and -1 on failure. + */ int init (CORBA::ORB_ptr orb, ACE_Time_Value *timeout = 0); - // Look for a Naming Service for a period of <timeout> using - // <resolve_initial_references>. Return 0 if Naming Service is - // successfully located, and -1 on failure. + /// Destructor. ~TAO_Naming_Client (void); - // Destructor. + /// Returns a pointer to the root Naming Context. CosNaming::NamingContext_ptr operator-> (void) const; - // Returns a pointer to the root Naming Context. + /** + * Returns a pointer to the root Naming Context. This ptr is + * duplicated via <_duplicate> so that it can be stored into a + * <*_var>. + */ CosNaming::NamingContext_ptr get_context (void) const; - // Returns a pointer to the root Naming Context. This ptr is - // duplicated via <_duplicate> so that it can be stored into a - // <*_var>. protected: + /// Reference to the root Naming Context. CosNaming::NamingContext_var naming_context_; - // Reference to the root Naming Context. }; #include "ace/post.h" diff --git a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h index 57b57aa85e8..f49345d0f10 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Persistent_Context_Index.h -// -// = AUTHOR -// Marina Spivak <marina@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Persistent_Context_Index.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + */ +//============================================================================= + #ifndef TAO_PERSISTENT_CONTEXT_INDEX_H #define TAO_PERSISTENT_CONTEXT_INDEX_H @@ -23,132 +20,144 @@ #include "nsconf.h" #include "tao/PortableServer/PortableServer.h" +/** + * @class TAO_Persistent_Context_Index + * + * @brief This class facilitates implementation of Persistent + * Naming Service. It keeps track, centrally, of several pieces of + * info for each Persistent Naming Context, allowing to perform the + * initialization necessary for each Naming Context to + * restore the state of the Naming Service from persistent storage + * on server start-up. + * + * This class creates a memory-mapped file, allocates a hash + * table from that file, and uses the hash table to store POA id, + * and table and counter pointers for each Persistent Naming + * Context. There are methods for adding and deleting entries + * from this hash table as new Persistent Naming Contexts are + * created and old ones are destroyed. This hash table + * facilitates Persistent Naming Context servant initialization + * upon Naming Server start-up. + */ class TAO_Naming_Export TAO_Persistent_Context_Index { - // = TITLE - // This class facilitates implementation of Persistent - // Naming Service. It keeps track, centrally, of several pieces of - // info for each Persistent Naming Context, allowing to perform the - // initialization necessary for each Naming Context to - // restore the state of the Naming Service from persistent storage - // on server start-up. - // - // = DESCRIPTION - // This class creates a memory-mapped file, allocates a hash - // table from that file, and uses the hash table to store POA id, - // and table and counter pointers for each Persistent Naming - // Context. There are methods for adding and deleting entries - // from this hash table as new Persistent Naming Contexts are - // created and old ones are destroyed. This hash table - // facilitates Persistent Naming Context servant initialization - // upon Naming Server start-up. public: // = Some typedefs for convenience. + /// Hash map in which we will store info about each Persistent Naming Context. typedef ACE_Hash_Map_With_Allocator<TAO_Persistent_Index_ExtId, TAO_Persistent_Index_IntId> CONTEXT_INDEX; - // Hash map in which we will store info about each Persistent Naming Context. + /// Hash map used by Persistent Naming Context to keep its state. typedef ACE_Hash_Map_With_Allocator<TAO_Persistent_ExtId, TAO_Persistent_IntId> CONTEXT; - // Hash map used by Persistent Naming Context to keep its state. + /// Allocator we will be using to make the Naming Service persistent. typedef ACE_Allocator_Adapter <ACE_Malloc <ACE_MMAP_MEMORY_POOL, TAO_SYNCH_MUTEX> > ALLOCATOR; - // Allocator we will be using to make the Naming Service persistent. // = Initialization and termination methods. + /// Constructor. TAO_Persistent_Context_Index (CORBA::ORB_ptr orb, PortableServer::POA_ptr poa); - // Constructor. + /** + * Create ACE_Allocator, open/create memory-mapped file with the + * specified file name/base address. Find or allocate <index_>. + * Return 0 on success or -1 on failure. + */ int open (const ACE_TCHAR *file_name, void * base_address = TAO_NAMING_BASE_ADDR); - // Create ACE_Allocator, open/create memory-mapped file with the - // specified file name/base address. Find or allocate <index_>. - // Return 0 on success or -1 on failure. + /** + * If <index_> contains no entries (i.e., was just created), create + * a root Persistent Naming Context servant with table of size + * <context_size>, and make an entry for it + * in the <index_>. If <index_> contains entries, create a + * Persistent Naming Context servant for each entry. Return 0 on + * success and -1 on failure. + */ int init (size_t context_size); - // If <index_> contains no entries (i.e., was just created), create - // a root Persistent Naming Context servant with table of size - // <context_size>, and make an entry for it - // in the <index_>. If <index_> contains entries, create a - // Persistent Naming Context servant for each entry. Return 0 on - // success and -1 on failure. + /** + * Destructor. The memory mapped file that was opened/created is + * not deleted, since we want it to keep the state of the Naming + * Service until the next run. + */ ~TAO_Persistent_Context_Index (void); - // Destructor. The memory mapped file that was opened/created is - // not deleted, since we want it to keep the state of the Naming - // Service until the next run. // = Methods for adding/removing entries. + /** + * Create an entry for a Persistent Naming Context in <index_>, + * i.e., a context with <poa_id>, <counter> and <hash_map> has just + * been created, and is registering with us. + */ int bind (const char *poa_id, ACE_UINT32 *&counter, CONTEXT *hash_map); - // Create an entry for a Persistent Naming Context in <index_>, - // i.e., a context with <poa_id>, <counter> and <hash_map> has just - // been created, and is registering with us. + /// Remove an entry for the Persistent Naming Context with <poa_id> + /// from <index_> (i.e., this context has just been destroyed). int unbind (const char *poa_id); - // Remove an entry for the Persistent Naming Context with <poa_id> - // from <index_> (i.e., this context has just been destroyed). // = Accessors. + /// Return allocator. ACE_Allocator *allocator (void); - // Return allocator. + /// Return orb pointer. CORBA::ORB_ptr orb (void); - // Return orb pointer. + /// Return a pointer to the root Naming Context (returns a copy - must be + /// deallocated by the user). CosNaming::NamingContext_ptr root_context (void); - // Return a pointer to the root Naming Context (returns a copy - must be - // deallocated by the user). private: + /// Helper for the <init> method. Iterates over <index_>, and + /// creates a servant for each entry. int recreate_all (void); - // Helper for the <init> method. Iterates over <index_>, and - // creates a servant for each entry. + /// Helper for the <open> method. int create_index (void); - // Helper for the <open> method. + /// Helper for <create_index> method: places hash table into an + /// allocated space. int create_index_helper (void *buffer); - // Helper for <create_index> method: places hash table into an - // allocated space. + /// Lock to prevent multiple threads from modifying entries in the + /// <index_> simultanneously. TAO_SYNCH_MUTEX lock_; - // Lock to prevent multiple threads from modifying entries in the - // <index_> simultanneously. + /** + * Allocator that deals out memory from a memory-mapped file. We + * use it here, and in TAO_Persistent_Naming_Context, whenever we + * deal with data that should be kept in persistent store. + */ ALLOCATOR *allocator_; - // Allocator that deals out memory from a memory-mapped file. We - // use it here, and in TAO_Persistent_Naming_Context, whenever we - // deal with data that should be kept in persistent store. + /// Hash map where we keep entries for all Persistent Naming + /// Contexts. CONTEXT_INDEX *index_; - // Hash map where we keep entries for all Persistent Naming - // Contexts. + /// Name of the memory-mapped file used by <allocator_>. const ACE_TCHAR *index_file_; - // Name of the memory-mapped file used by <allocator_>. + /// Base address for the memory-mapped file. void *base_address_; - // Base address for the memory-mapped file. + /// ORB. We use it for several object_to_string conversions, and + /// keep it around for Persistent Naming Contexts' use. CORBA::ORB_var orb_; - // ORB. We use it for several object_to_string conversions, and - // keep it around for Persistent Naming Contexts' use. + /// POA under which to register Persistent Naming Context servants + /// during start-up. PortableServer::POA_var poa_; - // POA under which to register Persistent Naming Context servants - // during start-up. + /// The reference to the root Naming Context. CosNaming::NamingContext_var root_context_; - // The reference to the root Naming Context. }; #include "ace/post.h" diff --git a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.h b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.h index 643c20db0e3..ee4a6a10dec 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Persistent_Entries.h -// -// = AUTHOR -// Marina Spivak <marina@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Persistent_Entries.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + */ +//============================================================================= + #ifndef TAO_PERSISTENT_ENTRIES_H #define TAO_PERSISTENT_ENTRIES_H @@ -27,103 +24,105 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_Persistent_IntId + * + * @brief Helper class for TAO_Persistent_Bindings_Map: unifies several + * data items, so they can be stored together as a <value> + * for a <key> in a hash table holding the state of a Persistent + * Naming Context. + * + * This class holds a strigified IOR and a binding type, so + * they can be stored together as a <value> for a <key> in a + * hash table holding the state of a Persistent Naming Context. + * Memory for the ior isn't allocated/deallocated, this class just + * copies a pointer. + */ class TAO_Naming_Export TAO_Persistent_IntId { - // = TITLE - // Helper class for TAO_Persistent_Bindings_Map: unifies several - // data items, so they can be stored together as a <value> - // for a <key> in a hash table holding the state of a Persistent - // Naming Context. - // - // = DESCRIPTION - // This class holds a strigified IOR and a binding type, so - // they can be stored together as a <value> for a <key> in a - // hash table holding the state of a Persistent Naming Context. - // - // Memory for the ior isn't allocated/deallocated, this class just - // copies a pointer. public: // = Initialization and termination methods. + /// Constructor. TAO_Persistent_IntId (void); - // Constructor. + /// Constructor. TAO_Persistent_IntId (char * obj_ref, CosNaming::BindingType type /* = CosNaming::nobject */); - // Constructor. + /// Copy constructor. TAO_Persistent_IntId (const TAO_Persistent_IntId & rhs); - // Copy constructor. + /// Destructor. ~TAO_Persistent_IntId (void); - // Destructor. + /// Assignment operator. void operator= (const TAO_Persistent_IntId & rhs); - // Assignment operator. // = Data members. + /// Stringified IOR to be stored in a Persistent Naming Context. const char *ref_; - // Stringified IOR to be stored in a Persistent Naming Context. + /// Binding type for <ref_>. CosNaming::BindingType type_; - // Binding type for <ref_>. }; +/** + * @class TAO_Persistent_ExtId + * + * @brief Helper class for TAO_Persistent_Bindings_Map: unifies several + * data items, so they can be stored together as a <key> + * for a <value> in a hash table holding the state of a Persistent + * Naming Context. + * + * This class holds id and kind strings, so + * they can be stored together as a <key> for a <value> in a + * hash table holding the state of a Persistent Naming Context. + * Memory for id and kind isn't allocated/deallocated, this + * class just copies pointers. + */ class TAO_Naming_Export TAO_Persistent_ExtId { - // = TITLE - // Helper class for TAO_Persistent_Bindings_Map: unifies several - // data items, so they can be stored together as a <key> - // for a <value> in a hash table holding the state of a Persistent - // Naming Context. - // - // = DESCRIPTION - // This class holds id and kind strings, so - // they can be stored together as a <key> for a <value> in a - // hash table holding the state of a Persistent Naming Context. - // - // Memory for id and kind isn't allocated/deallocated, this - // class just copies pointers. public: // = Initialization and termination methods. + /// Constructor. TAO_Persistent_ExtId (void); - // Constructor. + /// Constructor. TAO_Persistent_ExtId (const char *id, const char *kind); - // Constructor. + /// Copy constructor. TAO_Persistent_ExtId (const TAO_Persistent_ExtId & rhs); - // Copy constructor. + /// Destructor. ~TAO_Persistent_ExtId (void); - // Destructor. // = Assignment and comparison methods. + /// Assignment operator (does copy memory). void operator= (const TAO_Persistent_ExtId & rhs); - // Assignment operator (does copy memory). + /// Equality comparison operator (must match both id_ and kind_). int operator== (const TAO_Persistent_ExtId &rhs) const; - // Equality comparison operator (must match both id_ and kind_). + /// Inequality comparison operator. int operator!= (const TAO_Persistent_ExtId &rhs) const; - // Inequality comparison operator. + /// <hash> function is required in order for this class to be usable by + /// ACE_Hash_Map_Manager. u_long hash (void) const; - // <hash> function is required in order for this class to be usable by - // ACE_Hash_Map_Manager. // = Data members. + /// <id> portion of the name to be associated with some object + /// reference in a Persistent Naming Context. const char * id_; - // <kind> portion of the name to be associated with some object - // reference in a Persistent Naming Context. + /// <kind> portion of the name to be associated with some object + /// reference in a Persistent Naming Context. const char * kind_; - // <id> portion of the name to be associated with some object - // reference in a Persistent Naming Context. // Accessors. @@ -131,98 +130,100 @@ public: const char * kind (void); }; +/** + * @class TAO_Persistent_Index_IntId + * + * @brief Helper class for TAO_Persistent_Context_Index: unifies several + * data items, so they can be stored together as a <value> + * for a <key> in a hash table holding the state of a Persistent + * Context Index. (Persistent Context Index is like directory + * that stores info about every active Naming Context). + * + * This class holds a counter and a hash map pointers, so + * they can be stored together as a <value> for a <key> in a + * hash table holding the state of a Persistent Context Index. + */ class TAO_Naming_Export TAO_Persistent_Index_IntId { - // = TITLE - // Helper class for TAO_Persistent_Context_Index: unifies several - // data items, so they can be stored together as a <value> - // for a <key> in a hash table holding the state of a Persistent - // Context Index. (Persistent Context Index is like directory - // that stores info about every active Naming Context). - // - // = DESCRIPTION - // This class holds a counter and a hash map pointers, so - // they can be stored together as a <value> for a <key> in a - // hash table holding the state of a Persistent Context Index. - // public: // = Initialization and termination methods. + /// Constructor. TAO_Persistent_Index_IntId (void); - // Constructor. + /// Constructor. TAO_Persistent_Index_IntId (ACE_UINT32 *counter, ACE_Hash_Map_With_Allocator<TAO_Persistent_ExtId, TAO_Persistent_IntId> * hash_map); - // Constructor. + /// Copy constructor. TAO_Persistent_Index_IntId (const TAO_Persistent_Index_IntId & rhs); - // Copy constructor. + /// Destructor. ~TAO_Persistent_Index_IntId (void); - // Destructor. + /// Assignment operator (does copy memory). void operator= (const TAO_Persistent_Index_IntId & rhs); - // Assignment operator (does copy memory). // = Data members. + /// Pointer to a Persistent Naming Context's counter. ACE_UINT32 *counter_; - // Pointer to a Persistent Naming Context's counter. + /// Pointer to a Persistent Naming Context's hash map. ACE_Hash_Map_With_Allocator<TAO_Persistent_ExtId, TAO_Persistent_IntId> * hash_map_; - // Pointer to a Persistent Naming Context's hash map. }; +/** + * @class TAO_Persistent_Index_ExtId + * + * @brief Helper class for TAO_Persistent_Context_Index: holds + * Persistent Naming Context POA id, so it can be stored as a <key> + * for a <value> in a hash table holding state of a Persistent + * Context Index. (Persistent Context Index is like directory + * that stores info about every active Naming Context). + * + * We need this wrapper class around the actual data because we must + * provide <hash> function for it to work with + * ACE_Hash_Map_Manager. + */ class TAO_Naming_Export TAO_Persistent_Index_ExtId { - // = TITLE - // Helper class for TAO_Persistent_Context_Index: holds - // Persistent Naming Context POA id, so it can be stored as a <key> - // for a <value> in a hash table holding state of a Persistent - // Context Index. (Persistent Context Index is like directory - // that stores info about every active Naming Context). - // - // = DESCRIPTION - // We need this wrapper class around the actual data because we must - // provide <hash> function for it to work with - // ACE_Hash_Map_Manager. - // public: // = Initialization and termination methods. + /// Constructor. TAO_Persistent_Index_ExtId (void); - // Constructor. + /// Constructor. TAO_Persistent_Index_ExtId (const char *poa_id); - // Constructor. + /// Copy constructor. TAO_Persistent_Index_ExtId (const TAO_Persistent_Index_ExtId & rhs); - // Copy constructor. + /// Destructor. ~TAO_Persistent_Index_ExtId (void); - // Destructor. // = Assignment and comparison methods. + /// Assignment operator (does copy memory). void operator= (const TAO_Persistent_Index_ExtId & rhs); - // Assignment operator (does copy memory). + /// Equality comparison operator (must match both id_ and kind_). int operator== (const TAO_Persistent_Index_ExtId &rhs) const; - // Equality comparison operator (must match both id_ and kind_). + /// Inequality comparison operator. int operator!= (const TAO_Persistent_Index_ExtId &rhs) const; - // Inequality comparison operator. + /// <hash> function is required in order for this class to be usable by + /// ACE_Hash_Map_Manager. u_long hash (void) const; - // <hash> function is required in order for this class to be usable by - // ACE_Hash_Map_Manager. // = Data member. + /// POA id to be associated with the rest of the info for some + /// Persistent Naming Context in the Persistent Context Index. const char * poa_id_; - // POA id to be associated with the rest of the info for some - // Persistent Naming Context in the Persistent Context Index. }; #include "ace/post.h" diff --git a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h index 970c52cad66..f37796083e1 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h @@ -1,17 +1,14 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Persistent_Naming_Context.h -// -// = AUTHOR -// Marina Spivak <marina@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Persistent_Naming_Context.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + */ +//============================================================================= + #ifndef TAO_PERSISTENT_NAMING_CONTEXT_H #define TAO_PERSISTENT_NAMING_CONTEXT_H @@ -21,220 +18,249 @@ #include "Persistent_Entries.h" #include "naming_export.h" +/** + * @class TAO_Persistent_Bindings_Map + * + * @brief Provides hash-table-based persistent storage for + * name to object bindings in a Naming Context. + * + * Wrapper on top of ACE_Hash_Map_With_Allocator (which is a wrapper + * around ACE_Hash_Map_Manager). Uses ACE_Allocator (allocating + * from persistent storage) to make bindings persistent and + * supports TAO_Bindings_Map interface. Used by TAO_Persistent_Naming_Context. + */ class TAO_Naming_Export TAO_Persistent_Bindings_Map : public TAO_Bindings_Map { - // = TITLE - // Provides hash-table-based persistent storage for - // name to object bindings in a Naming Context. - // - // = DESCRIPTION - // Wrapper on top of ACE_Hash_Map_With_Allocator (which is a wrapper - // around ACE_Hash_Map_Manager). Uses ACE_Allocator (allocating - // from persistent storage) to make bindings persistent and - // supports TAO_Bindings_Map interface. Used by TAO_Persistent_Naming_Context. public: + /// Underlying data structure - typedef for ease of use. typedef ACE_Hash_Map_With_Allocator<TAO_Persistent_ExtId, TAO_Persistent_IntId> HASH_MAP; - // Underlying data structure - typedef for ease of use. // = Initialization and termination methods. + /// Constructor. TAO_Persistent_Bindings_Map (CORBA::ORB_ptr orb); - // Constructor. + /// Allocate hash map of size <hash_map_size> from persistent storage + /// using the <alloc>. int open (size_t hash_map_size, ACE_Allocator *alloc); - // Allocate hash map of size <hash_map_size> from persistent storage - // using the <alloc>. + /// The hash map has already been preallocated for us. We just need + /// to set our data members take ownership of it. void set (HASH_MAP *map, ACE_Allocator *alloc); - // The hash map has already been preallocated for us. We just need - // to set our data members take ownership of it. + /// Destructor. Does not deallocate the hash map: if an instance of + /// this class goes out of scope, its hash_map remains in persistent storage. virtual ~TAO_Persistent_Bindings_Map (void); - // Destructor. Does not deallocate the hash map: if an instance of - // this class goes out of scope, its hash_map remains in persistent storage. + /** + * This method removes the hash map from persistent storage/frees up + * the memory. The hash map better be empty, since we are not + * cleaning up the insides. (We could add <close> to clean entries, + * but not the data inside the entries. + */ void destroy (void); - // This method removes the hash map from persistent storage/frees up - // the memory. The hash map better be empty, since we are not - // cleaning up the insides. (We could add <close> to clean entries, - // but not the data inside the entries. // = Accessor methods. + /// Get a pointer to the underlying hash map. HASH_MAP *map (void); - // Get a pointer to the underlying hash map. + /// Return the size of the underlying hash table. size_t total_size (void); - // Return the size of the underlying hash table. + /// Return the size of the underlying hash table. virtual size_t current_size (void); - // Return the size of the underlying hash table. // = Name bindings manipulation methods. + /** + * Add a binding with the specified parameters to the table. + * Return 0 on success and -1 on failure, 1 if there already is a + * binding with <id> and <kind>. + */ virtual int bind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type); - // Add a binding with the specified parameters to the table. - // Return 0 on success and -1 on failure, 1 if there already is a - // binding with <id> and <kind>. + /** + * Overwrite a binding containing <id> and <kind> (or create a new + * one if one doesn't exist) with the specified parameters. Return + * 0 or 1 on success. Return -1 or -2 on failure. (-2 is returned + * if the new and old bindings differ in type). + */ virtual int rebind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type); - // Overwrite a binding containing <id> and <kind> (or create a new - // one if one doesn't exist) with the specified parameters. Return - // 0 or 1 on success. Return -1 or -2 on failure. (-2 is returned - // if the new and old bindings differ in type). + /** + * Remove a binding containing <id> and <kind> from the table. + * Return 0 on success and -1 on failure. + */ virtual int unbind (const char * id, const char * kind); - // Remove a binding containing <id> and <kind> from the table. - // Return 0 on success and -1 on failure. + /** + * Find the binding containing <id> and <kind> in the table, and + * pass binding's type and object back to the caller by reference. + * Return 0 on success and -1 on failure. Note: a 'duplicated' object + * reference is assigned to <obj>, so the caller is responsible for + * its deallocation. + */ virtual int find (const char * id, const char * kind, CORBA::Object_ptr & obj, CosNaming::BindingType &type); - // Find the binding containing <id> and <kind> in the table, and - // pass binding's type and object back to the caller by reference. - // Return 0 on success and -1 on failure. Note: a 'duplicated' object - // reference is assigned to <obj>, so the caller is responsible for - // its deallocation. protected: + /** + * Helper to the <open> method. By isolating placement new into a + * separate method, we can deal with memory allocation failures more + * efficiently. If there is a problem in HASH_MAP constructor, we + * can clean up preallocated space. + */ int open_helper (size_t hash_table_size, void *buffer); - // Helper to the <open> method. By isolating placement new into a - // separate method, we can deal with memory allocation failures more - // efficiently. If there is a problem in HASH_MAP constructor, we - // can clean up preallocated space. + /// Helper: factors common code from <bind> and <rebind>. int shared_bind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type, int rebind); - // Helper: factors common code from <bind> and <rebind>. + /// Pointer to the allocator we use to make bindings persistent. ACE_Allocator *allocator_; - // Pointer to the allocator we use to make bindings persistent. + /// Pointer to the underlying hash map. HASH_MAP *map_; - // Pointer to the underlying hash map. + /// Pointer to the orb. We need it to do string/object conversions. CORBA::ORB_var orb_; - // Pointer to the orb. We need it to do string/object conversions. }; class TAO_Persistent_Context_Index; +/** + * @class TAO_Persistent_Naming_Context + * + * @brief This class plays a role of a 'ConcreteImplementor' in the + * Bridge pattern architecture of the CosNaming::NamingContext implementation. + * + * This class provides a persistent implementation of the + * NamingContext functionality, i.e., the state is preserved across + * process boundaries. Derives from TAO_Hash_Naming_Context and + * uses TAO_Persistent_Bindings_Map to store name to object bindings. + */ class TAO_Naming_Export TAO_Persistent_Naming_Context : public TAO_Hash_Naming_Context { - // = TITLE - // This class plays a role of a 'ConcreteImplementor' in the - // Bridge pattern architecture of the CosNaming::NamingContext implementation. - // - // = DESCRIPTION - // This class provides a persistent implementation of the - // NamingContext functionality, i.e., the state is preserved across - // process boundaries. Derives from TAO_Hash_Naming_Context and - // uses TAO_Persistent_Bindings_Map to store name to object bindings. - // public: + /// Underlying data structure - typedef for ease of use. typedef TAO_Persistent_Bindings_Map::HASH_MAP HASH_MAP; - // Underlying data structure - typedef for ease of use. // = Initialization and termination methods. + /// Constructor. MUST be followed up by <init> to allocate the + /// underlying data structure from persistent storage! TAO_Persistent_Naming_Context (PortableServer::POA_ptr poa, const char *poa_id, TAO_Persistent_Context_Index *context_index); - // Constructor. MUST be followed up by <init> to allocate the - // underlying data structure from persistent storage! + /// Allocate the underlying data structure from persistent storage. + /// Returns 0 on success and -1 on failure. int init (size_t hash_table_size = ACE_DEFAULT_MAP_SIZE); - // Allocate the underlying data structure from persistent storage. - // Returns 0 on success and -1 on failure. + /** + * Constructor that takes in preallocated data structure and takes + * ownership of it. This constructor is for 'recreating' servants + * from persistent state. + */ TAO_Persistent_Naming_Context (PortableServer::POA_ptr poa, const char *poa_id, TAO_Persistent_Context_Index *context_index, HASH_MAP * map, ACE_UINT32 *counter); - // Constructor that takes in preallocated data structure and takes - // ownership of it. This constructor is for 'recreating' servants - // from persistent state. + /// Destructor. virtual ~TAO_Persistent_Naming_Context (void); - // Destructor. // = Utility methods. + /** + * This utility method factors out the code needed to create a new + * Persistent Naming Context servant and activate it under the + * specified POA with the specified id. This function is static so + * that the code can be used, both from inside the class (e.g., <new_context>), + * and from outside (e.g., Naming_Utils.cpp). + */ static CosNaming::NamingContext_ptr make_new_context (PortableServer::POA_ptr poa, const char *poa_id, size_t context_size, TAO_Persistent_Context_Index *ind ACE_ENV_ARG_DECL); - // This utility method factors out the code needed to create a new - // Persistent Naming Context servant and activate it under the - // specified POA with the specified id. This function is static so - // that the code can be used, both from inside the class (e.g., <new_context>), - // and from outside (e.g., Naming_Utils.cpp). // = Methods not implemented in TAO_Hash_Naming_Context. + /** + * This operation returns a new naming context implemented by the + * same naming server in which the operation was invoked. The + * context is not bound. + */ virtual CosNaming::NamingContext_ptr new_context (ACE_ENV_SINGLE_ARG_DECL); - // This operation returns a new naming context implemented by the - // same naming server in which the operation was invoked. The - // context is not bound. + /** + * Returns at most the requested number of bindings <how_many> in + * <bl>. If the naming context contains additional bindings, they + * are returned with a BindingIterator. In the naming context does + * not contain any additional bindings <bi> returned as null. + */ virtual void list (CORBA::ULong how_many, CosNaming::BindingList_out &bl, CosNaming::BindingIterator_out &bi ACE_ENV_ARG_DECL); - // Returns at most the requested number of bindings <how_many> in - // <bl>. If the naming context contains additional bindings, they - // are returned with a BindingIterator. In the naming context does - // not contain any additional bindings <bi> returned as null. protected: + /** + * Set <destroyed_> flag (inherited from TAO_Hash_Naming_Context) to + * <level>. Legal values for <destroyed_> are 0, 1, and 2. The + * values specify the extent of cleanup that should take place in the + * context's destructor: + * '0' - no cleanup (e.g., if the context goes out of scope, but + * it's state is to remain in persistent storage); + * '1' - free up the underlying data structure in persistent storage + * (e.g., if the initialization of this context was only partially completed + * due to some failures, and we need to roll back); + * '2' - free up the underlying data structure, and deregister this + * naming context from its <index_> (e.g., if the context had + * <destroy> method invoked and needs to be completely removed from existence). + */ void set_cleanup_level (int level); - // Set <destroyed_> flag (inherited from TAO_Hash_Naming_Context) to - // <level>. Legal values for <destroyed_> are 0, 1, and 2. The - // values specify the extent of cleanup that should take place in the - // context's destructor: - // '0' - no cleanup (e.g., if the context goes out of scope, but - // it's state is to remain in persistent storage); - // '1' - free up the underlying data structure in persistent storage - // (e.g., if the initialization of this context was only partially completed - // due to some failures, and we need to roll back); - // '2' - free up the underlying data structure, and deregister this - // naming context from its <index_> (e.g., if the context had - // <destroy> method invoked and needs to be completely removed from existence). + /// Counter used for generation of POA ids for children Naming + /// Contexts. ACE_UINT32 *counter_; - // Counter used for generation of POA ids for children Naming - // Contexts. + /** + * A pointer to the underlying data structure used to store name + * bindings. While our superclass (TAO_Hash_Naming_Context) also + * maintains a pointer to the data structure, keeping this pointer + * around saves us from the need to downcast when invoking + * non-virtual methods. + */ TAO_Persistent_Bindings_Map *persistent_context_; - // A pointer to the underlying data structure used to store name - // bindings. While our superclass (TAO_Hash_Naming_Context) also - // maintains a pointer to the data structure, keeping this pointer - // around saves us from the need to downcast when invoking - // non-virtual methods. + /** + * A pointer to the index object of this naming service: it keeps + * track of all the naming contexts created. Every time we make a + * new context or destroy one, we need to make an entry there. + * Also, we get the allocator needed to initialize us from this guy. + */ TAO_Persistent_Context_Index *index_; - // A pointer to the index object of this naming service: it keeps - // track of all the naming contexts created. Every time we make a - // new context or destroy one, we need to make an entry there. - // Also, we get the allocator needed to initialize us from this guy. }; #include "ace/post.h" diff --git a/TAO/orbsvcs/orbsvcs/Naming/Storable.h b/TAO/orbsvcs/orbsvcs/Naming/Storable.h index e2aaa24b8f4..cc4354dba66 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Storable.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Storable.h @@ -1,17 +1,13 @@ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Storable.h -// -// = AUTHOR -// Bruce Trask <trask_b@ociweb.com> -// Chanaka Liyanaarachchi <chanaka@ociweb.com> -// -// ============================================================================ +//============================================================================= +/** + * @file Storable.h + * + * $Id$ + * + * @author Bruce Trask <trask_b@ociweb.com> Chanaka Liyanaarachchi <chanaka@ociweb.com> + */ +//============================================================================= + #ifndef STORABLE_H #define STORABLE_H @@ -98,9 +94,9 @@ class TAO_Writer_Base public: + /// This is used to indicate to the Writer that the bindings map is now + /// empty and therefore now persistence resources are needed for it. int delete_bindings_; - // this is used to indicate to the Writer that the bindings map is now - // empty and therefore now persistence resources are needed for it. }; diff --git a/TAO/orbsvcs/orbsvcs/Naming/Storable_Naming_Context.h b/TAO/orbsvcs/orbsvcs/Naming/Storable_Naming_Context.h index 1c7961ab54f..a61946f2a0d 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Storable_Naming_Context.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Storable_Naming_Context.h @@ -1,17 +1,14 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Storable_Naming_Context.h -// -// = AUTHOR -// Bruce Trask <trask_b@ociweb.com> -// -// ============================================================================ +//============================================================================= +/** + * @file Storable_Naming_Context.h + * + * $Id$ + * + * @author Bruce Trask <trask_b@ociweb.com> + */ +//============================================================================= + #ifndef TAO_STORABLE_NAMING_CONTEXT_H #define TAO_STORABLE_NAMING_CONTEXT_H @@ -27,80 +24,91 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_Storable_Bindings_Map + * + * @brief Provides hash-table-based transient storage for name to object + * bindings in a Naming Context. + * + * A thin wrapper on top of ACE_Hash_Map_Manager. Supports + * TAO_Bindings_Map interface. Used by TAO_Transient_Naming_Context. + */ class TAO_Naming_Export TAO_Storable_Bindings_Map : public TAO_Bindings_Map, public TAO_Storable_Base { - // = TITLE - // Provides hash-table-based transient storage for name to object bindings in a - // Naming Context. - // - // = DESCRIPTION - // A thin wrapper on top of ACE_Hash_Map_Manager. Supports - // TAO_Bindings_Map interface. Used by TAO_Transient_Naming_Context. public: + /// Underlying data structure - typedef for ease of use. typedef ACE_Hash_Map_Manager<TAO_Persistent_ExtId, TAO_Persistent_IntId, ACE_Null_Mutex> HASH_MAP; - // Underlying data structure - typedef for ease of use. // = Initialization and termination methods. + /// Constructor. TAO_Storable_Bindings_Map (size_t hash_table_size); - // Constructor. + /// Constructor. TAO_Storable_Bindings_Map (size_t hash_table_size, CORBA::ORB_ptr orb, const char* poa_id,PortableServer::POA_ptr poa); + /// Destructor. virtual ~TAO_Storable_Bindings_Map (void); - // Destructor. // = Accessors. + /// Get a reference to the underlying hash map. HASH_MAP &map (void); - // Get a reference to the underlying hash map. + /// Return the size of the underlying hash table. size_t total_size (void); - // Return the size of the underlying hash table. + /// Return current number of entries (name bindings) in the + /// underlying hash map. virtual size_t current_size (void); - // Return current number of entries (name bindings) in the - // underlying hash map. // = Name bindings manipulation methods. + /** + * Add a binding with the specified parameters to the table. + * Return 0 on success and -1 on failure, 1 if there already is a + * binding with <id> and <kind>. + */ virtual int bind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type); - // Add a binding with the specified parameters to the table. - // Return 0 on success and -1 on failure, 1 if there already is a - // binding with <id> and <kind>. + /** + * Overwrite a binding containing <id> and <kind> (or create a new + * one if one doesn't exist) with the specified parameters. Return + * 0 or 1 on success. Return -1 or -2 on failure. (-2 is returned + * if the new and old bindings differ in type). + */ virtual int rebind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type); - // Overwrite a binding containing <id> and <kind> (or create a new - // one if one doesn't exist) with the specified parameters. Return - // 0 or 1 on success. Return -1 or -2 on failure. (-2 is returned - // if the new and old bindings differ in type). + /** + * Remove a binding containing <id> and <kind> from the table. + * Return 0 on success and -1 on failure. + */ virtual int unbind (const char * id, const char * kind); - // Remove a binding containing <id> and <kind> from the table. - // Return 0 on success and -1 on failure. + /** + * Find the binding containing <id> and <kind> in the table, and + * pass binding's type and object back to the caller by reference. + * Return 0 on success and -1 on failure. Note: a 'duplicated' object + * reference is assigned to <obj>, so the caller is responsible for + * its deallocation. + */ virtual int find (const char * id, const char * kind, CORBA::Object_ptr & obj, CosNaming::BindingType &type); - // Find the binding containing <id> and <kind> in the table, and - // pass binding's type and object back to the caller by reference. - // Return 0 on success and -1 on failure. Note: a 'duplicated' object - // reference is assigned to <obj>, so the caller is responsible for - // its deallocation. virtual void Write(TAO_Writer_Base& wrtr); @@ -108,15 +116,15 @@ public: private: + /// Helper: factors common code from <bind> and <rebind>. int shared_bind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type, int rebind); - // Helper: factors common code from <bind> and <rebind>. + /// Hash map used for storage. HASH_MAP map_; - // Hash map used for storage. CORBA::ORB_ptr orb_; @@ -125,27 +133,30 @@ private: PortableServer::POA_var poa_; }; +/** + * @class TAO_Storable_Naming_Context + * + * @brief This class plays a role of a 'ConcreteImplementor' in the + * Bridge pattern architecture of the CosNaming::NamingContext + * implementation. + * + * This class provides a implementation of the + * NamingContext functionality, i.e., the state can be preserved + * across process boundaries. Derives from + * TAO_Hash_Naming_Context and uses TAO_Storable_Bindings_Map to + * store name to object bindings. + */ class TAO_Naming_Export TAO_Storable_Naming_Context : public TAO_Hash_Naming_Context { - // = TITLE - // This class plays a role of a 'ConcreteImplementor' in the - // Bridge pattern architecture of the CosNaming::NamingContext - // implementation. - // - // = DESCRIPTION - // This class provides a implementation of the - // NamingContext functionality, i.e., the state can be preserved - // across process boundaries. Derives from - // TAO_Hash_Naming_Context and uses TAO_Storable_Bindings_Map to - // store name to object bindings. public: + /// Underlying data structure - typedef for ease of use. typedef TAO_Storable_Bindings_Map::HASH_MAP HASH_MAP; - // Underlying data structure - typedef for ease of use. // = Initialization and termination methods. + /// Constructor. TAO_Storable_Naming_Context (CORBA::ORB_ptr orb, PortableServer::POA_ptr poa, const char *poa_id, @@ -153,6 +164,7 @@ public: const ACE_TCHAR *persistence_directory, size_t hash_table_size = ACE_DEFAULT_MAP_SIZE); + /// Constructor. TAO_Storable_Naming_Context (CORBA::ORB_ptr orb, PortableServer::POA_ptr poa, const char *poa_id, @@ -161,12 +173,17 @@ public: const ACE_TCHAR *persistence_directory, size_t hash_table_size = ACE_DEFAULT_MAP_SIZE); - // Constructor. - + /// Destructor. virtual ~TAO_Storable_Naming_Context (void); - // Destructor. // = Utility methods. + /** + * This utility method factors out the code needed to create a new + * Storable Naming Context servant and activate it under the + * specified POA with the specified id. This function is static so + * that the code can be used, both from inside the class (e.g., + * <new_context>), and from outside (e.g., Naming_Utils.cpp). + */ static CosNaming::NamingContext_ptr make_new_context ( CORBA::ORB_ptr orb, PortableServer::POA_ptr poa, @@ -176,12 +193,6 @@ public: const ACE_TCHAR *persistence_directory ACE_ENV_ARG_DECL); - // This utility method factors out the code needed to create a new - // Storable Naming Context servant and activate it under the - // specified POA with the specified id. This function is static so - // that the code can be used, both from inside the class (e.g., - // <new_context>), and from outside (e.g., Naming_Utils.cpp). - // = Methods not implemented in TAO_Hash_Naming_Context. static CosNaming::NamingContext_ptr recreate_all( @@ -195,93 +206,113 @@ public: ACE_ENV_ARG_DECL); + /** + * This operation returns a new naming context implemented by the + * same naming server in which the operation was invoked. The + * context is not bound. + */ virtual CosNaming::NamingContext_ptr new_context (ACE_ENV_SINGLE_ARG_DECL); - // This operation returns a new naming context implemented by the - // same naming server in which the operation was invoked. The - // context is not bound. + /** + * Returns at most the requested number of bindings <how_many> in + * <bl>. If the naming context contains additional bindings, they + * are returned with a BindingIterator. In the naming context does + * not contain any additional bindings <bi> returned as null. + */ virtual void list (CORBA::ULong how_many, CosNaming::BindingList_out &bl, CosNaming::BindingIterator_out &bi ACE_ENV_ARG_DECL); - // Returns at most the requested number of bindings <how_many> in - // <bl>. If the naming context contains additional bindings, they - // are returned with a BindingIterator. In the naming context does - // not contain any additional bindings <bi> returned as null. virtual void rebind (const CosNaming::Name& n, CORBA::Object_ptr obj ACE_ENV_ARG_DECL); + /** + * Create a binding for name <n> and object <obj> in the naming + * context. Compound names are treated as follows: ctx->bind (<c1; + * c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, + * obj) if the there already exists a binding for the specified + * name, <AlreadyBound> exception is thrown. Naming contexts should + * be bound using <bind_context> and <rebind_context> in order to + * participate in name resolution later. + */ virtual void bind (const CosNaming::Name &n, CORBA::Object_ptr obj ACE_ENV_ARG_DECL); - // Create a binding for name <n> and object <obj> in the naming - // context. Compound names are treated as follows: ctx->bind (<c1; - // c2; c3; cn>, obj) = (ctx->resolve (<c1; c2; cn-1>))->bind (<cn>, - // obj) if the there already exists a binding for the specified - // name, <AlreadyBound> exception is thrown. Naming contexts should - // be bound using <bind_context> and <rebind_context> in order to - // participate in name resolution later. + /** + * This is the version of <bind> specifically for binding naming + * contexts, so that they will participate in name resolution when + * compound names are passed to be resolved. + */ virtual void bind_context (const CosNaming::Name &n, CosNaming::NamingContext_ptr nc ACE_ENV_ARG_DECL); - // This is the version of <bind> specifically for binding naming - // contexts, so that they will participate in name resolution when - // compound names are passed to be resolved. + /** + * This is a version of <rebind> specifically for naming contexts, + * so that they can participate in name resolution when compound + * names are passed. + */ virtual void rebind_context (const CosNaming::Name &n, CosNaming::NamingContext_ptr nc ACE_ENV_ARG_DECL); - // This is a version of <rebind> specifically for naming contexts, - // so that they can participate in name resolution when compound - // names are passed. + /** + * Return object reference that is bound to the name. Compound name + * resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = + * ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service + * does not return the type of the object. Clients are responsible + * for "narrowing" the object to the appropriate type. + */ virtual CORBA::Object_ptr resolve (const CosNaming::Name &n ACE_ENV_ARG_DECL); - // Return object reference that is bound to the name. Compound name - // resolve is defined as follows: ctx->resolve (<c1; c2; cn>) = - // ctx->resolve (<c1; c2 cn-1>)->resolve (<cn>) The naming service - // does not return the type of the object. Clients are responsible - // for "narrowing" the object to the appropriate type. + /** + * Remove the name binding from the context. When compound names + * are used, unbind is defined as follows: ctx->unbind (<c1; c2; + * cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) + */ virtual void unbind (const CosNaming::Name &n ACE_ENV_ARG_DECL); - // Remove the name binding from the context. When compound names - // are used, unbind is defined as follows: ctx->unbind (<c1; c2; - // cn>) = (ctx->resolve (<c1; c2; cn-1>))->unbind (<cn>) + /** + * This operation creates a new context and binds it to the name + * supplied as an argument. The newly-created context is + * implemented by the same server as the context in which it was + * bound (the name argument excluding the last component). + */ virtual CosNaming::NamingContext_ptr bind_new_context ( const CosNaming::Name &n ACE_ENV_ARG_DECL); - // This operation creates a new context and binds it to the name - // supplied as an argument. The newly-created context is - // implemented by the same server as the context in which it was - // bound (the name argument excluding the last component). + /** + * Delete the naming context. The user should take care to <unbind> any + * bindings in which the given context is bound to some names, to + * avoid dangling references when invoking <destroy> operation. + * NOTE: <destory> is a no-op on the root context. + * NOTE: after <destroy> is invoked on a Naming Context, all + * BindingIterators associated with that Naming Context are also destroyed. + */ virtual void destroy (ACE_ENV_SINGLE_ARG_DECL); - // Delete the naming context. The user should take care to <unbind> any - // bindings in which the given context is bound to some names, to - // avoid dangling references when invoking <destroy> operation. - // NOTE: <destory> is a no-op on the root context. - // NOTE: after <destroy> is invoked on a Naming Context, all - // BindingIterators associated with that Naming Context are also destroyed. protected: + /// Counter used for generation of POA ids for children Naming + /// Contexts. ACE_UINT32 counter_; - // Counter used for generation of POA ids for children Naming - // Contexts. + /** + * A pointer to the underlying data structure used to store name + * bindings. While our superclass (TAO_Hash_Naming_Context) also + * maintains a pointer to the data structure, keeping this pointer + * around saves us from the need to downcast when invoking + * non-virtual methods. + */ TAO_Storable_Bindings_Map *storable_context_; - // A pointer to the underlying data structure used to store name - // bindings. While our superclass (TAO_Hash_Naming_Context) also - // maintains a pointer to the data structure, keeping this pointer - // around saves us from the need to downcast when invoking - // non-virtual methods. CORBA::ORB_ptr orb_; diff --git a/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h b/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h index 3af69ee0ec8..4af5399eb7f 100644 --- a/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h +++ b/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h @@ -1,17 +1,14 @@ /* -*- C++ -*- */ -// $Id$ -// ============================================================================ -// -// = LIBRARY -// cos -// -// = FILENAME -// Transient_Naming_Context.h -// -// = AUTHOR -// Marina Spivak <marina@cs.wustl.edu> -// -// ============================================================================ +//============================================================================= +/** + * @file Transient_Naming_Context.h + * + * $Id$ + * + * @author Marina Spivak <marina@cs.wustl.edu> + */ +//============================================================================= + #ifndef TAO_TRANSIENT_NAMING_CONTEXT_H #define TAO_TRANSIENT_NAMING_CONTEXT_H @@ -25,156 +22,176 @@ # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ +/** + * @class TAO_Transient_Bindings_Map + * + * @brief Provides hash-table-based transient storage for name to object + * bindings in a Naming Context. + * + * A thin wrapper on top of ACE_Hash_Map_Manager. Supports + * TAO_Bindings_Map interface. Used by TAO_Transient_Naming_Context. + */ class TAO_Naming_Export TAO_Transient_Bindings_Map : public TAO_Bindings_Map { - // = TITLE - // Provides hash-table-based transient storage for name to object bindings in a - // Naming Context. - // - // = DESCRIPTION - // A thin wrapper on top of ACE_Hash_Map_Manager. Supports - // TAO_Bindings_Map interface. Used by TAO_Transient_Naming_Context. public: + /// Underlying data structure - typedef for ease of use. typedef ACE_Hash_Map_Manager<TAO_ExtId, TAO_IntId, ACE_Null_Mutex> HASH_MAP; - // Underlying data structure - typedef for ease of use. // = Initialization and termination methods. + /// Constructor. TAO_Transient_Bindings_Map (size_t hash_table_size); - // Constructor. + /// Destructor. virtual ~TAO_Transient_Bindings_Map (void); - // Destructor. // = Accessors. + /// Get a reference to the underlying hash map. HASH_MAP &map (void); - // Get a reference to the underlying hash map. + /// Return the size of the underlying hash table. size_t total_size (void); - // Return the size of the underlying hash table. + /// Return current number of entries (name bindings) in the + /// underlying hash map. virtual size_t current_size (void); - // Return current number of entries (name bindings) in the - // underlying hash map. // = Name bindings manipulation methods. + /** + * Add a binding with the specified parameters to the table. + * Return 0 on success and -1 on failure, 1 if there already is a + * binding with <id> and <kind>. + */ virtual int bind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type); - // Add a binding with the specified parameters to the table. - // Return 0 on success and -1 on failure, 1 if there already is a - // binding with <id> and <kind>. + /** + * Overwrite a binding containing <id> and <kind> (or create a new + * one if one doesn't exist) with the specified parameters. Return + * 0 or 1 on success. Return -1 or -2 on failure. (-2 is returned + * if the new and old bindings differ in type). + */ virtual int rebind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type); - // Overwrite a binding containing <id> and <kind> (or create a new - // one if one doesn't exist) with the specified parameters. Return - // 0 or 1 on success. Return -1 or -2 on failure. (-2 is returned - // if the new and old bindings differ in type). + /** + * Remove a binding containing <id> and <kind> from the table. + * Return 0 on success and -1 on failure. + */ virtual int unbind (const char * id, const char * kind); - // Remove a binding containing <id> and <kind> from the table. - // Return 0 on success and -1 on failure. + /** + * Find the binding containing <id> and <kind> in the table, and + * pass binding's type and object back to the caller by reference. + * Return 0 on success and -1 on failure. Note: a 'duplicated' object + * reference is assigned to <obj>, so the caller is responsible for + * its deallocation. + */ virtual int find (const char * id, const char * kind, CORBA::Object_ptr & obj, CosNaming::BindingType &type); - // Find the binding containing <id> and <kind> in the table, and - // pass binding's type and object back to the caller by reference. - // Return 0 on success and -1 on failure. Note: a 'duplicated' object - // reference is assigned to <obj>, so the caller is responsible for - // its deallocation. private: + /// Helper: factors common code from <bind> and <rebind>. int shared_bind (const char *id, const char *kind, CORBA::Object_ptr obj, CosNaming::BindingType type, int rebind); - // Helper: factors common code from <bind> and <rebind>. + /// Hash map used for storage. HASH_MAP map_; - // Hash map used for storage. }; +/** + * @class TAO_Transient_Naming_Context + * + * @brief This class plays a role of a 'ConcreteImplementor' in the + * Bridge pattern architecture of the CosNaming::NamingContext + * implementation. + * + * This class provides a transient implementation of the + * NamingContext functionality, i.e., the state is not preserved + * across process boundaries. Derives from + * TAO_Hash_Naming_Context and uses TAO_Transient_Bindings_Map to + * store name to object bindings. + */ class TAO_Naming_Export TAO_Transient_Naming_Context : public TAO_Hash_Naming_Context { - // = TITLE - // This class plays a role of a 'ConcreteImplementor' in the - // Bridge pattern architecture of the CosNaming::NamingContext - // implementation. - // - // = DESCRIPTION - // This class provides a transient implementation of the - // NamingContext functionality, i.e., the state is not preserved - // across process boundaries. Derives from - // TAO_Hash_Naming_Context and uses TAO_Transient_Bindings_Map to - // store name to object bindings. public: + /// Underlying data structure - typedef for ease of use. typedef TAO_Transient_Bindings_Map::HASH_MAP HASH_MAP; - // Underlying data structure - typedef for ease of use. // = Initialization and termination methods. + /// Constructor. TAO_Transient_Naming_Context (PortableServer::POA_ptr poa, const char *poa_id, size_t hash_table_size = ACE_DEFAULT_MAP_SIZE); - // Constructor. + /// Destructor. virtual ~TAO_Transient_Naming_Context (void); - // Destructor. // = Utility methods. + /** + * This utility method factors out the code needed to create a new + * Transient Naming Context servant and activate it under the + * specified POA with the specified id. This function is static so + * that the code can be used, both from inside the class (e.g., <new_context>), + * and from outside (e.g., Naming_Utils.cpp). + */ static CosNaming::NamingContext_ptr make_new_context (PortableServer::POA_ptr poa, const char *poa_id, size_t context_size ACE_ENV_ARG_DECL); - // This utility method factors out the code needed to create a new - // Transient Naming Context servant and activate it under the - // specified POA with the specified id. This function is static so - // that the code can be used, both from inside the class (e.g., <new_context>), - // and from outside (e.g., Naming_Utils.cpp). // = Methods not implemented in TAO_Hash_Naming_Context. + /** + * This operation returns a new naming context implemented by the + * same naming server in which the operation was invoked. The + * context is not bound. + */ virtual CosNaming::NamingContext_ptr new_context (ACE_ENV_SINGLE_ARG_DECL); - // This operation returns a new naming context implemented by the - // same naming server in which the operation was invoked. The - // context is not bound. + /** + * Returns at most the requested number of bindings <how_many> in + * <bl>. If the naming context contains additional bindings, they + * are returned with a BindingIterator. In the naming context does + * not contain any additional bindings <bi> returned as null. + */ virtual void list (CORBA::ULong how_many, CosNaming::BindingList_out &bl, CosNaming::BindingIterator_out &bi ACE_ENV_ARG_DECL); - // Returns at most the requested number of bindings <how_many> in - // <bl>. If the naming context contains additional bindings, they - // are returned with a BindingIterator. In the naming context does - // not contain any additional bindings <bi> returned as null. protected: + /// Counter used for generation of POA ids for children Naming + /// Contexts. ACE_UINT32 counter_; - // Counter used for generation of POA ids for children Naming - // Contexts. + /** + * A pointer to the underlying data structure used to store name + * bindings. While our superclass (TAO_Hash_Naming_Context) also + * maintains a pointer to the data structure, keeping this pointer + * around saves us from the need to downcast when invoking + * non-virtual methods. + */ TAO_Transient_Bindings_Map *transient_context_; - // A pointer to the underlying data structure used to store name - // bindings. While our superclass (TAO_Hash_Naming_Context) also - // maintains a pointer to the data structure, keeping this pointer - // around saves us from the need to downcast when invoking - // non-virtual methods. }; #include "ace/post.h" |