Product Introduction

Red Hat JBoss A-MQ adheres to the JMS 1.1 specification in implementing all of the standard JMS features including:

Point-to-point (PTP) messaging uses queue destinations. Queues handle messages in a first in, first out (FIFO) manner. Messages are consumed from the queue in the order in which they are received. Once a message is consumed from a queue it is removed from the queue.

PTP messaging is similar to person-to-person email sent and received through a mail server. Each message dispatched to a queue is delivered only once to only one receiver. The queue stores all messages until they either expire or are retrieved by a receiver.

Clients that produce messages are referred to as senders. Messages are sent either synchronously or asynchronously. When sending messages synchronously, the producer waits until the broker, not a receiver, acknowledges receipt of the messages.

Clients that consume messages are referred to as receivers. Receivers consume messages from the end of the queue. Multiple receivers can register concurrently on the same queue, but only one of them will receive any given message. It is the receiver's responsibility to acknowledge the receipt of a message. By default, JBoss A-MQ guarantees once-only delivery of any message to the next available, registered consumer, thus distributing messages in a quasi round-robin fashion across them.

Publish and subscribe (Pub/Sub) messaging uses topic destinations. Topics distribute published messages to any clients that are currently subscribed and waiting to consume them. Once all of the clients that are subscribed to the topic have consumed a message it is removed from the destination.

Pub/sub messaging is similar to a mailing list subscription, where all clients currently subscribed to the list receive every message sent to it. Any message dispatched to a topic is automatically delivered to all of the topic's subscribers.

Clients that produce messages are referred to as publishers. Messages are sent either synchronously or asynchronously. When sending messages synchronously, the producer waits until the broker, not a consumer, acknowledges receipt of the messages.

Clients that consume messages are referred to as subscribers. Topics typically have multiple subscribers concurrently registered to receive messages from it. Typically, subscribers must be actively connected to a topic to receive published messages. They will miss messages that are published while they are disconnected.

To ensure that they do not miss messages due to connectivity issues, a subscriber can register as a durable subscriber. The topic will store messages for a durable subscriber and deliver the messages when the durable subscriber reconnects.

JBoss A-MQ supports the request/reply messaging paradigm, which provides a mechanism for a consumer to inform the producer whether it has successfully retrieved and processed a message dispatched to a queue or a topic destination.

JBoss A-MQ's request/reply mechanism implements a two-way conversation in which a temporary destination is used for the reply message. The producer specifies the temporary destination in the request message's JMSReplyTo header, and the consumer identifies the request message to which the reply corresponds using the reply message's JMSCorrelationID property.

Persistent messaging ensures no message is lost due to a system failure, a broker failure, or an inactive consumer. This is so because the broker always stores persistent messages in its stable message store before dispatching them to their intended destination. This guarantee comes at a cost to performance. Persistent messages are sent synchronously—producers block until the broker confirms receipt and storage of each message. Writes to disk, typical for a message store, are slow compared to network transmissions.

Because non-persistent messages are sent asynchronously and are not written to disk by the broker, they are significantly faster than persistent messages. But non-persistent messages can be lost when the system or broker fails or when a consumer becomes inactive before the broker dispatches the messages to their destination.

The default behavior of JMS brokers and consumers is to use persistent messaging. JBoss A-MQ defaults to storing persistent messages in a lightweight, file-based message store. The default is intended to provide persistence at the lowest cost. If you need to use a more robust (RDBMS) message store or want to forgo persistence in favor of performance, you can change the defaults.

There are several ways to alter the default persistence behavior when using JBoss A-MQ:

For details, see the guide, Configuring Broker Persistence, on the Red Hat Customer Portal.

JBoss A-MQ supports JMS transactions that occur between a client and broker.

A transaction consists of a number of messages grouped into a single unit. If any one of the messages in the transaction fails, the producer can rollback the entire transaction, so that the broker flushes all of the transacted messages. If all messages in the transaction succeed, the producer can commit the entire transaction, so that the broker dispatches all of the transacted messages.

Transactions improve the efficiency of the broker because they enable it to process messages in batch. A batch consists of all messages a producer sends to the broker before calling commit(). The broker caches all of these messages in a transaction store until it receives the commit command, then dispatches all of them, in batch, to their destination.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

JBoss A-MQ supports XA transactions that occur between a client and broker.

