LibraryPrintFeedback

Broker Client Connectivity Guide

Version 7.1

December 2012
Trademark Disclaimer
Third Party Acknowledgements
Revision History

Table of Contents

1. Protocol Summary
Simple Connections
Discovery Protocols
2. OpenWire Protocol
3. Stomp Protocol
Introduction to the Stomp Protocol
Stomp Heartbeats
4. REST Protocols
Introduction to the REST Protocol
Protocol Details
REST Example
5. VM Transport
6. Discovering Brokers
Discovery Agents
Fuse Fabric Discovery Agent
Static Discovery Agent
Multicast Discovery Agent
Zeroconf Discovery Agent
Dynamic Discovery Protocol
Fanout Protocol
A. Transport Options
TCP and NIO Transports
SSL Transport
UDP Transport
Wire Format Options
Index

List of Figures

4.1. Welcome Page for Web Examples
4.2. The Send a JMS Message Form
4.3. Default Option to Browse a Queue
4.4. Option to Browse a Queue as XML
4.5. Option to Browse a Queue as Atom
4.6. Option to Browse a Queue as RSS 1.0
5.1. Clients Connected through the VM Transport

List of Tables

1.1. Protocols for Simple Connections
1.2. Summary of Discovery Protocols
2.1. Transport Protocols Supported by OpenWire
2.2. Transport Options Supported by OpenWire Protocol
3.1. Transport Protocols Supported by Stomp
3.2. Transport Options Supported by Stomp Protocol
4.1. HTTP RESTful Operations
4.2. URL Options Recognized by the Message Servlet
4.3. Message Servlet RESTful HTTP Operations
4.4. URL Options Recognized by the QueueBrowse Servlet
4.5. Form Properties Recognized by Message Servlet
5.1. VM Transport Broker Configuration Options
5.2. VM Transport Options
5.3. Broker Options
6.1. Dynamic Discovery Protocol Options
6.2. Fanout Protocol Options
A.1. TCP and NIO Transport Options
A.2. SSL Transport Options
A.3. SSL Transport Options
A.4. Transport Options Supported by OpenWire Protocol

List of Examples

4.1. Web Form for Sending a Message to a Queue or Topic
4.2. Configuration of an Embedded Servlet Engine
5.1. Simple VM URI Syntax
5.2. Basic VM URI
5.3. Simple URI with broker options
5.4. Advanced VM URI Syntax
5.5. Advanced VM URI
6.1. Enabling a Discovery Agent on a Broker
6.2. Fuse Fabric Discovery Agent URI Format
6.3. Client Connection URL using Fuse Fabric Discovery
6.4. Static Discovery Agent URI Format
6.5. Discovery URI using the Static Discovery Agent
6.6. Multicast Discovery Agent URI Format
6.7. Enabling a Multicast Discovery Agent on a Broker
6.8. Client Connection URL using Multicast Discovery
6.9. Zeroconf Discovery Agent URI Format
6.10. Enabling a Multicast Discovery Agent on a Broker
6.11. Client Connection URL using Zeroconf Discovery
6.12. Dynamic Discovery URI
6.13. Discovery Protocol URI
6.14. Injecting Transport Options into a Discovered Transport
6.15. Fanout URI Syntax
6.16. Fanout Protocol URI

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 ProtocolTransport ProtocolSample URLDescription
OpenWireTCPtcp://Host:Port

Connect to the message broker endpoint at Host:Port using the OpenWire over TCP protocol.

This URL is also used to configure the transport connector in a broker.

OpenWireTCPnio://Host:PortSame as tcp, except that the New I/O (NIO) Java API is used, which provides better performance in some scenarios.
OpenWireSSLssl://Host:Port

Connect to the message broker endpoint at Host:Port using the OpenWire over SSL protocol.

This URL is also used to configure the transport connector in a broker.

OpenWireHTTPhttp://Host:Port

Connect to the message broker endpoint at Host:Port using the OpenWire over HTTP protocol (HTTP tunneling). You can use this protocol to navigate through firewalls.

This URL is also used to configure the transport connector in a broker.

OpenWireHTTPShttps://Host:Port

Connect to the message broker endpoint at Host:Port using the OpenWire over HTTPS protocol

This URL is also used to configure the transport connector in a broker.

StompTCPstomp://Host:Port

Connect to the message broker endpoint at Host:Port using the Stomp over TCP protocol.

This URL is also used to configure the transport connector in a broker.

StompSSLstomp+ssl://Host:Port

Connect to the message broker endpoint at Host:Port using the Stomp over SSL protocol.

This URL is also used to configure the transport connector in a broker.

RESTHTTPhttp://Host:Port/ demo/message/FOO/BAR ?timeout=10000 &type=queue

