ChangeLogTag:Mon Jul 5 19:47:04 1999 Marina Spivak <marina@cs.wustl.edu>

22 files changed, 624 insertions, 352 deletions

diff --git a/TAO/ChangeLog-99c b/TAO/ChangeLog-99c
index 4f0ed7cea03..60313f427cb 100644
--- a/TAO/ChangeLog-99c
+++ b/TAO/ChangeLog-99c
@@ -1,3 +1,45 @@
+Mon Jul  5 19:47:04 1999  Marina Spivak  <marina@cs.wustl.edu>
+
+	* orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.cpp
+	* orbsvcs/orbsvcs/Naming/Entries.h
+	* orbsvcs/orbsvcs/Naming/Hash_Naming_Context.cpp
+	* orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h
+	* orbsvcs/orbsvcs/Naming/Naming_Context.cpp
+	* orbsvcs/orbsvcs/Naming/Naming_Context.h
+	* orbsvcs/orbsvcs/Naming/Naming_Utils.cpp
+	* orbsvcs/orbsvcs/Naming/Naming_Utils.h
+	* orbsvcs/orbsvcs/Naming/Persistent_Context_Index.cpp
+	* orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h
+	* orbsvcs/orbsvcs/Naming/Persistent_Entries.cpp
+	* orbsvcs/orbsvcs/Naming/Persistent_Entries.h
+	* orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.cpp
+	* orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h
+	* orbsvcs/orbsvcs/Naming/Transient_Naming_Context.cpp
+	* orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h :
+	  Fixed several memory leaks that were due to superclass
+	  destructors not being virtual.
+	  Updated the implementation to reflect several
+	  changes/clarifications from the INS specification (mostly
+	  regarding exception conditions).
+	  Added comments, cleaned up the code, etc. in the remaining
+	  files, which brings my 'review' of Naming implementation files
+	  to a close.
+
+	* orbsvcs/orbsvcs/Naming/README
+	  Added a short description about the structure of implementation
+	  files.
+
+	* orbsvcs/Naming_Service/Naming_Service.cpp:
+	  Destroy the POA on shutdown.
+
+	* orbsvcs/Naming_Service/README
+	  Updated the file and added description of
+	  implementation-specific policies.
+
+	* orbsvcs/tests/Simple_Naming/client.cpp
+	  Updated test to reflect changes in the behaviour of the Naming
+	  Service (due to clarifications in the INS spec).
+
 Mon Jul  5 17:10:00 1999  Chris Gill  <cdgill@cs.wustl.edu>
 
         * orbsvcs/Scheduling_Service/Scheduling_Service.cpp
@@ -5,7 +47,7 @@ Mon Jul  5 17:10:00 1999  Chris Gill  <cdgill@cs.wustl.edu>
           orbsvcs/orbsvcs/Sched/Reconfig_Scheduler_T.{cpp, h}
           orbsvcs/orbsvcs/Sched/Reconfig_Sched_Utils[_T].{cpp, h}: bug
 	  fixes from testing, added missing schedule configuration code.
-	
+
 Mon Jul 05 16:06:51 1999  Irfan Pyarali  <irfan@cs.wustl.edu>
 
 	* tao/Exception.cpp (_info): Added _info() to CORBA::Exception and
diff --git a/TAO/orbsvcs/Naming_Service/Naming_Service.cpp b/TAO/orbsvcs/Naming_Service/Naming_Service.cpp
index 9edb245c7ed..3abbb4f93aa 100644
--- a/TAO/orbsvcs/Naming_Service/Naming_Service.cpp
+++ b/TAO/orbsvcs/Naming_Service/Naming_Service.cpp
@@ -159,12 +159,21 @@ int
 TAO_Naming_Service::run (CORBA_Environment& ACE_TRY_ENV)
 {
   if (time_ == 0)
+    {
       return this->orb_manager_.run (ACE_TRY_ENV);
+      ACE_CHECK_RETURN (-1);
+    }
   else
     {
-      ACE_Time_Value *t = new ACE_Time_Value (time_);
-      return this->orb_manager_.run (ACE_TRY_ENV, t);
+      ACE_Time_Value t (time_);
+      return this->orb_manager_.run (ACE_TRY_ENV, &t);
+      ACE_CHECK_RETURN (-1);
     }
+
+  // Clean up after we exit from the loop.
+  PortableServer::POA_var poa = this->orb_manager_.root_poa ();
+  poa->destroy (1, 1, ACE_TRY_ENV);
+  ACE_CHECK_RETURN (-1);
 }
 
 // Destructor.
diff --git a/TAO/orbsvcs/Naming_Service/README b/TAO/orbsvcs/Naming_Service/README
index c5814b5883a..55db915353a 100644
--- a/TAO/orbsvcs/Naming_Service/README
+++ b/TAO/orbsvcs/Naming_Service/README
@@ -1,135 +1,171 @@
 // $Id$
 
-        This directory contains the files that implement the TAO
-Naming server.  The TAO Naming Service uses IP Multicast to process
-client "resolve_initial_references()" requests.
+This directory contains the files that implement the TAO
+Naming server.
+
 
 To Run:
 ======
 
-% Naming_Service [-ORBobjrefstyle url]
-                 [-ORBnameserviceport nsport]
+% Naming_Service [-ORBnameserviceport nsport]
                  [-o ior_output_file]
                  [-p pid_file_name]
                  [-s context_size]
                  [-t time]
                  [-f persitence_file_name]
 
-Arguments:
-==========
-        port
-                 The ORB port.
-
+Optional Command-line Arguments:
+===============================
         nsport
-                Multicast port.
-
+                Multicast port for listening for requests from
+                clients trying to bootstrap to a Naming Service
+                through the use of multicast.
 
         output_file
-                The name of the file, in which to store IOR of the
-                root Naming Service context.  (This file can then be
-                used by clients instead of multicast, to obtain the
-                Naming Service IOR).
+                The name of the file, in which to store the IOR of the
+                root Naming Service context.
 
        pid_file_name
                 The name of the file, in which to store the process id
                 of the Naming Service server.
 
         context_size
-                 Size of the hash table allocated upon the creation of
+                 Size of the hash table allocated for
                  the root Naming Context (if one is created).  All
                  contexts created under the root will use the same
                  size for their hash tables.  The default is 1024.
 
         time
-                How long the server should listen for requests before
-                exiting.
+                How long (in seconds) the server should listen for
+                client requests before terminating.
 
         persistence_file_name
-                The name of the file to use to store/read from the
-                persistent state of the Naming Service.
+                The name of the file to use to store/retrieve
+                persistent state of the Naming Service.  Without this
+                option, Naming Service is started in non-persistent mode.
 
 Environment Variables:
 =====================
 
-        NameServicePort - Multicast port to listen on for
-        "resolve_initial_references" requests.
+        NameServicePort
+                Multicast port for listening for requests from
+                clients trying to bootstrap to a Naming Service
+                through the use of multicast.
+
 
 Persistence:
 ===========
 TAO Naming Service has an optional persistence capability.  By
-default, a non-persistent version of the Naming Service is used.
+default, the Naming Service is started in a non-persistent mode.
 Supplying "-f" command-line option to the server causes a persistent
 version of the Naming Service to run.
 
-The file, which name is supplied along with the "-f" option, is used to store the
+The file specified with the "-f" option is used to store the
 persistent state of the Naming Service, i.e., all Naming Contexts and
-all their bindings.  When "-f" option is specified:
+their bindings.  When "-f" option is specified:
 
-    1. If the specified file does not exist, the file is created
+    1. If the specified file does not exist, it is created
        and used to store the state of the Naming Service.  An initial
        (root) Naming Context is also created.
 
     2. If the specified file exists, it is scanned and:
                         a) If any inconsistency is detected in the