XA transactions work similarly to JMS transactions, except XA transactions use a two-phase commit scheme and require an XA Transaction Manager and persistent messaging. The Transaction Manager and two-phase commit scheme are used because the broker is required to write every message in an XA transaction to a persistent message store, rather than caching them locally, until the producer calls commit().

XA transactions are recommended when you are using more than one resource, such as reading a message and writing to a database. This is so because XA transactions provide atomic transactions for multiple transactional resources, which prevents duplicate messages resulting from system failures.

For more information, see ActiveMQ in Action (Snyder, Bosanac, and Davies) and What are XA transactions? What is a XA datasource?.

Messages are the backbone of a messaging system and the most important part of the JMS specification. A messages is a self-contained autonomous entity that may be resent several times across many clients throughout its life span. Each consumer along a message's route will examine it and, depending on its contents, may execute some business logic, modify it, or create new messages to accomplish a communicated task.

As shown in Figure 2.1, “Anatomy of a JMS message”, a JMS message consists of three components:

The body component contains the payload, which can be textual or binary data, as specified by using one of the six supported Java message types:

Message headers contain a predefined set of metadata that are used to communicate information about a message between the different parties that handle the message. The header properties are identified by a JMS prefix and outlined in the JMS specification.

A number of the headers are automatically assigned by the producer's send() method and some are automatically set by the broker. The remaining headers are left to the user to set when a message is created.

Message properties, like message headers, provide metadata about a message to the different parties that handle the message. The difference between message headers and message properties is that message properties are not standardized. They allow JMS providers and client applications to add their own metadata to a message. A messaging client does not need to understand the properties to consume a message containing them. Unrecognized properties are simply ignored.

Client applications can create user-defined properties based on Java primitive types. The JMS API also provides generic methods for working with these user-defined properties.

Red Hat JBoss A-MQ has a number of vendor specific message properties that are used to control how the broker treats messages, The JBoss A-MQ specific properties are identified by the JMSActiveMQBroker prefix.

There are a few JMS-defined properties that are identified by the JMSX prefix. Vendors are not required to support all of these properties.

For a list of supported headers and properties, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

Developing applications using the JMS APIs is a straightforward process. The APIs facilitate the creation of objects that mitigate the interface between client applications and the message broker. Once connected to a broker, clients can create, send and receive messages.

A JMS application typically consist of these basic interfaces and classes:

Figure 2.2, “Messaging sequence” shows the typical sequence of events involved in sending or receiving messages in a Red Hat JBoss A-MQ client application.

The following procedure shows how to implement the sequence of events shown in Figure 2.2, “Messaging sequence”:

Red Hat JBoss A-MQ provides a variety of ways for building and deploying messaging applications including:

JBoss A-MQ provides a variety network protocols that enable producers and consumers to communicate with a broker:

For details, see the Client Connectivity Guide on the Red Hat Customer Portal.

JBoss A-MQ provides client-side APIs for variety of programming languages. The language support varies based on the transport connection used by the client.

When using OpenWire you can use the following client APIs:

When using STOMP you can use the following client APIs:

In addition to being deployed as a standalone Java application, JBoss A-MQ can be embedded in other Java applications. Embedded brokers can run client and broker functions concurrently in one process. Clients that run in the same processes as an embedded broker can use the VM transport to improve communication speed with the broker. Embedded brokers can still connect to external clients.

Red Hat JBoss A-MQ can be deployed in a number of JEE and OSGi containers including:

Composite destinations provide a mechanism for producers to send the same message to multiple destinations at the same time.

For an enterprise that needs real-time analytics, this feature enables its messaging application to send one message concurrently to many different client applications to process. For example, only one producer need send a single message to the warehouse to request more inventory and, at the same time, to broadcast that message to an in-store monitoring system that tracks customer purchases, current stock levels, and inventory replacement.

A composite destination treats a string of multiple, comma-separated destinations as one destination, but sends messages to each of the individual destinations. Composite destinations must be made up of comma separated lists that that are made up of either all topics or all queues.

For details, see the Client Connectivity Guide on the Red Hat Customer Portal

Virtual destinations provide a mechanism for publishers to broadcast messages via a topic to a pool of receivers subscribing through queues.

To do so, consumers register a subscription to a queue that is backed by a virtual topic, like this: Consumer.<qname>.VirtualTopic.<tname>.

When the producer publishes messages to the virtual topic, the broker pushes the messages out to each consumer's queue, from which the consumers retrieve them. This feature enables you to failover queue subscribers, to load balance messages across competing queue subscribers, and to use message groups on queue subscribers.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

