From 048ee2ccf2fa95658388a0dc8768cf3f8d6a8735 Mon Sep 17 00:00:00 2001
From: Jonathan Robie <jonathan@apache.org>
Date: Thu, 29 Apr 2010 16:35:47 +0000
Subject: Changed code examples and references from doxygen main page to the
 new API classes.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@939372 13f79535-47bb-0310-9956-ffa450edef68
---
 qpid/cpp/docs/api/doxygen_mainpage.h | 330 ++++++++++++++++++++++++++---------
 1 file changed, 248 insertions(+), 82 deletions(-)

(limited to 'qpid/cpp/docs/api')

diff --git a/qpid/cpp/docs/api/doxygen_mainpage.h b/qpid/cpp/docs/api/doxygen_mainpage.h
index 83efaba31d..cb36d7edb0 100644
--- a/qpid/cpp/docs/api/doxygen_mainpage.h
+++ b/qpid/cpp/docs/api/doxygen_mainpage.h
@@ -25,109 +25,275 @@
  *
  * <h2>Messaging Client API classes</h2>
  * <ul>
- * <li><p>\ref clientapi</p></li>
+ * <li><p>\ref messaging</p></li>
  * <li><p>\ref qmfapi</p></li>
  * </ul>
  * 
  * <h2>Code for common tasks</h2>
  *
- * <ul><li><p>Includes and Namespaces</p>
- * <pre> \#include <qpid/client/Connection.h>
- * \#include <qpid/client/Session.h>
- * \#include <qpid/client/Message.h>
- * \#include <qpid/client/SubscriptionManager.h>
  * 
- *
- * using namespace qpid::client; 
- * using namespace qpid::framing;</pre></li>
+ * <h3>Includes and Namespaces</h3>
  * 