-                        stored state or the file is not recognized by
-                        the Naming Service, the server exits.  A
-                        noncorrupted version of the file must be used.
-
-                        b) If no Naming Contexts exist, an initial
-                        (root) Naming Context is created.
-
-                        c) If one or more Naming Contexts exist, the
-                        state stored in the file becomes the state of
+                        stored state, or the file is not recognized by
+                        the Naming Service, the server exits.  (This
+                        may happen, for example, if a server or host
+                        crashed in the middle of writing a record to
+                        this file on a previous run).  A
+                        noncorrupted version of the file must be used instead.
+
+                        b) If the file is recognized and is ok, the
+                        state stored in the file becomes the current state of
                         the Naming Service.
 
-Sample Run:
-==========
-
-% Naming_Service -ORBobjrefstyle url -ORBnameserviceport 19999
-starting up daemon <unknown>
-opening dynamic service Resource_Factory
-did dynamic on Resource_Factory, error = 0
-opening dynamic service Client_Strategy_Factory
-did dynamic on Client_Strategy_Factory, error = 0
-opening dynamic service Server_Strategy_Factory
-did dynamic on Server_Strategy_Factory, error = 0
-listening as object <iiop:1.0//tango:20000/P35194c690003809cRootPOA/child_poa/NameService>
-The multicast server setup is done.
-
-NameService Client:
-==================
-
-A client of the TAO Naming Service will use the ORB
-resolve_initial_references() method to resolve the "NamingService"
-object service.  By default, this resolution is performed using
-Multicast.  This behavior can be overridden in the following ways:
-
-        1. Pass the argument -ORBnameserviceior ior.
-           This ior is got from the output of the Naming_Service from
-           line 'listening as object <iiop:..>'.
-
-           For example, If a client wants to use the Naming_Service
-           from the sample run it could use:
-
-           % client -ORBnameserviceior <iiop:1.0//tango:20000/P35194c690003809cRootPOA/child_poa/NameService>
-
-        2. Set the environment variable `NameServiceIOR' (minus the
-           quotes), as follows in csh or tcsh:
-
-           % setenv NameServiceIOR <iiop:1.0//tango:20000/P35194c690003809cRootPOA/child_poa/NameService>
-
-           and then run the client,
-
-           % client <.. client's arguments>
-
-These two techniques may be needed in an environment where
-
-        1. There is more than one NamingService, to avoid the
-           confusion of a server registering its object with one
-           NamingService and the client getting the reply from some
-           other NamingService.
-
-        2. The OS platform doesn't support multicast.
 
-        3. The client or server isn't written using TAO, and therefore
-           doesn't use TAO's multicast NameService resolution protocol.
+Implementation Policies:
+=======================
+
+- Destroying Binding Iterators
+             A binding iterator is destroyed when client invokes
+             <destroy> operation either on the iterator itself or on
+             the naming context it is iterating over.  In both cases,
+             subsequent calls on the binding iterator object will
+             cause OBJECT_NOT_EXIST exception.
+
+- Dealing with orphaned contexts
+             This implementation of the Naming Service does not
+             include any form of 'garbage collection' for orphaned
+             naming contexts.  It is solely the responsibility of
+             clients to clean up after themselves and not leak server
+             resources.  All the resources, including orphaned
+             contexts, are released during the Naming Server
+             shutdown.
+
+Clients: ways to bootstrap to the Naming Service:
+================================================
+
+There are several methods for a client to bootstrap to a Naming
+Service, i.e., there are several mechanisms <resolve_initial_references> can use
+when asked for "NameService".
+
+       1. By default (unless other options are specified - see items 2
+          and 3 below), ip multicast is used to locate a Naming
+          Service. TAO Naming Server is listening for client multicast
+          requests on a specified port.  On the client side,
+          <resolve_initial_references> sends out a multicast request
+          on the network, trying to locate a Naming Service.  When a
+          Naming Server receives a multicast request from a client, it
+          replies to the sender with the ior of its root
+          Naming Context.  Note, the port used for this bootstrapping
+          process, i.e., 'multicast port', has nothing to do with the
+          ORB port used for CORBA communication.  Other points worth
+          mentioning:
+
+          - A client and a server will only click through this
+            multicast protocol if they are using the same multicast
+            port.  For both client and server -ORBnameserviceport
+            command-line option and NameServicePort environment
+            variable can be used to specify the multicast port to use.
+            If none is specified, the default port is used.  (The
+            ability to specify multicast ports can be used to match
+            certain clients with certain Naming Servers, when there
+            are more than one Naming Server running on the network).
+
+          - If there are several Naming Servers running on the
+            network, each listening on the same port for
+            multicast requests, each will send a reply to a client's
+            request.  The client's orb will use the first response it
+            receives, so the Naming Service will, in fact, be selected at
+            random.
+
+          Since this mechanism is proprietary to TAO (i.e.,
+          non-standard), it only works when both client and server are
+          written using TAO.  There is no way to turn multicasting
+          off, but it is used only as a last resort, i.e., any of the
+          options below will override it.
+
+          When OS platform doesn't support multicast, or client or
+          server isn't written using TAO, or a more reliable location
+          method is desired, etc., one of the options below can be
+          used to bootstrap to the Naming Service.
+
+        2. Command-line option -ORBnameserviceior or environment
+           variable NameServiceIOR can be used on the client side to
+           specify the object that the call to
+           <resolve_initial_references> should return to the client.
+           (On the server side, -o option can be used to get the ior).
+
+           Example (Unix, same host):
+
+           % TAO_ROOT/orbsvcs/Naming_Service -o ior_file
+           % my_client -ORBnameserviceior file://ior_file
+
+           On the first line, we start the Naming Service, and output
+           its ior to <ior_file>.  On the second line, we start some
+           client, and specify the ior <resolve_initial_references>
+           should return for the Naming Service in a file format.
+
+        3. TAO implements Interoperable Naming Service.  So, most of the
+           initialzation options provided by INS can be used to
+           bootstrap to the Naming Service (see TAO's releasenotes for the
+           status of INS implementation).
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.cpp b/TAO/orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.cpp
index 59b1bcb5245..be97306e0bc 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.cpp
+++ b/TAO/orbsvcs/orbsvcs/Naming/Bindings_Iterator_T.cpp
@@ -127,6 +127,10 @@ TAO_Bindings_Iterator<ITERATOR, TABLE_ENTRY>::next_n (CORBA::ULong how_many,
       ACE_THROW_RETURN (CORBA::OBJECT_NOT_EXIST (), 0);
     }
 
+  // Check for illegal parameter values.
+  if (how_many == 0)
+    ACE_THROW_RETURN (CORBA::BAD_PARAM (), 0);
+
   // If there are no more bindings...
   if (hash_iter_->done ())
       return 0;
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Entries.h b/TAO/orbsvcs/orbsvcs/Naming/Entries.h
index b22550d89ee..561e07b5273 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Entries.h
+++ b/TAO/orbsvcs/orbsvcs/Naming/Entries.h
@@ -32,11 +32,16 @@
 class TAO_ORBSVCS_Export TAO_IntId
 {
   // = TITLE
-  //     Stores information a context keeps for each bound name.
+  //     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
-  //     Each bound name is associated with an object reference and
-  //     the type of binding.
+  //     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.
   TAO_IntId (void);
@@ -55,22 +60,28 @@ public:
   void operator= (const TAO_IntId & rhs);
   // Assignment operator (does copy memory).
 
+  // = Data members.
+
   CORBA::Object_ptr ref_;
-  // CORBA object reference of the bound object.
+  // Object reference to be stored in a Transient Naming Context.
 
   CosNaming::BindingType type_;
-  // Indicator of whether the object is a NamingContext that should
-  // participate in name resolution when compound names are used.
+  // Binding type for <ref_>.
 };
 
 class TAO_ORBSVCS_Export TAO_ExtId
 {
   // = TITLE
-  //    Stores the name to which an object is bound.
+  //     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 is used as the External ID for the
-  //    <ACE_Hash_Map_Manager>.
+  //     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.
 
@@ -87,6 +98,8 @@ public:
   ~TAO_ExtId (void);
   // Destructor.
 
+  // = Assignment and comparison operators.
+
   void operator= (const TAO_ExtId & rhs);
   // Assignment operator (does copy memory).
 
@@ -97,18 +110,23 @@ public:
   // Inequality comparison operator.
 
   u_long hash (void) const;
-  // This class has to have a hash for use with ACE_Hash_Map_Manager.
+  // <hash> function is required in order for this class to be usable by
+  // ACE_Hash_Map_Manager.
+
+  // = Data members.
 
   ACE_CString kind_;
-  // Any information user wants to store (not used by Naming Service).
+  // <kind> portion of the name to be associated with some object
+  // reference in a Transient Naming Context.
 
   ACE_CString id_;
-  // Any information user wants to store (not used by Naming Service).
+  // <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.
 
   const char * id (void);
   const char * kind (void);
-  // Accessors.
-
 };
 
 #endif /* TAO_ENTRIES_H */
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.cpp b/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.cpp
index ccf6193bfe4..24ca105d609 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.cpp
+++ b/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.cpp
@@ -15,7 +15,11 @@
 #include "ace/Auto_Ptr.h"
 #include "Hash_Naming_Context.h"
 
-ACE_RCSID(Naming, Hash_Naming_Context, "$Id:")
+ACE_RCSID(Naming, Hash_Naming_Context, "$Id$")
+
+TAO_Bindings_Map::~TAO_Bindings_Map (void)
+{
+}
 
 TAO_Hash_Naming_Context::TAO_Hash_Naming_Context (PortableServer::POA_ptr poa,
                                                   const char *poa_id)
@@ -81,9 +85,6 @@ TAO_Hash_Naming_Context::get_context (const CosNaming::Name &name,
       ex.rest_of_name.length (rest_len);
       ex.rest_of_name[rest_len - 1] = name[name_len - 1];
 
-      if (ex.why == CosNaming::NamingContext::not_object)
-        ex.why = CosNaming::NamingContext::missing_node;
-
       ACE_RETHROW;
     }
   ACE_ENDTRY;
@@ -199,12 +200,20 @@ TAO_Hash_Naming_Context::rebind (const CosNaming::Name& n,
   else
     // If we received a simple name, we need to rebind it in this
     // context.
-    if (this->context_->rebind (n[0].id,
-                               n[0].kind,
-                               obj,
-                               CosNaming::nobject)
-        == -1)
-      ACE_THROW (CORBA::INTERNAL ());
+    {
+      int result = this->context_->rebind (n[0].id,
+                                           n[0].kind,
+                                           obj,
+                                           CosNaming::nobject);
+      // Check for error conditions.
+      if (result == -1)
+        ACE_THROW (CORBA::INTERNAL ());
+
+      else if (result == -2)
+        ACE_THROW (CosNaming::NamingContext::NotFound
+                   (CosNaming::NamingContext::not_object,
+                    n));
+    }
 }
 
 void
@@ -222,6 +231,10 @@ TAO_Hash_Naming_Context::bind_context (const CosNaming::Name &n,
   if (this->destroyed_)
     ACE_THROW (CORBA::OBJECT_NOT_EXIST ());
 
+  // Do not allow binding of nil context reference.
+  if (CORBA::is_nil (nc))
+    ACE_THROW (CORBA::BAD_PARAM ());
+
   // Get the length of the name.
   CORBA::ULong name_len = n.length ();
 
@@ -298,14 +311,23 @@ TAO_Hash_Naming_Context::rebind_context (const CosNaming::Name &n,
       context->rebind_context (simple_name, nc, ACE_TRY_ENV);
       ACE_CHECK;
     }
-  // If we received a simple name, we need to rebind it in this
-  // context.
   else
-    if (this->context_->rebind (n[0].id,
-                               n[0].kind,
-                               nc,
-                               CosNaming::ncontext) < 0)
-      ACE_THROW (CORBA::INTERNAL ());
+    // If we received a simple name, we need to rebind it in this
+    // context.
+    {
+      int result = this->context_->rebind (n[0].id,
+                                           n[0].kind,
+                                           nc,
+                                           CosNaming::ncontext);
+      // Check for error conditions.
+      if (result == -1)
+        ACE_THROW (CORBA::INTERNAL ());
+
+      else if (result == -2)
+        ACE_THROW (CosNaming::NamingContext::NotFound
+                   (CosNaming::NamingContext::not_context,
+                    n));
+    }
 }
 
 CORBA::Object_ptr
@@ -342,7 +364,7 @@ TAO_Hash_Naming_Context::resolve (const CosNaming::Name& n,
                             obj,
                             type) == -1)
     ACE_THROW_RETURN (CosNaming::NamingContext::NotFound
-                      (CosNaming::NamingContext::not_object,
+                      (CosNaming::NamingContext::missing_node,
                        n),
                       CORBA::Object::_nil ());
 
@@ -444,7 +466,7 @@ TAO_Hash_Naming_Context::unbind (const CosNaming::Name& n,
     if (this->context_->unbind (n[0].id,
                                 n[0].kind) == -1)
       ACE_THROW (CosNaming::NamingContext::NotFound
-                 (CosNaming::NamingContext::not_object,
+                 (CosNaming::NamingContext::missing_node,
                   n));
 }
 
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h b/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h
index 699f74baa24..b37759e94cf 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h
+++ b/TAO/orbsvcs/orbsvcs/Naming/Hash_Naming_Context.h
@@ -37,6 +37,9 @@ class TAO_ORBSVCS_Export TAO_Bindings_Map
 
 public:
 
+  virtual ~TAO_Bindings_Map (void);
+  // Destructor.
+
   virtual size_t current_size (void) = 0;
   // Return current number of entries (name bindings) in the
   // underlying hash map.
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Naming_Context.cpp b/TAO/orbsvcs/orbsvcs/Naming/Naming_Context.cpp
index fc43c2eb9a3..335fb60c1ee 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Naming_Context.cpp
+++ b/TAO/orbsvcs/orbsvcs/Naming/Naming_Context.cpp
@@ -138,3 +138,7 @@ TAO_Naming_Context::list (CORBA::ULong how_many,
 {
   impl_->list (how_many, bl, bi, ACE_TRY_ENV);
 }
+
+TAO_Naming_Context_Impl::~TAO_Naming_Context_Impl (void)
+{
+}
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Naming_Context.h b/TAO/orbsvcs/orbsvcs/Naming/Naming_Context.h
index a48ea9b3812..7aadc9fe6bf 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Naming_Context.h
+++ b/TAO/orbsvcs/orbsvcs/Naming/Naming_Context.h
@@ -204,6 +204,9 @@ class TAO_ORBSVCS_Export TAO_Naming_Context_Impl
 
 public:
 
+  virtual ~TAO_Naming_Context_Impl (void);
+  // Destructor.
+
   // = CosNaming::NamingContext idl interface methods.
 
   virtual void bind (const CosNaming::Name &n,
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.cpp b/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.cpp
index d4e563cba61..eba715964bf 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.cpp
+++ b/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.cpp
@@ -114,20 +114,25 @@ TAO_Naming_Server::init_new_naming (CORBA::ORB_ptr orb,
   ACE_TRY
     {
       if (persistence_location != 0)
+        //
+        // Initialize Persistent Naming Service.
+        //
         {
+          // Allocate and initialize Persistent Context Index.
           ACE_NEW_RETURN (this->context_index_,
                           TAO_Persistent_Context_Index (orb, poa),
                           -1);
 
-          if (this->context_index_->open (persistence_location) == -1)
-            ACE_DEBUG ((LM_DEBUG,
-                        "context_index->open failed"));
-
-          if (this->context_index_->init () == -1)
-            ACE_DEBUG ((LM_DEBUG,
-                        "context_index->init failed"));
+          if (this->context_index_->open (persistence_location) == -1
+              || this->context_index_->init (context_size) == -1)
+            {
+              if (TAO_debug_level >0)
+                ACE_DEBUG ((LM_DEBUG,
+                            "TAO_Naming_Server: context_index initialization failed\n"));
+              return -1;
+            }
 
-          // Set the ior and objref to the root naming context.
+          // Set the root Naming Context reference and ior.
           this->naming_service_ior_= this->context_index_->root_ior ();
 
           CORBA::Object_var obj =
@@ -142,6 +147,9 @@ TAO_Naming_Server::init_new_naming (CORBA::ORB_ptr orb,
         }
       else
         {
+          //
+          // Initialize Transient Naming Service.
+          //
           this->naming_context_ =
             TAO_Transient_Naming_Context::make_new_context (poa,
                                                             TAO_ROOT_NAMING_CONTEXT,
@@ -149,32 +157,39 @@ TAO_Naming_Server::init_new_naming (CORBA::ORB_ptr orb,
                                                             ACE_TRY_ENV);
           ACE_TRY_CHECK;
 
-          // Stringify the objref we'll be implementing, and print it
-          // to stdout.  Someone will take that string and give it to
-          // a client.
+          // Set the root Naming Context ior.
           this->naming_service_ior_=
             orb->object_to_string (this->naming_context_.in (),
                                    ACE_TRY_ENV);
           ACE_TRY_CHECK;
         }
 
-      // To make NS locatable through iioploc.  Right now not
-      // checking the return value.
-      orb->_tao_add_to_IOR_table ("NameService",
-                                  this->naming_context_.in ());
-
+      // Make the Naming Service locatable through iioploc.
+      if (orb->_tao_add_to_IOR_table ("NameService",
+                                      this->naming_context_.in ())
+          == -1)
+        {
+          if (TAO_debug_level >0)
+            ACE_DEBUG ((LM_DEBUG,
+                        "TAO_Naming_Server: cannot add to ior table.\n"));
+          return -1;
+        }
 #if defined (ACE_HAS_IP_MULTICAST)
+      //
+      // Install ior multicast handler.
+      //
       // Get reactor instance from TAO.
       ACE_Reactor *reactor =
         TAO_ORB_Core_instance ()->reactor ();
 
       // First, see if the user has given us a multicast port number
-      // for the name service on the command-line;
+      // on the command-line;
       u_short port =
         TAO_ORB_Core_instance ()->orb_params ()->name_service_port ();
 
       if (port == 0)
         {
+          // Check environment var. for multicast port.
           const char *port_number =
             ACE_OS::getenv ("NameServicePort");
 
@@ -182,10 +197,13 @@ TAO_Naming_Server::init_new_naming (CORBA::ORB_ptr orb,
             port = ACE_OS::atoi (port_number);
         }
 
+      // Port wasn't specified on the command-line or in environment -
+      // use the default.
       if (port == 0)
         port = TAO_DEFAULT_NAME_SERVER_REQUEST_PORT;
 
-      // Instantiate a server which will receive requests for an ior
+      // Instantiate a handler which will handle client requests for
+      // the root Naming Context ior, received on the multicast port.
       ACE_NEW_RETURN (this->ior_multicast_,
                       TAO_IOR_Multicast (this->naming_service_ior_.in (),
                                          port,
@@ -199,20 +217,19 @@ TAO_Naming_Server::init_new_naming (CORBA::ORB_ptr orb,
         {
           if (TAO_debug_level > 0)
             ACE_DEBUG ((LM_DEBUG,
-                        "cannot register Event handler\n"));
+                        "TAO_Naming_Server: cannot register Event handler\n"));
           return -1;
         }
-      else
-        {
-          if (TAO_debug_level > 0)
-            ACE_DEBUG ((LM_DEBUG,
-                        "The multicast server setup is done.\n"));
-        }
+
+      if (TAO_debug_level > 0)
+        ACE_DEBUG ((LM_DEBUG,
+                    "TAO_Naming_Server: The multicast server setup is done.\n"));
+
 #endif /* ACE_HAS_IP_MULTICAST */
     }
   ACE_CATCHANY
     {
-      ACE_PRINT_EXCEPTION (ACE_ANY_EXCEPTION, "Naming Service");
+      ACE_PRINT_EXCEPTION (ACE_ANY_EXCEPTION, "TAO_Naming_Server");
       return -1;
     }
   ACE_ENDTRY;
@@ -227,8 +244,6 @@ TAO_Naming_Server::naming_service_ior (void)
   return CORBA::string_dup (this->naming_service_ior_.in ());
 }
 
-// Returns a pointer to the NamingContext.
-
 CosNaming::NamingContext_ptr
 TAO_Naming_Server::operator-> (void) const
 {
@@ -248,16 +263,12 @@ TAO_Naming_Server::~TAO_Naming_Server (void)
   delete context_index_;
 }
 
-// Returns a pointer to the NamingContext.
-
 CosNaming::NamingContext_ptr
 TAO_Naming_Client::operator -> (void) const
 {
   return this->naming_context_.ptr ();
 }
 
-// Returns a pointer to the NamingContext.
-
 CosNaming::NamingContext_ptr
 TAO_Naming_Client::get_context (void) const
 {
@@ -272,7 +283,8 @@ TAO_Naming_Client::init (CORBA::ORB_ptr orb,
   ACE_TRY
     {
       CORBA::Object_var naming_obj =
-        orb->resolve_initial_references ("NameService", timeout);
+        orb->resolve_initial_references ("NameService", timeout, ACE_TRY_ENV);
+      ACE_TRY_CHECK;
 
       if (CORBA::is_nil (naming_obj.in ()))
         ACE_ERROR_RETURN ((LM_ERROR,
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.h b/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.h
index abf599ed60c..83f4c85eed7 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.h
+++ b/TAO/orbsvcs/orbsvcs/Naming/Naming_Utils.h
@@ -48,6 +48,17 @@ class TAO_ORBSVCS_Export TAO_Naming_Server
   //    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:
   TAO_Naming_Server (void);
   // Default constructor.
@@ -123,37 +134,39 @@ protected:
 class TAO_ORBSVCS_Export TAO_Naming_Client
 {
   // = TITLE
-  //    Defines a wrapper class that simplifies initialization and
-  //    access to a <NamingContext>.
+  //    This class is intended to simplify programs that want to play
+  //    the role of Naming Service clients.
   //
   // = DESCRIPTION
-  //    This class takes an ORB reference and contacts the
-  //    NamingService naming context object under that.  It also
+  //    Wrapper class that locates the root Naming Context.  It also
   //    defines the operator-> so that <NamingContext> functions like
-  //    <resolve>, etc. can be called on a <NameServer> object.  This
-  //    class is intended to simplify programs that want to play the
-  //    role of a Naming Service clients.
+  //    <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.
+
   TAO_Naming_Client (void);
   // Default constructor.
 
   int init (CORBA::ORB_ptr orb,
             ACE_Time_Value *timeout = 0);
-  // Initialize the name server.
+  // 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.
 
   ~TAO_Naming_Client (void);
   // Destructor.
 
   CosNaming::NamingContext_ptr operator-> (void) const;
-  // Returns a <NamingContext_ptr>.
+  // Returns a pointer to the root Naming Context.
 
   CosNaming::NamingContext_ptr get_context (void) const;
-  // Returns the NamingContext
+  // Returns a pointer to the root Naming Context.
 
 protected:
   CosNaming::NamingContext_var naming_context_;
-  // NamingContext ptr.
+  // Reference to the root Naming Context.
 };
 
 #endif /* TAO_NAMING_UTILS_H */
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.cpp b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.cpp
index a5f74068c99..97f8ecad34c 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.cpp
+++ b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.cpp
@@ -28,6 +28,7 @@ TAO_Persistent_Context_Index::bind (const char *poa_id,
 {
   ACE_GUARD_RETURN (ACE_SYNCH_MUTEX, ace_mon, this->lock_, -1);
 
+  // Allocate memory for items to be stored in the table.
   size_t poa_id_len = ACE_OS::strlen (poa_id) + 1;
   size_t counter_len = sizeof (ACE_UINT32);
   char *ptr = (char *) this->allocator_->malloc (poa_id_len + counter_len);
@@ -36,6 +37,7 @@ TAO_Persistent_Context_Index::bind (const char *poa_id,
     return -1;
   else
     {
+      // Populate memory with data.
       counter = ACE_reinterpret_cast (ACE_UINT32 *, ptr);
       *counter = 0;
       char * poa_id_ptr = ptr + counter_len;
@@ -119,8 +121,12 @@ TAO_Persistent_Context_Index::open (LPCTSTR file_name,
 }
 
 int
-TAO_Persistent_Context_Index::init (void)
+TAO_Persistent_Context_Index::init (size_t context_size)
 {
+  // Note: in case of an early exit from this (or helper) function due
+  // to an error condition, we rely on POA to clean up all of the servants
+  // already registered with it.
+
   // Return value of this function (necessary to keep compilers quiet).
   int status = 0;
 
@@ -132,8 +138,8 @@ TAO_Persistent_Context_Index::init (void)
 
       CosNaming::NamingContext_var result =
         TAO_Persistent_Naming_Context::make_new_context (poa_.in (),
-                                                         "NameService",
-                                                         ACE_DEFAULT_MAP_SIZE,
+                                                         TAO_ROOT_NAMING_CONTEXT,
+                                                         context_size,
                                                          this,
                                                          ACE_TRY_ENV);
       ACE_CHECK_RETURN (-1);
@@ -153,13 +159,13 @@ TAO_Persistent_Context_Index::init (void)
 int
 TAO_Persistent_Context_Index::recreate_all (void)
 {
-  INDEX::ITERATOR *index_iter = 0;
+  CONTEXT_INDEX::ITERATOR *index_iter = 0;
 
   ACE_NEW_RETURN (index_iter,
-                  (INDEX::ITERATOR) (*index_),
+                  (CONTEXT_INDEX::ITERATOR) (*index_),
                   -1);
 
-  ACE_Auto_Basic_Ptr<INDEX::ITERATOR> it (index_iter);
+  ACE_Auto_Basic_Ptr<CONTEXT_INDEX::ITERATOR> it (index_iter);
 
   // Because of broken old g++!!!
   typedef ACE_Hash_Map_With_Allocator<TAO_Persistent_Index_ExtId,
@@ -170,6 +176,7 @@ TAO_Persistent_Context_Index::recreate_all (void)
   if (TAO_debug_level > 0)
     ACE_DEBUG ((LM_DEBUG, "Starting to recreate Naming Contexts from the file... \n"));
 
+  // For each entry in <index_>, create a Naming Context servant.
   do
     {
       index_iter->next (entry);
@@ -198,9 +205,10 @@ TAO_Persistent_Context_Index::recreate_all (void)
       // Let <implementation> know about it's <interface>.
       context_impl->interface (context);
 
-      // Change what we hold in auto pointer.
+      // Release auto pointer and start using reference counting to
+      // control our servant.
       temp.release ();
-      ACE_Auto_Basic_Ptr<TAO_Naming_Context> temp2 (context);
+      PortableServer::ServantBase_var s = context;
 
       // Register with the POA.
       ACE_DECLARE_NEW_CORBA_ENV;
@@ -215,19 +223,13 @@ TAO_Persistent_Context_Index::recreate_all (void)
       CosNaming::NamingContext_var result = context->_this (ACE_TRY_ENV);
       ACE_CHECK_RETURN (-1);
 
-      // Give POA the ownership of this servant.
-      context->_remove_ref (ACE_TRY_ENV);
-      ACE_CHECK_RETURN (-1);
-
+      // If this is the root Naming Context, take a note of it.
       if (context_impl->root ())
         {
           this->root_ior_=
             orb_->object_to_string (result.in (), ACE_TRY_ENV);
           ACE_CHECK_RETURN (-1);
         }
-
-      temp2.release ();
-
     } while (index_iter->advance ());
 
   return 0;
@@ -236,6 +238,7 @@ TAO_Persistent_Context_Index::recreate_all (void)
 int
 TAO_Persistent_Context_Index::create_index (void)
 {
+  // Make sure that the file name is of the legal length.
   if (ACE_OS::strlen (index_file_) >= MAXNAMELEN + MAXPATHLEN)
     {
       errno = ENAMETOOLONG;
@@ -253,7 +256,7 @@ TAO_Persistent_Context_Index::create_index (void)
 #endif /* CHORUS */
 
   // Create the allocator with the appropriate options.  The name used
-  // for  the lock is the same one as used for the file.
+  // for  the lock is the same as one used for the file.
   ACE_NEW_RETURN (this->allocator_,
                   ALLOCATOR (this->index_file_,
                              this->index_file_,
@@ -261,7 +264,7 @@ TAO_Persistent_Context_Index::create_index (void)
                   -1);
 
 #if !defined (ACE_LACKS_ACCESS)
-  // Now check if the backing store has been created successfully
+  // Now check if the backing store has been created successfully.
   if (ACE_OS::access (this->index_file_, F_OK) != 0)
     ACE_ERROR_RETURN ((LM_ERROR,
                        "create_index\n"),
@@ -270,29 +273,39 @@ TAO_Persistent_Context_Index::create_index (void)
 
   void *context_index = 0;
 
-  // This is the easy case since if we find the Context Index Map
-  // we know it's already initialized.
+  // This is the easy case since if we find hash table in the
+  // memory-mapped file we know it's already initialized.
   if (this->allocator_->find (TAO_NAMING_CONTEXT_INDEX, context_index) == 0)
-    this->index_ = (INDEX *) context_index;
+    this->index_ = (CONTEXT_INDEX *) context_index;
 
+  // Create a new <index_> (because we've just created a new
+  // memory-mapped file).
   else
     {
-      size_t index_size = sizeof (INDEX);
+      size_t index_size = sizeof (CONTEXT_INDEX);
       context_index = this->allocator_->malloc (index_size);
 
-      if (context_index == 0)
-        return -1;
-
-      // @@Need to deal with exception below?
-      // Initialize the map into its memory location (e.g., shared memory).
-      ACE_NEW_RETURN (this->index_,
-                      (context_index) INDEX (this->allocator_),
-                      -1);
-
-      if (this->allocator_->bind (TAO_NAMING_CONTEXT_INDEX, context_index) == -1)
-        ACE_ERROR_RETURN ((LM_ERROR, "create_index\n"), -1);
+      if (context_index == 0
+          || create_index_helper (context_index) == -1
+          || this->allocator_->bind (TAO_NAMING_CONTEXT_INDEX,
+                                     context_index) == -1)
+        {
+          // Attempt to clean up.
+          ACE_ERROR ((LM_ERROR,
+                      "create_index\n"));
+          this->allocator_->remove ();
+          return -1;
+        }
     }
+  return 0;
+}
 
+int
+TAO_Persistent_Context_Index::create_index_helper (void *buffer)
+{
+  ACE_NEW_RETURN (this->index_,
+                  (buffer) CONTEXT_INDEX (this->allocator_),
+                  -1);
   return 0;
 }
 
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h
index 04a155a21df..2b60b3ede0f 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h
+++ b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Context_Index.h
@@ -22,87 +22,129 @@
 class TAO_ORBSVCS_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.
 
   typedef ACE_Hash_Map_With_Allocator<TAO_Persistent_Index_ExtId,
-    TAO_Persistent_Index_IntId> INDEX;
+    TAO_Persistent_Index_IntId> CONTEXT_INDEX;
+  // Hash map in which we will store info about each Persistent Naming Context.
+
   typedef ACE_Hash_Map_With_Allocator<TAO_Persistent_ExtId,
     TAO_Persistent_IntId> CONTEXT;
+  // Hash map used by Persistent Naming Context to keep its state.
+
+  typedef ACE_Allocator_Adapter <ACE_Malloc <ACE_MMAP_MEMORY_POOL, ACE_SYNCH_MUTEX>
+  > ALLOCATOR;
+  // Allocator we will be using to make the Naming Service persistent.
 
   // = Initialization and termination methods.
+
   TAO_Persistent_Context_Index (CORBA::ORB_ptr orb,
                                 PortableServer::POA_ptr poa);
-  // "Do-nothing" constructor.
+  // Constructor.
 
   int open (LPCTSTR file_name,
             void * base_address = ACE_DEFAULT_BASE_ADDR);
-  //
-
-  int init (void);
-  // go through the index of contexts and create a servant of each,
-  // and register it with POA.  If no contexts are present, create one.
+  // 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 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.
 
   ~TAO_Persistent_Context_Index (void);
-  // destructor, do some cleanup :TBD: last dtor should "compress"
-  // file
+  // 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.
 
   int bind (const char *poa_id,
             ACE_UINT32 *&counter,
             CONTEXT *hash_map);
-  // Create an entry - new context is created.
+  // 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 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).
 
-  int unbind (const char * poa_id);
-  // Unbind an entry - a context is destroyed.
+  // = Accessors.
 
   ACE_Allocator *allocator (void);
-  // accessor.
+  // Return allocator.
 
   CORBA::ORB_ptr orb (void);
-  //
-
-  char * root_ior (void);
-  //
+  // Return orb pointer.
 
-  //@@ ACE_Null_Mutex might be sufficient here.
-  typedef ACE_Allocator_Adapter <ACE_Malloc <ACE_MMAP_MEMORY_POOL, ACE_SYNCH_MUTEX>
-  > ALLOCATOR;
+  char *root_ior (void);
+  // Return ior of the root Naming Context (returns a copy - must be
+  // deallocated by the user).
 
 private:
 
   int recreate_all (void);
-  //
+  // Helper for the <init> method.  Iterates over <index_>, and
+  // creates a servant for each entry.
 
   int create_index (void);
-  // Allocate the appropriate type of map manager that stores the
-  // key/value binding.
+  // Helper for the <open> method.
+
+  int create_index_helper (void *buffer);
+  // Helper for <create_index> method: places hash table into an
+  // allocated space.
 
   ACE_SYNCH_MUTEX lock_;
   // Lock to prevent multiple threads from modifying entries in the
-  // hash map simultanneously.
+  // <index_> simultanneously.
 
   ALLOCATOR *allocator_;
-  // Pointer to the 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.
 
-  INDEX *index_;
-  // Pointer to the allocated map manager.
+  CONTEXT_INDEX *index_;
+  // Hash map where we keep entries for all Persistent Naming
+  // Contexts.
 
   LPCTSTR index_file_;
-  // Name of the file used for storage.
+  // Name of the memory-mapped file used by <allocator_>.
 
   void *base_address_;
+  // Base address for the memory-mapped file.
 
   CORBA::ORB_var orb_;
-  //
+  // ORB.  We use it for several object_to_string conversions, and
+  // keep it around for Persistent Naming Contexts' use.
 
   PortableServer::POA_var poa_;
-  //
+  // POA under which to register Persistent Naming Context servants
+  // during start-up.
 
   CORBA::String_var root_ior_;
-  //
+  // The ior of the root Naming Context.
 };
 
 #endif /* TAO_PERSISTENT_CONTEXT_INDEX_H */
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.cpp b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.cpp
index fb113e989c0..e84401349f6 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.cpp
+++ b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.cpp
@@ -50,12 +50,6 @@ TAO_Persistent_IntId::operator= (const TAO_Persistent_IntId &rhs)
   ref_ = rhs.ref_;
 }
 
-CosNaming::BindingType
-TAO_Persistent_IntId::type (void)
-{
-  return type_;
-}
-
 TAO_Persistent_ExtId::TAO_Persistent_ExtId (void)
   : id_ (0),
     kind_ (0)
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.h b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.h
index 9d90b2f5f26..69cf5d1a450 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.h
+++ b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Entries.h
@@ -28,11 +28,18 @@
 class TAO_ORBSVCS_Export TAO_Persistent_IntId
 {
   // = TITLE
-  //     Stores information a context keeps for each bound name.
+  //     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
-  //     Each bound name is associated with an object reference and
-  //     the type of binding.
+  //     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.
   TAO_Persistent_IntId (void);
@@ -49,28 +56,32 @@ public:
   // Destructor.
 
   void operator= (const TAO_Persistent_IntId & rhs);
-  // Assignment operator (does copy memory).
+  // Assignment operator.
 
-  CosNaming::BindingType type (void);
-  //
+  // = Data members.
 
-  const char * ref_;
-  // This should be allocated from shared/mmap memory.
+  const char *ref_;
+  // Stringified IOR to be stored in a Persistent Naming Context.
 
   CosNaming::BindingType type_;
-  // Indicator of whether the object is a NamingContext that should
-  // participate in name resolution when compound names are used.
+  // Binding type for <ref_>.
 };
 
 class TAO_ORBSVCS_Export TAO_Persistent_ExtId
 {
   // = TITLE
-  //    Stores the name to which an object is bound.
+  //     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 is used as the External ID for the
-  //    <ACE_Hash_Map_Manager>.  We do not allocate memory for <id>
-  //    and <kind>, we do not deallocate it.
+  //     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.
 
@@ -87,6 +98,8 @@ public:
   ~TAO_Persistent_ExtId (void);
   // Destructor.
 
+  // = Assignment and comparison methods.
+
   void operator= (const TAO_Persistent_ExtId & rhs);
   // Assignment operator (does copy memory).
 
@@ -97,13 +110,21 @@ public:
   // Inequality comparison operator.
 
   u_long hash (void) const;
-  // This class has to have a hash for use with ACE_Hash_Map_Manager.
+  // <hash> function is required in order for this class to be usable by
+  // ACE_Hash_Map_Manager.
+
+  // = Data members.
 
   const char * id_;
+  // <kind> portion of the name to be associated with some object
+  // reference in a Persistent Naming Context.
+
   const char * kind_;
-  // These point into shared/mmaped memory.
+  // <id> portion of the name to be associated with some object
+  // reference in a Persistent Naming Context.
 
   // Accessors.
+
   const char * id (void);
   const char * kind (void);
 };
@@ -111,11 +132,17 @@ public:
 class TAO_ORBSVCS_Export TAO_Persistent_Index_IntId
 {
   // = TITLE
-  //     Stores information about a context.
+  //     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
-  //     Each context
-  //     the type of binding.
+  //     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.
   TAO_Persistent_Index_IntId (void);
@@ -135,23 +162,30 @@ public:
   void operator= (const TAO_Persistent_Index_IntId & rhs);
   // Assignment operator (does copy memory).
 
+  // = Data members.
+
   ACE_UINT32 *counter_;
-  //
+  // Pointer to a Persistent Naming Context's counter.
 
   ACE_Hash_Map_With_Allocator<TAO_Persistent_ExtId,
     TAO_Persistent_IntId> * hash_map_;
-  // The pointer to the context's bindings hash map.
+  // Pointer to a Persistent Naming Context's hash map.
 };
 
 class TAO_ORBSVCS_Export TAO_Persistent_Index_ExtId
 {
   // = TITLE
-  //    Stores the poa_id of a context.
+  //    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
-  //    This class is used as the External ID for the
-  //    <ACE_Hash_Map_Manager>.  We do not allocate memory for
-  //    <poa_id>, we do not deallocate it.
+  //    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.
 
@@ -167,6 +201,8 @@ public:
   ~TAO_Persistent_Index_ExtId (void);
   // Destructor.
 
+  // = Assignment and comparison methods.
+
   void operator= (const TAO_Persistent_Index_ExtId & rhs);
   // Assignment operator (does copy memory).
 
@@ -177,11 +213,14 @@ public:
   // Inequality comparison operator.
 
   u_long hash (void) const;
-  // This class has to have a hash for use with ACE_Hash_Map_Manager.
+  // <hash> function is required in order for this class to be usable by
+  // ACE_Hash_Map_Manager.
 
-  const char * poa_id_;
-  // These point into shared/mmaped memory.
+  // = Data member.
 
+  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.
 };
 
 #endif /* TAO_PERSISTENT_ENTRIES_H */
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.cpp b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.cpp
index a805e00d505..6542dc39e89 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.cpp
+++ b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.cpp
@@ -73,7 +73,7 @@ TAO_Persistent_Bindings_Map::find (const char *id,
       ACE_DECLARE_NEW_CORBA_ENV;
       obj = orb_->string_to_object (entry.ref_, ACE_TRY_ENV);
       ACE_CHECK_RETURN (-1);
-      type = entry.type ();
+      type = entry.type_;
 
       return 0;
     }
@@ -93,7 +93,7 @@ TAO_Persistent_Bindings_Map::~TAO_Persistent_Bindings_Map (void)
 void
 TAO_Persistent_Bindings_Map::destroy (void)
 {
-//  (void) this->map_->~ACE_Hash_Map_With_Allocator ();
+  this->map_->ACE_Hash_Map_With_Allocator<TAO_Persistent_ExtId, TAO_Persistent_IntId>::~ACE_Hash_Map_With_Allocator ();
   this->allocator_->free (map_);
 }
 
@@ -211,29 +211,40 @@ TAO_Persistent_Bindings_Map::shared_bind (const char * id,
             }
         }
       else
+        // Rebind.
         {
-          // Do a rebind.  If there's already any entry, this will return the existing
-          // <new_name> and <new_internal> and overwrite the existing name binding.
           TAO_Persistent_ExtId old_name;
           TAO_Persistent_IntId old_entry;
 
-          result = this->map_->rebind (new_name, new_entry,
-                                       old_name, old_entry,
-                                       this->allocator_);
+          // Check that the types of old and new entries match.
+          if (this->map_->find (new_name,
+                                old_entry,
+                                this->allocator_) == 0
+              && type != old_entry.type_)
+            result = -2;
+
+          // If types match, perform rebind.
+          else
+            result = this->map_->rebind (new_name, new_entry,
+                                         old_name, old_entry,
+                                         this->allocator_);
           if (result == 1)
             {
-              // Free up the memory we allocated in shared_bind().  Note that this
-              // assumes that the "ref" pointer comes first and that the id,
-              // kind, and ref are contiguously allocated (see above for details)
+              // Free up the old binding's memory, if it was replaced.
+              // Note, this assumes that the "ref" pointer comes
+              // first, and that the id, kind, and ref are contiguously
+              // allocated (see beginning of this method for details).
               this->allocator_->free ((void *) old_entry.ref_);
             }
         }
 
-      if (result == -1)
-        // Free our dynamically allocated memory.
+      // Check for failures, and clean up dynamically allocated memory
+      // if necessary.
+      if (result < 0)
         this->allocator_->free ((void *) ptr);
+
       else
-        // If bind() or rebind() succeed, they will automatically sync
+        // If bind() or rebind() succeeded, they will automatically sync
         // up the map manager entry.  However, we must sync up our
         // name/value memory.
         this->allocator_->sync (ptr, total_len);
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h
index d1a1f83a65d..1f1338d4ec9 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h
+++ b/TAO/orbsvcs/orbsvcs/Naming/Persistent_Naming_Context.h
@@ -86,8 +86,9 @@ public:
                       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.  Returns
-  // -1 on failure.
+  // 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 unbind (const char * id,
                       const char * kind);
diff --git a/TAO/orbsvcs/orbsvcs/Naming/README b/TAO/orbsvcs/orbsvcs/Naming/README
index ac89e7bebe2..ced27c7503f 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/README
+++ b/TAO/orbsvcs/orbsvcs/Naming/README
@@ -1,73 +1,68 @@
-// $Id:
+// $Id$
 
 CONTENT
+=======
+This directory contains files implementing CosNaming idl interfaces
+(from CORBA COSS), as well as a few utilities.  Server code, service
+executable, and documentation for using the service are located in
+$TAO_ROOT/orbsvcs/Naming_Service.
 
-This directory contains files implementing CosNaming idl interface
-from CORBA COSS, as well as a few utilities.
 
+UTILITIES
+=========
+Naming_Utils.{h,cpp} contain utility classes that can simplify
+programs which play a role of Naming Service server or client.  See
+$TAO_ROOT/orbsvcs/Naming_Service/Naming_Service.{h,cpp} and
+$TAO_ROOT/orbsvcs/tests/Simple_Naming/client.{h,cpp} for examples of
+using these classes.
 
-ARCHITECTURE
 
-The architecture of the Naming Service (i.e., CosNaming)
-implementation follows the Bridge pattern.
-Below is the list of player classes:
+IMPLEMENTATION
+==============
+The architecture for TAO's implementation of CosNaming::NamingContext
+interface follows the Bridge pattern.
 
- * TAO_Naming_Context (in Naming_Context.h) - this class inherits from
-   POA skeleton, and plays the role of 'Abstraction' (aka 'Interface') -
-   it forwards all client requests to a 'ConcreteImplementor' through an
-   'Implementor' pointer.
+ * TAO_Naming_Context (in Naming_Context.h) inherits from
+   POA skeleton, and plays the role of 'Abstraction' (aka 'Interface')
+   in the Bridge architecture - it forwards all client
+   requests to a 'ConcreteImplementor' through an 'Implementor' pointer.
 
- * TAO_Naming_Context_Impl (in Naming_Context.h) - this is an abstract base class for all
+ * TAO_Naming_Context_Impl (in Naming_Context.h) is an abstract base class for all
    concrete implementations of NamingContext functionality (i.e., 'Implementor').
 
- * TAO_Hash_Naming_Context (in Hash_Naming_Context.h) - this
-   class inherits from TAO_Naming_Context_Impl.  It is a
-   'ConcreteImplementor' which uses ACE_Hash_Map_Manager to implement
-   NamingContext functionality.
-
- * A set of classes implementing a persistent version of the Naming
-   Context functionality.  These are the classes in
-   Shared_Hash_Map_T.{h, cpp}, and Persistent* files.
-
-The class structure described above makes it easy to:
-
-1) Create and plug different Naming Service implementations by
+ * Currently, TAO Naming Service has two 'ConcreteImplementors':
+   TAO_Transient_Naming_Context (in Transient_Naming_Context.h), and
+   TAO_Persistent_Naming_Context (in Persistent_Naming_Context.h),
+   providing non-persistent and persistent, hash-table-based implementations of the
+   NamingContext functionality, correspondingly.  Both
+   'ConcreteImplementors' inherit from TAO_Hash_Naming_Context (in
+   Hash_Naming_Context.h), which, in turn, inherits from
+   TAO_Naming_Context_Impl.  TAO_Hash_Naming_Context factors out code
+   common to both 'ConcreteImplementors'. (Here we have a form of the
+   Template Method pattern).
+
+*  Other major classes:
+   - TAO_Persistent_Context_Index - facilitates implementation of the
+     Persistent version of the Naming Service.
+   - TAO_BindingsIterator - implements CosNaming::BindingIterator
+     interface.  Can be used with either of the NamingContext 'ConcreteImplementors'.
+
+*  Persistent implementation of the Naming Service uses ACE_Allocators
+   and memory-mapped files.
+
+The Bridge implementation class structure makes it easy to:
+
+1) Create and plug-in different CosNaming::NamingContext implementations by
    subclassing TAO_Naming_Context_Impl.
 
-2) Dynamically load an appropriate Naming Service implementation at
-   run-time based on the config file entry by making TAO_Naming_Context_Impl
-   inherit from ACE_Service_Object, etc.
-
+2) Dynamically load an appropriate NamingContext implementation at
+   run-time, based on the config file entry, by making TAO_Naming_Context_Impl
+   inherit from ACE_Service_Object...
 
-PERSISTENCE
-
-The first version of Persistent Naming implementation is here!
-It is based on the memory-mapped files.  Directions on how to use the
-Persistent version of the Naming Service can be found in
-TAO/orbsvcs/Naming_Service/README (by using a command-line option).
-
-The current set of classes implementing persistent version of the
-Naming Service will be restructured for one of the upcoming releases
-(to factor out commonality, get rid of unnecessary generality, etc.),
-at which time more documentation will be available in this README file
-and in the source code.
 
 TO-DO
-
-- code review/comments of Entries, Persistent_Entries,
-  Persistent_Context_Index, Naming_Utils, Bindings_Iterator
-
-- Update README file
-- Factor out Naming_Util initialization code into a factory
-- make sure we can pass hash_table_size to Persistent Naming Context.
-
-- purify
-
-- Check for proper destruction of contexts
-
---------------------------------------------------
-- update Naming Service slides.
-
-- do code review of Simple_Naming.
-
-- add Load Balancing functionality.
+=====
+Extend CosNaming::NamingContext interface and its implementation to
+support binding of more than one object per name and name
+resolution according to policies (e.g., random or round robin), to provide
+Load Balancing functionality.
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.cpp b/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.cpp
index e0ec6bf8302..7d68701e129 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.cpp
+++ b/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.cpp
@@ -100,6 +100,7 @@ TAO_Transient_Bindings_Map::shared_bind (const char * id,
 {
   TAO_ExtId new_name (id, kind);
   TAO_IntId new_entry (obj, type);
+  TAO_IntId old_entry;
 
   if (rebind == 0)
     // Do a normal bind.
@@ -107,7 +108,16 @@ TAO_Transient_Bindings_Map::shared_bind (const char * id,
 
   else
     // Rebind.
-    return this->map_.rebind (new_name, new_entry);
+    {
+      // Check that types of old and new entries match.
+      if (this->map_.find (new_name,
+                           old_entry) == 0
+          && type != old_entry.type_)
+        return -2;
+
+      else
+        return this->map_.rebind (new_name, new_entry);
+    }
 }
 
 TAO_Transient_Naming_Context::TAO_Transient_Naming_Context (PortableServer::POA_ptr poa,
diff --git a/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h b/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h
index 07d03d9af60..b561ef6aa70 100644
--- a/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h
+++ b/TAO/orbsvcs/orbsvcs/Naming/Transient_Naming_Context.h
@@ -73,8 +73,9 @@ public:
                       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.  Returns
-  // -1 on failure.
+  // 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 unbind (const char * id,
                       const char * kind);
diff --git a/TAO/orbsvcs/tests/Simple_Naming/README b/TAO/orbsvcs/tests/Simple_Naming/README
index 57cda7c6b08..5e8c01ad0d3 100644
--- a/TAO/orbsvcs/tests/Simple_Naming/README
+++ b/TAO/orbsvcs/tests/Simple_Naming/README
@@ -8,7 +8,7 @@ To run all tests automatically -
 To run tests manually -
 	start the Naming Service (see
 	TAO/orbsvcs/Naming_Service/README for valid options),
-	then run ./client with one of the options below.       
+	then run ./client with one of the options below.
 
 NOTE: if running tests manually, Naming Service has to be restarted
 before each test (this is due to some tests not 'cleaning up' bindings
@@ -32,21 +32,21 @@ The following options exist:
         output should be redirected to some file, say, "foo".  Then,
         "process-m-output.pl" script can be used to analyze the test
         output and print out a diagnostic message.  Invoke the output
-        processing script like so: 
-        "process-m-output.pl foo number_of_threads", 
-        where <foo> is the name of the file containing test output, 
+        processing script like so:
+        "process-m-output.pl foo number_of_threads",
+        where <foo> is the name of the file containing test output,
         and <number_of_threads> is the argument that was supplied with
         "-m" option  to the client.)
 
         Example (on a Unix system):
-        $ ../../Naming_Service &        
-        $ ./client -m 10 >& foo         
-        $ ./process-m-output.pl foo 10        
+        $ ../../Naming_Service &
+        $ ./client -m 10 >& foo
+        $ ./process-m-output.pl foo 10
 
         where the steps correspond to 1)starting the Naming Service,
         2) running the client and redirecting the output to a file,
         and 3) running the diagnostic script.
-        Don't forget to kill the Naming Service after you are done.        
+        Don't forget to kill the Naming Service after you are done.
 
 Persistent test consists of two parts (below).
 
@@ -59,7 +59,7 @@ Persistent test consists of two parts (below).
         The values for these options must be the same for both runs of
         the Naming Service (i.e., for part 1 and part 2 of persistent test).
 
--c <ior> 
+-c <ior>
         Run the Persistent Naming Service test, part 2.  Requires an
         argument specifying the ior, which was produced in part 1 of
         the test.  Note, in order to test out persistent capabilities
@@ -172,7 +172,7 @@ root->resolve () (with a Name of length 0) - should get InvalidName exception.
 root->bind (foo, obj) - should get AlreadyBound exception.
 root->bind (level1/foo, obj) - should get AlreadyBound exception.
 root->unbind (level1/level2/bar) - should get NotFound exception
-  with why = not_object, rest_of_name = bar.
+  with why = missing_node, rest_of_name = bar.
 root->unbind (level1/level3/foo) - should get NotFound exception
   with why = missing_node, rest_of_name = level3/foo.
 root->unbind (level1/foo/foo) -should get NotFound exception
diff --git a/TAO/orbsvcs/tests/Simple_Naming/client.cpp b/TAO/orbsvcs/tests/Simple_Naming/client.cpp
index 46eb7d4238f..9233d1c1b04 100644
--- a/TAO/orbsvcs/tests/Simple_Naming/client.cpp
+++ b/TAO/orbsvcs/tests/Simple_Naming/client.cpp
@@ -823,7 +823,7 @@ Exceptions_Test::not_found_test (TAO_Naming_Client &root_context,
     }
   ACE_CATCH (CosNaming::NamingContext::NotFound, ex)
     {
-      if (ex.why == CosNaming::NamingContext::not_object &&
+      if (ex.why == CosNaming::NamingContext::missing_node &&
           ex.rest_of_name.length () == 1
           && ACE_OS::strcmp (ex.rest_of_name[0].id.in (),
                              "bar") == 0)