ChangeLogTag:Thu May 11 12:27:35 2000 Carlos O'Ryan <coryan@uci.edu>

2 files changed, 227 insertions, 129 deletions

diff --git a/TAO/docs/tutorials/Quoter/Simple/Persistent/index.html b/TAO/docs/tutorials/Quoter/Simple/Persistent/index.html
index d2d5236399f..c227387f8f2 100644
--- a/TAO/docs/tutorials/Quoter/Simple/Persistent/index.html
+++ b/TAO/docs/tutorials/Quoter/Simple/Persistent/index.html
@@ -12,49 +12,97 @@
 
     <h3>Introduction - Improving the Server</h3>
     
-    <P>In this section, we will improve the <a href = ../Server/server.cpp> 
-    simple server</a>  which we have developed before. We will use POA policies
-    to create an object with a persistent object reference. </P>
+    <P>In this section, we will improve the
+      <!-- @@ Priyanka: I think the HTML spec requires you to use
+      quotes for all URLs
+      -->
+      <A HREF="../Server/server.cpp">
+	simple server
+      </A>
+      which we have developed before. We will use POA policies
+      to create an object with a persistent object reference.
+    </P>
     <P>
-    The characteristics of a POA are controlled via POA policies. These POA 
-    policies are specified when the POA is created. POA policies have the 
-    same form: their values are specified using an enumerated type. One such 
-    policy is the LifeSpanPolicy.The LifespanPolicyValue can be Transient or 
-    Persistent.
+      The characteristics of a POA are controlled via POA policies,
+      that are specified when the POA is created.
+      POA policies are have the same form: their values are specified
+      at creation time using an enumerated type.
+      In our example we will use the <CODE>LifeSpanPolicy</CODE>
+      that controls how the lifetime of object references relates to
+      the lifetime of the POAs that generate the object reference
+      and the <CODE>IdAssingmentPolicy</CODE> that controls how are
+      object ids assigned.
     </P>
 
-    <P> CORBA objects that can live irrespective of any particular process in 
-      which they are created or activated are called Persistent Objects. 
-      The shorter-lived objects whose life time is bounded by the lifetime of 
-      the POA in which they are created are called Transient Objects.
-    </P>
-    <P> The standard life span policy for the RootPOA is Transient. This means
-      that any application that needs to support persistent objects must create
-      at least another POA with the Persistent life span policy. 
+    <P>
+      CORBA Objects that can live irrespective of any particular
+      process in which they are created or activated are called
+      <EM>Persistent Objects</EM>,
+      likewise,
+      shorter-lived objects whose life time is bound to the
+      lifetime of the POA in which they are created are called
+      <EM>Transient Objects</EM>.
+      Notice that this has nothing to do with the state of the object,
+      an application can create transient objects to access some
+      persistent information maintained in a database,
+      for exammple,
+      the object can represent a different session or transaction view
+      of the data,
+      simlilarly, some persistent object references may have no state
+      or no persistent state,
+      for example, a logging facility is persistent because it is
+      always available, but it may maintain no state or simply cache
+      some state for the current activation.
+      In general though,
+      objects that have persistent state are accessed throught
+      persistent object references.
     </P>
-    <P> Let's create a new child POA with the RootPOA as its 
-      parent. We will create two policies for this childPOA. One policy is the 
-      Life Span Policy which we will set to be Persistent. The second policy 
-      is the Id Assignment Policy. 
+    <P>
+      The standard life span policy for the RootPOA is
+      <CODE>TRANSIENT</CODE>.
+      This means that any application that needs to support persistent
+      objects must create at least another POA with the Persistent
+      life span policy.
+      In our example we will create two policies for this child POA.
+      One policy is the <CODE>LifeSpanPolicy</CODE> which we will set
+      to be <CODE>PERSISTENT</CODE>.
+      Usually applications that create persistent object references
+      also set the <CODE>IdAssignmentPolicy</CODE>,
+      so they can assign the object ids in a predictable way,
+      consistent across server activations.
+      It is possible, but very unusual, to use system ids with
+      persistent object references.
     </P>
-    <P> A POA identifies its object by an object identifier, specified 
-      using the ObjectId type, defined in the PortableServer module. Within the
-      scope of a POA, all Object IDs must be unique. An application can either 
-      supply its own ObjectID or have the POA create object identifiers for it.
+    <!--
+    <P>A POA identifies its object by an object identifier, specified 
+      using the ObjectId type, defined in the PortableServer module.
+      Within the scope of a POA, all Object IDs must be unique.
+      An application can either supply its own ObjectID or have the
+      POA create object identifiers for it.
       This Object identification is controlled by the IdAssignmentPolicy. If
       the policy value is set to be <CODE>USER_ID</CODE>, the application has 
-      the choice. Else, if this policy value is set to be 
-      <CODE>SYSTEM_ID</CODE>, the RootPOA creates the ObjectIDs. Let's give our 
+      the choice. Otherwise, if this policy value is set to be 
+      <CODE>SYSTEM_ID</CODE>, the RootPOA creates the ObjectIDs.
+      Let's give our 
       application a choice for the creation of its Object's IDs. 
     </P>
-    <P>For more about POA and its policies, please refer Advanced CORBA 
-      Programming with C++ by Henning and Vinoski. There are many examples in 
-      <CODE>$TAO_ROOT/examples/POA/</CODE> that show how to use the other 
-      policies in the POA.
+    -->
+    <P>For more about POA and its policies,
+      please refer to
+      "Advanced CORBA Programming with C++"
+      by Henning and Vinoski.
+      The TAO distribution also includes many examples on how to use
+      the POA and its policies in the 
+      <CODE>$TAO_ROOT/examples/POA</CODE> 
+      directory.
     </P> 
-    <H3> Child POA Creation </H3>
+
+    <H3>Child POA Creation</H3>
      
-    As before we first initialize the ORB, get a reference to the Root POA.
+    <P>
+      As before we first initialize the ORB,
+      and obtain a reference to the Root POA.
+    </P>
  <PRE>
     CORBA::ORB_var orb = CORBA::ORB_init (argc, argv);
     CORBA::Object_var poa_object = 
@@ -62,8 +110,11 @@
     PortableServer::POA_var poa = 
       PortableServer::POA::_narrow (poa_object.in ());
  </PRE>    
-    
-    Next get the POAManager of the RootPOA and activate it. 
+
+    <P>
+      Next get the <CODE>POAManager</CODE> of the <CODE>RootPOA</CODE>
+      and use it to activate the <CODE>RootPOA</CODE>
+    </P>
  <PRE>
     PortableServer::POAManager_var poa_manager = 
       poa->the_POAManager ();
@@ -71,45 +122,41 @@
     poa_manager->activate ();
  </PRE>
     
-    <P>The policies of a POA are stored in a sequence. Let's first create a 
-      CORBA::PolicyList sequence. Since we are creating two policies, let's 
-      initialize its length to be 2.
-    </P> 
- <PRE>
-    CORBA::PolicyList polices;
-    policies.length (2);
- </PRE>
-    <P> Now to create a LifeSpanPolicy Object and an IdAssignmentpolicy Object.
-      We use the <CODE>create_lifespan_policy</CODE> operation of the Root POA
-      to create a LifespanPolicy object.Since we want the POA to be 
-      <CODE>PERSISTENT</CODE>, we pass the same as its value. For creating the 
-      IdAssignmentPolicy object, we use the 
-      <CODE>create_id_assignment_policy</CODE> operation of the Root POA and 
-      pass <CODE>USER_ID</CODE> as its value. 
-    </P>
+    <P>
+      Now we create a <CODE>LifeSpanPolicy</CODE>
+      object with the <CODE>PERSISTENT</CODE> value:
  <PRE>
     // Create a PERSISTENT LifespanPolicy object
     PortableServer::LifespanPolicy_var lifespan = 
-      poa->create_lifespan_policy (PortableServer::PERSISTENT); 
-    
+      poa->create_lifespan_policy (PortableServer::PERSISTENT);
+</PRE>
+    <P>
+      and next we create <CODE>IdAssignmentPolicy</CODE> object with
+      the <CODE>USER_ID</CODE> value:
+    </P>
+<PRE>    
     // Create a USER_ID IdAssignmentPolicy object
     PortableServer::IdAssignmentPolicy_var idassignment = 
       poa->create_id_assignment_policy (PortableServer::USER_ID);
  </PRE>
-    <P>Now that we have created the respective objects, we copy our reference
-      to these objects into the policy list.
+    <P>Next we can initialize the sequence of policies:
     </P>
  <PRE>
+    CORBA::PolicyList polices;
+    policies.length (2);
     policies[0] =
       PortableServer::IdAssignmentPolicy::_duplicate (idassignment);
     policies[1] = 
       PortableServer::LifespanPolicy::_duplicate (lifespan);
  </PRE>
