Version 7.1
Copyright © 2012 Red Hat, Inc. and/or its affiliates.
Table of Contents
List of Figures
List of Tables
List of Examples
Fuse MQ Enterprise supports a wide variety of protocols for client-to-broker, broker-to-broker, and client-to-client connections. The intention is that the variety of protocols will make it easier to connect to a range of client types. Different network topologies can also be supported with the help of special protocols, such as discovery and peer-to-peer.
The following protocols can be used either for straightforward client-to-broker connections (transport connector) or broker-to-broker connections (network connector). For each wire protocol (that is, on-the-wire message encoding), Fuse MQ Enterprise supports one or more associated transport protocols. Hence, you can configure connections with a wide variety of wire protocol/transport protocol combinations.
Table 1.1 shows the protocol combinations that messaging clients can use to connect directly to the message broker.
Table 1.1. Protocols for Simple Connections
| Wire Protocol | Transport Protocol | Sample URL | Description |
|---|---|---|---|
| OpenWire | TCP | tcp:// |
Connect to the message broker endpoint at
This URL is also used to configure the transport connector in a broker. |
| OpenWire | TCP | nio:// | Same as tcp, except that the New I/O (NIO) Java API is
used, which provides better performance in some scenarios. |
| OpenWire | SSL | ssl:// |
Connect to the message broker endpoint at
This URL is also used to configure the transport connector in a broker. |
| OpenWire | HTTP | http:// |
Connect to the message broker endpoint at
This URL is also used to configure the transport connector in a broker. |
| OpenWire | HTTPS | https://Host:Port |
Connect to the message broker endpoint at
This URL is also used to configure the transport connector in a broker. |
| Stomp | TCP | stomp://Host:Port |
Connect to the message broker endpoint at
This URL is also used to configure the transport connector in a broker. |
| Stomp | SSL | stomp+ssl://Host:Port |
Connect to the message broker endpoint at
This URL is also used to configure the transport connector in a broker. |
| REST | HTTP | http:// |
Connect to the message broker endpoint at
For example, the sample URL is built up from a Web context name,
This URL is not used to configure the REST transport
connector in a broker. Use the |
| RESTs | HTTPS | http:// | |
| XMPP | TCP | xmpp://Host:Port | Configure the transport connector in a message broker to accept XMPP
connections on
Host:Port
(for example, from an Instant Messaging client). |
| VM | N/A | vm://BrokerName | Configure clients to connect to a broker embedded within the same Java Virtual
Machine (JVM). The BrokerName is the broker name of the
embedded broker. |
A discovery protocol builds a connection to a message broker in two steps:
Obtain a list of available broker endpoints.
Connect to one or more endpoints from the discovered list, according to some selection algorithm.
Discovery protocols are particularly useful for clients that connect to a cluster of message brokers.
Table 1.2 describes the discovery protocols that clients can use.
Table 1.2. Summary of Discovery Protocols
| Protocol | Sample URL | Description |
|---|---|---|
| Failover | failover://(uri1,...,uriN)?TransportOptions | Configure clients to connect to one of the broker endpoints from the URI list,
uri1,...,uriN.
The transport options,
?TransportOptions, are specified in
the form of a query list. If no transport options are required, you can omit the
parentheses and the question mark, ?. For more information
see Failover Protocol in Fault Tolerant Messaging. |
| Discovery | discovery://( | Configure clients to connect to one of the broker endpoints from a URI list
that is dynamically discovered at runtime, using a discovery agent. The discovery
agent URI, DiscoveryAgentUri, is normally a multicast
discovery agent—for example, multicast://default. For more information
see Dynamic Discovery Protocol. |
| Fanout | fanout://( | Configure clients to connect to all of the broker endpoints from a dynamically discovered URI list. For more information see Fanout Protocol. |
The discovery protocol supports a number of discovery agents, which are also specified in the form of a URI. For details of the supported discovery agents, see Discovery Agents.
![]() | Note |
|---|---|
Although discovery agent URIs look superficially like transport URIs, they are not the same thing. A discovery agent URI can only be used in certain contexts and cannot be used directly in place of a transport URI. |
The OpenWire protocol is a JMS compliant wire protocol (defining message types and message encodings) that is native to the Fuse MQ Enterprise. The protocol is designed to be fully-featured, JMS-compliant, and highly performant. It is the default protocol of the Fuse MQ Enterprise.
Table 2.1 shows the transport protocols supported by the OpenWire wire protocol:
Table 2.1. Transport Protocols Supported by OpenWire
| Transport Protocol | URL | Description |
|---|---|---|
| TCP | tcp:// |
Endpoint URL for OpenWire over TCP/IP. The broker
listens for TCP connections on the host machine,
|
| TCP | nio:// | Same as tcp, except that the New I/O
(NIO) Java API is used, which provides better
performance in some scenarios. |
| SSL | ssl:// |
(Java clients only) Endpoint URL for OpenWire over TCP/IP, where the socket layer is secured using SSL (or TLS). For details of how to configure an SSL connection, see ActiveMQ Security Guide. |
| HTTP | http:// |
(Java clients only) Endpoint URL for OpenWire over HTTP. |
| HTTPS | https:// |
(Java clients only) Endpoint URL for OpenWire over HTTP, where the socket layer is secured by SSL (or TLS). For details of how to configure a HTTPS connection, see ActiveMQ Security Guide. |
OpenWire supports a number of transport options, which can be set as query options on the transport URL. For example, to specify that error messages should omit the stack trace, use a URL like the following:
tcp://localhost:61616?wireformat.stackTraceEnabled=false
Where the wireformat.stackTraceEnabled property is set to
false to disable the inclusion of stack traces in error messages.
Table 2.2 gives the complete list of transport options for
OpenWire.
Table 2.2. Transport Options Supported by OpenWire Protocol
| Property | Default | Description | Negotiation policy |
|---|---|---|---|
wireformat
.stackTraceEnabled | true |
Should the stack trace of an exception occuring on the broker be sent to the client? |
Set to |
wireformat
.tcpNoDelayEnabled | false |
Provides a hint to the peer that TCP
|
Set to |
wireformat
.cacheEnabled | true |
Should commonly repeated values be cached so that less marshalling occurs? |
Set to |
wireformat
.cacheSize | 1024 |
If |
Use the smaller of the two values. |
wireformat
.tightEncodingEnabled | true |
Should wire size be optimized over CPU usage? |
Set to |
wireformat
.prefixPacketSize | true |
Should the size of the packet be prefixed before each packet is marshalled? |
Set to |
wireformat
.maxInactivityDuration | 30000 |
The maximum inactivity duration (before which the
socket is considered dead) in milliseconds. On some
platforms it can take a long time for a socket to
appear to die, so we allow the broker to kill
connections if they are inactive for a period of time.
Set to a value |
Use the smaller of the two values. |
wireformat
.maxInactivityDurationInitalDelay |
Fuse MQ Enterprise currently supports the following client types for the OpenWire protocol:
Java clients—the Java API conforms fully to the JMS specification.
If you want to develop an OpenWire client using other programming languages, try one of the following client types from the Apache ActiveMQ project:
C++ clients—for C++ clients, Apache ActiveMQ provides the CMS (C++ Messaging Service) API, which is closely modelled on the JMS specification. Only the TCP transport is supported for C++ clients.
The Stomp protocol is a simplified messaging protocol that is being developed as an open source project (http://stomp.codehaus.org/). The advantage of the stomp protocol is that you can easily improvise a messaging client—even when a specific client API is not available—because the protocol is so simple.
Table 3.1 shows the transport protocols supported by the Stomp wire protocol:
Table 3.1. Transport Protocols Supported by Stomp
| Transport Protocol | URL | Description |
|---|---|---|
| TCP | stomp:// |
Endpoint URL for Stomp over TCP/IP. The broker listens for TCP connections on the host
machine, |
| SSL | stomp+ssl://Host:Port |
Endpoint URL for secure Stomp over SSL. The broker listens for TCP connections on the
host machine, |
The Stomp protocol supports the following transport options:
Table 3.2. Transport Options Supported by Stomp Protocol
| Property | Default | Description |
|---|---|---|
transport
.defaultHeartBeat | 0,0 |
Simulated client heartbeat policy of legacy Stomp 1.0 clients. This option is set in
the |
Stomp 1.1 adds support for heartbeats (keepalive messages) on Stomp connections. Negotiation of a heartbeat policy is normally initiated by the client (Stomp 1.1 clients only) and the client must be configured to enable heartbeats. No broker settings are required to enable support for heartbeats, however.
At the level of the Stomp wire protocol, heartbeats are negotiated when the client establishes the Stomp connection and the following messages are exchanged between client and server:
CONNECT heart-beat:CltSend,CltRecvCONNECTED: heart-beat:SrvSend,SrvRecv
The CltSend, CltRecv,
SrvSend, and SrvRecv fields are
interpreted as follows:
CltSendIndicates the minimum frequency of messages sent from the client, expressed as the maximum time between messages in units of milliseconds. If the client does not send a regular Stomp message within this time limit, it must send a special heartbeat message, in order to keep the connection alive.
A value of zero indicates that the client does not send heartbeats.
CltRecvIndicates how often the client expects to receive message from the server, expressed as the maximum time between messages in units of milliseconds. If the client does not receive any messages from the server within this time limit, it would time out the connection.
A value of zero indicates that the client does not expect heartbeats and will not time out the connection.
SrvSendIndicates the minimum frequency of messages sent from the server, expressed as the maximum time between messages in units of milliseconds. If the server does not send a regular Stomp message within this time limit, it must send a special heartbeat message, in order to keep the connection alive.
A value of zero indicates that the server does not send heartbeats.
SrvRecvIndicates how often the server expects to receive message from the client, expressed as the maximum time between messages in units of milliseconds. If the server does not receive any messages from the client within this time limit, it would time out the connection.
A value of zero indicates that the server does not expect heartbeats and will not time out the connection.
In order to ensure that the rates of sending and receiving required by the client and the server are mutually compatible, the client and the server negotiate the heartbeat policy, adjusting their sending and receiving rates as needed.
A difficulty arises, if you want to support an inactivity timeout on your Stomp connections when legacy Stomp 1.0 clients are connected to your broker. The Stomp 1.0 protocol does not support heartbeats, so Stomp 1.0 clients are not capable of negotiating a heartbeat policy.
To get around this limitation, you can specify the
transport.defaultHeartBeat option in the broker's
transportConnector element, as follows:
<transportConnector name="stomp" uri="stomp://0.0.0.0:0?transport.defaultHeartBeat=5000,0" />
The effect of this setting is that the broker now behaves as if the Stomp 1.0 client had sent the following Stomp frame when it connected:
CONNECT heart-beat:5000,0
This means that the broker will expect the client to send a message at least once every
5000 milliseconds (5 seconds). The second integer value, 0, indicates that the
client does not expect to receive any heartbeats from the server (which makes sense, because
Stomp 1.0 clients do not understand heartbeats).
Now, if the Stomp 1.0 client does not send a regular message after 5 seconds, the
connection will time out, because the Stomp 1.0 client is not capable of sending out a heartbeat
message to keep the connection alive. Hence, you should choose the value of the timeout in
transport.defaultHeartBeat such that the connection will stay alive, as long
as the Stomp 1.0 clients are sending messages at their normal rate.
The REST protocol is a simple HTTP-based protocol that enables you to contact the message broker through a Web browser. You can contact the message broker by navigating to appropriately formatted URLs or by posting HTML forms.
The Fuse MQ Enterprise's REST protocol is based on a subset of the HTTP protocol. Hence, HTTP is the only supported transport.
REST supports the following client types:
Web forms—use conventional HTML forms to
POST a message to a destination (queue or topic) or to
GET a message from a destination—see Example of posting a message .
Ajax clients—an Asynchronous JavaScript And Xml (Ajax) library that enables you to communicate with a REST endpoint using JavaScript in a DHTML Web page.
Representational State Transfer (REST) is a software architecture designed for distributed systems, like the World Wide Web. For details of the REST architecture and the philosophy underlying it, see the REST Wikipedia article.
One of the key concepts of a RESTful architecture is that the interaction between different network nodes should take on a very simple form. In particular, the number of operations in a RESTful protocol must be kept small: for example, the REST protocol in Fuse requires just three operations.
In general, a REST interaction consists of the following elements:
Operation—belongs to a restricted, well-known set of
operations—for example, in the HTTP protocol, the main operations are
GET, POST, PUT, and
DELETE. The advantage of this approach is that, in contrast to RPC
architectures, there is no need to define interfaces for a RESTful protocol. The
operations are all known in advance.
URI—identifies the resource that the operation acts on. For
example, a HTTP GET operation acts on the URI by fetching data from
the resource identified by the URI.
Data (if required)—needed for operations that send data to the remote resource.
HTTP is a good example of a protocol demonstrating RESTful design principles. In fact,
proponents of REST argue that it is precisely the RESTful qualities of HTTP that enabled the
rapid expansion of the World Wide Web. In keeping with REST principles, HTTP has a
restricted operation set, consisting of only eight operations: GET,
POST, PUT, DELETE,
OPTIONS, HEAD, TRACE, and
CONNECT.
For the purpose of implementing a RESTful protocol, the first four HTTP
operations—GET, POST, PUT, and
DELETE—are the most important. The semantics of these operations are
described briefly in Table 4.1 .
Table 4.1. HTTP RESTful Operations
| Operation | Description |
|---|---|
GET | Fetch the remote resource identified by the URI. |
POST | Add/append/insert data to the remote resource identified by the URI. |
PUT | Replace the remote resource identified by the URI with the data from this operation. |
DELETE | Delete the remote resource identified by the URI. |
This simple set of operations—analogous to the classic CRUD (Create, Replace, Update, and Delete) operations for a database—turns out to be remarkably powerful and flexible.
The following servlets—which are automatically deployed in the message broker Web console—implement RESTful access to the Fuse message queues:
The RESTful Web service implemented by the Fuse message servlet
enables you to enqueue and dequeue messages over HTTP. You can, therefore, use the message
servlet to implement message producers and message consumers as Web forms.
To interact with the Fuse message servlet, construct a URL of the
following form:
http://Host:Port/WebContext/message/DestinationPath?Opt1=Val1&Opt2=Val2...
Where the URL is constructed from the following parts:
Host:Port—the
host and port of the servlet engine. For example, in the default message broker
configuration, a HTTP port is opened on localhost:8161.
WebContext—in a Web application, it is usual to group
related components (servlets and so on) under a particular Web context,
WebContext. For example, for the REST demonstration
servlets, the Web context is demo by default.
message—routes this URL to the message
servlet.
DestinationPath—specifies the compound name of a queue or
topic in the message broker. For example, the FOO.BAR queue has the
destination path, FOO/BAR.
?Opt1=Val1&Opt2=Val2—you
can add some options in order to qualify how the URL is processed.
For example, the following URL can be used to fetch a message from the
FOO.BAR queue, where the Web console has the default
configuration:
http://localhost:8161/demo/message/FOO/BAR?type=queue&timeout=5000
Table 4.2 shows the URL options recognized by the
message servlet:
Table 4.2. URL Options Recognized by the Message Servlet
| URL Option | Description |
|---|---|
type | Can be either queue or topic. |
timeout | When consuming a message from a queue, specifies the length of time (in units of milliseconds) the client is prepared to wait. |
Three HTTP operations—GET, POST, and
DELETE—are recognized by the message servlet. The
semantics of these operations are described briefly in Table 4.3 .
Table 4.3. Message Servlet RESTful HTTP Operations
| Operation | Description |
|---|---|
GET | Consume a single message from the destination (queue or topic) specified by the URL. |
POST | Send a single message to the destination (queue or topic) specified by the URL. |
DELETE | Consume a single message from the destination (queue or topic) specified by the
URL. This operation has the same effect as GET. |
For details of the form properties recognized by the message servlet
(for POSTing a message), see Example of posting a message .
The RESTful Web service implemented by the queueBrowse servlet
enables you to monitor the contents and status of any queue or topic in the Web console.
Effectively, the queueBrowse servlet is a simple management tool.
To interact with the Fuse queueBrowse servlet, construct a URL of the
following form:
http://Host:Port/WebContext/queueBrowse/DestinationPath?Opt1=Val1&Opt2=Val2...
The queueBrowse URL has a similar structure to the
message URL (see message servlet ),
except that the queueBrowse URL is built from
WebContext/queueBrowse instead of
WebContext/message.
For example, the following URL can be used to browse the FOO.BAR
queue, where the Web console has the default configuration:
http://localhost:8161/demo/queueBrowse/FOO/BAR
Table 4.4 shows the URL options recognized by the
queueBrowse servlet:
Table 4.4. URL Options Recognized by the QueueBrowse Servlet
| URL Option | Description |
|---|---|
view |
Specifies the format for viewing the queue/topic. The following views are supported:
|
feedType |
In combination with the setting,
|
contentType | Override the MIME content type of the view. |
maxMessages | The maximum number of messages to render. |
Example 4.1 shows an example of the Web form used to
send a message to the FOO.BAR queue in the Web console, as demonstrated
in Send a message .
Example 4.1. Web Form for Sending a Message to a Queue or Topic
<html>
<head>
<title>Send a JMS Message</title>
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body>
<h1>Send a JMS Message</h1>
<form action="message/FOO/BAR" method="post">
<p>
<label for="destination">Destination name</label>
<input type="text" name="destination"/>
</p>
<p>
<label for="type">Destination Type: </label>
<select name="type">
<option selected value="queue">Queue</option>
<option type" value="topic">Topic</option>
</select>
</p>
<p>
<textarea name="body" rows="30" cols="80">
Enter some text here for the message body...
</textarea>
</p>
<p>
<input type="submit" value="Send"/>
<input type="reset"/>
</p>
</form>
</body>
</html>Table 4.5 describes the form properties that are recognized by the message servlet.
Table 4.5. Form Properties Recognized by Message Servlet
| Form Property | Description |
|---|---|
| Form action |
The |
destination | The compound name of the destination queue or topic, using a period,
., as the delimiter (for example, FOO.BAR).
If this property is specified in the form, it overrides the value of the
DestinationPath in the form action. |
type | Destination type, equals queue or
topic. |
body | Message body. |
To consume a message from a topic or queue, send a HTTP GET operation (for example, by
following a hypertext link) using the URL format described in message servlet .
For example, to consume a message from the
FOO.BAR queue, navigate to the following URL:
http://localhost:8161/demo/message/FOO/BAR?timeout=10000&type=queue
To browse a queue using the queueBrowse servlet, simply navigate to
an URL of the appropriate form, as described in queueBrowse servlet .
For example, to browse the FOO.BAR queue in XML format:
http://localhost:8161/demo/queueBrowse/FOO/BAR?view=xml
To browse the FOO.BAR queue as an Atom 1.0 feed:
http://localhost:8161/demo/queueBrowse/FOO/BAR?view=rss&feedType=atom_1.0
To browse the FOO.BAR queue as an RSS 1.0 feed:
http://localhost:8161/demo/queueBrowse/FOO/BAR?view=rss&feedType=rss_1.0
This section describes how to run the REST example, which consists of a servlet engine integral to the message broker binary, and some demonstration servlets that run as a Web application. To connect to the Web applications, you can use your favorite Web browser.
You must ensure that the message broker is configured to instantiate an embedded servlet
engine. In your broker configuration file, conf/activemq.xml, check that
there is a jetty element configured as shown in Example 4.2 .
Example 4.2. Configuration of an Embedded Servlet Engine
<!-- Embedded servlet engine for serving up the Admin console --> <jetty xmlns="http://mortbay.com/schemas/jetty/1.0"> <connectors> <nioConnector port="8161" /> </connectors> <handlers> <webAppContext contextPath="/admin" resourceBase="${activemq.base}/webapps/admin" logUrlOnStart="true" /> <webAppContext contextPath="/demo" resourceBase="${activemq.base}/webapps/demo" logUrlOnStart="true" /> </handlers> </jetty>
With the configuration shown in Example 4.2 , the servlet engine opens up a HTTP port on IP port, 8161. The following Web applications are loaded:
Demonstration application (from webapps/demo),
REST protocol servlets (from webapps/demo).
Web console servlet (from webapps/admin),
To run the REST Web example, perform the following steps:
To run the embedded servlet engine, open a new command window and enter the following command to start the default message broker:
activemq
This step assumes that your broker is configured as described in Example prerequisites.
Open your favorite Web browser (for example, Firefox or Internet Explorer) and navigate to the following URL:
http://localhost:8161/demo
Your browser should now show the welcome page for the Web examples, as shown in Figure 4.1.
To view the form for publishing messages, click the link, Send a message. The Send a JMS Message form now appears in your browser, as shown in Figure 4.2.
In the Destination name text field, enter
FOO.BAR to send a message to the FOO.BAR queue.
Leave the Destination Type as Queue. Then enter an
arbitrary text message in the large message text box. Click the Send
button at the bottom of the form to send the message.
Using the history feature of your browser, navigate back to the example welcome page
(see Figure 4.1 ). The
queueBrowse servlet supports a variety of ways to browse the contents
of a queue and these are listed at the bottom of the welcome page. The following browsing
options are listed:
If you click on Browse a queue, you should see a page like Figure 4.3 .
If you click on Browse a queue as XML, you should see a page like Figure 4.4 .
If you click on Browse a queue as Atom, you should see a page like Figure 4.5 .
If you click on Browse a queue as RSS 1.0 or Browse a queue as RSS 2.0, you should see a page like Figure 4.6 .
To receive a message from the FOO.BAR queue, open the example welcome
page in your browser, http://localhost:8161/demo, and click the link, Receive a message.
You should now see the text of the message that you sent earlier. You will probably also receive an error from your browser, if the message is not formatted as HTML or XML (which the browser expects).
The VM transport enables Java clients running inside the same JVM to communicate with each other inside the JVM, without having to resort to a using a network connection. Because the clients require a broker to communicate, the VM transport can implicitly create an embedded broker the first time it is accessed. Figure 5.1 shows the basic architecture of the VM protocol.
The URI used to specify the VM transport comes in two flavors to provide maximum control over how the embedded broker is configured:
The VM transport uses a broker embedded in the same JVM as the clients to facilitate communication between the clients. The embedded broker can be created in several ways:
explicitly defining the broker in the application's configuration
explicitly creating the broker using the Java APIs
automatically when the first client attempts to connect to it using the VM transport
The VM transport uses the broker name specified in either the simple URI or in the configuration provided by the advanced URI's broker URI to determine if an embedded broker needs to be created. When a client uses the VM transport to connect to a broker, the transport checks to see if an embedded broker by that name already exists. If it does exist, the client is connected to the broker. If it does not exist, the broker is created and then the broker is connected to it.
When using explicitly created brokers there is a danger that your clients will
attempt to connect to the embedded broker before it is started. If this happens, the VM
transport will auto-create an instance of the broker for you. To avoid this conflict
you can set the waitForStart option or the create=false option
to manage how the VM transport determines when to create a new embedded broker.
The simple VM URI is used in most situations. It allows you to specify the name of the embedded broker to which the client will connect. It also allows for some basic broker configuration.
Example 5.1 shows the syntax for a simple VM URI.
BrokerName specifies the name of the embedded broker
to which the client connects.
TransportOptions specifies the configuration for the
transport. They are specified in the form of a query list. Table 5.2
lists the available options.
In addition to the transport options listed in Table 5.2, the simple VM URI can use the options described in Table 5.1 to configure the embedded broker.
Table 5.1. VM Transport Broker Configuration Options
| Option | Description |
|---|---|
broker.*
| Properties prefixed by broker. configure the embedded
broker. You can specify any of the standard broker options described in
Table 5.3. |
brokerConfig
| Specifies an external broker configuration file. For example, to pick up the
broker configuration file, activemq.xml, you would set
brokerConfig as follows:
brokerConfig=xbean:activemq.xml. |
![]() | Important |
|---|---|
The broker configuration options specified on the VM URI are only meaningful if the client is responsible for instantiating the embedded broker. If the embedded broker is already started, the transport will ignore the broker configuration properties. |
Example 5.2 shows a basic VM URI that connects to
an embedded broker named broker1.
Example 5.3 creates and connects to an embedded broker that uses a non-persistent message store.
The advanced VM URI provides you full control over how the embedded broker is configured. It uses a broker configuration URI similar to the one used by the administration tool to configure the embedded broker.
Example 5.4 shows the syntax for an advanced VM URI.
BrokerConfigURI is a broker configuration URI.
TransportOptions specifies the configuration for the
transport. They are specified in the form of a query list. Table 5.2
lists the available options.
Example 5.5 creates and connects to an embedded broker configured using a broker configuration URI.
Table 5.2 shows options for configuring the VM transport.
Table 5.2. VM Transport Options
Table 5.3 shows the options used to configure the broker using the simple VM URI.
Table 5.3. Broker Options
One of the main strengths of Fuse MQ Enterprise is that brokers can be located dynamically through out your infrastructure. In order for clients and other brokers to be able to interact with a broker, they need some way of discovering that the broker exists. Fuse MQ Enterprise does this using a combination of discovery agents and special URI schemes.
In order for location transparency to work, the members of a messaging application need a way for discovering each other. In Fuse MQ Enterprise this is accomplished using two pieces:
discovery agents—components that advertise the brokers available to other members of a messaging applicaiton
discovery URI—a URI that looks up all of the discoverable brokers and presents them as a list of actual URIs for use by the client or network connector
A discovery agent is a mechanism that advertises available brokers to clients and other brokers. When a client, or broker, using a discovery URI starts up it will look for any brokers that are available using the specified discovery agent. The clients will update their lists periodically using the same mechanism.
How a discovery agent learns about the available brokers varies between agents. Some agents
use a static list, some use a third party registry, and some rely on the brokers to provide
the information. For discovery agents that rely on the brokers for information, it is
necessary to enable the discovery agent in the message broker configuration. For example, to
enable the multicast discovery agent on an Openwire endpoint, you edit the relevant
transportConnector element as shown in
Example 6.1.
Example 6.1. Enabling a Discovery Agent on a Broker
<transportConnectors> <transportConnector name="openwire" uri="tcp://localhost:61716" discoveryUri="multicast://default" /> </transportConnectors>
Where the discoveryUri attribute on the
transportConnector element is initialized to
multicast://default.
![]() | Tip |
|---|---|
If a broker uses multiple transport connectors, you need to configure each transport connector to use a discovery agent individually. This means that different connectors can use different discovery mechanisms or that one or more of the connectors can be indiscoverable. |
Fuse MQ Enterprise currently supports the following discovery agents:
The Fuse Fabric discovery agent uses Fuse Fabric to discover the brokers in a specified group. The discovery agent requires that all of the discoverable brokers be deployed into a single fabric. When the client attempts to connect to a broker the agent looks up all of the available brokers in the fabric's registry and returns the ones in the specified group.
The Fuse Fabric discovery agent URI conforms to the syntax in Example 6.2.
Where GID is the ID of the broker group from which the client
discovers the available brokers.
The Fuse Fabric discovery agent requires that the discoverable brokers are deployed into a single fabric.
The best way to deploy brokers into a fabric is using Fuse Management Console. For information on using Fuse Management Console see Fuse Management Console Documentation.
You can also use the console to deploy brokers into a fabric. See Fabric Console Commands in Console Reference.
To use the agent a client must be configured to connect to a broker using a discovery protocol that uses a Fuse Fabric agent URI as shown in Example 6.3.
A client using the URL in Example 6.3 will
discover all the brokers in the nwBrokers broker group and generate a list of
brokers to which it can connect.
The static discovery agent does not truly discover the available brokers. It uses an explicit list of broker URLs to specify the available brokers. Brokers are not involved with the static discovery agent. The client only knows about the brokers that are hard coded into the agent's URI.
The static discovery agent is a client-side only agent. It does not require any configuration on the brokers that will be discovered.
To use the agent, you simply configure the client to connect to a broker using a discovery protocol that uses a static agent URI.
The static discovery agent URI conforms to the syntax in Example 6.4.
Example 6.5 shows a discovery URI that configures a client to use the static discovery agent to connect to one member of a broker pair.
Example 6.5. Discovery URI using the Static Discovery Agent
discovery://(static://(tcp://localhost:61716,tcp://localhost:61816))
The multicast discovery agent uses the IP multicast protocol to find any message brokers currently active on the local network. The agent requires that each broker you want to advertise is configured to use the multicast agent to publish its details to a multicast group. Clients using the multicast agent as part of the discovery URI they use for connecting to a broker will use the agent to receive the list of available brokers advertising in the specified multicast group.
![]() | Important |
|---|---|
Your local network (LAN) must be configured appropriately for the IP/multicast protocol to work. |
The multicast discovery agent URI conforms to the syntax in Example 6.6.
Where GroupID is an alphanumeric identifier. All
participants in the same discovery group must use the same
GroupID.
For a broker to be discoverable using the multicast discovery agent, you must enable
the discovery agent in the broker's configuration. To enable the multicast discovery agent
you set the transportConnector element's
discoveryUri attribute to a mulitcast discovery agent URI as
shown in Example 6.7.
Example 6.7. Enabling a Multicast Discovery Agent on a Broker
<transportConnectors> <transportConnector name="openwire" uri="tcp://localhost:61716" discoveryUri="multicast://default" /> </transportConnectors>
The broker configured in Example 6.7 is
discoverable as part of the multicast group default.
To use the multicast agent a client must be configured to connect to a broker using a discovery URI that uses a multicast agent URI as shown in Example 6.8.
A client using the URI in Example 6.8 will
discover all the brokers advertised in the default multicast group and generate
a list of brokers to which it can connect.
The zeroconf discovery agent is derived from Apple’s Bonjour Networking technology, which defines the zeroconf protocol as a mechanism for discovering services on a network. Fuse MQ Enterprise bases its implementation of the zeroconf discovery agent on JmDSN, which is a service discovery protocol that is layered over IP/multicast and is compatible with Apple Bonjour.
The agent requires that each broker you want to advertise is configured to use a multicast discovery agent to publish its details to a multicast group. Clients using the zeroconf agent as part of the discovery URI they use for connecting to a broker will use the agent to receive the list of available brokers advertising in the specified multicast group.
![]() | Important |
|---|---|
Your local network (LAN) must be configured to use IP/multicast for the zeroconf agent to work. |
The zeroconf discovery agent URI conforms to the syntax in Example 6.9.
Where the GroupID is an alphanumeric identifier. All
participants in the same discovery group must use the same
GroupID.
For a broker to be discoverable using the zeroconf discovery agent, you must enable
a multicast discovery agent in the broker's configuration. To enable the multicast discovery
agent you set the transportConnector element's
discoveryUri attribute to a mulitcast discovery agent URI as
shown in Example 6.10.
Example 6.10. Enabling a Multicast Discovery Agent on a Broker
<transportConnectors> <transportConnector name="openwire" uri="tcp://localhost:61716" discoveryUri="multicast://NEGroup" /> </transportConnectors>
The broker configured in Example 6.10 is
discoverable as part of the multicast group NEGroup.
To use the agent a client must be configured to connect to a broker using a discovery protocol that uses a zeroconf agent URI as shown in Example 6.11.
A client using the URL in Example 6.11 will
discover all the brokers advertised in the NEGroup multicast group and generate
a list of brokers to which it can connect.
The dynamic discovery protocol combines reconnect logic with a discovery agent to dynamically create a list of brokers to which the client can connect. The discovery protocol invokes a discovery agent in order to build up a list of broker URIs. The protocol then randomly chooses a URI from the list and attempts to establish a connection to it. If it does not succeed, or if the connection subsequently fails, a new connection is established to one of the other URIs in the list.
Example 6.12 shows the syntax for a discovery URI.
DiscoveryAgentUri is URI for the discovery agent used to
build up the list of available brokers. Discovery agents are described in
Discovery Agents.
The options, ?, are specified in the form
of a query list. The discovery options are described in
Table 6.1. You can also inject transport options as
described in Setting options on the discovered transports.Options
![]() | Tip |
|---|---|
If no options are required, you can drop the parentheses from the URI. The resulting
URI would take the form
|
The discovery protocol supports the options described in Table 6.1.
Table 6.1. Dynamic Discovery Protocol Options
Example 6.13 shows a discovery URI that uses a multicast discovery agent.
The list of transport options, Options, in the discovery URI
can also be used to set options on the discovered transports. If you
set an option not listed in Setting options on the discovered transports,
the URI parser attempts to inject the option setting into every one of the discovered
endpoints.
Example 6.14 shows a discovery URI that sets the TCP
connectionTimeout option to 10 seconds.
Example 6.14. Injecting Transport Options into a Discovered Transport
discovery://(multicast://default)?connectionTimeout=10000
The 10 second timeout setting is injected into every discovered TCP endpoint.
The fanout protocol enables a producer to auto-discover broker endpoints and broadcast topic messages to all of the discovered brokers. The fanout protocol gives producers a convenient mechanism for broadcasting messages to multiple brokers that are not part of a network of brokers.
The fanout protocol relies on a discovery agent to build up the list of broker URIs to which it connects.
Example 6.15 shows the syntax for a fanout URI.
DiscoveryAgentUri is URI for the discovery agent used to
build up the list of available brokers. Discovery agents are described in
Discovery Agents.
The options, ?, are specified in the form
of a query list. The discovery options are described in
Table 6.2. You can also inject transport options as
described in Setting options on the discovered transports.Options
![]() | Tip |
|---|---|
If no options are required, you can drop the parentheses from the URI. The resulting
URI would take the form
|
The fanout protocol supports the transport options described in Table 6.2.
Table 6.2. Fanout Protocol Options
| Option Name | Default | Description |
|---|---|---|
initialReconnectDelay
| 10 | Specifies, in milliseconds, how long the transport will wait before the first reconnect attempt. |
maxReconnectDelay
| 30000 | Specifies, in milliseconds, the maximum amount of time to wait between reconnect attempts. |
useExponentialBackOff
| true | Specifies if an exponential back-off is used between reconnect attempts. |
backOffMultiplier
| 2 | Specifies the exponent used in the exponential back-off algorithm. |
maxReconnectAttempts
| 0 | Specifies the maximum number of reconnect attempts before an error is sent
back to the client. 0 specifies unlimited attempts. |
fanOutQueues
| false | Specifies whether queue messages are replicated to every connected broker. For more information see Applying fanout to queue messages. |
minAckCount
| 2 | Specifies the minimum number of brokers to which the client must connect before it sends out messages. For more informaiton see Minimum number of brokers. |
Example 6.16 shows a discovery URI that uses a multicast discovery agent.
The fanout protocol replicates topic messages by sending each topic message to all of the connected brokers. By default, however, the fanout protocol does not replicate queue messages.
For queue messages, the fanout protocol picks one of the brokers at random and sends all of the queue messages to that broker. This is a sensible default, because under normal circumstances, you would not want to create more than one copy of a queue message.
It is possible to change the default behavior by setting the fanOutQueues
option to true. This configures the protocol so that it also replicates queue
messages.
By default, the fanout protocol does not start sending messages until the producer has
connected to a minimum of two brokers. You can customize this minimum
value using the minAckCount option.
Setting minimum number of brokers equal to the expected number of discovered brokers ensures that all of the available brokers start receiving messages at the same time. This ensures that no messages are missed if a broker starts up after the producer has started sending messages.
You have to be careful when using the fanout protocol with brokers that are joined in a network of brokers.
The combination of the fanout protocol's broadcasting behavior and the nature of how
messages are propagated through a network of brokers makes it likely that consumers will
receive duplicate messages. If, for example, you joined four brokers into a network of
brokers and connected a consumer listening for messages on topic hello.jason to
broker A and connected a producer to broker B to send messages to topic
hello.jason, the consumer would get one copy of the messages. If, on the other
hand, the producer connects to the network using the fanout protocol, the producer will
connect to every broker in the network simultaneously and start sending messages. Each of
the four brokers will receive a copy of every message and deliver its copy to the
consumer. So, for each message, the consumer will get four copies.
The TCP transport is used for creating OpenWire/TCP endpoints. The NIO transport is similar to the TCP transport, except that it uses the Java New I/O (NIO) socket library, which can provide better scalability when used on the server side. TCP and NIO have the same transport options.
A TCP URI has the following syntax:
tcp://Host[:Port]?transportOptions
An NIO URI has the following syntax:
nio://Host[:Port]?transportOptions
Where the transport options, transportOptions, are specified
as follows:
?option=value&option=value&...
In XML configuration, you must escape the & symbol, replacing it with
&. For example:
?option=value&option=value&...
When setting a client-side option, the name of the options is exactly as given in Table A.1. For example, to enable tracing on a client TCP
endpoint, set the trace option as follows:
tcp://fusesource.com:61616?trace=trueWhen setting a server-side option, there are two alternative option syntaxes as follows:
To configure options on the TCP listener socket, add the transport.
prefix to the option names shown in Table A.1. For
example, to enable tracing on a TCP listener socket, set the trace option
as follows:
tcp://fusesource.com:61616?transport.trace=trueTo configure options on a TCP connection socket (which is spawned from the
listener socket whenever the server accepts a new TCP connection), use the option name
exactly as given in Table A.1. For example, to enable
tracing on a TCP connection socket, set the trace option as
follows:
tcp://fusesource.com:61616?trace=trueTable A.1 shows the options supported by the TCP and the NIO URIs.
Table A.1. TCP and NIO Transport Options
| Option | Default | Description |
|---|---|---|
minmumWireFormatVersion | 0 | The minimum wire format version that is allowed. |
trace | false | Causes all commands sent over the transport to be logged. |
daemon | false | Specifies whether the transport thread runs as a daemon or not. Useful to enable when embedding in a Spring container or in a web container, to allow the container to shut down properly. |
useLocalHost | true | When true, causes the local machine's name to resolve to
localhost. |
socketBufferSize | 64*1024 | Sets the socket buffer size in bytes. |
keepAlive | false | When true, enables TCP
KeepAlive on the broker connection. Useful to ensure that inactive
consumers do not time out. |
soTimeout | 0 | Sets the socket timeout in milliseconds |
soWriteTimeout | 0 | Sets the socket write timeout in milliseconds |
connectionTimeout | 30000 | A non-zero value specifies the connection timeout in milliseconds. A zero value means wait forever for the connection to be established. Negative values are ignored. |
closeAsync | true | The false value causes all sockets to be closed
synchronously. |
soLinger | MIN_INTEGER | When > -1, enables the SoLinger socket option with this value.
When equal to -1, disables SoLinger. (from 5.6.0). |
maximumConnections | MAX_VALUE | The maximum number of sockets the broker is allowed to create. |
diffServ | 0 | (Client only) The preferred Differentiated Services
traffic class to be set on outgoing packets, as described in RFC 2475. Valid integer
values are [0,64). Valid string values are EF,
AF[1-3][1-4] or CS[0-7]. With JDK 6, only works when the
Java Runtime uses the IPv4 stack, which can be done by setting the
java.net.preferIPv4Stack system property to true. Cannot
be used at the same time as the typeOfService option. |
typeOfService | 0 | (Client only) The preferred type of
service value to be set on outgoing packets. Valid integer values are
[0,256). With JDK 6, only works when the Java Runtime uses the IPv4
stack, which can be done by setting the java.net.preferIPv4Stack system
property to true. Cannot be used at the same time as the
diffServ option. |
wireFormat | The name of the wire format to use. | |
wireFormat.* | All the properties with this prefix are used to configure the wireFormat. See Table A.4 for more information. |
The SSL transport is used for creating OpenWire/TCP endpoints with SSL/TLS enabled.
![]() | Note |
|---|---|
The URI transport options described here are not sufficient to configure an SSL endpoint completely. You must also associate X.509 certificates with the endpoint. For more details, see SSL/TLS Security in ActiveMQ Security Guide. |
An SSL URI has the following syntax:
ssl://Host[:Port]?transportOptions
Where the transport options, transportOptions, are specified
as follows:
?option=value&option=value&...
In XML configuration, you must escape the & symbol, replacing it with
&. For example:
?option=value&option=value&...
The SSL transport inherits all of the options supported by the TCP transport URI. See Table A.1.
Table A.2 shows the options supported by the SSL URI.
Table A.2. SSL Transport Options
| Option | Default | Description |
|---|---|---|
transport.enabledCipherSuites | Specifies the cipher suites accepted by this endpoint, in the form of a comma-separated list. | |
transport.enabledProtocols | Specifies the secure socket protocols accepted by this endpoint, in the form of
a comma-separated list. If using Sun's JSSE provider, possible values are:
SSL, SSLv2, SSLv3, TLS, or
TLSv1. | |
transport.wantClientAuth | (Server only) If true, the server requests
(but does not require) the client to send a certificate. | |
transport.needClientAuth | false | (Server only) If true, the server
requires the client to send its certificate. If the client
fails to send a certificate, the server will throw an error and close the
session. |
transport.enableSessionCreation | true | (Server only) If true, the server socket
creates a new SSL session every time it accepts a connection and spawns a new
socket. If false, an existing SSL session must be resumed when the
server socket accepts a connection. |
The UDP transport enables you to send datagrams using the unreliable UDP/IP protocol.
![]() | Warning |
|---|---|
Because UDP does not keep track of IP packets, you can lose messages sent over a raw UDP connection. It is up to you to provide a reliability layer to avoid message loss over UDP. |
A UDP URI has the following syntax:
udp://Host[:Port]?transportOptions
Where the transport options, transportOptions, are specified
as follows:
?option=value&option=value&...
In XML configuration, you must escape the & symbol, replacing it with
&. For example:
?option=value&option=value&...
Table A.3 shows the options supported by the UDP URI.
Table A.3. SSL Transport Options
| Option | Default | Description |
|---|---|---|
minmumWireFormatVersion | 0 | The minimum version wire format that is allowed. |
trace | false | Causes all commands sent over the transport to be logged. |
useLocalHost | true | When true, causes the local machine's name to resolve to
localhost. |
datagramSize | 4*1024 | Specifies the size of a datagram. |
wireFormat | The name of the wire format to use. | |
wireFormat.* | All options with this prefix are used to configure the wire format. See Table A.4 for more information. |
The wire format options configure the OpenWire message layer and can be specified as transport options with any of the preceding transports.
Table A.4 shows the wire format options supported by the OpenWire protocol.
Table A.4. Transport Options Supported by OpenWire Protocol
| Option | Default | Description | Negotiation policy |
|---|---|---|---|
wireformat
.stackTraceEnabled | true |
Should the stack trace of an exception occuring on the broker be sent to the client? |
Set to |
wireformat
.tcpNoDelayEnabled | false |
Provides a hint to the peer that TCP |
Set to |
wireformat
.cacheEnabled | true |
Should commonly repeated values be cached so that less marshalling occurs? |
Set to |
wireformat
.cacheSize | 1024 |
If |
Use the smaller of the two values. |
wireformat
.tightEncodingEnabled | true |
Should wire size be optimized over CPU usage? |
Set to |
wireformat
.prefixPacketSize | true |
Should the size of the packet be prefixed before each packet is marshalled? |
Set to |
wireformat
.maxInactivityDuration | 30000 |
The maximum inactivity duration (before which the socket is considered dead)
in milliseconds. On some platforms it can take a long time for a socket to appear
to die, so we allow the broker to kill connections if they are inactive for a
period of time. Set to a value |
Use the smaller of the two values. |
wireformat
.maxInactivityDurationInitalDelay | 10000 | The initial delay in starting the maximum inactivity checks. Note: The mis-spelling, Inital, is a
typographic error in the source code. |