Added some doxygen comments for the client API.

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

10 files changed, 408 insertions, 16 deletions

diff --git a/qpid/cpp/lib/client/ClientChannel.h b/qpid/cpp/lib/client/ClientChannel.h
index f76569498a..e617da05c0 100644
--- a/qpid/cpp/lib/client/ClientChannel.h
+++ b/qpid/cpp/lib/client/ClientChannel.h
@@ -38,8 +38,35 @@
 
 namespace qpid {
 namespace client {
-    enum ack_modes {NO_ACK=0, AUTO_ACK=1, LAZY_ACK=2, CLIENT_ACK=3};
+    /**
+     * The available acknowledgements modes
+     * 
+     * \ingroup clientapi
+     */
+    enum ack_modes {
+        /** No acknowledgement will be sent, broker can
+            discard messages as soon as they are delivered
+            to a consumer using this mode. **/
+        NO_ACK     = 0,  
+        /** Each message will be automatically
+            acknowledged as soon as it is delivered to the
+            application **/  
+        AUTO_ACK   = 1,  
+        /** Acknowledgements will be sent automatically,
+            but not for each message. **/
+        LAZY_ACK   = 2,
+        /** The application is responsible for explicitly
+            acknowledging messages. **/  
+        CLIENT_ACK = 3 
+    };
 
+    /**
+     * Represents an AMQP channel, i.e. loosely a session of work. It
+     * is through a channel that most of the AMQP 'methods' are
+     * exposed.
+     * 
+     * \ingroup clientapi
+     */
     class Channel : private virtual qpid::framing::BodyHandler, public virtual qpid::sys::Runnable{
         struct Consumer{
             MessageListener* listener;
@@ -83,25 +110,180 @@ namespace client {
 	virtual void handleHeartbeat(qpid::framing::AMQHeartbeatBody::shared_ptr body);
 
     public:
+        /**
+         * Creates a channel object.
+         * 
+         * @param transactional if true, the publishing and acknowledgement
+         * of messages will be transactional and can be committed or
+         * aborted in atomic units (@see commit(), @see rollback())
+         * 
+         * @param prefetch specifies the number of unacknowledged
+         * messages the channel is willing to have sent to it
+         * asynchronously
+         */
 	Channel(bool transactional = false, u_int16_t prefetch = 500);
 	~Channel();
 
+        /**
+         * Declares an exchange.
+         * 
+         * In AMQP Exchanges are the destinations to which messages
+         * are published. They have Queues bound to them and route
+         * messages they receive to those queues. The routing rules
+         * depend on the type of the exchange.
+         * 
+         * @param exchange an Exchange object representing the
+         * exchange to declare
+         * 
+         * @param synch if true this call will block until a response
+         * is received from the broker
+         */
 	void declareExchange(Exchange& exchange, bool synch = true);
+        /**
+         * Deletes an exchange
+         * 
+         * @param exchange an Exchange object representing the exchange to delete
+         * 
+         * @param synch if true this call will block until a response
+         * is received from the broker
+         */
 	void deleteExchange(Exchange& exchange, bool synch = true);
+        /**
+         * Declares a Queue
+         * 
+         * @param queue a Queue object representing the queue to declare
+         * 
+         * @param synch if true this call will block until a response
+         * is received from the broker
+         */
 	void declareQueue(Queue& queue, bool synch = true);
+        /**
+         * Deletes a Queue
+         * 
+         * @param queue a Queue object representing the queue to delete
+         * 
+         * @param synch if true this call will block until a response
+         * is received from the broker
+         */
 	void deleteQueue(Queue& queue, bool ifunused = false, bool ifempty = false, bool synch = true);
+        /**
+         * Binds a queue to an exchange. The exact semantics of this
+         * (in particular how 'routing keys' and 'binding arguments'
+         * are used) depends on the type of the exchange.
+         * 
+         * @param exchange an Exchange object representing the
+         * exchange to bind to
+         * 
+         * @param queue a Queue object representing the queue to be
+         * bound
+         * 
+         * @param key the 'routing key' for the binding
+         * 
+         * @param args the 'binding arguments' for the binding
+         * 
+         * @param synch if true this call will block until a response
+         * is received from the broker
+         */
 	void bind(const Exchange& exchange, const Queue& queue, const std::string& key, 
                   const qpid::framing::FieldTable& args, bool synch = true);
+        /**
+         * Creates a 'consumer' for a queue. Messages in (or arriving
+         * at) that queue will be delivered to consumers
+         * asynchronously.
+         * 
+         * @param queue a Queue instance representing the queue to
+         * consume from
+         * 
+         * @param tag an identifier to associate with the consumer
+         * that can be used to cancel its subscription (if empty, this
+         * will be assigned by the broker)
+         * 
+         * @param listener a pointer to an instance of an
+         * implementation of the MessageListener interface. Messages
+         * received from this queue for this consumer will result in
+         * invocation of the received() method on the listener, with
+         * the message itself passed in.
+         * 
+         * @param ackMode the mode of acknowledgement that the broker
+         * should assume for this consumer. @see ack_modes
+         * 
+         * @param noLocal if true, this consumer will not be sent any
+         * message published by this connection
+         * 
+         * @param synch if true this call will block until a response
+         * is received from the broker
+         */
         void consume(Queue& queue, std::string& tag, MessageListener* listener, 
                      int ackMode = NO_ACK, bool noLocal = false, bool synch = true);
+        /**
+         * Cancels a subscription previously set up through a call to consume().
+         *
+         * @param tag the identifier used (or assigned) in the consume
+         * request that set up the subscription to be cancelled.
+         * 
+         * @param synch if true this call will block until a response
+         * is received from the broker
+         */
 	void cancel(std::string& tag, bool synch = true);
+        /**
+         * Synchronous pull of a message from a queue.
+         * 
+         * @param msg a message object that will contain the message
+         * headers and content if the call completes.
+         * 
+         * @param queue the queue to consume from
+         * 
+         * @param ackMode the acknowledgement mode to use (@see
+         * ack_modes)
+         * 
+         * @return true if a message was succcessfully dequeued from
+         * the queue, false if the queue was empty.
+         */
         bool get(Message& msg, const Queue& queue, int ackMode = NO_ACK);
+        /**
+         * Publishes (i.e. sends a message to the broker).
+         * 
+         * @param msg the message to publish
+         * 
+         * @param exchange the exchange to publish the message to
+         * 
+         * @param routingKey the routing key to publish with
+         * 
+         * @param mandatory if true and the exchange to which this
+         * publish is directed has no matching bindings, the message
+         * will be returned (see setReturnedMessageHandler()).
+         * 
+         * @param immediate if true and there is no consumer to
+         * receive this message on publication, the message will be
+         * returned (see setReturnedMessageHandler()).
+         */
         void publish(Message& msg, const Exchange& exchange, const std::string& routingKey, 
                      bool mandatory = false, bool immediate = false);
 
+        /**
+         * For a transactional channel this will commit all
+         * publications and acknowledgements since the last commit (or
+         * the channel was opened if there has been no previous
+         * commit). This will cause published messages to become
+         * available to consumers and acknowledged messages to be
+         * consumed and removed from the queues they were dispatched
+         * from.
+         * 
+         * Transactionailty of a channel is specified when the channel
+         * object is created (@see Channel()).
+         */
         void commit();
+        /**
+         * For a transactional channel, this will rollback any
+         * publications or acknowledgements. It will be as if the
+         * ppblished messages were never sent and the acknowledged
+         * messages were never consumed.
+         */
         void rollback();
 
+        /**
+         * Change the prefetch in use.
+         */
         void setPrefetch(u_int16_t prefetch);
 
 	/**
@@ -113,8 +295,17 @@ namespace client {
 	 */
 	void run();
 
+        /**
+         * Closes a channel, stopping any message dispatching.
+         */
         void close();
 
+        /**
+         * Set a handler for this channel that will process any
+         * returned messages
+         * 
+         * @see publish()
+         */
 	void setReturnedMessageHandler(ReturnedMessageHandler* handler);
 
         friend class Connection;
diff --git a/qpid/cpp/lib/client/ClientExchange.cpp b/qpid/cpp/lib/client/ClientExchange.cpp
index 8252c3e2f6..5e5f3f14c6 100644
--- a/qpid/cpp/lib/client/ClientExchange.cpp
+++ b/qpid/cpp/lib/client/ClientExchange.cpp
@@ -28,6 +28,7 @@ const std::string qpid::client::Exchange::DIRECT_EXCHANGE = "direct";
 const std::string qpid::client::Exchange::TOPIC_EXCHANGE = "topic";
 const std::string qpid::client::Exchange::HEADERS_EXCHANGE = "headers";
 
-const qpid::client::Exchange qpid::client::Exchange::DEFAULT_DIRECT_EXCHANGE("amq.direct", DIRECT_EXCHANGE);
-const qpid::client::Exchange qpid::client::Exchange::DEFAULT_TOPIC_EXCHANGE("amq.topic", TOPIC_EXCHANGE);
-const qpid::client::Exchange qpid::client::Exchange::DEFAULT_HEADERS_EXCHANGE("amq.headers", HEADERS_EXCHANGE);
+const qpid::client::Exchange qpid::client::Exchange::DEFAULT_EXCHANGE("", DIRECT_EXCHANGE);
+const qpid::client::Exchange qpid::client::Exchange::STANDARD_DIRECT_EXCHANGE("amq.direct", DIRECT_EXCHANGE);
+const qpid::client::Exchange qpid::client::Exchange::STANDARD_TOPIC_EXCHANGE("amq.topic", TOPIC_EXCHANGE);
+const qpid::client::Exchange qpid::client::Exchange::STANDARD_HEADERS_EXCHANGE("amq.headers", HEADERS_EXCHANGE);
diff --git a/qpid/cpp/lib/client/ClientExchange.h b/qpid/cpp/lib/client/ClientExchange.h
index 8edc62713b..1c84a917a8 100644
--- a/qpid/cpp/lib/client/ClientExchange.h
+++ b/qpid/cpp/lib/client/ClientExchange.h
@@ -25,20 +25,73 @@
 
 namespace qpid {
 namespace client {
-
+    
+    /**
+     * A 'handle' used to represent an AMQP exchange in the Channel
+     * methods. Exchanges are the destinations to which messages are
+     * published. 
+     * 
+     * There are different types of exchange (the standard types are
+     * available as static constants, see DIRECT_EXCHANGE,
+     * TOPIC_EXCHANGE and HEADERS_EXCHANGE).  A Queue can be bound to
+     * an exchange using Channel::bind() and messages published to
+     * that exchange are then routed to the queue based on the details
+     * of the binding and the type of exchange.
+     *
+     * There are some standard exchange instances that are predeclared
+     * on all AMQP brokers. handles for these are defined as statisc
+     * members (see DEFAULT_DIRECT_EXCHANGE, DEFAULT_TOPIC_EXCHANGE
+     * and DEFAULT_HEADERS_EXCHANGE). There is also the 'default'
+     * exchange which is nameless and of type 'direct' and has every
+     * declared queue bound to it by their name.
+     * 
+     * \ingroup clientapi
+     */
     class Exchange{
 	const std::string name;
 	const std::string type;
 
     public:
-
+        /**
+         * A direct exchange routes messages published with routing
+         * key X to any queue bound with key X (i.e. an exact match is
+         * used).
+         */
 	static const std::string DIRECT_EXCHANGE;
+        /**
+         * A topic exchange treat the key with which a queue is bound
+         * as a pattern and routes all messages whose routing keys
+         * match that pattern to the bound queue. The routing key for
+         * a message must consist of zero or more alpha-numeric words
+         * delimited by dots. The pattern is of a similar form but *
+         * can be used to match excatly one word and # can be used to
+         * match zero or more words.
+         */
 	static const std::string TOPIC_EXCHANGE;
+        /**
+         * The headers exchange routes messages based on whether their
+         * headers match the binding arguments specified when
+         * binding. (see the AMQP spec for more details).
+         */
 	static const std::string HEADERS_EXCHANGE;
 
-	static const Exchange DEFAULT_DIRECT_EXCHANGE;
-	static const Exchange DEFAULT_TOPIC_EXCHANGE;
-	static const Exchange DEFAULT_HEADERS_EXCHANGE;
+        /**
+         * The 'default' exchange, nameless and of type 'direct'. Has
+         * every declared queue bound to it by name.
+         */
+	static const Exchange DEFAULT_EXCHANGE;
+        /**
+         * The standard direct exchange, named amq.direct.
+         */
+	static const Exchange STANDARD_DIRECT_EXCHANGE;
+        /**
+         * The standard topic exchange, named amq.topic.
+         */
+	static const Exchange STANDARD_TOPIC_EXCHANGE;
+        /**
+         * The standard headers exchange, named amq.header.
+         */
+	static const Exchange STANDARD_HEADERS_EXCHANGE;
 
 	Exchange(std::string name, std::string type = DIRECT_EXCHANGE);
 	const std::string& getName() const;
diff --git a/qpid/cpp/lib/client/ClientMessage.h b/qpid/cpp/lib/client/ClientMessage.h
index c1bcea3720..b46eb0bc72 100644
--- a/qpid/cpp/lib/client/ClientMessage.h
+++ b/qpid/cpp/lib/client/ClientMessage.h
@@ -28,6 +28,12 @@
 namespace qpid {
 namespace client {
 
+    /**
+     * A representation of messages for sent or recived through the
+     * client api.
+     *
+     * \ingroup clientapi
+     */
     class Message{
 	qpid::framing::AMQHeaderBody::shared_ptr header;
         std::string data;
@@ -40,9 +46,25 @@ namespace client {
 	Message();
 	~Message();
 	
+        /**
+         * Allows the application to access the content of messages
+         * received.
+         * 
+         * @return a string representing the data of the message
+         */
 	inline std::string getData(){ return data; }
+        /**
+         * Allows the application to set the content of messages to be
+         * sent.
+         * 
+         * @param data a string representing the data of the message
+         */
 	inline void setData(const std::string& _data){ data = _data; }
 
+        /**
+         * @return true if this message was delivered previously (to
+         * any consumer) but was not acknowledged.
+         */
 	inline bool isRedelivered(){ return redelivered; }
 	inline void setRedelivered(bool _redelivered){  redelivered = _redelivered; }
 
@@ -66,6 +88,9 @@ namespace client {
 	void setContentType(const std::string& type);
 	void setContentEncoding(const std::string& encoding);
 	void setHeaders(const qpid::framing::FieldTable& headers);
+        /**
+         * Sets the delivery mode. 1 = non-durable, 2 = durable.
+         */
 	void setDeliveryMode(u_int8_t mode);
 	void setPriority(u_int8_t priority);
 	void setCorrelationId(const std::string& correlationId);
diff --git a/qpid/cpp/lib/client/ClientQueue.h b/qpid/cpp/lib/client/ClientQueue.h
index df7235e4ab..037856ecd2 100644
--- a/qpid/cpp/lib/client/ClientQueue.h
+++ b/qpid/cpp/lib/client/ClientQueue.h
@@ -26,6 +26,31 @@
 namespace qpid {
 namespace client {
 
+    /**
+     * A 'handle' used to represent an AMQP queue in the Channel
+     * methods. Creating an instance of this class does not cause the
+     * queue to be created on the broker. Rather, an instance of this
+     * class should be passed to Channel::declareQueue() to ensure
+     * that the queue exists or is created.
+     * 
+     * Queues hold messages and allow clients to consume
+     * (see Channel::consume()) or get (see Channel::get()) those messags. A
+     * queue receives messages by being bound to one or more Exchange;
+     * messages published to that exchange may then be routed to the
+     * queue based on the details of the binding and the type of the
+     * exchange (see Channel::bind()).
+     * 
+     * Queues are identified by a name. They can be exclusive (in which
+     * case they can only be used in the context of the connection
+     * over which they were declared, and are deleted when then
+     * connection closes), or they can be shared. Shared queues can be
+     * auto deleted when they have no consumers.
+     * 
+     * We use the term 'temporary queue' to refer to an exclusive
+     * queue.
+     * 
+     * \ingroup clientapi
+     */
     class Queue{
 	std::string name;
         const bool autodelete;
@@ -33,9 +58,35 @@ namespace client {
 
     public:
 
+        /**
+         * Creates an unnamed, temporary queue. A name will be
+         * assigned to this queue instance by a call to
+         * Channel::declareQueue().
+         */
 	Queue();
+        /**
+         * Creates a shared queue with a given name, that will not be
+         * autodeleted.
+         * 
+         * @param name the name of the queue
+         */
 	Queue(std::string name);
+        /**
+         * Creates a queue with a given name.
+         * 
+         * @param name the name of the queue
+         * 
+         * @param temp if true the queue will be a temporary queue, if
+         * false it will be shared and not autodeleted.
+         */
 	Queue(std::string name, bool temp);
+        /**
+         * This constructor allows the autodelete and exclusive
+         * propeties to be explictly set. Note however that if
+         * exclusive is true, autodelete has no meaning as exclusive
+         * queues are always destroyed when the connection that
+         * created them is closed.
+         */
 	Queue(std::string name, bool autodelete, bool exclusive);
 	const std::string& getName() const;
 	void setName(const std::string&);
diff --git a/qpid/cpp/lib/client/Connection.h b/qpid/cpp/lib/client/Connection.h
index aec4de0b37..7d3f1a1446 100644
--- a/qpid/cpp/lib/client/Connection.h
+++ b/qpid/cpp/lib/client/Connection.h
@@ -38,14 +38,26 @@
 #include <ResponseHandler.h>
 
 namespace qpid {
+    /**
+     * The client namespace contains all classes that make up a client
+     * implementation of the AMQP protocol. The key classes that form
+     * the basis of the client API to be used by applications are
+     * Connection and Channel.
+     */
 namespace client {
 
     class Channel;
 
     /**
+     * \defgroup clientapi Application API for an AMQP client
+     */
+
+    /**
      * Represents a connection to an AMQP broker. All communication is
      * initiated by establishing a connection, then opening one or
-     * more channels over that connection.
+     * more Channels over that connection.
+     * 
+     * \ingroup clientapi
      */
     class Connection : public virtual qpid::framing::InputHandler, 
         public virtual qpid::sys::TimeoutHandler, 
@@ -92,21 +104,52 @@ namespace client {
 	~Connection();
 
         /**
-         *
+         * Opens a connection to a broker.
+         * 
+         * @param host the host on which the broker is running
+         * 
+         * @param port the port on the which the broker is listening
+         * 
+         * @param uid the userid to connect with
+         * 
+         * @param pwd the password to connect with (currently SASL
+         * PLAIN is the only authentication method supported so this
+         * is sent in clear text)
+         * 
+         * @param virtualhost the AMQP virtual host to use (virtual
+         * hosts, where implemented(!), provide namespace partitioning
+         * within a single broker).
          */
         void open(const std::string& host, int port = 5672, 
                   const std::string& uid = "guest", const std::string& pwd = "guest", 
                   const std::string& virtualhost = "/");
+        /**
+         * Closes the connection. Any further use of this connection
+         * (without reopening it) will not succeed.
+         */
         void close();
+        /**
+         * Opens a Channel. In AMQP channels are like multi-plexed
+         * 'sessions' of work over a connection. Almost all the
+         * interaction with AMQP is done over a channel.
+         * 
+         * @param channel a pointer to a channel instance that will be
+         * used to represent the new channel.
+         */
 	void openChannel(Channel* channel);
 	/*
          * Requests that the server close this channel, then removes
          * the association to the channel from this connection
+         *
+         * @param channel a pointer to the channel instance to close
          */
 	void closeChannel(Channel* channel);
 	/*
          * Removes the channel from association with this connection,
 	 * without sending a close request to the server.
+         *
+         * @param channel a pointer to the channel instance to
+         * disassociate
          */
 	void removeChannel(Channel* channel);
 
@@ -117,6 +160,9 @@ namespace client {
 
 	virtual void shutdown();
 
+        /**
+         * @return the maximum frame size in use on this connection
+         */
 	inline u_int32_t getMaxFrameSize(){ return max_frame_size; }
     };
 
diff --git a/qpid/cpp/lib/client/MessageListener.h b/qpid/cpp/lib/client/MessageListener.h
index 669a8d2a05..cfb917b4f8 100644
--- a/qpid/cpp/lib/client/MessageListener.h
+++ b/qpid/cpp/lib/client/MessageListener.h
@@ -28,6 +28,14 @@
 namespace qpid {
 namespace client {
 
+    /**
+     * An interface through which asynchronously delivered messages
+     * can be received by an application. 
+     * 
+     * @see Channel::consume()
+     * 
+     * \ingroup clientapi
+     */
     class MessageListener{
     public:
         virtual ~MessageListener();
diff --git a/qpid/cpp/lib/client/MethodBodyInstances.h b/qpid/cpp/lib/client/MethodBodyInstances.h
index 7663a8b3ae..3ab0c9af8f 100644
--- a/qpid/cpp/lib/client/MethodBodyInstances.h
+++ b/qpid/cpp/lib/client/MethodBodyInstances.h
@@ -20,17 +20,16 @@
  */
 #include <framing/amqp_framing.h>
 
-/**
- * This file replaces the auto-generated instances in the former
- * amqp_methods.h file. Add additional instances as needed.
- */
-
 #ifndef _MethodBodyInstances_h_
 #define _MethodBodyInstances_h_
 
 namespace qpid {
 namespace client {
 
+/**
+ * A list of method body instances that can be used to compare against
+ * incoming bodies.
+ */
 class MethodBodyInstances
 {
 private:
diff --git a/qpid/cpp/lib/client/ReturnedMessageHandler.h b/qpid/cpp/lib/client/ReturnedMessageHandler.h
index 2b5edbe2ea..137f0b2e17 100644
--- a/qpid/cpp/lib/client/ReturnedMessageHandler.h
+++ b/qpid/cpp/lib/client/ReturnedMessageHandler.h
@@ -28,6 +28,14 @@
 namespace qpid {
 namespace client {
 
+    /**
+     * An interface through which returned messages can be received by
+     * an application.
+     * 
+     * @see Channel::setReturnedMessageHandler()
+     * 
+     * \ingroup clientapi
+     */
     class ReturnedMessageHandler{
     public:
         virtual ~ReturnedMessageHandler();
diff --git a/qpid/cpp/lib/common/framing/FieldTable.h b/qpid/cpp/lib/common/framing/FieldTable.h
index 3d09cdec64..6fa10ab108 100644
--- a/qpid/cpp/lib/common/framing/FieldTable.h
+++ b/qpid/cpp/lib/common/framing/FieldTable.h
@@ -28,11 +28,21 @@
 #define _FieldTable_
 
 namespace qpid {
+    /**
+     * The framing namespace contains classes that are used to create,
+     * send and receive the basic packets from which AMQP is built.
+     */
 namespace framing {
 
 class Value;
 class Buffer;
 
+/**
+ * A set of name-value pairs. (See the AMQP spec for more details on
+ * AMQP field tables).
+ *
+ * \ingroup clientapi
+ */
 class FieldTable
 {
   public: