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

Red Hat JBoss A-MQ 7.0Beta
Using the AMQP Python Client
For use with A-MQ Clients 1.1.0
Red Hat Customer Content
Services
Red Hat JBoss A-MQ 7.0-Beta Using the AMQP Python Client
For use with A-MQ Clients 1.1.0
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
http://creativecommons.org/licenses/by-sa/3.0/
. 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.
Table of Contents
Table of Contents
.CHAPTER
. . . . . . . . .1.. .OVERVIEW
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . .
1.1. KEY FEATURES
3
1.2. KEY CONCEPTS
3
1.3. SUPPORTED CONFIGURATIONS
4
.CHAPTER
. . . . . . . . .2.. .INSTALLATION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5. . . . . . . . . .
2.1. USING YOUR SUBSCRIPTION
5
2.2. INSTALLING ON RED HAT ENTERPRISE LINUX
5
.CHAPTER
. . . . . . . . .3.. .GETTING
. . . . . . . . STARTED
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7. . . . . . . . . .
3.1. PREPARING THE BROKER
7
3.2. RUNNING HELLO WORLD
7
.CHAPTER
. . . . . . . . .4.. .EXAMPLES
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8. . . . . . . . . .
4.1. SENDING MESSAGES
8
4.2. RECEIVING MESSAGES
8
. . . . . . . . . .5.. .USING
CHAPTER
. . . . . .THE
. . . . API
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
...........
5.1. BASIC OPERATION
5.2. MORE INFORMATION
10
11
. . . . . . . . . .6.. .COMPATIBILITY
CHAPTER
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
...........
6.1. USING AMQP PYTHON CLIENT WITH A-MQ BROKER
6.2. USING AMQP PYTHON CLIENT WITH A-MQ INTERCONNECT
12
12
1
Red Hat JBoss A-MQ 7.0-Beta Using the AMQP Python Client
2
CHAPTER 1. OVERVIEW
CHAPTER 1. OVERVIEW
The AMQP Python Client is a Python library for writing messaging applications. It allows you to write
client and server applications that send and receive AMQP messages.
The AMQP Python Client is based on the Proton API from Apache Qpid.
1.1. KEY FEATURES
The AMQP Python 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.
1.2. KEY CONCEPTS
The AMQP Python 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
Red Hat JBoss A-MQ 7.0-Beta Using the AMQP Python 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.
1.3. SUPPORTED CONFIGURATIONS
The AMQP Python Client is supported on RHEL 6 and 7 for Python versions 2.6 and 2.7.
4
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 https://access.redhat.com/.
2. If you do not already have an account, create one.
3. Log in to your account.
Activating a Subscription
1. Go to https://access.redhat.com/.
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 https://access.redhat.com/products/red-hat-jboss-a-mq/.
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 https://access.redhat.com/.
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.
2.2. INSTALLING ON RED HAT ENTERPRISE LINUX
5
Red Hat JBoss A-MQ 7.0-Beta Using the AMQP Python Client
Before starting, make sure your subscription is activated and your system is registered. Then use
yum or dnf to install the python-qpid-proton and python-qpid-proton-docs packages.
$ sudo yum install python-qpid-proton python-qpid-proton-docs
To test that the install was successful, try importing the proton Python module using the Python
interpreter.
$ python
[...]
>>> import proton
>>> proton.__file__
'/usr/lib64/python2.7/site-packages/proton/__init__.pyc'
>>> exit()
6
CHAPTER 3. GETTING STARTED
CHAPTER 3. GETTING STARTED
Before starting, make sure the client and documentation packages are installed.
3.1. 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 0.0.0.0:5672 for protocols [AMQP]
[...]
15:01:39,691 INFO [org.apache.activemq.artemis.core.server]
AMQ221007: Server is now live
3.2. RUNNING HELLO WORLD
The Hello World example sends a message to the examples queue and then fetches it back. On
success it prints Hello World! to the console.
Using a new terminal window, change directory to the Python examples directory and run the
helloworld.py example.
$ cd /usr/share/proton-0.13.0/examples/python/
$ python helloworld.py
Hello World!
7
Red Hat JBoss A-MQ 7.0-Beta Using the AMQP Python Client
CHAPTER 4. EXAMPLES
4.1. SENDING MESSAGES
from __future__ import print_function
import sys
from proton import *
from proton.handlers import *
from proton.reactor import *
class Sender(MessagingHandler):
def __init__(self, address, message_body):
super(Sender, self).__init__()
self.address = address
self.message_body = message_body
self.sent = False
def on_start(self, event):
event.container.create_sender(self.address)
print("SENDER: Created sender for target address
'{0}'".format(self.address))
def on_sendable(self, event):
if self.sent:
return
message = Message(self.message_body)
event.sender.send(message)
print("SENDER: Sent message '{0}'".format(self.message_body))
event.connection.close()
self.sent = True
try:
address, message_body = sys.argv[1:]
except:
sys.exit("Usage: sender.py ADDRESS MESSAGE")
handler = Sender(address, message_body)
container = Container(handler)
try:
container.run()
except KeyboardInterrupt:
pass
4.2. RECEIVING MESSAGES
8
CHAPTER 4. EXAMPLES
4.2. RECEIVING MESSAGES
from __future__ import print_function
import sys
from proton import *
from proton.handlers import *
from proton.reactor import *
class Receiver(MessagingHandler):
def __init__(self, address, max_count):
super(Receiver, self).__init__()
self.address = address
self.max_count = max_count
self.count = 0
def on_start(self, event):
event.container.create_receiver(self.address)
print("RECEIVER: Created receiver for source address
'{0}'".format(self.address))
def on_message(self, event):
print("RECEIVER: Received message
'{0}'".format(event.message.body))
self.count += 1
if self.count == self.max_count:
event.connection.close()
try:
address = sys.argv[1]
except:
sys.exit("Usage: receiver.py ADDRESS [MAX-COUNT]")
try:
max_count = int(sys.argv[2])
except:
max_count = 0
handler = Receiver(address, max_count)
container = Container(handler)
try:
container.run()
except KeyboardInterrupt:
pass
See the Qpid Proton Python tutorial for more examples.
9
Red Hat JBoss A-MQ 7.0-Beta Using the AMQP Python Client
CHAPTER 5. USING THE API
5.1. BASIC OPERATION
5.1.1. Handling Messaging Events
The AMQP Python Client is an asynchronous event-driven API. To handle events, the user supplies
callback-method implementations using the MessageHandler class.
from proton.handlers import MessagingHandler
from proton.reactor import Container
class ExampleHandler(MessagingHandler):
# The container event loop has started
def on_start(self, event):
pass
# A message can be sent
def on_sendable(self, event):
pass
# A message is received
def on_message(self, event):
pass
handler = ExampleHandler()
container = Container(handler)
container.run()
These are only a few common-case events. The full set is documented here.
5.1.2. Connecting to a Remote Peer
To connect to a remote server or client, use the Container.connect() method with a URL
containing a host and port. This is typically called inside the MessagingHandler.on_start()
method.
class ExampleHandler(MessagingHandler):
def on_start(self, event):
connection = event.container.connect("example.com:5672")
def on_connection_opened(self, event):
connection = event.connection
print("Connection {0} is open".format(connection))
5.1.3. Listening for Incoming Connections
The AMQP Python Client can accept inbound network connections, allowing you to build messaging
servers. To start listening for connections, use the Container.listen() method with a URL
containing the local host address and port to listen on.
class ExampleHandler(MessagingHandler):
10
CHAPTER 5. USING THE API
def on_start(self, event):
acceptor = event.container.listen("example.com:5672")
def on_connection_opened(self, event):
connection = event.connection
print("New incoming connection {0}".format(connection))
5.1.4. Setting the Container Identity
When the AMQP Python 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 Container constructor.
handler = ExampleHandler()
container = 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.
5.2. MORE INFORMATION
For detailed information about the API, see the Qpid Proton Python API reference.
11
Red Hat JBoss A-MQ 7.0-Beta Using the AMQP Python Client
CHAPTER 6. COMPATIBILITY
6.1. USING AMQP PYTHON 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.
6.2. USING AMQP PYTHON 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.
12