Using AMQP 1.0

Advanced Message Queuing Protocol (AMQP) 1.0 is a wire-line protocol that defines messages and procedures for sending and receiving messages over a network. Using an OASIS standardized protocol for messaging allows any client speaking AMQP on the wire to communicate with other AMQP speaking clients or brokers on the network regardless of the languages the clients are using.

AMQP 1.0 is a richly featured and extensible protocol that provides support for:

  • Most message exchange patterns including publish-subscribe, request-reply and message queue.
  • All classes of service.
  • Detailed header fields such as TTL, replyTo and user properties.
  • Portable encoding of messages.

If you'd like to learn more about AMQP 1.0, consider taking a look at amqp.org.

As of VMR version 8.4.0 for Solace VMRs, and as of hardware appliance load 8.3.0 for the 3530 / 3560s, Solace routers can act as AMQP 1.0 brokers, so any AMQP 1.0 compliant client can interact with a Solace router as it would with other AMQP 1.0 brokers.

If you're already familiar with AMQP 1.0 and just want to start messaging, you'll want to go over to Get Started with AMQP 1.0 Messaging Tutorials. There you'll find a number of tutorials that will help you get going in no time.

The sections below are recommended for programmers and network architects who require background information regarding potential use-cases, and information about specific features, limitations and choices associated with using the Solace implementation. Refer to Managing AMQP 1.0 Messaging for information about managing the AMQP service on the router.

Why Solace Support for AMQP 1.0?

Message routing is often required between entities who use different transports and protocols for sending and receiving messages. In many such environments, one can frequently find AMQP being used in applications like back-end server messaging to message brokers. In these sort of multi-protocol environments, a Solace router can be used to direct messages back and forth amongst the messaging entities using the transports and protocols the entities use. There isn't a need for multiple messaging brokers to handle the different types of messaging applications.

Connected Vehicle Applications in a Multi-Protocol Environment

The diagram above shows a simple example of a multi-protocol environment where different entities, making use of different protocols, are exchanging messages.

In this example, each car periodically connects through MQTT to the Solace router through the Internet and publishes information, such as its location, to be centrally monitored so that it can be found in the case of theft. At the same time, individual car owners may query this information through their mobile devices, using REST from their browser, asking such questions as “Where did I park my car today?”. Access Control List (ACL) rules on the router ensure that each mobile device only accesses status published by their owner's car.

Also, each car's GPS can receive updates to its maps. The servers originating GPS updates are directly attached to the Solace router and use an AMQP interface to allow the use features not offered by MQTT, such as publishing real-time traffic updates with assured-delivery and a TTL so that the latest information is available to a car when it elects to connect, yet time out and disappear from the car’s queue once out-of-date.

Advanced Subjects for Developers

The Solace router supports the AMQP 1.0 broker role. In its simplest form, this means that the Solace router only accepts AMQP connections and never initiates them. A summary of where Solace's broker implementation differs from the AMQP 1.0 specification can be found on the AMQP 1.0 Protocol Conformance page.

For instructions on how to administer and configure the AMQP service on a Solace router, refer to Managing AMQP 1.0 Messaging.

The next sections will discuss some key areas that could be useful to if you're going to develop applications that will interact with Solace's AMQP implementation:

Mapping AMQP Terminology to Solace Terminology

If you're reading through the AMQP protocol specification it's important to note how certain key AMQP terms map to equivalent Solace router terms. The following table shows how they correspond.

AMQP Term Solace Term Comments
Container Client or Router  
Connection Client Object Every connection from a container outside the router is represented by a unique client object.
Session N/A There is no visible session concept on the router; however, a "session" is automatically created after a client is successfully authenticated and a transport link between the client and router is successfully established for data exchange.
Link (inbound) Ingress Flow All ingress links of a given connection are implemented with a single common ingress flow.
Link (outbound) Egress Flow Each egress link of a given connection is implemented with an individual egress flow.
Source (on broker) Queue or Topic-Endpoint Clients always receive from an endpoint.
Target (on broker) Topic or Queue or Topic-Endpoint Clients can send to a topic or endpoint.