Connect to the message broker endpoint at Host:Port using the REST protocol. The REST endpoint is implemented as a servlet deployed in a servlet engine.

For example, the sample URL is built up from a Web context name, demo, followed by the servlet name, message, followed by a destination name, FOO/BAR, and some query options.

This URL is not used to configure the REST transport connector in a broker. Use the <jetty> tag to configure the REST endpoint in the broker.

RESTsHTTPShttp://Host:Port/ demo/message/FOO/BAR ?timeout=10000 &type=queue 
XMPPTCPxmpp://Host:PortConfigure the transport connector in a message broker to accept XMPP connections on Host:Port (for example, from an Instant Messaging client).
VMN/Avm://BrokerNameConfigure clients to connect to a broker embedded within the same Java Virtual Machine (JVM). The BrokerName is the broker name of the embedded broker.

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]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.

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.


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,CltRecv

CONNECTED:
heart-beat:SrvSend,SrvRecv

The CltSend, CltRecv, SrvSend, and SrvRecv fields are interpreted as follows:

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.

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.

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:

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:


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 .


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:


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 .


Table 4.5 describes the form properties that are recognized by the message servlet.


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

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 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.


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.


[Important]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.


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.


Where the discoveryUri attribute on the transportConnector element is initialized to multicast://default.

[Tip]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 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]Important

Your local network (LAN) must be configured to use IP/multicast for the zeroconf agent to work.

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, ?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.

[Tip]Tip

If no options are required, you can drop the parentheses from the URI. The resulting URI would take the form discovery://DiscoveryAgentUri

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, ?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.

[Tip]Tip

If no options are required, you can drop the parentheses from the URI. The resulting URI would take the form fanout://DiscoveryAgentUri

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.

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=true

When setting a server-side option, there are two alternative option syntaxes as follows:

TCP listener socket options

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=true
TCP connection socket options

To 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=true

Table A.1 shows the options supported by the TCP and the NIO URIs.

Table A.1. TCP and NIO Transport Options

OptionDefaultDescription
minmumWireFormatVersion0The 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.
soTimeout0Sets the socket timeout in milliseconds
soWriteTimeout0Sets the socket write timeout in milliseconds
connectionTimeout30000A 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.
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. (from 5.6.0).
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.4 for more information.

The SSL transport is used for creating OpenWire/TCP endpoints with SSL/TLS enabled.

[Note]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.

Table A.4 shows the wire format options supported by the OpenWire protocol.

Table A.4. Transport Options Supported by OpenWire Protocol

OptionDefaultDescriptionNegotiation policy
wireformat .stackTraceEnabledtrue

Should the stack trace of an exception occuring on the broker be sent to the client?

Set to false if either side is false.

wireformat .tcpNoDelayEnabledfalse

Provides a hint to the peer that TCP nodelay should be enabled on the communications Socket.

Set to false if either side is false.

wireformat .cacheEnabledtrue

Should commonly repeated values be cached so that less marshalling occurs?

Set to false if either side is false.

wireformat .cacheSize1024

If cacheEnabled is true, this property specifies the maximum number of values to cache.

Use the smaller of the two values.

wireformat .tightEncodingEnabledtrue

Should wire size be optimized over CPU usage?

Set to false if either side is false.

wireformat .prefixPacketSizetrue

Should the size of the packet be prefixed before each packet is marshalled?

Set to true if both sides are true.

wireformat .maxInactivityDuration30000

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 <= 0 to disable inactivity monitoring.

Use the smaller of the two values.

wireformat .maxInactivityDurationInitalDelay10000The initial delay in starting the maximum inactivity checks. Note: The mis-spelling, Inital, is a typographic error in the source code.  

D

discovery agent
Fuse Fabric, Fuse Fabric Discovery Agent
multicast, Multicast Discovery Agent
static, Static Discovery Agent
zeroconf, Zeroconf Discovery 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
discoveryUri, Configuring a broker, Configuring a broker

E

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

F

fabric://, URI
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, URI

M

multicast discovery agent
broker configuration, Configuring a broker
URI, URI
multicast://, URI

S

static discovery agent
URI, Using the agent
static://, Using the agent

T

transportConnector
discoveryUri, Configuring a broker, Configuring a broker

V

VM
advanced URI, Advanced URI syntax
broker configuration, Simple URI syntax
broker name, Simple URI syntax
broker.*, Simple URI syntax
brokerConfig, Simple URI syntax
create, Embedded brokers, Transport options
embedded broker, Embedded brokers
marshal, Transport options
simple URI, Simple URI syntax
waitForStart, Embedded brokers, Transport options
wireFormat, Transport options
VM URI
advanced, Advanced URI syntax
simple, Simple URI syntax

Z

zeroconf discovery agent
broker configuration, Configuring a broker
URI, URI
zeroconf://, URI