Revised document and addressed Nanbors comments + made design changes

1 files changed, 104 insertions, 87 deletions

diff --git a/TAO/docs/Smart_Proxies.html b/TAO/docs/Smart_Proxies.html
index 4fe35dbd03b..f105e8c8a06 100644
--- a/TAO/docs/Smart_Proxies.html
+++ b/TAO/docs/Smart_Proxies.html
@@ -25,49 +25,37 @@ bgcolor="#ffffff">
 user defined.
 <P>By default, the IDL compiler generates proxy classes for IDL interfaces.
 The proxy is an exact image of the target object on whom the
-<!-- @@ The proxy has the same methods as the targeting interface? -->
-invocations are to be made by the client. A proxy packadges the
-request along with its Service Context which gets marshalled and sent
-<!-- @@ Kirthika, I don't think smart proxies will be able to access the -->
-<!--    service contexts for the invocation.  Therefore, I don't quite -->
-<!--    understand why service contexts are mentioned here.  Can you -->
-<!--    please clarify this?  -->
-to the target object.</p>
+invocations are to be made by the client, i.e. it has the same methods
+as the targeting interface. A proxy packadges the request which gets
+marshalled and sent to the target object.</p>
+
 <P>The user may wish to manually change the proxy code for the following
 reasons:
 <P>
 <h3><a name="Examples">Examples</a></h3>
 
-<P>1) Cache information about the rempote object locally to save the
+<P>1) Cache information about the remote object locally to save the
 expense of going across the wire for every request.
 
 <P>2) Batch updates/accesses to the remote object.
 <p>For instance:<br>
-Consider a remote Database which has an api which can update 10
-records at one shot. To leverage performance, one would want to use
-this method.</p>
-<!-- @@ Shouldn't the api supports methods for updating both  -->
-<!--    single record and multiple records?  -->
-
-<P> So on an update method on the smart stub, instead of an remote
-<!-- @@ So a user can use the smart proxy to implement the -->
-<!--    single record update method to cache requests .......? -->
-invocation per record, the record-info will be cached and then after
-10 such records to be updated are obtained, the actual remote
-invocation could be made.</p>
+Consider a remote Database which has an API which can update either a
+single record or 10 records at one shot. To leverage performance, one
+would want to use this method. So a user can use the smart proxy to
+implement the 10 record update method by caching single record update
+requests.</p>
 
 <P> It is not certain whether this usecase might not induce extra
 overhead and whether the proxy can be smart enough to deduce the use
 of this kind of batch processing. Also, this scheme wont work for
 two-way calls.The "cached-oneways" feature might make more sense in
-this scenario.</p>
-<!-- @@ Of course in this case, the application programmer will -->
-<!--    have to determine how this caching optimization changes -->
-<!--    the semantics of the original interface.  -->
+this scenario. Thus the application programmer will have to determine
+how this caching optimisation changes the semantics of the original
+interface.</p>
 
 <P>3) The client can make a single request which results in a sequence
-of invocations.
-<!-- @@ Possibly to other objects. -->
+of invocations to one or possibly more objects.
+
 <p> For instance:<br>
 The smart stub has some private methods (since this is user specific
 this should be possible) which do validation of the request to be
@@ -85,27 +73,23 @@ target object.</p>
 <P>3) It has to be done before the invocations on the target object are
 done, so when will it get created?
 <P>4) What about collocation? Will those stubs fall under this category?</p>
-<!-- @@ Will smart proxies work for collocated object references? -->
+<p>5) Will smart proxies work for collocated object references?</p>
 
 <h3>Design Needs and discussion points</h3>
 
-<P>A ProxyFactory is needed which will create the stubs (either default
-<!-- @@ A user defined ProxyFactory. -->
-or smart). This factory should be able to create different kinds of
-proxies.</p>
+<P>A ProxyFactory (either default or user-defined) is needed which
+will create the stubs (either default or smart). This factory should
+be able to create different kinds of proxies.</p>
 
 <P>The <code>unchecked_narrow</code> method needs to return the
 appropriate stub.</p>
 
-<P>Collacated stubs need to be handled too.</p>
-<!-- @@ Does it mean the factory object should generate collocated -->
-<!-- stubs or it should generate smart procy for collocated object -->
-<!-- references?-->
+<P>Collacated stubs need to be handled too. This means that smart
+proxies need to be generated for collocated object references too.</p>
 
 <P>An existing function for creating stubs has to replaced by a class
 which will handle all cases viz. default stubs, smart stubs (proxies),
 collcated stubs.</p>
-<!-- @@ Same concern as above. -->
 
 <h2><a name="Design Overview">Design Overview</a></h2>
 
@@ -119,27 +103,24 @@ Stub:</p>
 registered with it.</p>
 
 <P>2. DefaultStubFactory
-<p>The stub factory which will replace the factory function
-currently generated by TAO_IDL to create default stubs.</p>
-<!-- @@ Hmm, I thought we will keep the collocated stub factory -->
-<!-- function.  Can you please clarify this.-->
+<p>The factory which returns the proxy_ptr which is used in the
+<code>unchecked_narow</code> method to create the appropriate proxy
+object.
 
 <P>3. DefaultSmartStub.
 <p>The smart stub interface which makes it easier for the
 user to simply implement only the methods he wishes to change and also
-provides and <br>common interface to address remote as well as collocated
+provides a <br>common interface to address remote as well as collocated
 stubs.</p>
 
 <P>Classes to be defined by the user:</p>
 
-<P>1. SmartFactory.
+<P>1. SmartFactory - inherits from DefaultStubFactory class.
 <p>The factory which will create the smart stub which the
-user wants.Its necessary that an object of this class is created.</p>
-<!-- @@ Which base class should it inherit from? -->
+user wants. Its necessary that an object of this class is created.</p>
 
-<P>2. SmartStub.
+<P>2. SmartStub - derivative of the DefaultSmartStub class.
 <p>The stub which has the user desired extra functionality.</p>
-<!-- @@ Should it inherit from a particular class. -->
 
 <P>*Note: Names are as they are to make it easier to comprehend the
 concept.</p>
@@ -148,22 +129,22 @@ concept.</p>
 
 <pre>
 // To be generated by TAO_IDL.
-class StubFactoryAdaptor
+class ProxyFactoryAdaptor
 {
  // DESCRIPTION:
  // Behaves like a singleton and contains the
  // factory object which is used to create the
- // default/smart stubs.
+ // default/smart Proxys.
 public:
 
- static StubFactoryAdaptor *instance (void)
+ static ProxyFactoryAdaptor *instance (void)
   {
-    if (StubFactoryAdaptor::factory_ == 0)
+    if (ProxyFactoryAdaptor::factory_ == 0)
     {
       Perform Double-Checked Locking Optimisation...
       this->factory = new DefaultFactory;
     }
-    // @@ return this->factory;
+    return this->factory;
   }
 
  // Register the factory with the Adaptor.
@@ -173,7 +154,7 @@ public:
 
    // If there is a factory already existing, replace it.
 
-   if (StubFactoryAdaptor::factory_ != 0)
+   if (ProxyFactoryAdaptor::factory_ != 0)
      delete this->factory_;
    this->factory_ = df;
  }
@@ -185,14 +166,14 @@ public:
    delete this->factory_;
  }
 
- // Delegation of the stub creation to the factory
- static interface_ptr create_stub (void)
+ // Delegation of the Proxy creation to the factory
+ static interface_ptr create_proxy (void)
  {
-   return this->factory_->create_stub ();
+   return this->factory_->create_proxy ();
  }
 
 protected:
- StubFactoryAdaptor (void);
+ ProxyFactoryAdaptor (void);
 
  static DefaultFactory *factory_;
 
@@ -202,10 +183,11 @@ protected:
 class DefaultFactory
 {
  // DESCRIPTION:
- // This class creates default stubs and is the parent
- // for the different stub factories.
- // @@ Will it create the collocated stub also?  Or, it is just
- //    a factory for remote stubs?
+ // This class is the parent for the different Proxy factories. The
+ // Proxy could either be collocated or remote and hence here only
+ // the Proxy pointer is returned which will be created on invocation of
+ // <unchecked_narrow>.
+
 public:
  DefaultFactory (void)
  {
@@ -218,24 +200,24 @@ public:
    this->close ();
  }
 
- // The default stub is created.
- interface_ptr create_stub (void)
+ // By default the proxy is simply returned.
+ interface_ptr create_proxy (interface_ptr proxy)
  {
-   return new DefaultStub;
+   return proxy;
  }
 
  // Whenever the factory object is created, automatically it
- // gets registered with the StubFactoryAdaptor.
+ // gets registered with the ProxyFactoryAdaptor.
  int open (void)
  {
-   StubFactorydaptor::instance ()->register(this);
+   ProxyFactorydaptor::instance ()->register(this);
    If above fails, return error else 0.
  }
 
  // Job done, unregisteration is done.
  int close (void)
  {
-   StubFactorydaptor::instance ()->unregister(this);
+   ProxyFactorydaptor::instance ()->unregister(this);
    If above fails, return error else 0.
  }
 
@@ -247,55 +229,90 @@ class SmartFactory : public DefaultFactory
  // DESCRIPTION:
  // An object of this class has to be defined by the user
  // which will cause it to be registered with the
- // StubFactoryAdaptor.
+ // ProxyFactoryAdaptor.
 public:
- Smartinterface_ptr create_stub (void)
+
+ Smartinterface_ptr create_proxy (interface_ptr proxy)
  {
-   return new SmartStub;
-   // @@ How will this work with collocated object references?
-   //    I thought you were going to make smart proxies work
-   //    with both remote and collocated object.
+   return (!CORBA::is_nil (proxy) ? new SmartProxy (proxy) : proxy);
   }
 };
 
 // This class will be generated by the TAO_IDL.