Red Hat JBoss A-MQ allows you deploy a group of brokers into a fabric. All of the brokers in a fabric are managed by a distributed Fabric Ensemble that stores runtime and configuration information for all of the brokers in the fabric. Using this information the ensemble enables you to manage large deployments by:

Figure 3.1, “A Fabric” shows the components of a fabric with seven brokers and an ensemble consisting of three servers.

The key components of the fabric are:

The Fabric Ensemble, based on Apache Zookeeper, maintains two databases:

The ensemble is intended to be distributed across multiple machines to provide a level of high-availability. The servers in the ensemble use a quorum policy to elect the master server and will re-elect a new master when the current master fails. To ensure optimal performance of the ensemble you should deploy an odd number of Fabric Servers to maintain the ensemble. The more servers in the ensemble, the more failures it can endure.

The ensemble is dynamically updated by the Fabric Agents running in the containers that make up the fabric. The agents routinely report the status of their container to the ensemble. Configuration profiles are also updated dynamically when they are edited.

A profile is a collection of configuration data that defines the runtime parameters for a container. It contains details about:

Profiles are additive and can inherit properties from parent profiles. This makes it possible to create standardized configurations that can be used throughout your deployment. The profile for a specific container will inherit the standard configuration from the base profile and add any specific settings needed to tailor the container for its specific deployment environment.

Profiles are organized into versions. A version is a collection of profiles. Creating a new version copies all of the profiles from the parent version and stores them in a new collection. A Fabric Container can access only one version at a time, so changes made to the profiles in one version will only effect the containers that are assigned to the version being edited. This makes it easy to roll out changes to a fabric incrementally.

A Fabric Agent is the link between the ensemble and a Fabric Container. It communicates with the ensemble to:

One of the advantages of a fabric is that you can manage it from any of the containers in the fabric. The fabric command shell interacts directly with the ensemble, so all changes are immediately picked up by all of the containers in the fabric.

You can also use the Web-based Fuse Management Console, included in the JBoss A-MQ distribution, to work with a fabric. When JBoss A-MQ is running, the Fuse Management Console is available at http://localhost:8181. The Fuse Management Console allows you to:

For JBoss A-MQ, the Fuse Management Console allows you to manage and monitor broker instances, destinations, and consumers. For example, you can:

If planned for, disaster scenarios that result in the loss of a message broker need not obstruct message delivery. Making a messaging system fault tolerant involves:

Red Hat JBoss A-MQ provides mechanisms that make building fault tolerant messaging systems easy.

A master/slave topology defines a master broker that actively processes messages and one or more slave brokers that replicate the master broker's state. When the master broker fails, one of the slave brokers takes over, becoming the new master broker. Client applications can reconnect to the new master broker and resume processing as normal.

JBoss A-MQ supports two types of master/slave clusters:

For details, see the Fault Tolerant Messaging guide on the Red Hat Customer Portal.

The failover protocol allows you to configure a client with a list of brokers to which it can connect. When one broker fails, a client using the failover protocol will automatically reconnect to a new broker from its list. As long as one of the brokers on the list is running, the client can continue to function uninterrupted.

When combined with brokers deployed in a master/slave topology, the failover protocol is a key part of a fault-tolerant messaging system. The clients will automatically fail over to the slave broker if the master fails. The clients will remain functional and continue working as if nothing had happened.

For more information, see Client Failover in the Fault Tolerant Messaging guide on the Red Hat Customer Portal.

A reliable messaging system guarantees that messages are delivered to their intended recipients in the correct order. JMS guaranteed messaging relies on three mechanisms:

Red Hat JBoss A-MQ provides additional features for ensuring reliable messaging, including the recovery of failed messages.

JBoss A-MQ's redelivery policy provides a mechanism for modifying the maximum number of times and the frequency at which the broker attempts to redeliver expired and undeliverable messages.

Normally, the broker tries to redeliver messages to consumers when:

You can tune the client's redelivery policy by editing its connection in the broker's configuration file.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

When a message cannot be delivered to its destination, JBoss A-MQ sends it to the dead letter queue, ActiveMQ.DLQ. When a message is sent to the dead letter queue, an advisory message is sent to the topic ActiveMQ.Advisory.MessageDLQd.*.

Messages held in the dead letter queue can be consumed or reviewed by an administrator at a later time. This can help with debugging delivery issues and ensures that messages are not lost.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