- * <li><p>Opening and closing connections and sessions</p>
- * <pre> Connection connection;
- * try {
- *    connection.open(host, port);
- *    Session session =  connection.newSession();
- *    ...
- *    connection.close();
- *    return 0;
- * } catch(const std::exception& error) {
- *    std::cout << error.what() << std::endl;
+ * <pre>
+ * #include <qpid/messaging/Connection.h>
+ * #include <qpid/messaging/Message.h>
+ * #include <qpid/messaging/Receiver.h>
+ * #include <qpid/messaging/Sender.h>
+ * #include <qpid/messaging/Session.h>
+ * 
+ * #include <iostream>
+ * 
+ * using namespace qpid::messaging;
+ * </pre>
+ * 
+ * <h3>Opening Sessions and Connections</h3>
+ * 
+ * <pre>
+ * int main(int argc, char** argv) {
+ *     std::string broker = argc > 1 ? argv[1] : "localhost:5672";
+ *     std::string address = argc > 2 ? argv[2] : "amq.topic";
+ *     Connection connection(broker);
+ *     try {
+ *         connection.open();
+ *         Session session = connection.createSession();
+ * 
+ * 	// ### Your Code Here ###
+ *         
+ *         connection.close();
+ *         return 0;
+ *     } catch(const std::exception& error) {
+ *         std::cerr << error.what() << std::endl;
+ *         connection.close();
+ *         return 1;   
+ *     }
  * }
- * return 1;</pre>
- *
- *
- * <li><p>Declaring and binding queues:</p>
- *
- * <pre> session.queueDeclare(arg::queue="message_queue");
- * session.exchangeBind(arg::exchange="amq.direct", arg::queue="message_queue", arg::bindingKey="routing_key");</pre></li>
- *
- * <li><p>Sending a message:</p>
- *
- * <pre> message.getDeliveryProperties().setRoutingKey("routing_key"); 
- * message.setData("Hi, Mom!");
- * session.messageTransfer(arg::content=message,  arg::destination="amq.direct");</pre></li>
- *
- * <li><p>Sending a message (asynchronous):</p>
- *
- * <pre> ##include <qpid/client/AsyncSession.h>
- * async(session).messageTransfer(arg::content=message,  arg::destination="amq.direct");
- *  ...
- * session.sync();</pre></li>
+ * </pre>
  * 
+ * <h3>Creating and Sending a Message</h3>
+ * 
+ * <pre>
+ * Sender sender = session.createSender(address);
+ * sender.send(Message("Hello world!"));
+ * </pre>
+ * 
+ * <h3>Setting Message Content</h3>
+ * 
+ * <pre>
+ * Message message;
+ * message.setContent("Hello world!");
+ * 
+ * // In some applications, you should also set the content type,
+ * // which is a MIME type
+ * message.setContentType("text/plain");
+ * </pre>
+ * 
+ * <h3>Receiving a Message</h3>
+ * 
+ * <pre>
+ * Receiver receiver = session.createReceiver(address);
+ * Message message = receiver.fetch(Duration::SECOND * 1); // timeout is optional
+ * session.acknowledge(); // acknowledge message receipt
+ * std::cout << message.getContent() << std::endl;
+ * </pre>
+ * 
+ * <h3>Receiving Messages from Multiple Sources</h3>
+ * 
+ * To receive messages from multiple sources, create a receiver for each
+ * source, and use session.nextReceiver().fetch() to fetch messages.
+ * session.nextReceiver() is guaranteed to return the receiver
+ * responsible for the first available message on the session.
+ * 
+ * <pre>
+ * Receiver receiver1 = session.createReceiver(address1);
+ * Receiver receiver2 = session.createReceiver(address2);
+ * 
+ * Message message =  session.nextReceiver().fetch();
+ * session.acknowledge(); // acknowledge message receipt
+ * std::cout << message.getContent() << std::endl;
+ * </pre>
+ * 
+ * <h3>Replying to a message:</h3>
+ * 
+ * <pre>
+ * // Server creates a service queue and waits for messages
+ * // If it gets a request, it sends a response to the reply to address
  *
- * <li><p>Replying to a message:</p>
- * <pre> Message request, response; 
- * ...
- * if (request.getMessageProperties().hasReplyTo()) {
- *    string routingKey = request.getMessageProperties().getReplyTo().getRoutingKey();
- *    string exchange = request.getMessageProperties().getReplyTo().getExchange();
- *    response.getDeliveryProperties().setRoutingKey(routingKey);
- *    messageTransfer(arg::content=response, arg::destination=exchange);
- * } 
- * </pre></li>
- *
- * <li><p>A message listener:</p>
- *
- * <pre> class Listener : public MessageListener{
- *  private:
- *    SubscriptionManager& subscriptions;
- *  public:
- *    Listener(SubscriptionManager& subscriptions);
- *    virtual void received(Message& message);
- * };
- *
- * void Listener::received(Message& message) {
- *    std::cout << "Message: " << message.getData() << std::endl;
- *    if (endCondition(message)) {
- *       subscriptions.cancel(message.getDestination());
- *    }
- * }</pre></li>
+ * Receiver receiver = session.createReceiver("service_queue; {create: always}");
+ * Message request = receiver.fetch();
+ * const Address&amp; address = request.getReplyTo(); // Get "reply-to" from request ...
+ * if (address) {
+ *   Sender sender = session.createSender(address); // ... send response to "reply-to"
+ *   Message response("pong!");
+ *   sender.send(response);
+ *   session.acknowledge();
+ * }
  *
- * <li><p>Using a message listener with a subscription manager:</p>
  *
- * <pre> SubscriptionManager subscriptions(session);
+ * // Client creates a private response queue - the # gets converted
+ * // to a unique string for the response queue name. Client uses the
+ * // name of this queue as its reply-to.
  *
- * Listener listener(subscriptions);
- * subscriptions.subscribe(listener, "message_queue");
- * subscriptions.run();</pre></li>
+ * Sender sender = session.createSender("service_queue");
+ * Address responseQueue("#response-queue; {create:always, delete:always}");
+ * Receiver receiver = session.createReceiver(responseQueue);
  *
- * <li><p>Using a LocalQueue with a subscription manager</p>
+ * Message request;
+ * request.setReplyTo(responseQueue);
+ * request.setContent("ping");
+ * sender.send(request);
+ * Message response = receiver.fetch();
+ * std::cout << request.getContent() << " -> " << response.getContent() << std::endl;
+ * </pre>
+ * 
+ * 
+ * <h3>Getting and Setting Standard Message Properties</h3>
+ * 
+ * This shows some of the most commonly used message properties, it is
+ * not complete.
+ * 
+ * <pre>
+ * Message message("Hello world!");
+ * message.setContentType("text/plain");
+ * message.setSubject("greeting");
+ * message.setReplyTo("response-queue");
+ * message.setTtl(100); // milliseconds
+ * message.setDurable(1);
+ * 
+ * std::cout << "Content: " << message.getContent() << std::endl
+ *           << "Content Type: " << message.getContentType()
+ *           << "Subject: " << message.getSubject()
+ * 	  << "ReplyTo: " << message.getReplyTo()
+ * 	  << "Time To Live (in milliseconds) " << message.getTtl()
+ * 	  << "Durability: " << message.getDurable();
+ * </pre>
+ * 
+ * <h3>Getting and Setting Application-Defined Message Properties</h3>
+ * 
+ * <pre>
+ * std::string name = "weekday";
+ * std::string value = "Thursday";
+ * message.getProperties()[name] = value;
+ * 
+ * std:string s = message.getProperties()["weekday"];
+ * </pre>
+ * 
+ * <h3>Transparent Failover</h3>
+ * 
+ * If a connection opened using the reconnect option, it will
+ * transparently reconnect if the connection is lost.
+ * 
+ * <pre>
+ * Connection connection(broker);
+ * connection.setOption("reconnect", true);
+ * try {
+ *     connection.open();
+ *     ....
+ * </pre>
+ * 
  *
- * <pre> SubscriptionManager subscriptions(session);
- *   
- * LocalQueue local_queue;
- * subscriptions.subscribe(local_queue, string("message_queue"));
- *  
+ * <h3>Maps</h3>
+ * 
+ * Maps provide a simple way to exchange binary data portably, across
+ * languages and platforms. Maps can contain simple types, lists, or
+ * maps.
+ * 
+ * 
+ * <pre>
+ * // Sender
+ * 
+ * Variant::Map content;
+ * content["id"] = 987654321;
+ * content["name"] = "Widget";
+ * content["probability"] = 0.43;
+ * Variant::List colours;
+ * colours.push_back(Variant("red"));
+ * colours.push_back(Variant("green"));
+ * colours.push_back(Variant("white"));
+ * content["colours"] = colours;
+ * content["uuid"] = Uuid(true);
+ * 
  * Message message;
- * for (int i=0; i<10; i++) {
- *    local_queue.get(message, 10000);
- *    std::cout << message.getData() << std::endl;
- * }</pre></li><ul>
+ * encode(content, message);
+ * 	
+ * sender.send(message);
+ * </pre>
+ * 
+ * <pre>
+ * // Receiver
+ * 
+ * Variant::Map content;
+ * decode(receiver.fetch(), content);
+ * </pre>
  *
+ * <h3>Guaranteed Delivery</h3>
+ * 
+ * If a queue is durable, the queue survives a messaging broker crash, as
+ * well as any durable messages that have been placed on the queue. These
+ * messages will be delivered when the messaging broker is
+ * restarted. Delivery is not guaranteed unless both the message and the
+ * queue are durable.
+ * 
+ * <pre>
+ * Sender sender = session.createSender("durable-queue");
+ * 
+ * Message message("Hello world!");
+ * message.setDurable(1);
+ * 
+ * sender.send(Message("Hello world!"));
+ * </pre>
+ * 
+ * 
+ * <h3>Transactions</h3>
+ * 
+ * Transactions cover enqueues and dequeues.
+ * 
+ * When sending messages, a transaction tracks enqueues without actually
+ * delivering the messages, a commit places messages on their queues, and
+ * a rollback discards the enqueues.
+ * 
+ * When receiving messages, a transaction tracks dequeues without
+ * actually removing acknowledged messages, a commit removes all
+ * acknowledged messages, and a rollback discards acknowledgements. A
+ * rollback does not release the message, it must be explicitly released
+ * to return it to the queue.
+ * 
+ * <pre>
+ * Connection connection(broker);
+ * Session session =  connection.createTransactionalSession();
+ * ...
+ * if (looksOk)
+ *    session.commit();
+ * else 
+ *    session.rollback();
+ * </pre>
+ * 
+ * <h3>Logging</h3>
+ * 
+ * The Qpidd broker and C++ clients can both use environment variables to
+ * enable logging. Use QPID_LOG_ENABLE to set the level of logging you
+ * are interested in (trace, debug, info, notice, warning, error, or
+ * critical):
+ * 
+ * <pre>
+ * export QPID_LOG_ENABLE="warning+"
+ * </pre>
+ * 
+ * Use QPID_LOG_OUTPUT to determine where logging output should be
+ * sent. This is either a file name or the special values stderr, stdout,
+ * or syslog:
+ * 
+ * <pre>
+ * export QPID_LOG_TO_FILE="/tmp/myclient.out"
+ * </pre>
+ * 
  *
  */
 
 /**
- * \defgroup clientapi Qpid C++ Client API
+ * \defgroup messaging Qpid C++ Client API
  * \defgroup qmfapi Qpid Management Framework C++ API
  *
  */
+
+
+
-- 
cgit v1.2.1