libt2n: (gerd) some more documentation

[libt2n] / src / client_wrapper.hxx

diff --git a/src/client_wrapper.hxx b/src/client_wrapper.hxx
index 672308e..14dabfb 100644 (file)
--- a/src/client_wrapper.hxx
+++ b/src/client_wrapper.hxx
@@ -36,6 +36,12 @@
 namespace libt2n
 {
 
+/** @brief provide access to client_connection singletons and call-handling function
+
+    This is an abstact base class for use with T2nSingletonWrapper. It provides access
+    to the singleton-client_connection and offers a handle-method which is used for
+    every call to a method on a t2n-server.
+*/
 class ConnectionWrapper
 {
     private:
@@ -57,11 +63,30 @@ class ConnectionWrapper
         virtual ~ConnectionWrapper()
             { }
 
+        /** @brief return active connection, create new one if not existing
+
+            Return a pointer to an active client_connection. Use detail-data
+            stored within the derived class to create a new connection if needed,
+            otherwise return an alredy active connection. The derived class has
+            to take care of destroying the connection when not needed anymore.
+        */
         virtual client_connection* get_connection()=0;
 
-        virtual void handle(command_client* stubBase, boost::function< void() > f)
+        /** @brief this function is called on every execution of a method on a server
+
+            @param stubBase pointer to the command_client executing the call
+            @param f boost::function object containing the method to call and all parameters
+            @retval true if the call was successful and the original return-value of the called function can be used
+                    false if T2nSingletonWrapper has to create a return-value with the default-constructor
+
+            T2nSingletonWrapper will call this function on every execution of a server-side
+            method. This version will just call the function without any special treatment.
+            You can overload this function to implement different error handling strategies.
+        */
+        virtual bool handle(command_client* stubBase, boost::function< void() > f)
         {
             f();
+            return true;
         }
 
         long long get_command_timeout_usec(void)
@@ -138,6 +163,13 @@ class T2nSingletonWrapperMessages
         static const char* NotInitializedMessage;
 };
 
+/** @brief wrap calls to server-side-functions with different error-handling strategies
+
+    Template class to access a process-wide singleton server-connection and to wrap all
+    calls using this connection with an error-handling strategy (e.g. to reconnect when
+    the connection broke). The source looks very complicated due to heavy use of templates,
+    look at the 3rd codegen example to see how to use it.
+*/
 template< class Client >
 class T2nSingletonWrapper : public T2nSingletonWrapperMessages
 {
@@ -179,7 +211,7 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
             if (WrappedConnection.get() == NULL)
                 throw std::logic_error(NotInitializedMessage);
 
-            std::auto_ptr<Client> stub(new Client(*(WrappedConnection->get_connection()),
+            std::auto_ptr<Client> stub(new Client(WrappedConnection->get_connection(),
                 WrappedConnection->get_command_timeout_usec(),
                 WrappedConnection->get_hello_timeout_usec()));
 
@@ -193,8 +225,17 @@ class T2nSingletonWrapper : public T2nSingletonWrapperMessages
             ensure_singleton_there();
 
             typename detail::TypeWrap<R>::type result;
+
+            // bind our Client-object and the local result
             detail::Call<R> call( boost::bind( f, SingletonObject->Stub.get()), result );
-            WrappedConnection->handle(SingletonObject->Stub.get(),call);
+
+            // let the wrapper-handler call the fully-bound function
+            if (!WrappedConnection->handle(SingletonObject->Stub.get(),call))
+            {
+                // create an result with default-constructor if the handler could not
+                // successfully do a call but no exception occured
+                result=typename detail::TypeWrap<R>::type();
+            }
             return result;
         }