Red Hat JBoss A-MQ 7.0- Beta Using the AMQP CPP Client

Transcription

1 Red Hat JBoss A-MQ 7.0- Beta Using the AMQP CPP Client For use with A-MQ Clients Red Hat Customer Content Services

2

3 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client For use with A-MQ Clients 1.1.0

4 Legal Notice Copyright 2016 Red Hat, Inc. The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. Node.js is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. The OpenStack Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. All other trademarks are the property of their respective owners. Abstract This guide describes how to install and configure the client, run hands-on examples, and use your client with other A-MQ components.

5 Table of Contents Table of Contents. CHAPTER OVERVIEW KEY FEATURES KEY CONCEPTS SUPPORTED CONFIGURATIONS 4. CHAPTER INSTALLATION USING YOUR SUBSCRIPTION INSTALLING ON RED HAT ENTERPRISE LINUX 5. CHAPTER GETTING STARTED PREPARING THE BROKER BUILDING THE EXAMPLES SENDING AND RECEIVING MESSAGES 8. CHAPTER EXAMPLES CHAPTER USING THE.... API BASIC OPERATION SECURITY ERROR HANDLING 18 1

6 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client 2

7 CHAPTER 1. OVERVIEW CHAPTER 1. OVERVIEW The AMQP CPP Client is a C++ library for writing messaging applications. It allows you to write client and server applications that send and receive AMQP messages. The AMQP CPP Client is based on the Proton API from Apache Qpid. The code presented in this guide uses C++ 11 features. The AMQP CPP Client is also compatible with C++ 03, but the code will require small modifications KEY FEATURES The AMQP CPP Client offers convenience for simple tasks while still providing a full set of messaging tools to handle complex applications. An event-driven API that simplifies integration with existing applications. Access to all the features and capabilities of AMQP 1.0. Secure communication via SSL and SASL. Support for peer-to-peer and brokered messaging. Seamless conversion between AMQP and native data types. Heartbeating and automatic reconnect for reliable network connections KEY CONCEPTS The AMQP CPP Client sends and receives messages through a hierarchical system of connections types as shown below. Table 1.1. The connection hierarchy: Link Messages are transferred between connected peers over links. Links may have named source and target addresses, which can be used to identify the queue messages are sent to or received from. Links are established over sessions. Session Sessions are established over connections. Connection Connections are generally established between two uniquely identified containers. Though a connection can have multiple sessions, often this is not needed. The container API allows you to ignore sessions unless you require them. A connection operates using a transport. 3

8 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client Transport A transport is a network communication channel, such as a TCP connection. The sending of a message over a link is called a delivery. The message is the content sent, including all metadata such as headers and annotations. The delivery is the protocol exchange associated with the transfer of that content. To indicate that a delivery is complete, either the sender or the receiver settles it. When the other side learns that it has been settled, it will no longer communicate about that delivery. The receiver can also indicate whether they accept or reject the message SUPPORTED CONFIGURATIONS GNU C++ on RHEL 6, 7, compiling as C++ 03 or C Microsoft Visual Studio 2013 running on Windows Server 2012 R2. 4

9 CHAPTER 2. INSTALLATION CHAPTER 2. INSTALLATION 2.1. USING YOUR SUBSCRIPTION Using Your Subscription Red Hat JBoss A-MQ is provided through a software subscription. To manage your subscriptions, access your account at the Red Hat Customer Portal. Accessing Your Account 1. Go to 2. If you do not already have an account, create one. 3. Log in to your account. Activating a Subscription 1. Go to 2. Navigate to My Subscriptions. 3. Navigate to Activate a subscription and enter your 16-digit activation number. Downloading Zip and Tar Files To access zip or tar files, use the customer portal to find the relevant files for download. If you are using RPM packages, this step is not required. 1. Go to 2. Navigate to Download Latest. 3. Select the Download link for your component. Registering Your System for Packages To install RPM packages on Red Hat Enterprise Linux, your system must be registered. If you are using zip or tar files, this step is not required. 1. Go to 2. Navigate to Registration Assistant. 3. Select your OS version and continue to the next page. 4. Use the listed command in your system terminal to complete the registration. To learn more see How to Register and Subscribe a System to the Red Hat Customer Portal INSTALLING ON RED HAT ENTERPRISE LINUX 5

