You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jo...@apache.org on 2010/04/29 18:35:47 UTC
svn commit: r939372 - /qpid/trunk/qpid/cpp/docs/api/doxygen_mainpage.h
Author: jonathan
Date: Thu Apr 29 16:35:47 2010
New Revision: 939372
URL: http://svn.apache.org/viewvc?rev=939372&view=rev
Log:
Changed code examples and references from doxygen main page to the new API classes.
Modified:
qpid/trunk/qpid/cpp/docs/api/doxygen_mainpage.h
Modified: qpid/trunk/qpid/cpp/docs/api/doxygen_mainpage.h
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/docs/api/doxygen_mainpage.h?rev=939372&r1=939371&r2=939372&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/docs/api/doxygen_mainpage.h (original)
+++ qpid/trunk/qpid/cpp/docs/api/doxygen_mainpage.h Thu Apr 29 16:35:47 2010
@@ -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;
+ * }
+ * }
+ * </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
+ *
+ * Receiver receiver = session.createReceiver("service_queue; {create: always}");
+ * Message request = receiver.fetch();
+ * const Address& 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();
* }
- * 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>
+ * // 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.
+ *
+ * Sender sender = session.createSender("service_queue");
+ * Address responseQueue("#response-queue; {create:always, delete:always}");
+ * Receiver receiver = session.createReceiver(responseQueue);
+ *
+ * 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>
*
*
- * <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>
- *
- * <li><p>Using a message listener with a subscription manager:</p>
- *
- * <pre> SubscriptionManager subscriptions(session);
- *
- * Listener listener(subscriptions);
- * subscriptions.subscribe(listener, "message_queue");
- * subscriptions.run();</pre></li>
- *
- * <li><p>Using a LocalQueue with a subscription manager</p>
- *
- * <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
*
*/
+
+
+
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org