If a subscriber's connection to a topic fails it will typically miss messages that arrive before it can reconnect. To prevent this from happening subscribers can register a durable subscription. A durable subscription instructs the broker to store all messages arriving at the topic while the durable subscriber is disconnected from it. The broker delivers all accumulated messages that have not expired to the durable subscriber when it reconnects to the topic. If the durable subscriber unsubscribes from the topic without first reconnecting, the broker discards all of the subscriber's accumulated messages.

As with nondurable subscriptions, each durable subscriber gets a copy of the messages sent to the topic. For durable messages, the broker saves only one copy of a message in its durable message store. For each durable subscriber, a durable subscription object in the broker's message store maintains a pointer to its next stored message and dispatches a copy of the message to its subscriber.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

Messages are consumed off of a queue in FIFO order. If multiple consumers are connected to the queue, there is no way to ensure that any one consumer will receive a particular message or sequence of messages. Using an exclusive consumer, you can direct the broker to select one of a queue's consumers to receive all messages from the queue. If that consumer stops or fails, the broker selects another of the queue's consumers to take its place.

Exclusive consumers can also be used as a distributed locking mechanism. Because messaging is often used to broadcast data from an external resource, you'd probably build redundancy into the system to ensure that the broadcast application continues functioning should individual processes fail. Distributed locks on resources are typically used to limit access of the resource's data to only one process at a time, but they incur overhead and don't work for processes running across multiple machines. In this case, you can employ exclusive consumer functionality to create distributed locks for all processes that access the external resource.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

This feature enables multiple consumers on the same queue to process, in FIFO order, messages tagged with the same JMSXGroupID. It also facilitates concurrency as multiple consumers can parallel process different message groups, each identified by a unique JMSXGroupID.

The producer assigns a message to a group by setting the JMSXGroupID property in the message header. The broker dispatches all messages tagged with the same JMSXGroupID value to a single consumer. If that consumer becomes unavailable, the broker dispatches subsequent messages in the group to another consumer.

Message groups are similar to message selectors, except that the broker selects which consumer receives a particular message group and automatically reassigns the message group to another consumer when the current one becomes unavailable.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

This feature provides a caching mechanism that improves reliability without the overhead of persistent messaging. It enables consumers to retrieve nonpersistent messages that were sent before the consumer started or that went undelivered because the consumer had to restart.

The broker can cache a configurable number of nonpersistent messages for topic destinations. Enabling this feature requires two steps:

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

In a scalable messaging system, brokers can support an increasing number of concurrently connected clients. In a high-performance messaging system, brokers can process messages through the system, from producers to consumers, at a high rate. In a scalable high-performance messaging system, multiple brokers can concurrently process a large volume of messages for a large number of concurrently connected clients.

You can scale up Red Hat JBoss A-MQ to provide connectivity for thousands of concurrent client connections and many more destinations.

Besides the obvious components—network and system hardware, transport protocols, message compression—which you can tune to increase application performance, JBoss A-MQ provides means for avoiding bottlenecks caused by large messages and for scheduling message dispatches.

As shown in Figure 3.2, “Network of Brokers Example”, the brokers in a network of brokers are connected together by network connectors, which define the broker-to-broker links that form the basis of the network. Through network connectors, a network of brokers keeps track of all active consumers, receiving notifications whenever a consumer connects to or disconnects from the network. Using the information provided through client registration, brokers can determine where and how to route messages to any consumer in a network of brokers.

The brokers use a store-and-forward delivery method to move messages between them. A broker first stores messages locally before passing them on to another broker in its network. This scheme supports the distribution of queues and topics across a network of brokers.

A network of brokers can be employed in a variety of network topologies, such as hub-and-spoke, daisy chain, or mesh.

For details, see Using Networks of Brokers on the Red Hat Customer Portal.

For details, see Master/Slave in Fault Tolerant Messaging on the Red Hat Customer Portal.

Blob(binary large object) messages provide a mechanism for robust transfers of very large files, avoiding the bottlenecks often associated with them. Retrieval of a blob message is atomic. Blob messages are transferred out-of-bounds (outside the broker application) via FTP or HTTP. The blob message does not contain the file. It is only a notification that a blob is available for retrieval. The blob message contains the producer-supplied URL of the blob's location and a helper method for acquiring an InputStream to the actual data.

Though blob transfers are more robust than stream transfers, blobs rely on an external server for data storage.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

