ChangeLogTag:Sun Nov 2 15:45:55 2003 Balachandran Natarajan <bala@dre.vanderbilt.edu>

11 files changed, 228 insertions, 48 deletions

diff --git a/TAO/ChangeLog b/TAO/ChangeLog
index 44331bc1aae..2329813d31f 100644
--- a/TAO/ChangeLog
+++ b/TAO/ChangeLog
@@ -1,3 +1,18 @@
+Sun Nov  2 15:45:55 2003  Balachandran Natarajan  <bala@dre.vanderbilt.edu>
+
+	* tao/Collocated_Invocation.h:
+	* tao/Invocation_Adapter.cpp:
+	* tao/Invocation_Adapter.h:
+	* tao/Invocation_Base.h:
+	* tao/LocateRequest_Invocation.h:
+	* tao/LocateRequest_Invocation_Adapter.cpp:
+	* tao/LocateRequest_Invocation_Adapter.h:
+	* tao/Remote_Invocation.cpp:
+	* tao/Remote_Invocation.h:
+	* tao/Synch_Invocation.h:
+
+	  Added and improved doxygen documentation.
+
 Sat Nov  1 14:58:02 2003  Balachandran Natarajan  <bala@dre.vanderbilt.edu>
 
 	* tao/Sync_Strategies.cpp:
diff --git a/TAO/tao/Collocated_Invocation.h b/TAO/tao/Collocated_Invocation.h
index 93fba967dce..9278ea97f40 100644
--- a/TAO/tao/Collocated_Invocation.h
+++ b/TAO/tao/Collocated_Invocation.h
@@ -37,20 +37,49 @@ namespace TAO
   /**
    * @class Collocated_Invocation
    *
-   * @brief Base class for ..
+   * @brief Class for Collocated invocations
    *
    * @NOTE: Reliable oneways are not handled properly including use of
-   *  interceptors.
+   * interceptors. This class should technically serve as the base
+   * for all invocation types. But now, this is the only class that
+   * handles collocated invocations and that too in a brain dead way.
    */
   class TAO_Export Collocated_Invocation : public Invocation_Base
   {
   public:
+    /// Constructor used by TAO::Invocation_Adapter
+    /**
+     * @param et, The effective target in which this invocation is now
+     * flowing
+     *
+     * @param t, The target on which invocation first started.
+     *
+     * @param stub, Stub for target @t
+     *
+     * @param detail, operation details of the invocation including
+     * the service context list
+     *
+     * @param response_expected, flag to indicate whether the
+     * operation encapsulated by @a detail returns a response or not.
+     */
     Collocated_Invocation (CORBA::Object_ptr et,
                            CORBA::Object_ptr t,
                            TAO_Stub *stub,
                            TAO_Operation_Details &detail,
                            bool response_expected = true);
 
+    /// Invocation on the collocated object mediated through this
+    /// class.
+    /**
+     * Practically this method is a place holder to do the
+     * following
+     *  - Call the start and end interception points on the client
+     *    side.
+     *
+     *  - Handle location forwards that could be thrown by the
+     *    servant.
+     *
+     */
     Invocation_Status invoke (Collocation_Proxy_Broker *cpb,
                               Collocation_Strategy strat
                               ACE_ENV_ARG_DECL)
diff --git a/TAO/tao/Invocation_Adapter.cpp b/TAO/tao/Invocation_Adapter.cpp
index 4ffb4656e3d..1ac723d54b4 100644
--- a/TAO/tao/Invocation_Adapter.cpp
+++ b/TAO/tao/Invocation_Adapter.cpp
@@ -88,8 +88,6 @@ namespace TAO
         if (strat == TAO_CS_REMOTE_STRATEGY ||
             strat == TAO_CS_LAST)
           {
-
-
             status =
               this->invoke_remote_i (stub,
                                      details,
diff --git a/TAO/tao/Invocation_Adapter.h b/TAO/tao/Invocation_Adapter.h
index d3302778bbd..9ba0db72756 100644
--- a/TAO/tao/Invocation_Adapter.h
+++ b/TAO/tao/Invocation_Adapter.h
@@ -110,7 +110,7 @@ namespace TAO
                         TAO::Invocation_Type type = TAO_TWOWAY_INVOCATION,
                         TAO::Invocation_Mode mode = TAO_SYNCHRONOUS_INVOCATION);
 
-    /// Invoke the target
+    /// Invoke the target, and used by the generated code.
     /**
      * The implementation decides whether the target is remote or
      * collocated and takes the right decision.
diff --git a/TAO/tao/Invocation_Base.h b/TAO/tao/Invocation_Base.h
index cbf69e0430d..95b61f9cbdd 100644
--- a/TAO/tao/Invocation_Base.h
+++ b/TAO/tao/Invocation_Base.h
@@ -50,14 +50,14 @@ namespace TAO
    *
    * This class is the base of the invocation object hiererachy. This
    * hierarchy is classified  based on the type of invocation and the
-   * mode of the invocation. One of the objects from the hiererachy is
+   * mode of invocation. One of the objects from the hiererachy is
    * created on the stack for every invocation.
    *
-   * This class encapsulates the essential details that are required
-   * for PortableInterceptors to function correctly. Further this
-   * class also provides some helper and accessor methods that are
-   * used by clients.
-   * @@ More..
+   * In addition this class encapsulates the essential details that
+   * are required for PortableInterceptors to function
+   * correctly. Further this class also provides some helper and
+   * accessor methods that are used by clients.
+   *
    */
   class TAO_Export Invocation_Base
   {
@@ -65,7 +65,7 @@ namespace TAO
     virtual ~Invocation_Base (void);
 
     //@{
-    /// Accessor and mutator methods ..
+    /// Accessor and mutator methods
     TAO_ORB_Core *orb_core (void) const;
 
     TAO_Stub *stub (void) const;
@@ -73,13 +73,18 @@ namespace TAO
     /// Accessor and mutator methods for forwarded object
     /// locations.
     /**
-     * These methods have to be public so that the PortableInterceptor
-     * can use this.
+     * These access methods have to be public so that the
+     * PortableInterceptor can use them
      */
     CORBA::Object_ptr forwarded_reference (void);
     void forwarded_reference (CORBA::Object_ptr o);
 
-    /// Accessors for the service context list
+    /// Accessors for the service context list.
+    /**
+     * The service context lists are actually cached
+     * elsewhere. Providing this accessor helps the PI to access this
+     * list in both remote and collocated mode.
+     */
     TAO_Service_Context &request_service_context (void);
     TAO_Service_Context &reply_service_context (void);
 
@@ -104,10 +109,9 @@ namespace TAO
 
     /// Does this invocation return a response?
     CORBA::Boolean  response_expected (void) const;
-
     //@}
+
   protected:
-    /// Don't allow creation of an object of type Invocation_Base.
     /**
      * @param otarget, The original target on which this invocation
      * was started.
@@ -133,7 +137,7 @@ namespace TAO
     /// Forwarded object reference.
     CORBA::Object_var forwarded_to_;
 
-    /// Is the response expected?
+    /// Is response expected?
     bool response_expected_;
 
   private:
diff --git a/TAO/tao/LocateRequest_Invocation.h b/TAO/tao/LocateRequest_Invocation.h
index 3b664f1c43a..0d8df08b517 100644
--- a/TAO/tao/LocateRequest_Invocation.h
+++ b/TAO/tao/LocateRequest_Invocation.h
@@ -34,20 +34,41 @@ namespace TAO
 {
   class Profile_Transport_Resolver;
 
+  /**
+   * @class LocateRequest_Invocation
+   *
+   * @brief Object created bu TAO::LocateRequest_Invocation_Adapter to
+   * create and send LocateRequest invocation.
+   *
+   */
   class TAO_Export LocateRequest_Invocation
     : protected Synch_Twoway_Invocation
   {
   public:
-    LocateRequest_Invocation (CORBA::Object_ptr otarget,
-                              Profile_Transport_Resolver &resolver,
-                              TAO_Operation_Details &detail);
+    /**
+     * @param target, The target on which this invocation was
+     *  started.
+     *
+     * @param resolver, Comntainer of the profile and transport on
+     * which this invocation is on
+     *
+     * @param detail, Operation details of the invocation on @a
+     * target. This is of no practical importance since it is not used
+     * in this class. This is just to keep our base class happy.
+     *
+     */
+    LocateRequest_Invocation (
+        CORBA::Object_ptr otarget,
+        Profile_Transport_Resolver &resolver,
+        TAO_Operation_Details &detail);
 
+    /// Start the invocation.
     Invocation_Status invoke (ACE_Time_Value *max_wait_time
                               ACE_ENV_ARG_DECL)
       ACE_THROW_SPEC ((CORBA::Exception));
 
   private:
-
+    /// Helper to check the reply status
     Invocation_Status check_reply (TAO_Synch_Reply_Dispatcher &rd
                                    ACE_ENV_ARG_DECL);
 
diff --git a/TAO/tao/LocateRequest_Invocation_Adapter.cpp b/TAO/tao/LocateRequest_Invocation_Adapter.cpp
index 332e9e79dee..20dd2f48720 100644
--- a/TAO/tao/LocateRequest_Invocation_Adapter.cpp
+++ b/TAO/tao/LocateRequest_Invocation_Adapter.cpp
@@ -19,7 +19,7 @@ namespace TAO
   {
   }
 
-  bool
+  void
   LocateRequest_Invocation_Adapter::invoke (ACE_ENV_SINGLE_ARG_DECL)
   {
     CORBA::Object *effective_target = this->target_;
@@ -28,12 +28,11 @@ namespace TAO
       this->target_->_stubobj ();
 
     if (stub == 0)
-      ACE_THROW_RETURN (CORBA::INTERNAL (
-                          CORBA::SystemException::_tao_minor_code (
-                            TAO_DEFAULT_MINOR_CODE,
-                            EINVAL),
-                          CORBA::COMPLETED_NO),
-                        0);
+      ACE_THROW (CORBA::INTERNAL (
+                     CORBA::SystemException::_tao_minor_code (
+                       TAO_DEFAULT_MINOR_CODE,
+                         EINVAL),
+                        CORBA::COMPLETED_NO));
 
     ACE_Time_Value tmp_wait_time;
     ACE_Time_Value *max_wait_time = 0;
@@ -44,7 +43,6 @@ namespace TAO
     if (is_timeout)
       max_wait_time = &tmp_wait_time;
 
-
     Invocation_Status s = TAO_INVOKE_START;
 
     while (s == TAO_INVOKE_START ||
@@ -89,10 +87,10 @@ namespace TAO
             ACE_RE_THROW;
           }
         ACE_ENDTRY;
-        ACE_CHECK_RETURN (false);
+        ACE_CHECK;
       }
 
-    return true;
+    return;
   }
 
   CORBA::PolicyList *
diff --git a/TAO/tao/LocateRequest_Invocation_Adapter.h b/TAO/tao/LocateRequest_Invocation_Adapter.h
index 790c0bc284d..59220809fd9 100644
--- a/TAO/tao/LocateRequest_Invocation_Adapter.h
+++ b/TAO/tao/LocateRequest_Invocation_Adapter.h
@@ -29,16 +29,31 @@ namespace CORBA
 namespace TAO
 {
   /**
+   * @class LocateRequest_Invocation_Adapter
    *
+   * @brief Adapter class for locate request invocations.
    *
+   *  This class provides a look and feel similar to the
+   *  TAO::Invocation_Adapter though the functionalities are
+   *  different. For the record, IDL compiler doesn't know the
+   *  existence of this class. This class is concerned with the
+   *  creation and invocation of locate request invocations to the
+   *  target object
+   *
+   * @todo: Need to think what happens if the target is
+   *  collocated. Looks like there are no ways to utilize the
+   *  opportunity that may have been presented.
    */
   class TAO_Export LocateRequest_Invocation_Adapter
   {
   public:
-    LocateRequest_Invocation_Adapter (CORBA::Object_ptr target);
+    LocateRequest_Invocation_Adapter (
+        CORBA::Object_ptr target);
 
-    bool invoke (ACE_ENV_SINGLE_ARG_DECL);
+    /// Start the invocation on the target
+    void invoke (ACE_ENV_SINGLE_ARG_DECL);
 
+    /// Accessor to the inconsistent policy list
     CORBA::PolicyList *get_inconsistent_policies (void);
 
   private:
diff --git a/TAO/tao/Remote_Invocation.cpp b/TAO/tao/Remote_Invocation.cpp
index 475b51f35f2..97377e5371f 100644
--- a/TAO/tao/Remote_Invocation.cpp
+++ b/TAO/tao/Remote_Invocation.cpp
@@ -14,10 +14,12 @@ ACE_RCSID (tao,
 
 namespace TAO
 {
-  Remote_Invocation::Remote_Invocation (CORBA::Object_ptr otarget,
-                                        Profile_Transport_Resolver &resolver,
-                                        TAO_Operation_Details &detail,
-                                        bool response_expected)
+  Remote_Invocation::Remote_Invocation (
+      CORBA::Object_ptr otarget,
+      Profile_Transport_Resolver &resolver,
+      TAO_Operation_Details &detail,
+      bool response_expected)
+
     : Invocation_Base (otarget,
                        resolver.object (),
                        resolver.stub (),
@@ -31,7 +33,6 @@ namespace TAO
   Remote_Invocation::init_target_spec (TAO_Target_Specification &target_spec
                                        ACE_ENV_ARG_DECL)
   {
-
     /**
      * Mega hack for RTCORBA start. I don't think that
      * PortableInterceptor  would work here esp. for RTCORBA. PI needs
diff --git a/TAO/tao/Remote_Invocation.h b/TAO/tao/Remote_Invocation.h
index 61638659a53..383691acddd 100644
--- a/TAO/tao/Remote_Invocation.h
+++ b/TAO/tao/Remote_Invocation.h
@@ -40,12 +40,27 @@ namespace TAO
   /**
    * @class Remote_Invocation
    *
-   * @brief Base class for Twoway_Invocation and Oneway_Invocation.
+   * @brief Base class for remote invocations.
+   *
+   * This class encapulates some of the common functionalities used by
+   * synchronous, asynchronous, DII and DSI invocations.
    *
    */
   class TAO_Export Remote_Invocation : public Invocation_Base
   {
   public:
+    /**
+     * @param otarget, The original target on which this invocation
+     * was started. This is there to be passed up to its parent
+     * class.
+     *
+     * @param resolver, The profile and transport holder.
+     *
+     * @param op, operation details of the invocation on the target
+     *
+     * @param response_expected, flag to indicate whether the
+     * operation encapsulated by @a op returns a response or not.
+     */
     Remote_Invocation (CORBA::Object_ptr otarget,
                        Profile_Transport_Resolver &resolver,
                        TAO_Operation_Details &detail,
@@ -53,22 +68,27 @@ namespace TAO
 
   protected:
 
+    /// Initialize the @a spec.
     void init_target_spec (TAO_Target_Specification &spec
                            ACE_ENV_ARG_DECL);
 
+    /// Write the GIOP header into the stream.
     void write_header (TAO_Target_Specification &spec,
                        TAO_OutputCDR &out_stream
                        ACE_ENV_ARG_DECL);
 
+    /// Marshal the arguments into the stream.
     void marshal_data (TAO_OutputCDR &cdr
                        ACE_ENV_ARG_DECL);
 
+    /// Write the message onto the socket
     Invocation_Status send_message (TAO_OutputCDR &cdr,
                                     short message_semantics,
                                     ACE_Time_Value *max_wait_time
                                     ACE_ENV_ARG_DECL);
 
   protected:
+    /// Our resolver
     Profile_Transport_Resolver &resolver_;
   };
 }
diff --git a/TAO/tao/Synch_Invocation.h b/TAO/tao/Synch_Invocation.h
index 68aaeb2c8af..7346e3de91d 100644
--- a/TAO/tao/Synch_Invocation.h
+++ b/TAO/tao/Synch_Invocation.h
@@ -38,14 +38,49 @@ namespace TAO
 {
   class Profile_Transport_Resolver;
 
+  /**
+   * @class Synch_Twoway_Invocation
+   *
+   * @brief All the action for a synchronous twoway invocation happen
+   * here.
+   *
+   * An object of this is type is created by TAO::Invocation_Adapter
+   * and invokes a method on this class. The method takes care of
+   * creating and sending a request, waiting for a reply and
+   * demarshalling the reply for the client.
+   *
+   */
   class TAO_Export Synch_Twoway_Invocation : public Remote_Invocation
   {
   public:
+    /// Constructor used by TAO::Invocation_Adapter
+    /**
+     * @param otarget, The original target on which this invocation
+     * was started. This is there to be passed up to its parent
+     * class.
+     *
+     * @param resolver, The profile and transport holder.
+     *
+     * @param op, operation details of the invocation on the target
+     *
+     * @param response_expected, flag to indicate whether the
+     * operation encapsulated by @a op returns a response or not.
+     */
     Synch_Twoway_Invocation (CORBA::Object_ptr otarget,
                              Profile_Transport_Resolver &resolver,
                              TAO_Operation_Details &detail,
                              bool response_expected = true);
 
+    /// Method used by the adapter to kickstart an invocation to the
+    /// remote object.
+    /**
+     * There is a exception declaration in this method which ensures
+     * that the exceptions propogated by the remote objects are
+     * converted a CORBA exceptions for the clients. This method does
+     * a bunch of things necessary to create and send the
+     * invocation. This method is also nerve centre for the
+     * interceptor invocation points.
+     */
     Invocation_Status remote_twoway (ACE_Time_Value *max_wait_time
                                      ACE_ENV_ARG_DECL)
       ACE_THROW_SPEC ((CORBA::Exception));
@@ -62,57 +97,101 @@ namespace TAO
                                                      ACE_ENV_ARG_DECL)
       ACE_THROW_SPEC ((CORBA::Exception));
 
+    /// Helper method used to handle location forwarded replies.
     Invocation_Status location_forward (TAO_InputCDR &cdr
                                         ACE_ENV_ARG_DECL)
       ACE_THROW_SPEC ((CORBA::SystemException));
 
-
-
+    /// Helper method used to handle system exceptions from the remote
+    /// objects.
     Invocation_Status handle_system_exception (TAO_InputCDR &cdr
                                                ACE_ENV_ARG_DECL)
       ACE_THROW_SPEC ((CORBA::SystemException));
 
+    /// As the name suggests waits for a reply from the remote ORB.
     Invocation_Status wait_for_reply (ACE_Time_Value *max_wait_time,
                                       TAO_Synch_Reply_Dispatcher &rd,
                                       TAO_Bind_Dispatcher_Guard &bd
                                       ACE_ENV_ARG_DECL)
       ACE_THROW_SPEC ((CORBA::SystemException));
 
-
   private:
 
-    Invocation_Status check_reply_status (TAO_Synch_Reply_Dispatcher &rd
-                                          ACE_ENV_ARG_DECL);
-
+    /// Helper method that checks the reply status of the
+    /// replies and takes appropriate action.
+    Invocation_Status check_reply_status (
+        TAO_Synch_Reply_Dispatcher &rd
+        ACE_ENV_ARG_DECL);
 
   };
 
-  class TAO_Export Synch_Oneway_Invocation : public Synch_Twoway_Invocation
+  /**
+   * @class Synch_Oneway_Invocation
+   *
+   * @brief All the action for a synchronous oneway invocation happen
+   * here.
+   *
+   * This class inherits from twoway invocation for the following
+   * reasons
+   *
+   * - We deal with oneway invocation in more or less the same way as
+   *   two but for waiting for the reply
+   *
+   * - For some SYNC_SCOPE policies namely SYNC_WITH_TARGET and
+   *   SYNC_WITH_SERVER the invocation classes have to treat the
+   *   invocation as a twoway invocation (more or less)
+   *
+   */
+  class TAO_Export Synch_Oneway_Invocation :
+    public Synch_Twoway_Invocation
   {
   public:
+    /// Constructor used by TAO::Invocation_Adapter
+    /**
+     * @param otarget, The original target on which this invocation
+     * was started. This is there to be passed up to its parent
+     * class.
+     *
+     * @param resolver, The profile and transport holder.
+     *
+     * @param op, operation details of the invocation on the target
+     *
+     * @param response_expected, flag to indicate whether the
+     * operation encapsulated by @a op returns a response or not.
+     */
     Synch_Oneway_Invocation (CORBA::Object_ptr otarget,
                              Profile_Transport_Resolver &resolver,
                              TAO_Operation_Details &detail);
 
+    /// Method used by the adapter to kickstart an oneway invocation
+    /// to the remote object.
     Invocation_Status remote_oneway (ACE_Time_Value *max_wait_time
                                      ACE_ENV_ARG_DECL)
       ACE_THROW_SPEC ((CORBA::Exception));
   };
 
+  /**
+   * @class Reply_Guard
+   *
+   * @brief A guard class used for storing and forwarding the reply
+   *  status to the portable interceptors.
+   */
   class TAO_Export Reply_Guard
   {
   public:
     Reply_Guard (Invocation_Base *s,
                  Invocation_Status is);
 
+    /// The destructor calls Invocation_Base::reply_received with the
+    /// right reply status, which is useful for PI's.
     ~Reply_Guard (void);
 
+    /// Mutator to set the invocation status.
     void set_status (Invocation_Status s);
 
   private:
     Invocation_Base *invocation_;
     Invocation_Status status_;
-
   };
 
 }