-class DefaultSmartStub : public virtual DefaultStub
+class DefaultSmartProxy : public virtual DefaultProxy
 {
  // DESCRIPTION:
  // This class is the class from which the user will inherit
  // and simply override the methods he requires. This extra
  // level of indirection is necessary to be able to provide
- // the smartstub interface for even collcated stubs.
+ // the smartProxy interface for even collcated Proxys.
 public:
- DefaultSmartStub (void);
- int method ();  // @@ Interface operations?.
+ DefaultSmartProxy (interface_ptr proxy)
+  : proxy_ (proxy)
+
+ // Interface operations...
+ int method ()
+  {
+    this->proxy_.method ();
+  }
  ...
+ // @@@ Not sure how to handle support for native exception (i.e., no
+ // CORBA::Environement in the method signatures.  Maybe just put it in
+ // the IDL compiler and generate code for pure exception code or not
+ // based on the -Ge option.
 
 protected:
- // This pointer denotes the kind of proxy used:
+ // This var member denotes the kind of proxy used:
  // collacated-thru_poa, collocated-direct, or remote.
  // This is decided by the collocated strategy used along
- // with the smart stubs. Note: the collocated stubs
- // themselves are smart proxies.
- DefaultStub *stub;
+ // with the smart Proxys. Note: the collocated Proxys
+ // themselves are smart proxies. The proxy pointer passed
+ // thru the constructor willb eassigned to <proxy_>. The
+ // pointer will actually point to the smart proxy in case
+ // of smart proxies or else to the default proxy.
+  DefaultProxy_var proxy_;
 
- // @@ Okay, but I don't see where this stub can be initialized
- //    properly in the user defined factories.
 };
 
 // This class will be implemented by the user.
-class VerySmartStub : public DefaultSmartStub
+class VerySmartProxy : public DefaultSmartProxy
 {
  // DESCRIPTION:
- // This is the smart stub will is defined by the user
+ // This is the smart Proxy will is defined by the user
  // to suit his needs.
  int method ()
  {
    print "Yahoo, I am so smart"
-   this->stub->method ();
+   this->proxy_.method ();
  }
 
 }
+
+// Generated by TAO_IDL. Note the changes wherein the
+// ProxyFactoryAdaptor is used.
+
+interface_ptr _unchecked_narrow (CORBA::Object obj,
+                                 CORBA::Environment &)
+{
+   if (CORBA::is_nil (obj))
+        return test::_nil ();
+      TAO_Proxy* Proxy = obj->_stubobj ();
+      stub->_incr_refcnt ();
+      interface_ptr *default_proxy = interface::_nil ();
+
+      if (obj->_is_collocated () && _TAO_collocation_interface_Stub_Factory_function_pointer != 0)
+        {
+          default_proxy =
+            _TAO_collocation_interface_Stub_Factory_function_pointer (obj);
+        }
+
+      if (CORBA::is_nil (default_proxy))
+        ACE_NEW_RETURN (defualt_proxy, interface (stub), test::_nil ());
+
+      return ProxyFactoryAdaptor::instance ()->create_proxy (default_proxy);
+    }
+}
+
 </pre>
 
 <h2><a name="Acknowledgements">Acknowledgements</a></h2>
@@ -312,7 +329,7 @@ designing and discussing this feature.
 
 <p><h2>Last update:</h2></p>
 
-<p> Date: 19thSept99</p>
+<p> Date: 21thSept99</p>
 <p> By: <a href="mailto:kirthika@cs.wustl.edu">Kirthika Parameswaran</a></p>
 
 </BODY>