Updated documentation

1 files changed, 92 insertions, 91 deletions

diff --git a/TAO/docs/Smart_Proxies.html b/TAO/docs/Smart_Proxies.html
index 607fa505dc4..2324124556c 100644
--- a/TAO/docs/Smart_Proxies.html
+++ b/TAO/docs/Smart_Proxies.html
@@ -20,9 +20,6 @@ bgcolor="#ffffff">
   <li><a href="#ref">References</a>
 </ul>
 
-<!-- @@ Kirthika, can you please add more html tags into the -->
-<!-- document so it can be more readable in a browser?       -->
-
 <h2><a name="Introduction">Introduction</a></h2>
 
 <P>Smart Proxies (or Smart Stubs) are basically user-defined proxy
@@ -89,7 +86,7 @@ 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. This means that smart
+<P>Collocated 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
@@ -103,29 +100,29 @@ collcated stubs.</p>
 <P>Classses to be generated by TAO_IDL in addition to the Default
 Stub:</p>
 
-<P>1. StubFactoryAdaptor
-<p>The singleton which has the different stub factories
+<P>1. TAO_Proxy_Factory_Adapter
+<p>The singleton which has the different proxies (stubs) factories
 registered with it.</p>
 
-<P>2. DefaultStubFactory
+<P>2.TAO_Test_Default_Proxy_Factory
 <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
+<P>3. TAO_Smart_Proxy_Base
+<p>The smart proxy interface which makes it easier for the
 user to simply implement only the methods he wishes to change and also
 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 - inherits from DefaultStubFactory class.
-<p>The factory which will create the smart stub which the
+<P>1. SmartFactory - inherits from TAO_Default_Proxy_Factory class.
+<p>The factory which will create the smart proxy which the
 user wants. Its necessary that an object of this class is created.</p>
 
-<P>2. SmartStub - derivative of the DefaultSmartStub class.
-<p>The stub which has the user desired extra functionality.</p>
+<P>2. SmartProxy - derivative of the TAO_Smart_Proxy_Base class.
+<p>The proxy which has the user desired extra functionality.</p>
 
 <P>*Note: Names are as they are to make it easier to comprehend the
 concept.</p>
@@ -133,8 +130,9 @@ concept.</p>
 <h3>In more detail</h3>
 
 <pre>
-// To be generated by TAO_IDL.
-class ProxyFactoryAdaptor
+//------------------------ Generated by TAO_IDL------------------------
+
+class TAO_Proxy_Factory_Adapter
 {
  // DESCRIPTION:
  // Behaves like a singleton and contains the
@@ -142,50 +140,52 @@ class ProxyFactoryAdaptor
  // default/smart Proxys.
 public:
 
- static ProxyFactoryAdaptor *instance (void)
-  {
-    if (ProxyFactoryAdaptor::factory_ == 0)
-    {
-      Perform Double-Checked Locking Optimisation...
-      this->factory = new DefaultFactory;
-    }
-    return this->factory;
-  }
+ friend class ACE_Singleton<TAO_Proxy_Factory_Adapter, ACE_SYNCH_RECURSIVE_MUTEX>;
 
  // Register the factory with the Adaptor.
- static register (DefaultFactory *df)
+ register_proxy (TAO_Default_Proxy_Factory *df)
  {
    Perform Double-Checked Locking Optimisation...
 
    // If there is a factory already existing, replace it.
-
-   if (ProxyFactoryAdaptor::factory_ != 0)
-     delete this->factory_;
-   this->factory_ = df;
+   this->unregister_proxy_factory ();
+   this->proxy_factory_ = df;
+   this->delete_proxy_factory_ = 0;
  }
 
  // Remove the factory.
- static unregister (void)
+ unregister_proxy_factory (void)
  {
-   Perform Double-Checked Locking Optimisation...
-   delete this->factory_;
+   Perform Locking to ensure exclusive access.
+    if (this->delete_proxy_factory_ == 0 && this->proxy_factory_ != 0)
+    {
+      // Its necessary to set <delete_proxy_factory_> to 1 to make sure that it
+      // doesnt get into an infinite loop in <unregister_proxy_factory> as it is 
+      // invoked in the destructor of the class too.
+      this->delete_proxy_factory_ = 1;
+      delete this->proxy_factory_;
+      this->proxy_factory_ = 0;
+    }
  }
 
  // Delegation of the Proxy creation to the factory
- static interface_ptr create_proxy (void)
+ interface_ptr create_proxy (void)
  {
+   Verify that an <proxy_factory_> is available else make one.
+
    return this->factory_->create_proxy ();
  }
 
 protected:
- ProxyFactoryAdaptor (void);
-
- static DefaultFactory *factory_;
+ 
+ TAO_Test_Default_Proxy_Factory *proxy_factory_;
+ int delete_proxy_factory_;
+ ACE_Recursive_Thread_Mutex lock_;
 
 };
 
 // This class will also be generated by TAO_IDL.