Mapping AMQP Messages to SMF Messages

Native AMQP wire-line messages are accepted by the Solace router and translated to their equivalent Solace SMF messages and internal object state. This transformation is transparent to the client on the other end of the connection.

An AMQP message is composed of several parts. AMQP formally categorizes more parts of its message than SMF, and this has implications on mapping inbound and outbound messages. If an inbound message cannot be mapped from AMQP to SMF, the link on which the message arrived will be closed with an error. If an outbound message cannot be mapped from SMF to AMQP, the specific field in the message will be dropped.

Topic Syntax

The topic syntax to be used by an AMQP implementation is not defined by the protocol, and it's left up to the client and broker implementations to define. The Solace AMQP implementation uses SMF Topics syntax.

Mapping AMQP Addressing to Solace Queues & Topics

In the AMQP 1.0 protocol specification, the address field is used to identify the source and target of a link. On a Solace router, the address is either:

  • the name of a queue.
  • a topic in SMF format

Client Support

A Solace router offers clients on the end of an AMQP connection the same degree of support as other types of router clients except for the limitations or restrictions noted in the following table. For information about conformance with respect to the AMQP 1.0 specification, see AMQP 1.0 Protocol Conformance.

Solace Router Feature Level of Client Support for AMQP
Access Control Lists (ACLs) Special rules with respect to the reply-to #P2P topic prefix reserved by Solace for each individual client are of limited use for clients, which have no means to learn their assigned #P2P reply-to prefix.
Guaranteed Messaging

The Solace router supports client publishing and subscribing with the following exceptions:

  • When Guaranteed Messaging is not enabled, clients will receive a close frame with an indication of amqp:not-implemented and appropriate descriptive text.
  • Endpoint creation: Clients create arbitrary durable queues and topic endpoints when they bind as consumers, or bind to any existing queue or topic endpoint created through some other means, and create temporary queue and topic endponts.
  • Queue subscription management: Clients cannot add or remove subscriptions on queues they bind to.
  • Transactions: Clients cannot perform XA transactions.
  • DMQ eligible: All messages published by clients are treated as if DMQE (Dead Message Queue Eligible) is true.
  • Retransmission of an unacknowledged message sent to a client will only happen on client reconnect, and never due to a retransmit timeout as done for an SMF client.
Direct Messaging

The Solace router supports client direct publishing, but not subscribing.

TCP Transport The Solace router supports AMQP over TCP.
WebSocket Transport WebSocket transport is not supported for AMQP.
Authentication

AMQP uses the Simple Authentication and Security Layer (SASL) for authentication. The router supports ANONYMOUS, PLAIN, and EXTERNAL SASL mechanisms.

  • The ANONYMOUS mechanism must be used for the Solace basic authentication type of none.
  • The PLAIN mechanism must be used for Solace basic authentication types of internal, ldap, or radius. In this case the authcid and password fields of the sasl.init frame are used to establish identity.
  • The EXTERNAL mechanism must be used for Solace client-certificate authentication. In this case the identity is established through the fields of the provided client certificate in the normal manner.

Notes: If an client attempts to connect without a SASL exchange, and thus not provide any identity, the Solace router will accept the connection only in the basic/none case, and assign the client to the “default” client-username.

Kerberos is not supported.

Compression Compressed client connections are not supported.
Deliver-To-One The Deliver-To-One feature is not supported for AMQP.
Eliding All messages published by a client are treated as non-eligible for eliding.
Keepalive The Solace router uses the client-profile TCP keepalives on the connection. The Solace router never imposes an AMQP keepalive requirement on the client, although it respects AMQP keepalives requested by the client.
Sequenced-Topics Sequenced-topics are not supported for clients.
SolCache SolCache query functionality is provided by Solace APIs.
Subscription Managers Clients cannot manage subscriptions on behalf of other clients.
SSL/TLS The Solace router supports TLS negotiation by the broker exposing a separate, encrypted-only port with the expectation that every connection starts with a TLS exchange. After this, the client and broker continue with the normal AMQP frame exchange.
JMS Message Types StreamMessage and MapMessage are not supported.