10 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client Before starting, make sure your subscription is activated and your system is registered. Then use yum to install the qpid-proton-cpp-devel and qpid-proton-cpp-docs packages. $ sudo yum install qpid-proton-cpp-devel qpid-proton-cpp-docs In order to compile programs using the API, you will also need to install gcc-c++, cmake, and make. $ sudo yum install gcc-c++ cmake make 6

11 CHAPTER 3. GETTING STARTED CHAPTER 3. GETTING STARTED This chapter will guide you through a simple exercise to help you get started using the AMQP CPP Client. Before starting, make sure you have completed the steps in the Chapter 2, Installation chapter for your platform PREPARING THE BROKER The example programs require a running broker with a queue named examples. Follow these steps to define the queue and start the broker. 1. Install the broker. 2. Create a broker instance. 3. Configure the broker s authentication. Enable anonymous access. 4. Open the <broker-instance-dir>/etc/broker.xml file in a text editor. Add the following queue definition in the core queues element. broker.xml <configuration> <core xmlns="urn:activemq:core"> <queues> <queue name="examples"> <address>examples</address> </queue> 5. Start the broker instance and check the console for any critical errors logged during startup. $ <broker-instance-dir>/bin/artemis run [...] 14:43:20,158 INFO [org.apache.activemq.artemis.integration.bootstrap] AMQ101000: Starting ActiveMQ Artemis Server [...] 15:01:39,686 INFO [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at :5672 for protocols [AMQP] [...] 15:01:39,691 INFO [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live 3.2. BUILDING THE EXAMPLES This section illustrates how to compile some example programs which come with the client API. 1. Create a directory to hold the programs. This example will call it "AMQ7C++SmokeTest", but you can use any name you like. 7

12 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client $ mkdir AMQ7C++SmokeTest 1. Enter the new directory. $ cd AMQ7C++SmokeTest 1. Copy all the examples to this directory. $ cp -r /usr/share/proton /examples/cpp. Note The example directory name depends on the version of proton we just installed is the version as of the writing of this documentation. If a different version is actually installed, this directory name will need to be changed to reflect the actual name installed on the system. This example compiles all of the examples and will then run the two of interest. They can be compiled like this: $ cmake. $ make Note It is not recommended to use cmake in the same directory as the source being built. This example does so for simplicity. Consider creating a directory for builds and run cmake there SENDING AND RECEIVING MESSAGES The compiled example programs will use the broker we started earlier to queue the messages between sending and receiving. Sending Messages 1. Use one of the example programs to send 10 messages to a queue called examples. $./simple_send -m 10 The command line option -m 10 tells the program to send 10 messages. This will output: all messages confirmed $ 8

13 CHAPTER 3. GETTING STARTED By default the simple_send example connects to an AMQP listener on the same machine (IP address , port 5672) and sends messages to the AMQP address examples. This corresponds to the examples queue that we have configured in the A-MQ Broker. Receiving Messages 1. Execute the below commands as you did in the previous example: $./simple_recv -m 10 In this case the command line option -m 10 tells the program to exit after receiving 10 messages. simple_recv listening on :5672/examples {"sequence"=1 {"sequence"=2 {"sequence"=3 {"sequence"=4 {"sequence"=5 {"sequence"=6 {"sequence"=7 {"sequence"=8 {"sequence"=9 {"sequence"=10 $ The simple_recv example is similar to the simple_send example: It also connects to an AMQP listener on the same machine. By default it will subscribe to the AMQP address examples and it will receive 100 messages. 9

14 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client CHAPTER 4. EXAMPLES The following examples are slightly modified versions of the example code that was used in the Chapter 3, Getting Started chapter. The main modification is to remove the command-line option parsing. Send messages code #include <proton/connection.hpp> #include <proton/default_container.hpp> #include <proton/messaging_handler.hpp> #include <proton/tracker.hpp> #include <proton/value.hpp> #include <iostream> #include <map> class simple_send : public proton::messaging_handler { private: std::string url; proton::sender sender; int sent; int confirmed; int total; public: simple_send(const std::string &s, int c) : url(s), sent(0), confirmed(0), total(c) { void on_container_start(proton::container &c) override { sender = c.open_sender(url); void on_sendable(proton::sender &s) override { while (s.credit() && sent < total) { proton::message msg; std::map<std::string, int> m; m["sequence"] = sent + 1; msg.id(sent + 1); msg.body(m); s.send(msg); sent++; void on_tracker_accept(proton::tracker &t) override { confirmed++; if (confirmed == total) { std::cout << "all messages confirmed" << std::endl; t.connection().close(); 10

15 CHAPTER 4. EXAMPLES ; void on_transport_close(proton::transport &) override { sent = confirmed; int main(int argc, char **argv) { std::string address(" :5672/examples"); int message_count = 100; try { simple_send send(address, message_count); proton::default_container(send).run(); return 0; catch (const std::exception& e) { std::cerr << e.what() << std::endl; return 1; Receive messages code #include <proton/connection.hpp> #include <proton/default_container.hpp> #include <proton/delivery.hpp> #include <proton/messaging_handler.hpp> #include <proton/link.hpp> #include <proton/message_id.hpp> #include <proton/value.hpp> #include <iostream> #include <map> class simple_recv : public proton::messaging_handler { private: std::string url; proton::receiver receiver; uint64_t expected; uint64_t received; public: simple_recv(const std::string &s, int c) : url(s), expected(c), received(0) { void on_container_start(proton::container &c) override { receiver = c.open_receiver(url); std::cout << "simple_recv listening on " << url << std::endl; void on_message(proton::delivery &d, proton::message &msg) override { if (proton::get<uint64_t>(msg.id()) < received) { return; // Ignore duplicate 11

16 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client if (expected == 0 received < expected) { std::cout << msg.body() << std::endl; received++; ; if (received == expected) { d.receiver().close(); d.connection().close(); int main(int argc, char **argv) { std::string address(" :5672/examples"); int message_count = 100; try { simple_recv recv(address, message_count); proton::default_container(recv).run(); return 0; catch (const std::exception& e) { std::cerr << e.what() << std::endl; return 1; See Qpid Proton C++ API Examples for more examples. 12

17 CHAPTER 5. USING THE API CHAPTER 5. USING THE API 5.1. BASIC OPERATION DOCS: Are the slashes in the examples below part of the code, or markup that s incorrectly appearing in the rendered text? === Handling Messaging Events The AMQP CPP Client is an asynchronous event-driven API. To handle events, the user supplies callback-method implementations using the messaging_handler class. #include <proton/messaging_handler.hpp> #include <proton/default_container.hpp> class ExampleHandler: public proton::messaging_handler { // The container has started void on_container_start(proton::container& c) override { // A message can be sent void on_sendable(proton::sender& s) override { ; // A message is received void on_message(proton::delivery& d, proton::message& m) override { int main() { ExampleHandler h{; proton::default_container(h).run(); These are only a few common-case events. The full set is documented in the Qpid Proton C++ API Documentation Sending Messages The following code shows a class that will send a single message. It will close the connection after it has either been accepted or rejected. Note that the on_tracker_accept and on_tracker_reject events are handled to track our message being accepted or rejected. class MessageSender: public proton::messaging_handler { const proton::value message_; 1 // A message can be sent void on_sendable(proton::sender& s) override { auto msg = proton::message(message_); s.send(proton::message(msg)); s.close(); std::cout << "Message sent\n"; 13

18 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client void on_tracker_accept(proton::tracker& t) override { std::cout << "Message accepted\n"; t.connection().close(); void on_tracker_reject(proton::tracker& t) override { std::cout << "Message rejected\n"; t.connection().close(); public: MessageSender(const proton::value message) : message_(message) { ; 1 The proton::value class is used to hold the message that we send, this class can hold any value allowed in the AMQP type system. The MessageSender class can be created and used by the following main program (this code omits error handling for the sake of clarity): int main() { MessageSender sender{"hello World"; auto container = make_default_container(sender); container->open_sender(" /examples"); container->run(); 1 1 proton::container::open_sender() is used as a shortcut API which will create a sender directly from the container. This shortcut avoids us having to explicitly create a connection and a session. The URL specified in this API is split into an IP address which is used to create the connection and an AMQP address which is used to create the sender Receiving messages The following shows a class that receives a message and accepts or rejects it depending on a specific test: class MessageReceiver: public proton::messaging_handler { std::function<bool(proton::value&)> test_; // A message is received void on_message(proton::delivery& d, proton::message& m) override { std::cout << "Received message body: " << m.body(); if (test_(m.body())) { d.accept(); 14

19 CHAPTER 5. USING THE API std::cout << " - Accepting\n"; else { d.reject(); std::cout << " - Rejecting\n"; public: MessageReceiver(std::function<bool(proton::value&)> test) : test_(test) { ; This can be used by the following main (error handling omitted for clarity): int main() { MessageReceiver receiver{validate; auto container = make_default_container(receiver); container->open_receiver(" /examples"); container->run(); validate can be any function that has the appropriate signature: bool fn(proton::value&) 2 proton::container::open_receiver() is used as a shortcut API similar to proton::container::open_sender(). It avoids having to separately create the connection, session and receiver Connecting to a Remote Peer To connect to a remote server or client, use the proton::container::connect() method with a URL containing a host and port. This is typically called inside the messaging_handler::on_container_start() method. Here is the definition of the event handling class. Note that it takes the URL to which it should connect as a parameter to its constructor. class ExampleHandler: public proton::messaging_handler { const std::string url_; void on_container_start(proton::container& c) override { c.connect(url_); void on_connection_open(proton::connection& c) override { 15

20 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client std::cout << "Connection to " << url_ << " is open\n"; 1 public: ExampleHandler(const std::string& url) : url_(url) { ; 1 At this point in the connection open handler you will usually create a sender (proton::sender) or a receiver (proton::receiver) so that your program can send or receive messages. The event handler can be created and started from the program main like this (this code omits error handling for the sake of clarity): int main() { ExampleHandler h{" :5672"; proton::default_container(h).run(); Listening for Incoming Connections The AMQP CPP Client can accept inbound network connections, allowing you to build messaging servers. To start listening for connections, use the proton::container::listen() method with a URL containing the local host address and port to listen on. In this configuration you do not need to create a receiver for incoming messages, the receiver will get created automatically when the sender on the client side gets created. You can inspect the target address of the receiver to validate it in on_receiver_open and potentially reject invalid addresses by closing the receiver with an error indication using proton::receiver::close. class ExampleHandler: public proton::messaging_handler { void on_container_start(proton::container& c) override { c.listen(" "); 1 void on_connection_open(proton::connection& c) override { std::cout << "New incoming connection to " << c.virtual_host() << "\n"; void on_receiver_open(proton::receiver& r) override { std::cout << "New incoming receiver: target address: " << r.target().address() << "\n"; ; 2 16

21 CHAPTER 5. USING THE API 1 The special IP address " " is used when listening to specify listening to all available IPv4 interfaces. If you wanted to listen to all IPv6 interfaces then you should use "[::0]". 2 At this point you will usually want to validate the incoming address to be sure we can handle it. Then perhaps allocate any resources (for instance a queue) that might be needed later Setting the Container Identity When the AMQP CPP Client connects to a peer, it indicates its container ID, its unique identity on the network. To set the container ID, pass it to the proton::container constructor. ExampleHandler handler{; auto container = make_default_container(handler, "job-processor-3"); container->run(); If no ID is supplied by the user, a default UUID is generated when the container is constructed SECURITY Encrypted connections TLS/SSL The typical way to encrypt an AMQP connection is to use the "amqps" scheme in the URL that is used to specify the connection address. This will encapsulate the AMQP protocol inside the TLS/SSL encrypted protocol. For example: container->connect("amqps://example.com"); Connection User and Password The AMQP protocol is able to authenticate connections. Most authentication mechanisms require setting a user who is being authenticated and a password to do the authentication. You can set the user and password by using the same URL that specifies the connection address. For example: container->open_sender("amqps://alice:mysecret@example.com/examples"); This will set the user to "alice" and the password to "mysecret". 17

22 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client SASL Mechanisms AMQP commonly uses the SASL protocol to perform its authentication. One aspect of using SASL for this is that SASL can use a number of different mechanisms to perform the authentication. Sometimes you will want to restrict the mechanisms that can be chosen for a particular application either on the client or server side. To restrict the possible SASL mechanism (for both client and server) use the sasl_allowed_mechs connection option. This takes a string with a space separated list of the allowed mechanisms. For example: auto options = proton::connection_options{.sasl_allowed_mechs("anonymous"); container->open_sender(" /examples", proton::sender_options{, options); This will force the connection to authenticate using the ANONYMOUS mechanism even if the server we connect to offers us other more secure options ERROR HANDLING Errors in the AMQP CPP Client can be handled in two different ways: Catching exceptions. Overriding virtual functions to handle AMQP protocol or connection errors Catching exceptions Catching exceptions is the most basic, but least granular, way to handle errors. If an error is not handled using an override in a handler routine, an exception will be thrown and can be caught and handled. An exception thrown in this way will be thrown by the container s run method. All of the exceptions that can be thrown by the AMQP CPP Client are descended from proton::error which, in turn is a subclass of std::runtime_error (which is a subclass of std::exception). The code example below illustrates how a block could be written to catch any exception thrown from the AMQP CPP Client: try { // Something that might throw an exception catch (proton::error& e) { // Handle specific proton problem here catch (std::exception& e) { // Handle more general problem here 18

23 CHAPTER 5. USING THE API If there is no proton specific exception handling, you only need to catch std::exception since proton::error descends from it. For instance: int main() { try { // Something that might throw an exception catch (std::exception& e) { std::cerr << "Caught exception: " << e.what() << "\n"; Note As all exceptions in a C++ program can be assumed to descend from std::exception, you can write a code block to wrap your main method and display information about any std::exception errors Handling Specific AMQP or Connection Errors You can handle errors by overriding the following messaging_handler methods: on_transport_error(proton::transport&) on_connection_error(proton::connection&) on_session_error(proton::session&) on_receiver_error(proton::receiver&) on_sender_error(proton::sender&) These event handling routines are called whenever there is an error condition with the specific object that is in the event. After calling the error handler, the appropriate close handler will also be called. If not overridden the default error handler will be called with an indication of the error condition that occurred. There is also a default error handler: on_error(proton::error_condition&) If one of the more specific error handlers is not overridden this will be called. 19

24 Red Hat JBoss A-MQ 7.0-Beta Using the AMQP CPP Client Note As the close handlers will be called in the event of any error, only error itself need be handled within the error handler. Resource clean up can be managed by close handlers. If there is no error handling that is specific to a particular object it is typical to use the general on_error handler and not have a more specific handler. == More Information For more information about the API see the Qpid Proton C++ API Guide = Compatibility = Using AMQP CPP Client with A-MQ Broker A-MQ Broker is designed to interoperate with AMQP 1.0 clients. Check the following to ensure the broker is configured for AMQP messaging. Port 5672 in the network firewall is open. The A-MQ Broker AMQP acceptor is enabled. See Configuring Network Access. The necessary queues and topics are configured on the broker. See Configuring a Queue and Configuring a Topic. The broker is configured to permit access from your client. See Broker Security. = Using AMQP CPP Client with A-MQ Interconnect A-MQ Interconnect works with any AMQP 1.0 client. Check the following to ensure the components are configured correctly. Port 5672 in the network firewall is open. The router is configured to permit access from your client. See Interconnect Security. 20