Red Hat JBoss A-MQ

Connection Reference

A reference for all of the options for creating connections to a broker

Red Hat

Version 6.1

Legal Notice

Trademark Disclaimer

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Apache, ServiceMix, Camel, CXF, and ActiveMQ are trademarks of Apache Software Foundation. Any other names contained herein may be trademarks of their respective owners.

Legal Notice

Third Party Acknowledgements

One or more products in the Red Hat JBoss A-MQ release includes third party components covered by licenses that require that the following documentation notices be provided:
  • JLine (http://jline.sourceforge.net) jline:jline:jar:1.0
    License: BSD (LICENSE.txt) - Copyright (c) 2002-2006, Marc Prud'hommeaux
    All rights reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    • Neither the name of JLine nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • Stax2 API (http://woodstox.codehaus.org/StAX2) org.codehaus.woodstox:stax2-api:jar:3.1.1
    Copyright (c) <YEAR>, <OWNER> All rights reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • jibx-run - JiBX runtime (http://www.jibx.org/main-reactor/jibx-run) org.jibx:jibx-run:bundle:1.2.3
    License: BSD (http://jibx.sourceforge.net/jibx-license.html) Copyright (c) 2003-2010, Dennis M. Sosnoski.
    All rights reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    • Neither the name of JiBX nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • JavaAssist (http://www.jboss.org/javassist) org.jboss.javassist:com.springsource.javassist:jar:3.9.0.GA:compile
  • HAPI-OSGI-Base Module (http://hl7api.sourceforge.net/hapi-osgi-base/) ca.uhn.hapi:hapi-osgi-base:bundle:1.2
    License: Mozilla Public License 1.1 (http://www.mozilla.org/MPL/MPL-1.1.txt)
15 May 2015

Abstract

Red Hat JBoss A-MQ supports a number of different wire protocols and message formats. In addition, it overlays reconnection logic and discovery logic over these options. This guide provides a quick reference for understanding how to configure connections between brokers, clients, and other brokers.

Chapter 1. OpenWire over TCP

URI syntax

Example 1.1. Syntax for a vanilla TCP Connection

tcp://Host[:Port]?transportOptions
An NIO URI has the syntax shown in Example 1.2, “Syntax for NIO Connection”.

Example 1.2. Syntax for NIO Connection

nio://Host[:Port]?transportOptions

Setting transport options

OpenWire transport options, transportOptions, are specified as a list of matrix parameters. How you specify the options to use differs between a client-side URI and a broker-side URI:
  • When using a URI to open a connection between a client and a broker, you just specify the name of the option as shown.

    Example 1.3. Setting an Option on a Client-Side TCP URI

    tcp://fusesource.com:61616?trace=true
  • When using a URI to open a broker listener socket, you prefix the option name with transport. as shown.

    Example 1.4. Specifying Transport Options for a Listener Socket

    tcp://fusesource.com:61616?transport.trace=true
  • When using a URI to open a broker connection socket, you just specify the name of the option as shown.

    Example 1.5. Setting an Option on a Client-Side TCP URI

    tcp://fusesource.com:61616?trace=true
Important
In XML configuration, you must escape the & symbol, replacing it with &amp; as shown.

Example 1.6. Transport Options in XML

?option=value&amp;option=value&amp;...
Table 1.1, “TCP and NIO Transport Options” shows the options supported by the TCP and the NIO URIs.

Table 1.1. TCP and NIO Transport Options

OptionDefaultDescription
minmumWireFormatVersion0Specifies the minimum wire format version that is allowed.
tracefalseCauses all commands sent over the transport to be logged.
daemonfalseSpecifies 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.
useLocalHosttrueWhen true, causes the local machine's name to resolve to localhost.
socketBufferSize64*1024Sets the socket buffer size in bytes.
keepAlivefalseWhen true, enables TCP KeepAlive on the broker connection. Useful to ensure that inactive consumers do not time out.
soTimeout0Specifies, in milliseconds, the socket timeout.
soWriteTimeout0Specifies, in milliseconds, the timeout for socket write operations.
connectionTimeout30000Specifies, in milliseconds, the connection timeout. Zero means wait forever for the connection to be established.
closeAsynctrueThe false value causes all sockets to be closed synchronously.
soLingerMIN_INTEGERWhen > -1, enables the SoLinger socket option with this value. When equal to -1, disables SoLinger.
maximumConnectionsMAX_VALUEThe maximum number of sockets the broker is allowed to create.
diffServ0(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.
typeOfService0(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.1, “Wire Format Options Supported by OpenWire Protocol” for more information.
jms.* All the properties with this prefix are used to configure client connections to a broker. See Appendix B, Client Connection Options for more information.

Chapter 2. OpenWire over SSL

URI syntax

Example 2.1. Syntax for a vanilla SSL Connection

ssl://Host[:Port]?transportOptions
An SSL URI for using NIO has the syntax shown in Example 2.2, “Syntax for NIO Connection”.

Example 2.2. Syntax for NIO Connection

nio+ssl://Host[:Port]?transportOptions

Setting transport options

OpenWire transport options, transportOptions, are specified as a list of matrix parameters. How you specify the options to use differs between a client-side URI and a broker-side URI:
  • When using a URI to open a connection between a client and a broker, you just specify the name of the option as shown.

    Example 2.3. Setting an Option on a Client-Side TCP URI

    tcp://fusesource.com:61616?trace=true
  • When using a URI to open a broker listener socket, you prefix the option name with transport. as shown.

    Example 2.4. Specifying Transport Options for a Listener Socket

    tcp://fusesource.com:61616?transport.trace=true
  • When using a URI to open a broker connection socket, you just specify the name of the option as shown.

    Example 2.5. Setting an Option on a Client-Side TCP URI

    tcp://fusesource.com:61616?trace=true
Important
In XML configuration, you must escape the & symbol, replacing it with &amp; as shown.

Example 2.6. Transport Options in XML

?option=value&amp;option=value&amp;...
In addition to the options supported by the non-secure TCP/NIO transport listed in Table 1.1, “TCP and NIO Transport Options”, the SSL transport also supports the options for configuring the SSLServerSocket created for the connection. These options are listed in Table 2.1, “SSL Transport Options”.

Table 2.1. SSL Transport Options

OptionDefaultDescription
enabledCipherSuites Specifies the cipher suites accepted by this endpoint, in the form of a comma-separated list.
enabledProtocols Specifies the secure socket protocols accepted by this endpoint, in the form of a comma-separated list. If using Oracle's JSSE provider, possible values are: TLSv1, TLSv1.1, or TLSv1.2 (do not use SSLv2Hello or SSLv3, because of the POODLE security vulnerability, which affects SSLv3).
wantClientAuth (broker only) If true, the server requests (but does not require) the client to send a certificate.
needClientAuthfalse(broker 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.
enableSessionCreationtrue(broker 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.
Warning
If you are planning to enable SSL/TLS security, you must ensure that you explicitly disable the SSLv3 protocol, in order to safeguard against the Poodle vulnerability (CVE-2014-3566). For more details, see Disabling SSLv3 in JBoss Fuse 6.x and JBoss A-MQ 6.x.

Configuring broker SSL options

On the broker side, you must specify an SSL transport option using the syntax transport.OptionName. For example, to enable an OpenWire SSL port on a broker, you would add the following transport element:
<transportConnector name="ssl" uri="ssl:localhost:61617?transport.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2" />
Tip
Remember, if you are specifying more than one option in the context of XML, you need to escape the ampersand, &, between options as &amp;.

Configuring client SSL options

On the client side, you must specify an SSL transport option using the syntax socket.OptionName. For example, to connect to an OpenWire SSL port, you would use a URL like the following:
ssl:localhost:61617?socket.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2

Chapter 3. OpenWire over HTTP(S)

URI syntax

Example 3.1. Syntax for an HTTP Connection

tcp://Host[:Port]
An HTTPS URI has the syntax shown in Example 3.2, “Syntax for an HTTPS Connection”.

Example 3.2. Syntax for an HTTPS Connection

https://Host[:Port]

Dependencies

To use the HTTP(S) transport requires that the following JARs from the lib/optional folder are included on the classpath:
  • activemq-http-x.x.x.jar
  • xstream-x.x.x.jar
  • commons-logging-x.x.x.jar
  • commons-codec-x.x.x.jar
  • httpcore-x.x.x.jar
  • httpclient-x.x.x.jar

Chapter 4. OpenWire over UDP/IP

URI syntax

Example 4.1. Syntax for a UDP Connection

udp://Host[:Port]?transportOptions

Setting transport options

OpenWire transport options, transportOptions, are specified as a list of matrix parameters. How you specify the options to use differs between a client-side URI and a broker-side URI:
  • When using a URI to open a connection between a client and a broker, you just specify the name of the option as shown.

    Example 4.2. Setting an Option on a Client-Side TCP URI

    tcp://fusesource.com:61616?trace=true
  • When using a URI to open a broker listener socket, you prefix the option name with transport. as shown.

    Example 4.3. Specifying Transport Options for a Listener Socket

    tcp://fusesource.com:61616?transport.trace=true
  • When using a URI to open a broker connection socket, you just specify the name of the option as shown.

    Example 4.4. Setting an Option on a Client-Side TCP URI

    tcp://fusesource.com:61616?trace=true
Important
In XML configuration, you must escape the & symbol, replacing it with &amp; as shown.

Example 4.5. Transport Options in XML

?option=value&amp;option=value&amp;...

Table 4.1. UDP Transport Options

OptionDefaultDescription
minmumWireFormatVersion0The minimum version wire format that is allowed.
tracefalseCauses all commands sent over the transport to be logged.
useLocalHosttrueWhen true, causes the local machine's name to resolve to localhost.
datagramSize4*1024Specifies 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.1, “Wire Format Options Supported by OpenWire Protocol” for more information.
jms.* All the properties with this prefix are used to configure client connections to a broker. See Appendix B, Client Connection Options for more information.

Chapter 5. Stomp Protocol

Abstract

The Stomp protocol is a simplified messaging protocol that is specially designed for implementing clients using scripting languages. This chapter provides a brief introduction to the protocol.

Overview

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.
Important
Apache ActiveMQ implements the Stomp v1.1 specification, except for the treatment of spaces that appear at the beginning or end of message header keys. The ActiveMQ implementation of Stomp trims leading and trailing spaces in message header keys (but preserves leading and trailing spaces in the header values). This behaviour is liable to change in a future release.

URI syntax

Example 5.1, “Vanilla Stop URI” shows the syntax for a vanilla Stomp connection.

Example 5.1. Vanilla Stop URI

stomp://Host:[Port]?transportOptions
An NIO URI has the syntax shown in Example 5.2, “Syntax for Stomp+NIO Connection”.

Example 5.2. Syntax for Stomp+NIO Connection

stomp+nio://Host[:Port]?transportOptions
A secure Stomp URI has the syntax shown in Example 5.3, “Syntax for a Stomp SSL Connection”.

Example 5.3. Syntax for a Stomp SSL Connection

stomp+ssl://Host[:Port]?transportOptions
A secure Stomp+NIO URI has the syntax shown in Example 5.4, “Syntax for a Stomp+NIO SSL Connection”.

Example 5.4. Syntax for a Stomp+NIO SSL Connection

stomp+nio+ssl://Host[:Port]?transportOptions

Transport options

The Stomp protocol supports the following transport options:

Table 5.1. Transport Options Supported by Stomp Protocol

PropertyDefaultDescription
transport.defaultHeartBeat0,0
Specifies how the broker simulates the heartbeat policy when working with legacy Stomp 1.0 clients. The first value in the pair specifies, in milliseconds, the server will wait between messages before timing out the connection. The second value specifies, in milliseconds, the the client will wait between messages received from the server. Because Stomp 1.0 clients do not understand heartbeat messages, the second value should always be 0. This option is set in the uri attribute of a broker's transportConnector element to enable backward compatibility with Stomp 1.0 clients.
jms.* All the properties with this prefix are used to configure client connections to a broker. See Appendix B, Client Connection Options for more information.

SSL transport options

In addition to the options supported by the non-secure Stomp transports, the SSL transport also supports the options for configuring the SSLServerSocket created for the connection. These options are listed in Table 2.1, “SSL Transport Options”.
Warning
If you are planning to enable SSL/TLS security, you must ensure that you explicitly disable the SSLv3 protocol, in order to safeguard against the Poodle vulnerability (CVE-2014-3566). For more details, see Disabling SSLv3 in JBoss Fuse 6.x and JBoss A-MQ 6.x.

Configuring broker SSL options

On the broker side, you must specify an SSL transport option using the syntax transport.OptionName. For example, to enable a Stomp SSL port on a broker, you would add the following transport element:
<transportConnector name="stompssl" uri="stomp+ssl://localhost:61617?transport.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2" />
Tip
Remember, if you are specifying more than one option in the context of XML, you need to escape the ampersand, &, between options as &amp;.

Configuring client SSL options

On the client side, you must specify an SSL transport option using the syntax socket.OptionName. For example, to connect to a Stomp SSL port, you would use a URL like the following:
stomp+ssl://localhost:61617?socket.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2

Chapter 6. Multicast Protocol

Abstract

Multicast is an unreliable protocol that allows clients to connect to brokers using IP multicast.

URI syntax

Example 6.1, “Multicast URI” shows the syntax for a Multicast connection.

Example 6.1. Multicast URI

multicast://Host:[Port]?transportOptions

Transport options

The Multicast protocol supports the following transport options:

Table 6.1. Transport Options Supported by Multicast Protocol

PropertyDefaultDescription
groupdefaultSpecifies a unique group name that can segregate multicast traffic.
minmumWireFormatVersion0Specifies the minimum wire format version that is allowed.
tracefalseCauses all commands sent over the transport to be logged.
useLocalHosttrueWhen true, causes the local machine's name to resolve to localhost.
datagramSize4 * 1024Specifies the size of a datagram.
timeToLive-1Specifies the time to live of datagrams. Set greater than 1 to send packets beyond the local network. [a]
loopBackModefalseSpecifies whether loopback mode is used.
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.1, “Wire Format Options Supported by OpenWire Protocol” for more information.
jms.* All the properties with this prefix are used to configure client connections to a broker. See Appendix B, Client Connection Options for more information.
[a] This won't work for IPv4 addresses without setting the property java.net.preferIPv4Stack=true.

Chapter 7. MQ Telemetry Transport(MQTT) Protocol

Abstract

MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol. It was designed as a lightweight publish/subscribe messaging transport.

URI syntax

Example 7.1, “MQTT URI” shows the syntax for an MQTT connection.

Example 7.1. MQTT URI

mqtt://Host:[Port]?transportOptions
An NIO URI has the syntax shown in Example 7.2, “Syntax for MQTT+NIO Connection”.

Example 7.2. Syntax for MQTT+NIO Connection

mqtt+nio://Host[:Port]?transportOptions
A secure MQTT URI has the syntax shown in Example 7.3, “Syntax for an MQTT SSL Connection”.

Example 7.3. Syntax for an MQTT SSL Connection

mqtt+ssl://Host[:Port]?transportOptions
A secure MQTT+NIO URI has the syntax shown in Example 7.4, “Syntax for a MQTT+NIO SSL Connection”.

Example 7.4. Syntax for a MQTT+NIO SSL Connection

mqtt+nio+ssl://Host[:Port]?transportOptions

Transport options

The MQTT protocol supports the following transport options:

Table 7.1. MQTT Transport Options

PropertyDefaultDescription
transport.defaultKeepAlive0
Specifies, in milliseconds, the broker will allow a connection to be silent before it is closed. If a client specifies a keep-alive duration, this setting is ignored. This option is set in the uri attribute of a broker's transportConnector element.
jms.* All the properties with this prefix are used to configure client connections to a broker. See Appendix B, Client Connection Options for more information.

SSL transport options

In addition to the options supported by the non-secure MQTT transports, the SSL transport also supports the options for configuring the SSLServerSocket created for the connection. These options are listed in Table 2.1, “SSL Transport Options”.
Warning
If you are planning to enable SSL/TLS security, you must ensure that you explicitly disable the SSLv3 protocol, in order to safeguard against the Poodle vulnerability (CVE-2014-3566). For more details, see Disabling SSLv3 in JBoss Fuse 6.x and JBoss A-MQ 6.x.

Configuring broker SSL options

On the broker side, you must specify an SSL transport option using the syntax transport.OptionName. For example, to enable an MQTT SSL port on a broker, you would add the following transport element:
<transportConnector name="mqttssl" uri="mqtt+ssl://localhost:61617?transport.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2" />
Tip
Remember, if you are specifying more than one option in the context of XML, you need to escape the ampersand, &, between options as &amp;.

Configuring client SSL options

On the client side, you must specify an SSL transport option using the syntax socket.OptionName. For example, to connect to a MQTT SSL port, you would use a URL like the following:
mqtt+ssl://localhost:61617?socket.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2

Chapter 8. Advanced Message Queuing Protocol (AMQP)

Abstract

Oasis AMQP is an open standard application protocol for messaging. In contrast to JMS, AMQP standardizes the wire protocol, not the programming API, thus facilitating interoperability at the transport level.

URI syntax

The URI syntax given here is valid only for specifying the endpoint in a transport connector element (broker endpoint).
A basic AMQP endpoint has the following URI syntax:
amqp://Host:[Port]?transportOptions
An AMQP endpoint with NIO support has the following syntax:
amqp+nio://Host:[Port]?transportOptions
A secure AMQP endpoint has the following URI syntax:
amqp+ssl://Host:[Port]?transportOptions

Security

The AMQP adapter is fully integrated with Apache ActiveMQ security. This means that the broker accepts SASL (Simple Authentication and Security Layer) authentication and any authorization settings configured on the broker will be applied.
SSL security can also be enabled for AMQP. To enable SSL, configure the broker's sslContext element in the XML configuration and use the secure AMQP scheme, amqp+ssl, to define the AMQP URI in the broker's transportConnector element. For more details about SSL security, see the "Security Guide".

SSL transport options

In addition to the options supported by the non-secure AMQP transports, the SSL transport also supports the options for configuring the SSLServerSocket created for the connection. These options are listed in Table 2.1, “SSL Transport Options”.
Warning
If you are planning to enable SSL/TLS security, you must ensure that you explicitly disable the SSLv3 protocol, in order to safeguard against the Poodle vulnerability (CVE-2014-3566). For more details, see Disabling SSLv3 in JBoss Fuse 6.x and JBoss A-MQ 6.x.

Configuring broker SSL options

On the broker side, you must specify an SSL transport option using the syntax transport.OptionName. For example, to enable an AMQP SSL port on a broker, you would add the following transport element:
<transportConnector name="amqpssl" uri="amqp+ssl://localhost:61617?transport.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2" />
Tip
Remember, if you are specifying more than one option in the context of XML, you need to escape the ampersand, &, between options as &amp;.

Configuring client SSL options

On the client side, you must specify an SSL transport option using the syntax socket.OptionName. For example, to connect to an AMQP SSL port, you would use a URL like the following:
amqp+ssl://localhost:61617?socket.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2

Mapping from AMQP to JMS

Because AMQP is not a JMS compliant protocol, the AMQP messages and their headers are defined in a different format from JMS. It is therefore necessary to map AMQP messages to JMS format. The mapping is implemented by a transformer and the transformer type can be selected by specifying the transport.transformer option on the AMQP endpoint.
For example, the following transport connector selects the jms transformer type:
<transportConnector name="amqp" uri="amqp://localhost:5672?transport.transformer=jms"/>

AMQP-to-JMS transformers

Table 8.1, “AMQP-to-JMS Transformer Types” lists the available transformer types and describes the basic characteristics of each mapping.

Table 8.1. AMQP-to-JMS Transformer Types

TransformerDescription
native(Default) Wraps the bytes of the AMQP message into a JMS BytesMessage, and maps the AMQP message headers to JMS message headers.
rawWraps the bytes of the AMQP message into a JMS BytesMessage.
jmsMaps the body of the AMQP message to JMS body, and maps the AMQP message headers to JMS message headers.

Header mapping—all transformers

The JMS headers shown in the following table are always created, no matter which transformer type is selected.
AMQP HeaderJMS Header
 JMS_AMQP_NATIVE
message-formatJMS_AMQP_MESSAGE_FORMAT
The JMS_AMQP_NATIVE header is a boolean type, which indicates whether or not the JMS message body is a direct copy of the raw AMQP message body. It is set to true for the native and jms transformer types and false for the jms transformer type.

Header mapping—native or jms transformers

The JMS headers shown in the following table are mapped from AMQP headers, if the native or jms transformer type is selected.
AMQP HeaderJMS Header
header.durable JMSDeliveryMode
header.priority JMSPriority
header.ttl JMSExpiration
header.first-acquirer JMS_AMQP_FirstAcquirer
header.deliveryCount JMSXDeliveryCount
delivery-annotations.name JMS_AMQP_DA_name
message-annotations.x-opt-jms-type JMSType
message-annotations.x-opt-to-type Type of the JMSDestination
message-annotations.x-opt-reply-type Type of the JMSReplyTo
message-annotations.name JMS_AMQP_MA_name
application-properties.JMSXGroupID JMSXGroupID
application-properties.JMSXGroupSequence JMSXGroupSequence
application-properties.JMSXUserID JMSXUserID
application-properties.name name
properties.message-id JMSMessageID
properties.user-id JMSXUserID
properties.to JMSDestination
properties.subject JMS_AMQP_Subject
properties.reply-to JMSReplyTo
properties.correlation-id JMSCorrelationID
properties.content-type JMS_AMQP_ContentType
properties.content-encoding JMS_AMQP_ContentEncoding
properties.creation-time JMSTimestamp
properties.group-sequence JMSXGroupSequence
properties.reply-to-group-id JMS_AMQP_ReplyToGroupID
footer.name JMS_AMQP_FT_name
Note
The properties.user-id property is decoded as a UTF-8 String.

Default header values

When mapping AMQP message properties to JMS header values, the following default JMS header values are used:
JMS_AMQP_NATIVE
Defaults to true, if the transformer is native or raw, otherwise false.
JMSDeliveryMode
Defaults to javax.jms.Message.DEFAULT_DELIVERY_MODE.
JMSPriority
Defaults to javax.jms.Message.DEFAULT_PRIORITY.
JMSExpiration
Defaults to javax.jms.Message.DEFAULT_TIME_TO_LIVE.
JMSDestination type
Defaults to queue.
JMSReplyTo type
Defaults to queue.
JMSMessageID
Auto-generated, if not set.

Property type mapping

AMQP property types are converted to Java types as shown in the following table:
AMQP TypeJava TypeNotes
bool Boolean
byte Byte
short Short
int Integer
long Long
ubyte Byte or Short Short is used, if value > Byte.MAX_VALUE
ushort Short or Integer Integer is used if value > Short.MAX_VALUE
uint Integer or Long Long is used, if value > Integer.MAX_VALUE
ulong Long
double Double
float Float
symbol String
binary String Hex encoding of the binary value

Message body mapping

When the jms transformer type is selected, the AMQP message body is mapped to a JMS message type, as shown in the following table:
AMQP Body TypeJMS Message Type
null Message
Data BytesMessage
AmqpSequence StreamMessage
AmqpValue holding a null Message
AmqpValue holding a String TextMessage
AmqpValue holding a binary BytesMessage
AmqpValue holding a list StreamMessage
AmqpValue ObjectMessage

Chapter 9. VM Transport

Abstract

The VM transport allows clients to connect to each other inside the Java Virtual Machine (JVM) without the overhead of network communication.
The URI used to specify the VM transport comes in two flavors to provide maximum control over how the embedded broker is configured:
  • simple—specifies the name of the embedded broker to which the client connects and allows for some basic broker configuration
  • advanced—uses a broker URI to configure the embedded broker

1. Simple VM URI Syntax

URI syntax

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 9.1, “Simple VM URI Syntax” shows the syntax for a simple VM URI.

Example 9.1. Simple VM URI Syntax

vm://BrokerName?TransportOptions

Broker options

Table 9.1. VM Transport Broker Configuration Options

OptionDescription
broker.useJmxSpecifies if JMX is enabled. Default is true.
broker.persistentSpecifies if the broker uses persistent storage. Default is true.
broker.populateJMSXUserIDSpecifies if the broker populates the JMSXUserID message property with the sender’s authenticated username. Default is false.
broker.useShutdownHook Specifies if the broker installs a shutdown hook, so that it can shut down properly when it receives a JVM kill. Default is true.
broker.brokerNameSpecifies the broker name. Default is localhost.
broker.deleteAllMessagesOnStartupSpecifies if all the messages in the persistent store are deleted when the broker starts up. Default is false.
broker.enableStatisticsSpecifies if statistics gathering is enabled in the broker. Default is true.
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

Example 9.2, “Basic VM URI” shows a basic VM URI that connects to an embedded broker named broker1.

Example 9.2. Basic VM URI

vm://broker1
Example 9.3, “Simple URI with broker options” creates and connects to an embedded broker that uses a non-persistent message store.

Example 9.3. Simple URI with broker options

vm://broker1?broker.persistent=false

2. Advanced VM URI Syntax

URI syntax

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 9.4, “Advanced VM URI Syntax” shows the syntax for an advanced VM URI.

Example 9.4. Advanced VM URI Syntax

vm://(BrokerConfigURI)?TransportOptions
  • BrokerConfigURI is a broker configuration URI.
  • TransportOptions specifies the configuration for the transport. They are specified in the form of a query list. Table 9.2, “VM Transport Options” lists the available options.

Transport options

Table 9.2, “VM Transport Options” shows options for configuring the VM transport.

Table 9.2. VM Transport Options

OptionDescription
marshal If true, forces each command sent over the transport to be marshalled and unmarshalled using the specified wire format. Default is false.
wireFormatThe name of the wire format to use.
wireFormat.*All options with this prefix are used to configure the wire format. See Table A.1, “Wire Format Options Supported by OpenWire Protocol” for more information.
jms.*All the properties with this prefix are used to configure client connections to a broker. See Appendix B, Client Connection Options for more information.
createSpecifies if the VM transport will create an embedded broker if one does not exist. The default is true.
waitForStart Specifies the time, in milliseconds, the VM transport will wait for an embedded broker to start before creating one. The default is -1 which specifies that the transport will not wait.

Example

Example 9.5, “Advanced VM URI” creates and connects to an embedded broker configured using a broker configuration URI.

Example 9.5. Advanced VM URI

vm:(broker:(tcp://localhost:6000)?persistent=false)?marshal=false

Chapter 10. Dynamic Discovery Protocol

Abstract

The dynamic discovery protocol combines reconnect logic with a discovery agent to dynamically create a list of brokers to which the client can connect.

URI syntax

Example 10.1, “Dynamic Discovery URI” shows the syntax for a discovery URI.

Example 10.1. Dynamic Discovery URI

discovery:(DiscoveryAgentUri)?Options
DiscoveryAgentUri is URI for the discovery agent used to build up the list of available brokers. Discovery agents are described in Chapter 12, Discovery Agents.
The options, ?Options, are specified in the form of a query list. The discovery options are described in Table 10.1, “Dynamic Discovery Protocol Options”. You can also inject transport options into the discovered transports by adding their properties to the list.
Note
If no options are required, you can drop the parentheses from the URI. The resulting URI would take the form discovery:DiscoveryAgentUri

Transport options

The discovery protocol supports the options described in Table 10.1, “Dynamic Discovery Protocol Options”.

Table 10.1. Dynamic Discovery Protocol Options

OptionDefaultDescription
initialReconnectDelay 10Specifies, in milliseconds, how long to wait before the first reconnect attempt.
maxReconnectDelay 30000Specifies, in milliseconds, the maximum amount of time to wait between reconnect attempts.
useExponentialBackOff trueSpecifies if an exponential back-off is used between reconnect attempts.
backOffMultiplier 2Specifies the exponent used in the exponential back-off algorithm.
maxReconnectAttempts 0Specifies the maximum number of reconnect attempts before an error is sent back to the client. 0 specifies unlimited attempts.

Chapter 11. Fanout Protocol

Abstract

The fanout protocol allows clients to connect to multiple brokers at once and broadcast messages to consumers connected to all of the brokers at once.

URI syntax

Example 11.1, “Fanout URI Syntax” shows the syntax for a fanout URI.

Example 11.1. Fanout URI Syntax

fanout://(DiscoveryAgentUri)?Options
DiscoveryAgentUri is URI for the discovery agent used to build up the list of available brokers. The available discovery agents are listed in Chapter 12, Discovery Agents.
The options, ?Options, are specified in the form of a query list. The discovery options are described in Table 11.1, “Fanout Protocol Options”. You can also inject transport options into the discovered transports by adding their properties to the list.
Note
If no options are required, you can drop the parentheses from the URI. The resulting URI would take the form fanout://DiscoveryAgentUri

Transport options

The fanout protocol supports the transport options described in Table 11.1, “Fanout Protocol Options”.

Table 11.1. Fanout Protocol Options

Option NameDefaultDescription
initialReconnectDelay 10Specifies, in milliseconds, how long the transport will wait before the first reconnect attempt.
maxReconnectDelay 30000Specifies, in milliseconds, the maximum amount of time to wait between reconnect attempts.
useExponentialBackOff trueSpecifies if an exponential back-off is used between reconnect attempts.
backOffMultiplier 2Specifies the exponent used in the exponential back-off algorithm.
maxReconnectAttempts 0Specifies the maximum number of reconnect attempts before an error is sent back to the client. 0 specifies unlimited attempts.
fanOutQueues falseSpecifies whether queue messages are replicated to every connected broker.
minAckCount 2Specifies the minimum number of brokers to which the client must connect before it sends out messages.

Chapter 12. Discovery Agents

Abstract

A discovery agent is a mechanism that advertises available brokers to clients and other brokers.

Fabric agent

Example 12.1. Fuse Fabric Discovery Agent URI Format

fabric://GID
Where GID is the ID of the broker group from which the client discovers the available brokers.

Static agent

Example 12.2. Static Discovery Agent URI Format

static://(URI1,URI2,URI3,...)

Multicast agent

Example 12.3. Multicast Discovery Agent URI Format

multicast://GroupID
Where GroupID is an alphanumeric identifier. All participants in the same discovery group must use the same GroupID.

Zeroconf agent

Example 12.4. Zeroconf Discovery Agent URI Format

zeroconf://GroupID
Where the GroupID is an alphanumeric identifier. All participants in the same discovery group must use the same GroupID.

Chapter 13. Peer Protocol

Abstract

The peer protocol uses embedded brokers to enable messaging clients to communicate with each other directly.

URI syntax

A peer URI must conform to the following syntax:
peer://PeerGroup/BrokerName?BrokerOptions
Where the group name, PeerGroup, identifies the set of peers that can communicate with each other. That is, a given peer can connect only to the set of peers that specify the same PeerGroup name in their URLs. The BrokerName specifies the broker name for the embedded broker. The broker options, BrokerOptions, are specified in the form of a query list (for example, ?persistent=true).

Broker options

The peer URL supports the broker options described in Table 13.1, “Broker Options”.

Table 13.1. Broker Options

OptionDescription
useJmx If true, enables JMX. Default is true.
persistent If true, the broker uses persistent storage. Default is true.
populateJMSXUserID If true, the broker populates the JMSXUserID message property with the sender’s authenticated username. Default is false.
useShutdownHook If true, the broker installs a shutdown hook, so that it can shut down properly when it receives a JVM kill. Default is true.
brokerName Specifies the broker name. Default is localhost.
deleteAllMessagesOnStartup If true, deletes all the messages in the persistent store as the broker starts up. Default is false.
enableStatistics If true, enables statistics gathering in the broker. Default is true.

Dependencies

The peer protocol uses multicast discovery to locate active peers on the network. In order for this to work, you must ensure that the IP multicast protocol is enabled on your operating system.

Appendix A. OpenWire Format Options

Table A.1, “Wire Format Options Supported by OpenWire Protocol” shows the wire format options supported by the OpenWire protocol.

Table A.1. Wire Format Options Supported by OpenWire Protocol

OptionDefaultDescriptionNegotiation Policy
wireformat.stackTraceEnabledtrueSpecifies if the stack trace of an exception occurring on the broker is sent to the client.false if either side is false.
wireformat.tcpNoDelayEnabledfalseSpecifies if a hint is provided to the peer that TCP nodelay should be enabled on the communications socket.false if either side is false.
wireformat.cacheEnabledtrueSpecifies that commonly repeated values are cached so that less marshalling occurs.false if either side is false.
wireformat.cacheSize1024Specifies the maximum number of values to cache.Use the smaller of the two values.
wireformat.tightEncodingEnabledtrueSpecifies if wire size be optimized over CPU usage.false if either side is false.
wireformat.prefixPacketSizetrueSpecifies if the size of the packet be prefixed before each packet is marshalled.true if both sides are true.
wireformat.maxInactivityDuration30000Specifies the maximum inactivity duration, in milliseconds, before the broker considers the connection dead and kills it. <= 0 disables inactivity monitoring.Use the smaller of the two values.
wireformat.maxInactivityDurationInitalDelay10000Specifies the initial delay in starting inactivity checks. 

Appendix B. Client Connection Options

Overview

When creating a connection to a broker, a client can use the connection URI to configure a number of the connection properties. The properties are added to the connection URI as matrix parameters on the URI as shown in Example B.1, “Client Connection Options Syntax”.

Example B.1. Client Connection Options Syntax

URI?jms.option?jms.option...
Important
All of the client connection options are prefixed with jms.

Options

Table B.1, “Client Connection Options” shows the client connection options.

Table B.1. Client Connection Options

OptionDefaultDescription
alwaysSessionAsynctrueSpecifies if a separate thread is used for dispatching messages for each Session in the Connection. However, a separate thread is always used if there is more than one session, or the session isn't in auto acknowledge or dups ok mode.
clientID Specifies the JMS clientID to use for the connection.
closeTimeout15000Specifies the timeout, in milliseconds, before a connection close is considered complete. Normally a close() on a connection waits for confirmation from the broker; this allows that operation to timeout and save the client from hanging if there is no broker.
copyMessageOnSendtrueSpecifies if a JMS message should be copied to a new JMS Message object as part of the send() method in JMS. This is enabled by default to be compliant with the JMS specification. Disabling this can give you a performance, however you must not mutate JMS messages after they are sent.
disableTimeStampsByDefaultfalseSpecifies whether or not timestamps on messages should be disabled or not. Disabling them it adds a small performance boost.
dispatchAsyncfalseSpecifies if the broker dispatches messages to the consumer asynchronously.
nestedMapAndListEnabledtrueEnables/disables whether or not structured message properties and MapMessages are supported so that Message properties and MapMessage entries can contain nested Map and List objects.
objectMessageSerializationDeferedfalseSpecifies that the serialization of objects when they are set on an ObjectMessage is deferred. The object may subsequently get serialized if the message needs to be sent over a socket or stored to disk.
optimizeAcknowledgefalseSpecifies if messages are acknowledged in batches rather than individually. Enabling this could cause some issues with auto-acknowledgement on reconnection.
optimizeAcknowledgeTimeOut300Specifies the maximum time, in milliseconds, between batch acknowledgements when optimizeAcknowledge is enabled.
optimizedMessageDispatchtrueSpecifies if a larger prefetch limit is used for durable topic subscribers.
useAsyncSendfalseSpecifies in sends are performed asynchronously. Asynchronous sends provide a significant performance boost. The tradeoff is that the send() method will return immediately whether the message has been sent or not which could lead to message loss.
useCompressionfalseSpecifies if message bodies are compressed.
useRetroactiveConsumerfalseSpecifies whether or not retroactive consumers are enabled. Retroactive consumers allow non-durable topic subscribers to receive messages that were published before the non-durable subscriber started.
warnAboutUnstartedConnectionTimeout500Specifies the timeout, in milliseconds, from connection creation to when a warning is generated if the connection is not properly started and a message is received by a consumer. -1 disables the warnings.
auditDepth2048Specifies the size of the message window that will be audited for duplicates and out of order messages.
auditMaximumProducerNumber64Specifies the maximum number of producers that will be audited.
alwaysSyncSendfalseSpecifies if a message producer will always use synchronous sends when sending a message.
blobTransferPolicy.* Used to configure how the client handles blob messages. See the section called “Blob handling”.
prefetchPolicy.* Used to configure the prefect limits. See the section called “Prefetch limits”.
redeliveryPolicy.* Used to configure the redelivery policy. See the section called “Redelivery policy”.

Blob handling

Blob messages allow the broker to use an out of band transport to pass large files between clients. Table B.2, “Blob Message Properties” describes the connection URI options used to configure how a client handles blob messages.
Important
All of the prefetch options are prefixed with jms.blobTransferPolicy.

Table B.2. Blob Message Properties

OptionDescription
bufferSizeSpecifies the size of the buffer used when uploading or downloading blobs.
uploadUrlSpecifies the URL to which blob messages are stored for transfer. This value overrides the upload URI configured by the broker.

Prefetch limits

The prefetch limits control how many messages can be dispatched to a consumer and waiting to be acknowledged. Table B.3, “Connection URI Prefect Limit Options” describes the options used to configure the prefetch limits of consumers using a connection.
Important
All of the prefetch options are prefixed with jms.prefetchPolicy.

Table B.3. Connection URI Prefect Limit Options

OptionDescription
queuePrefetchSpecifies the prefect limit for all consumers using queues.
queueBrowserPrefetchSpecifies the prefect limit for all queue browsers.
topicPrefetchSpecifies the prefect limit for non-durable topic consumers.
durableTopicPrefetchSpecifies the prefect limit for durable topic consumers.
allSpecifies the prefect limit for all types of message consumers.

Redelivery policy

The redelivery policy controls the redelivery of messages in the event of connectivity issues. Table B.4, “Redelivery Policy Options” describes the options used to configure the redelivery policy of consumers using a connection.
Important
All of the prefetch options are prefixed with jms.redeliveryPolicy.

Table B.4. Redelivery Policy Options

OptionDefaultDescription
collisionAvoidanceFactor0.15Specifies the percentage of range of collision avoidance.
maximumRedeliveries6Specifies the maximum number of times a message will be redelivered before it is considered a poisoned pill and returned to the broker so it can go to a dead letter queue. -1 specifies an infinite number of redeliveries.
maximumRedeliveryDelay-1Specifies the maximum delivery delay that will be applied if the useExponentialBackOff option is set. -1 specifies that no maximum be applied.
initialRedeliveryDelay1000Specifies the initial redelivery delay in milliseconds.
redeliveryDelay1000Specifies the delivery delay, in milliseconds, if initialRedeliveryDelay is 0.
useCollisionAvoidancefalseSpecifies if the redelivery policy uses collision avoidance.
useExponentialBackOfffalseSpecifies if the redelivery time out should be increased exponentially.
backOffMultiplier5Specifies the back-off multiplier.

Index

D

discovery agent
Fuse Fabric, Fabric agent
multicast, Multicast agent
static, Static agent
zeroconf, Zeroconf agent
discovery protocol
backOffMultiplier, Transport options
initialReconnectDelay, Transport options
maxReconnectAttempts, Transport options
maxReconnectDelay, Transport options
URI, URI syntax
useExponentialBackOff, Transport options
discovery URI, URI syntax
discovery:, URI syntax

E

embedded broker
brokerName, Broker options
deleteAllMessagesOnStartup, Broker options
enableStatistics, Broker options
persistent, Broker options
populateJMSXUserID, Broker options
useJmx, Broker options
useShutdownHook, Broker options

F

fabric://, Fabric agent
fanout protocol
backOffMultiplier, Transport options
fanOutQueues, Transport options
initialReconnectDelay, Transport options
maxReconnectAttempts, Transport options
maxReconnectDelay, Transport options
minAckCount, Transport options
URI, URI syntax
useExponentialBackOff, Transport options
fanout URI, URI syntax
fanout://, URI syntax
Fuse Fabric discovery agent
URI, Fabric agent

H

HTTP
URI, URI syntax
HTTPS
URI, URI syntax

M

MQTT, URI syntax
MQTT+NIO, URI syntax
MQTT+SSL, URI syntax
Multicast, URI syntax
multicast discovery agent
URI, Multicast agent
multicast://, Multicast agent

N

NIO
URI, URI syntax
NIO+SSL
URI, URI syntax

S

SSL
URI, URI syntax
static discovery agent
URI, Static agent
static://, Static agent
STOMP, URI syntax
STOMP+NIO, URI syntax
STOMP+SSL, URI syntax

U

UDP
URI, URI syntax
URI
HTTP, URI syntax
HTTPS, URI syntax
MQTT, URI syntax
MQTT+NIO, URI syntax
MQTT+SSL, URI syntax
Multicast, URI syntax
NIO, URI syntax
NIO+SSL, URI syntax
SSL, URI syntax
STOMP, URI syntax
STOMP+NIO, URI syntax
STOMP+SSL, URI syntax
TCP, URI syntax
UDP, URI syntax

V

VM
advanced URI, URI syntax
broker configuration, Broker options
broker name, URI syntax
brokerConfig, Broker options
create, Transport options
marshal, Transport options
simple URI, Simple VM URI Syntax
waitForStart, Transport options
wireFormat, Transport options
VM URI
advanced, URI syntax
simple, Simple VM URI Syntax

Z

zeroconf discovery agent
URI, Zeroconf agent
zeroconf://, Zeroconf agent