Stream messages provide a mechanism for efficiently transferring very large files, avoiding the bottlenecks often associated with them. A stream message induces a client to function as a Java IOStream. The broker chunks OutputStream data received from the producer and dispatches each chunk as a JMS message. On the consumer, a corresponding InputStream must reassemble the data chunks.

This feature employs message groups so that messages with the same JMSXGroupID value are pinned to a single consumer. Using streams with queue destinations that connect to multiple receivers, regular or exclusive, does not affect message order. However, using streams with more than one producer could interfere with message ordering.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

Using properties in the org.apache.activemq.ScheduledMessage interface, you can schedule when messages are dispatched to a consumer. The broker stores scheduled messages persistently, so they survive broker failure and are dispatched upon broker startup.

Four ScheduledMessage properties appended to the transport connector enable fine-grained scheduling:

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

JBoss A-MQ supports reliable, high-performance load balancing on queues distributed across multiple consumers. If one of the consumers fails, JBoss A-MQ redelivers any unacknowledged messages to a queue's other consumers, by default, in round-robin order. When one consumer is faster than the others, it receives more messages, and when any consumer slows down, other consumers take up the slack. This enables a queue to reliably load balance processing across multiple consumer processes.

Using queues this way in a network of brokers, you can implement a grid-style processing model, in which a cluster of worker processes, in a scalable and efficient Staged Event-Driven Architecture (SEDA) way, asynchronously process messages sent to a queue.

For details, see Balancing Consumer Load in Using Networks of Brokers on the Red Hat Customer Portal.

Red Hat JBoss A-MQ provides many ways to manage and administer a messaging system. Some of these are built into the broker. Others are add-ons that you can download separately.

Act as administrative channels from which you can receive status on events taking place on the broker and on producers, consumers, and destinations in real time. They provide an alternative to JMX for discovering the running state of an active broker. Using Red Hat JBoss A-MQ advisory messages, you can monitor the messaging system using regular JMS messages, which are generated on system-defined topics. You can also use advisory messages to modify an application's behavior dynamically.

JBoss A-MQ uses advisory messages internally to notify connections on the availability of temporary destinations and to notify a network of brokers on the availability of consumers.

All advisory topics, except message delivery, are enabled by default. To enable the message delivery advisory topic, you must configure it in the destination policy in the broker's configuration file.

For details, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

Enabling a Command Agent on the broker, you can communicate with it directly to issue administrative queries and commands, such as listing available queues, topics, and subscriptions; or to view metadata, browse queues, and so on.

When enabled, the command agent listens to the ActiveMQ.Agent topic for messages. It processes all commands that are submitted as JMS text messages and posts the results back to ActiveMQ.Agent.

JBoss A-MQ provides several plug-ins for visualizing broker components and for retrieving statistics collected on a running broker.

For more information, see ActiveMQ in Action (Snyder, Bosanac, and Davies).

JBoss A-MQ provides extensive support for monitoring and controlling the broker's behavior from a JMX console, such as jConsole.

For details, see Using JMX in Managing and Monitoring a Broker on the Red Hat Customer Portal.

The Red Hat JBoss A-MQ management console provides centralized provisioning and monitoring of brokers deployed in a fabric.

JBoss Operations Network is a web-based SOA management and monitoring system based on Hyperic HQ Enterprise. It takes advantage of JBoss A-MQ's JMX-based reporting capabilities to provide real time administration and control of all runtime components.

For details, see the JBoss Operations Network Documentation.

Many third-party tools are available for administering Red Hat JBoss A-MQ. Here are a few:

The Red Hat JBoss A-MQ documentation is designed to be task oriented and to quickly lead a user to the information they need. The reading lists below are broken up by user type and organized in the order in which a user will likely want to read the content.

The books listed here provide information about JMS messaging and the basic information needed to develop messaging applications with Red Hat JBoss A-MQ.

The books listed here provide information and instructions to support system administrator functions.

Red Hat runs a series of webinars and makes the recordings available at Open Source SOA Webinars.

Red Hat also offers articles, reference architectures and other resources at https://access.redhat.com/knowledge/.

The books and reference materials listed here provide detailed information and instructions for designing, building, and deploying enterprise integration solutions and for using the tools that make it easier to do so. The books and reference materials in this list were authored by leading experts in this domain.

Red Hat provides mirrors of the documentation for the the Apache Software Foundation projects that form the basis of Red Hat JBoss A-MQ: