Real-Time Interactive Guide to AMQP

Technology used: AMQP 0-9-1 and Kaazing Gateway

The following is an interactive guide that takes you step-by-step through the main features of the Advanced Message Queuing Protocol (AMQP). This document contains the following sections:

About AMQP

AMQP is an open standard for messaging middleware originally designed by the financial services industry to provide an interoperable protocol for managing the flow of enterprise messages. AMQP uses a compact, efficient binary format for messaging and specifies both messaging capabilities and a network wire-level protocol. For more information about AMQP, visit http://www.amqp.org.

The 0-9-1 AMQP model defines the following components:

  • Exchange--clients publish messages to an exchange
  • Queue--clients read messages from a queue
  • Binding--a mapping from an exchange to a queue

An AMQP client connects to an AMQP broker and opens a channel. Once the channel is established, the client can send messages to an exchange and receive messages from a queue.

About This Real-Time Interactive Guide

This isn't your ordinary animated demo; instead, this is a real-time HTML5 Web page that communicates natively with an AMQP broker using a bidirectional WebSocket connection--provided by Kaazing Gateway--which reliably extends the AMQP messaging protocol to the Web with ultra high performance and minimal latency. If you'd like to see the code that was used to build this real-time Web page, check the source of this page and refer to the document Checklist: How to Build JavaScript Clients Using Kaazing Gateway.

Notes:
  • This guide uses version 0-9-1 of the AMQP protocol.
  • To use this interactive guide, you must install and run the Kaazing Gateway bundle and an AMQP Message broker as described in Setting Up Kaazing Gateway.

Connecting to an AMQP Broker

Before you can use the messaging features of an AMQP broker, you must establish a connection to the broker by specifying the broker address, a user name and password, and, optionally, a virtual host name (the name of a collection of exchanges and queues hosted on independent server domains). An AMQP client generally manages all of its communication on a single connection to an AMQP broker.

First, you must connect the client with an AMQP broker. To do this, perform the following steps:

  1. Accept the default values for all text boxes.
  2. Click Connect.

    The status should change from Not connected to Connected. The Location text box specifies a WebSocket URL (by default ws://localhost:8001/amqp) to your AMQP broker. The WebSocket connectivity is enabled by Kaazing Gateway.

Connect to AMQP Broker


Status:

Creating Channels

Once a connection to an AMQP broker has been established, the client must create a channel to communicate to the broker. A channel is a bi-directional connection between an AMQP client and an AMQP broker. AMQP is multi-channeled, which means that channels are multiplexed over a single network socket connection. Channels are light-weight and cheap, and therefore used in AMQP's exception handling mechanism--channels are closed when an exception occurs.

Let's create two channels--one for publishing messages to an exchange and one for consuming messages from a queue. To do this, perform the following step:

  1. Click New Channel twice.

    Your Channel list should now have two entries. The channels are identified by number.

Create Channels

Declaring an Exchange

AMQP messages are published to exchanges. Messages contain a routing key that contains the information about the message's destination. The exchange accepts messages and their routing keys and delivers them to a message queue. You can think of an exchange as an electronic mailman that delivers the messages to a mailbox (the queue) based on the address on the message's envelope (the routing key). Exchanges do not store messages.

AMQP defines different exchange types. Some of these exchange types (Direct, Fanout, and Topic) must be supported by all AMQP brokers while others (Headers and System) are optional. AMQP brokers can also support custom exchange types.The following are the different types of exchanges:

  • Direct--Messages are sent only to a queue that is bound with a binding key that matches the message's routing key.
  • Fanout--Messages are sent to every queue that is bound to the exchange.
  • Topic--Messages are sent to a queue based on categorical binding keys and wildcards.
  • Headers--Messages are sent to a queue based on their header property values.
  • System--Messages are sent to system services.

Exchanges can be durable, meaning that the exchange survives broker shut-down and must be deleted manually or non-durable (temporary) meaning that the exchange lasts only until the broker is shut down. Finally, to check if an exchange exists on the AMQP broker (without actually creating it), you can create a passive exchange.

Let's declare a fanout exchange called myexchange. To do this, perform the following steps:

  1. Select channel 1 (one of the two channels that was created in the previous step).
  2. If necessary, type myexchange in the Exchange Name text box.
  3. Select fanout from the Exchange Type dropdown list.
  4. Do not check any of the check boxes.
  5. Click Declare Exchange to declare a fanout exchange that messages can be published to. The message myexchange declared will display.

Declare Exchange



Options

Declaring a Queue

AMQP messages are consumed from queues. You can think of a queue as a mailbox; messages addressed to a particular address (the routing key) are placed in the mailbox for the consumer to pick up. If multiple consumers are bound to a single queue, only one of the consumers receives the message (the one that picked up the mail).

To check if a queue exists on the AMQP broker (without creating it), you can create a passive queue. Additionally, queues can be marked exclusive, which means that they are tied to a specific connection. If a queue is marked exclusive, it is deleted when the connection on which it was created is closed.

Queues can be durable, meaning that the queue survives broker shut-down and must be deleted manually or non-durable (temporary) meaning that the queue lasts only until the broker is shut down. Queues can also be marked Auto Delete, which means that the queue is automatically deleted when it is no longer in use.

Let's declare a temporary queue called myqueue on channel 2. You'll use this queue to consume the messages that were published on channel 1. To do this, perform the following steps:

  1. Select channel 2.
  2. If necessary, type myqueue in the Queue Name text box.
  3. Do not check any of the check boxes.
  4. Click Declare Queue to declare a queue that messages can be consumed from. The message myqueue has 0 messages and 0 consumers appears.

Declare Queue


Options

Binding an Exchange to a Queue

Once you have created an exchange and a queue in AMQP, you must bind--or map--one to the other so that messages published to a specific exchange are delivered to a particular queue. You bind a queue to an exchange with a routing key.

Let's bind the exchange and the queue that you previously declared to each other with a routing key called myroutingkey. To do this, perform the following steps:

  1. Select one of the channels (for example, channel 2).
  2. Accept the default names.
  3. Click Bind. The message myexchange bound appears.

Bind Exchange to Queue




Publishing Messages

Messages are published to exchanges. The established binding rules (routing keys) then determine to which queue a message is delivered. Messages have content, which consists of two parts:

  1. Content Header: A set of properties that describes the message.
  2. Content Body: A blob of binary data.

Additionally, messages can be marked Mandatory to send a notification to the publisher in case a message cannot be delivered to a queue. You can also mark a message Immediate and the message is returned to the sender if it cannot be routed to a queue consumer immediately.

Let's publish a few simple messages. To do this, perform the following steps:

  1. Select channel 1.
  2. Accept the default values for the Exchange Name and Routing Key Name and leave all check boxes unchecked.
  3. Enter"A plain text message" in the Message Body text box and click Publish

    You won't see any results yet (in the Consuming Messages section), but the messages are now waiting in the queue on the broker, ready to be consumed. You consume the messages in the next step.

Publish Messages



Options

Consuming Messages

Once messages are published, they can be consumed from a queue. A variety of options can be applied to messages in a queue. For example, publishers can choose to require acknowledgement (or not) of messages so that messages can be redelivered in the case of a delivery failure. If the queue is set to Exclusive, it is scoped to just the current connection and deleted when the connection on which it was established is closed. Additionally, you can use the No Local setting to notify the broker not to send messages to the connection on which the messages were published.

Let's consume some messages from the previously created queue. To do this, perform the following steps:

  1. Select channel 2.
  2. Accept the default values for Queue Name and Consumer Tag (the unique identifier for a subscription) and leave all the check boxes unchecked.
  3. Click Consume.

    The message "a plain text message" that you published earlier should now appear in this section.

  4. Go back to the Publishing Messages section and publish a few more text messages (type in some new text).

    The messages appear immediately in the Consuming Messages section, but in reality they have been published to the exchange on the AMQP broker, then routed to a queue on the broker, and finally consumed by the client--it's an example of real-time HTML5 WebSocket in action!

Consume Messages



Options

Using Transactions

AMQP supports transactional messaging through server local transactions. When the client commits the transaction, the server publishes a set of messages as one unit. Transactions only apply to message publishing and not to the actual delivery of the messages or the consumption of the messages from a queue. Consequently, rolling back a transaction (canceling the transaction before it is committed) does not remove any messages from a queue.

Note: Once you commit a transaction on a channel, a new transaction is started automatically. For this reason you must commit all future messages you want to publish on that channel or create a new, non-transactional channel to publish messages on.

Let's use a transaction to publish some messages. To do this, perform the following steps:

  1. Select a the same channel as the one you are publishing on (channel 1 in this case).
  2. Click Select.
  3. Go to the Publishing Messages section and publish two or three messages with the text "Transaction" to channel 1.
  4. In the Consuming Messages section, check that these messages do not appear yet; they should only appear there after the transaction has been committed.
  5. Click Commit to commit the transaction.
  6. Check the Consuming Messages section again.

    The "Transaction" messages should now display.

Use Transactions

Controlling Message Flow

You can use flow control in AMQP to temporarily--or permanently--halt the flow of messages from a publisher to a consumer. If you turn the message flow off, no messages are sent to the consumer.

Finally, let's take a look at what happens when you turn the message flow on a channel off and on. To do that, perform the following steps:

  1. Select the channel on which you are consuming messages (Channel 2).
  2. Click Flow Off
  3. Go to the Publishing Messages section and publish three messages with the text "Flow Test".
  4. Go to the Using Transactions section and click Commit (Channel 1 was changed to use transactions in the previous step).
  5. Check the Consuming Messages section to see if the messages appeared (they shouldn't have).
  6. Clicking Flow On to turn the message flow back on.
  7. Check the Consuming Messages section.

    The "Flow Test" message should now appear in the Consuming Messages section.

Control Message Flow

Summary

In this interactive, step-by-step document you have seen how the main features of AMQP work. Although not every single protocol feature was explained or shown in this guide, you should now have a good overview of what is possible with AMQP and you may be able to think of some practical use cases for AMQP. For more information on how to write your own AMQP Web client, refer to the document Checklist: How to Build JavaScript Clients Using Kaazing Gateway.