-    <P> Now let's come to the actual creation of the child POA. We create a POA
-      by invoking the <CODE>create_POA</CODE> on the POA for which we want to 
-      create the new child POA. Here, in our case, the RootPOA is the parent 
-      POA and the child POA is its child. So, we will invoke the 
-      <CODE>create_POA</CODE> operation on the RootPOA.
+    <!-- @@ Priyanka: I noticed that you used "let's" and "doesn't"
+    several times, I understand that it is not good style for
+    professional looking documents, then again it may be my fault,
+    because I was really loose on the first set of tutorials.
+    -->
+    <P>Now let's come to the actual creation of the child POA.
+      Child POAs are created using the <CODE>create_POA</CODE>
+      operation on the parent POA.
     </P>
  <PRE>
     PortableServer::POA_var child_poa = 
@@ -119,8 +166,11 @@
  </PRE>
     <P>The values which we pass to this <CODE>create_POA</CODE> operation are
       the name of the child POA, the POAManager of the child POA and the 
-      <CODE>CORBA::PolicyList</CODE>. Here, we have the POAManager of its 
-      parent, i.e. the RootPOAs POAManager, as the childPOA's POAManager.  
+      <CODE>CORBA::PolicyList</CODE>.
+      We can create a child controlled by a new
+      <CODE>POAManager</CODE> by passing
+      a nil reference, but commonly the <CODE>POAManager</CODE> of the
+      parent is used.
     </P>
     <P> Finally, we can now destroy the life span policy and id assignment 
       policy objects since they are no longer needed. The 
@@ -132,7 +182,9 @@
     idassignment->destroy ();
     lifespan->destroy ();
  </PRE>
-    <H3> Activating Objects in the child POA </H3>
+
+    <H3>Activating Objects in the child POA </H3>
+
     <P>Now that we have created a new POA, let's use this POA to activate the
       stock objects. The first step would be to create an instance of the 
       stock factory implementation. 
@@ -140,36 +192,37 @@
     // Create a servant of class Quoter_Stock_Factory_i
     Quoter_Stock_Factory_i stock_factory_i;
   </PRE>
-    <P>Now, we have to activate it. One of the most easy ways to 
-      activate an object is to use the POA object activation operations. One 
-      of the two operations is the <CODE>activate_object_with_id ()</CODE> 
-      operation. This operation has two input parameters: the Objects Id and 
-      the servant to incarnate the object. So, for this, we have to first 
-      get the ObjectId.
+    <P>
+      Objects can be activated explicitly using the
+      <CODE>activate_object_with_id ()</CODE> 
+      operation.
+      This operation has two input parameters:
+      id of the object and a pointer to the servant that implements
+      it.
+      We create the id using a helper function:
     </P>
  <PRE>
     PortableServer::ObjectId_var oid = 
       PortableServer::string_to_ObjectId ("Stock_Factory");
  </PRE>
-    <P>Here, we have used the <CODE>string_to_ObjectId</CODE> helper function
-      to convert the string "Stock_Factory" into an ObjectId. Now we can 
-      activate the "Stock_Factory" object.
+    <P>Next, we can activate the "Stock_Factory" object:
     </P>
  <PRE>
     child_poa->activate_object_with_id (oid.in (),
                                         &stock_factory_i);
  </PRE>
-    <P>This operation doesnt return the object reference of the new object. One
-      way to get the object reference is to invoke the 
-      <CODE>id_to_reference</CODE> operation on the POA after activating the 
-      object.
+    <P>
+      This operation does not return the object reference of the new
+      object,
+      but we can use the <CODE>id_to_reference</CODE> operation
+      to obtain the object reference:
     </P>
  <PRE>
     CORBA::Object_var stock_factory = 
       child_poa->id_to_reference (oid.in ());
  </PRE>
-    <P>Next, as before, we convert the object reference into an IOR string so 
-      that the client can use it.
+    <P>As before, we convert the object reference into an IOR string
+      so that the client can use it.
     </P>
  <PRE>
     CORBA::String_var ior = orb->object_to_string (stock_factory.in ());
@@ -186,6 +239,7 @@
     poa->destroy (1,1);
     orb->destroy ();
  </PRE>
+
     <H3>Exercise</H3>
 
     Modify the <a href=../Server/server.cpp>server.cpp</a> in the simple
@@ -198,22 +252,42 @@
     <a href=../Server/Stock_Factory_i.cpp>Stock_Factory_i.cpp</a>
     You can use this <a href=Makefile>Makefile</a>.
     <H3>Solution</H3>
-    Compare your server.cpp with <a href = server.cpp>server.cpp</a> file. 
+    Compare your server.cpp with
+    <a href="server.cpp">
+      server.cpp
+    </a> file. 
     
     <H3>Testing</H3>
     You can use the <a href=../Client/client.cpp>client.cpp</a> to check
     the results, as follows:
  <PRE>