-class DefaultFactory
+class TAO_Default_Proxy_Factory
 {
  // DESCRIPTION:
  // This class is the parent for the different Proxy factories. The
@@ -194,15 +194,24 @@ class DefaultFactory
  // <unchecked_narrow>.
 
 public:
- DefaultFactory (void)
+ TAO_Default_Proxy_Factory (int register_proxy_factory);
  {
-   if (this->open () == error)
-     print error;
+   // Unless told dont register. By default registration is done.
+   // This comes in handy while creating the TAO_Proxy_Factory_Adapter
+   // instance since we want either the user to set the factory. Only
+   // if that doesnt happen will the TAO_Default_Proxy_Factory be set
+   // to the factory delegated by the Adapter and that is done using
+   // the Lazy Evaluation Principle when the first call to <create_proxy>
+   // is done.
+
+   if (register_proxy_factory)
+    {
+      TAO_PROXY_FACTORY_ADAPTER::instance ()->register_proxy_factory (this);
+    }
  }
 
- ~DefaultFactory (void)
+ ~TAO_Default_Proxy_Factory (void)
  {
-   this->close ();
  }
 
  // By default the proxy is simply returned.
@@ -211,49 +220,21 @@ public:
    return proxy;
  }
 
- // Whenever the factory object is created, automatically it
- // gets registered with the ProxyFactoryAdaptor.
- int open (void)
- {
-   ProxyFactorydaptor::instance ()->register(this);
-   If above fails, return error else 0.
- }
-
- // Job done, unregisteration is done.
- int close (void)
- {
-   ProxyFactorydaptor::instance ()->unregister(this);
-   If above fails, return error else 0.
- }
-
-};
-
-// This has to be implemented by the user
-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
- // ProxyFactoryAdaptor.
-public:
-
- Smartinterface_ptr create_proxy (interface_ptr proxy)
- {
-   return (!CORBA::is_nil (proxy) ? new SmartProxy (proxy) : proxy);
-  }
 };
 
 // This class will be generated by the TAO_IDL.
-class DefaultSmartProxy : public virtual DefaultProxy
+class TAO_Smart_Proxy_Base : public virtual DefaultProxyInterface
 {
  // 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 smartProxy interface for even collcated Proxys.
+ // the smartProxy interface for even collocated Proxies.
 public:
- DefaultSmartProxy (interface_ptr proxy)
-  : proxy_ (proxy)
+
+ // The delegation to which underlying proxy is decided here.
+ TAO_Smart_Proxy_Base (interface_ptr proxy)
+  : base_proxy_ (proxy)
 
  // Interface operations...
  int method ()
@@ -261,26 +242,43 @@ public:
     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.
+ // @@ How are exceptions handled?
+ // This not an issue really because the actual method call is simply
+ // to the application level which is catch it as the exception is
+ // propogated upwards from the proxy level. 
 
 protected:
  // 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 Proxys. Note: the collocated Proxys
+ // with the smart Proxies. Note: the collocated Proxies
  // themselves are smart proxies. The proxy pointer passed
- // thru the constructor willb eassigned to <proxy_>. The
+ // thru the constructor will be assigned 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_;
+  DefaultProxyInterface_var base_proxy_;
 
 };
 
+// ----------------- User Implemenatation Begins here----------------
+
+// Note: This has to be implemented by the user
+class SmartFactory : public TAO_Default_Proxy_Factory
+{
+ // DESCRIPTION:
+ // An object of this class has to be defined by the user
+ // which will cause it to be registered with the
+ // ProxyFactoryAdaptor.
+public:
+
+ Smartinterface_ptr create_proxy (interface_ptr proxy)
+ {
+   return (!CORBA::is_nil (proxy) ? new SmartProxy (proxy) : proxy);
+  }
+};
+
 // This class will be implemented by the user.
-class VerySmartProxy : public DefaultSmartProxy
+class VerySmartProxy : public TAO_Smart_Proxy_Base
 {
  // DESCRIPTION:
  // This is the smart Proxy will is defined by the user
@@ -293,8 +291,11 @@ class VerySmartProxy : public DefaultSmartProxy
 
 }
 
+// --------------------Related Stub Changes------------------
+
+
 // Generated by TAO_IDL. Note the changes wherein the
-// ProxyFactoryAdaptor is used.
+// TAO_Proxy_Factory_Adapter is used.
 
 interface_ptr _unchecked_narrow (CORBA::Object obj,
                                  CORBA::Environment &)
@@ -312,24 +313,24 @@ interface_ptr _unchecked_narrow (CORBA::Object obj,
         }
 
       if (CORBA::is_nil (default_proxy))
-        ACE_NEW_RETURN (defualt_proxy, interface (stub), test::_nil ());
+        ACE_NEW_RETURN (default_proxy, interface (stub), test::_nil ());
 
-      return ProxyFactoryAdaptor::instance ()->create_proxy (default_proxy);
+      return TAO_PROXY_FACTORY_ADAPTER::instance ()->create_proxy (default_proxy);
     }
 }
-
 </pre>
 
 <h2><a name="Implementation Issues">Implementation Issues</a></h2>
 
 <p> 1) Native exceptions? How are these to be handled?</p>
-<p> Maybe just put it in the IDL compiler and generate code for pure
-exception code or not based on the -Ge option.
+<p> This not an issue really because the actual method call is simply
+to the application level which will catch it as the exception is
+propogated upwards from the proxy level.</p>
 
 <p> 2) What if the user wants to have a smart proxy which inherits from
 many interfaces?</p>
 <p> First have different smart proxies which inherit from the
-DefaultSmartProxy (every default smart proxy is for an interface) and
+TAO_Smart_Proxy_Base (every default smart proxy is for an interface) and
 then have a new smart proxy inheriting from the previously created
 smart proxies. But remember: the SmartProxyFactory should create the
 final smart proxy thru its create_proxy () method.