diff options
author | Jonathan Robie <jonathan@apache.org> | 2010-04-29 16:35:47 +0000 |
---|---|---|
committer | Jonathan Robie <jonathan@apache.org> | 2010-04-29 16:35:47 +0000 |
commit | 2d9f20b8084302d379d902e2289541d7c05d5233 (patch) | |
tree | 788c2c66d4e000f83a8fb98d3b0934d2e77b9bc1 /cpp/docs/api/doxygen_mainpage.h | |
parent | ef4d4e27089600c8c86aacb7b4b60051b73ce45e (diff) | |
download | qpid-python-2d9f20b8084302d379d902e2289541d7c05d5233.tar.gz |
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/qpid@939372 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'cpp/docs/api/doxygen_mainpage.h')
-rw-r--r-- | cpp/docs/api/doxygen_mainpage.h | 330 |
1 files changed, 248 insertions, 82 deletions
diff --git a/cpp/docs/api/doxygen_mainpage.h b/cpp/docs/api/doxygen_mainpage.h index 83efaba31d..cb36d7edb0 100644 --- a/cpp/docs/api/doxygen_mainpage.h +++ b/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& 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 * */ + + + |