-    $ ./server -ORBENDPOINT iiop://doc.ece.uci.edu:12345 > server.ref &
-    [1] 6933
+    $ ./server -ORBEndPoint iiop://localhost:12345 > server.ref &
  </PRE>
-    <P>What we did here is telling the server ORB to listen for requests on the
-      interface specified by the endpoint.For example, for the IIOP protocol, 
-      the endpoint information contains an Internet domain name or IP address 
-      and a TCP port number, basically in 
-      <CODE>iiop://hostname:port</CODE> format. 
+
+    <P>Normally the ORB selects a listening endpoint at random,
+      this is inadequate for applications with persistent object
+      references because the references will become invalid if the
+      server restarts in a new listening endpoint.
+      In TAO we can control the listening endpont(s) using the
+      <!-- @@ Priyanka: can you add a URL for the document that
+      describes all the ORB options?
+      -->
+      <CODE>-ORBEndPoint</CODE> option.
+      For example, for the IIOP protocol,
+      the endpoint information contains the name or IP address of the
+      host and a free TCP port number.
+      In the next
+      <A HREF="../Impl-Repo/index.html">
+	tutorial
+      </A>
+      we will learn how we can use
+      <!-- @@ Priyanka: can you add a URL for the document that
+      describes the implementation repository?
+      -->
+      Implementation Repository to work with persistent object
+      references without setting the listening endpoint explicitly.
     </P>
-    <P> Now, for the client part.
+    <P> The client is executed as usual:
     </P>
  <PRE>
     $ ./client file://server.ref MSFT RHAT
@@ -223,7 +297,7 @@
     </P>
  <PRE> 
     $ kill %1
-    $ ./server -ORBENDPOINT iiop://doc.ece.uci.edu:12345 > foo.ref &
+    $ ./server -ORBEndPoint iiop://localhost:12345 > foo.ref &
     [2] 6941
  </PRE>
     <P>If we run the client again,  we must get the result from the server 
@@ -232,8 +306,9 @@
  <PRE>
     $ ./client file://server.ref MSFT RHAT
  </PRE>
-    <P>What happens if we don't tell the server to listen from the same port?
-      Let's compile and run as we did in our simple server.
+    <P>What happens if we don't tell the server to listen from the
+      same port?
+      Let's try to run the new server as usual:
     </P>
  <PRE>
     $ ./server > server.ref &
@@ -247,32 +322,55 @@
     $ ./client file://server.ref MSFT RHAT
         CORBA exception raised!TRANSIENT (IDL:omg.org/CORBA/TRANSIENT:1.0)
  </PRE>
-    <P> A CORBA exception is raised saying that the object is a Transient one.
-      Since if the port is not specified, the ORB will listen to a random empty
-      port each time a new request arrives. Thsi results in the object being 
-      transient. 
+    <!-- @@ Priyanka: check my comments on what a TRANSIENT exception
+    means
+    -->
+    <P>A CORBA TRANSIENT exception is raised,
+      this indicates that some of the resources required to perform
+      the request are not available,
+      in this case the client ORB cannot find the server on the
+      expected port number,
+      without an Implementation Repository the client ORB cannot
+      locate the server in its new port,
+      it has to assume that the server is temporarly down,
+      and could be restarted in the future,
+      thus the TRANSIENT exception.
     </P> 
 
     <H3>More Reading</H3>
 
-    <P>The <A
-HREF="http://www.triodia.com/staff/michi-henning.html">Henning</A> and
-<A HREF="http://www.iona.com/hyplan/vinoski/">Vinoski</A> <A HREF="http://www.iona.com/hyplan/vinoski/#book">CORBA book</A> discusses POA policies in detail.  Likewise, 
-      the Schmidt and Vinoski 
-      <A HREF="http://www.cs.wustl.edu/~schmidt/report-doc.html">columns
+    <P>The
+      <A HREF="http://www.triodia.com/staff/michi-henning.html">
+	Henning
+      </A> 
+      and
+      <A HREF="http://www.iona.com/hyplan/vinoski/">
+	Vinoski
+      </A>
+      <A HREF="http://www.iona.com/hyplan/vinoski/#book">
+	CORBA book
+      </A> discusses POA policies in detail.
+      Likewise, the Schmidt and Vinoski 
+      <A HREF="http://www.cs.wustl.edu/~schmidt/report-doc.html">
+	columns
+      </A>
+      in C++ Report also include several articles about the POA.
+      Finally, the
+      <A HREF="http://www.cs.wustl.edu/~schmidt/TAO.html">
+	TAO
+      </A>
+      distribution includes several
+      <A HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/examples/POA">
+	examples
       </A>
-      in C++ Report also include several articles about the POA.  Finally,
-      the <A HREF="http://www.cs.wustl.edu/~schmidt/TAO.html">TAO</a> distribution includes 
-      <A
-HREF="http://www.cs.wustl.edu/~schmidt/ACE_wrappers/TAO/examples/POA">examples</A>
-that illustrate how to use the POA policies.
+      that illustrate how to use the POA policies.
     </P>
 
     <hr>
     <address><a href="mailto:pgontla@ece.uci.edu">Priyanka Gontla</a></address>
 <!-- Created: Wed Mar  1 20:29:59 PST 2000 -->
 <!-- hhmts start -->
-Last modified: Mon Apr  3 02:27:29 CDT 2000
+Last modified: Thu May 11 12:27:24 PDT 2000
 <!-- hhmts end -->
   </body>
 </html>
diff --git a/TAO/docs/tutorials/Quoter/Simple/Persistent/server.cpp b/TAO/docs/tutorials/Quoter/Simple/Persistent/server.cpp
index c542dcec18c..86775aa76f7 100644
--- a/TAO/docs/tutorials/Quoter/Simple/Persistent/server.cpp
+++ b/TAO/docs/tutorials/Quoter/Simple/Persistent/server.cpp
@@ -2,9 +2,9 @@
 
 //===========================================================================
 //
-// = FILENAME 
+// = FILENAME
 //     server.cpp
-// 
+//
 // = DESCRIPTION
 //
 //     In this example, a new POA (childPOA) is created and its
@@ -18,51 +18,51 @@
 #include "Stock_Factory_i.h"
 #include <iostream.h>
 
-int 
+int
 main (int argc, char *argv[])
 {
   try {
-    
+
     // Initialze the ORB.
     CORBA::ORB_var orb = CORBA::ORB_init (argc, argv);
-    
+
     // Get a reference to the RootPOA.
     CORBA::Object_var obj = orb->resolve_initial_references ("RootPOA");
-    
+
     // Get the POA_var object from Object_var.
-    PortableServer::POA_var root_poa = 
+    PortableServer::POA_var root_poa =
       PortableServer::POA::_narrow (obj.in ());
-    
+
     // Get the POAManager of the RootPOA.
-    PortableServer::POAManager_var poa_manager = 
+    PortableServer::POAManager_var poa_manager =
       root_poa->the_POAManager ();
-    
+
     poa_manager->activate ();
-    
+
     // Create a USER_ID IdAssignmentpolicy object.
-    PortableServer::IdAssignmentPolicy_var idassignment = 
+    PortableServer::IdAssignmentPolicy_var idassignment =
       root_poa->create_id_assignment_policy (PortableServer::USER_ID);
-    
+
     // Create a PERSISTENT LifespanPolicy object.
-    PortableServer::LifespanPolicy_var lifespan = 
+    PortableServer::LifespanPolicy_var lifespan =
       root_poa->create_lifespan_policy (PortableServer::PERSISTENT);
 
     // Policies for the childPOA to be created.
     CORBA::PolicyList policies;
     policies.length (2);
-    
-    policies[0] = 
+
+    policies[0] =
       PortableServer::IdAssignmentPolicy::_duplicate (idassignment);
-    
-    policies[1] = 
+
+    policies[1] =
       PortableServer::LifespanPolicy::_duplicate (lifespan);
-					     
+
     // Create the childPOA under the RootPOA.
-    PortableServer::POA_var child_poa = 
-      root_poa->create_POA ("childPOA", 
+    PortableServer::POA_var child_poa =
+      root_poa->create_POA ("childPOA",
                             poa_manager.in (),
                             policies);
-    
+
     // Destroy policy objects.
     idassignment->destroy ();
     lifespan->destroy ();
@@ -75,20 +75,20 @@ main (int argc, char *argv[])
       PortableServer::string_to_ObjectId ("Stock_Factory");
 
     // Activate the Stock_Factory object.
-    child_poa->activate_object_with_id (oid.in (), 
+    child_poa->activate_object_with_id (oid.in (),
 					&stock_factory_i);
 
     // Get the object reference.
     CORBA::Object_var stock_factory =
       child_poa->id_to_reference (oid.in ());
-    
+
     // Stringify all the object referencs.
     CORBA::String_var ior = orb->object_to_string (stock_factory.in ());
     // Print them out !
     std::cout << ior.in () << std::endl;
 
     orb-> run ();
-    
+
     // Destroy POA, waiting until the destruction terminates.
     root_poa->destroy (1, 1);
     orb->destroy ();