A bit more documentation for the client tests which are currently doubling as examples.

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid@486797 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 46 insertions, 10 deletions

diff --git a/cpp/tests/client_test.cpp b/cpp/tests/client_test.cpp
index 5ee53e3fa8..6a22a65ad2 100644
--- a/cpp/tests/client_test.cpp
+++ b/cpp/tests/client_test.cpp
@@ -18,6 +18,14 @@
  * under the License.
  *
  */
+
+/**
+ * This file provides a simple test (and example) of basic
+ * functionality including declaring an exchange and a queue, binding
+ * these together, publishing a message and receiving that message
+ * asynchronously.
+ */
+
 #include <iostream>
 
 #include <QpidError.h>
@@ -32,14 +40,19 @@ using namespace qpid::client;
 using namespace qpid::sys;
 using std::string;
 
+/**
+ * A simple message listener implementation that prints out the
+ * message content then notifies a montitor allowing the test to
+ * complete.
+ */
 class SimpleListener : public virtual MessageListener{
     Monitor* monitor;
 
 public:
     inline SimpleListener(Monitor* _monitor) : monitor(_monitor){}
 
-    inline virtual void received(Message& /*msg*/){
-	std::cout << "Received message " /**<< msg **/<< std::endl;
+    inline virtual void received(Message& msg){
+	std::cout << "Received message " << msg.getData()  << std::endl;
 	monitor->notify();
     }
 };
@@ -47,44 +60,67 @@ public:
 int main(int argc, char**)
 {
     try{               
-	Connection con(argc > 1);
-	Channel channel;
+        //Use a custom exchange
 	Exchange exchange("MyExchange", Exchange::TOPIC_EXCHANGE);
+        //Use a named, temporary queue
 	Queue queue("MyQueue", true);
-	
-	string host("localhost");
-	
+
+        //Create and open a connection
+	Connection con(argc > 1);
+	string host("localhost");	
 	con.open(host);
 	std::cout << "Opened connection." << std::endl;
+
+        //Create and open a channel on the connection through which
+        //most functionality is exposed
+	Channel channel;      
 	con.openChannel(&channel);
 	std::cout << "Opened channel." << std::endl;	
+
+        //'declare' the exchange and the queue, which will create them
+        //as they don't exist
 	channel.declareExchange(exchange);
 	std::cout << "Declared exchange." << std::endl;
 	channel.declareQueue(queue);
 	std::cout << "Declared queue." << std::endl;
+
+        //now bind the queue to the exchange
 	qpid::framing::FieldTable args;
 	channel.bind(exchange, queue, "MyTopic", args);
 	std::cout << "Bound queue to exchange." << std::endl;
 
-	//set up a message listener
+	//Set up a message listener to receive any messages that
+	//arrive in our queue on the broker. We only expect one, and
+	//as it will be received on another thread, we create a
+	//montior to use to notify the main thread when that message
+	//is received.
 	Monitor monitor;
 	SimpleListener listener(&monitor);
 	string tag("MyTag");
 	channel.consume(queue, tag, &listener);
-	channel.start();
 	std::cout << "Registered consumer." << std::endl;
 
+        //we need to enable the message dispatching for this channel
+        //and we want that to occur on another thread so we call
+        //start().
+	channel.start();
+
+        //Now we create and publish a message to our exchange with a
+        //routing key that will cause it to be routed to our queue
 	Message msg;
 	string data("MyMessage");
 	msg.setData(data);
 	channel.publish(msg, exchange, "MyTopic");
-	std::cout << "Published message." << std::endl;
+	std::cout << "Published message: " << data << std::endl;
 
 	{
             Monitor::ScopedLock l(monitor);
+            //now we wait until we receive notification that the
+            //message was received
             monitor.wait();
         }
         
+        //close the channel & connection
 	con.closeChannel(&channel);
 	std::cout << "Closed channel." << std::endl;
 	con.close();