Fuse Message Broker

Connectivity Guide

Version 5.5

Febuary 2012
Trademark Disclaimer
Third Party Acknowledgements
Revision History

Table of Contents

1. Protocol Summary
Simple Connections
Discovery Protocols
Peer-to-Peer Protocols
2. OpenWire Protocol
Introduction to the OpenWire Protocol
OpenWire Example
3. Stomp Protocol
Introduction to the Stomp Protocol
Protocol Details
Stomp Tutorial
Stomp Example
4. REST Protocols
Introduction to the REST Protocol
Protocol Details
REST Example
5. VM Transport
6. Peer-to-Peer Protocols
Peer Protocol
Peer Example
A. Transport Options
TCP and NIO Transports
SSL Transport
UDP Transport
Wire Format Options
Index

List of Figures

3.1. Connecting to the ActiveMQ JMX Port
3.2. Monitoring the Status of the FOO.BAR Queue
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
6.1. Peer Protocol Endpoints with Embedded Brokers

List of Tables

1.1. Protocols for Simple Connections
1.2. Summary of Discovery Protocols
1.3. Summary of Peer-to-Peer 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. Client Commands for the Stomp Protocol
3.3. Server Commands for the 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. Broker 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

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 in Using Networks of Brokers.

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.


The SUBSCRIBE command registers a client’s interest in listening to a specific destination. Like the SEND command, the SUBSCRIBE command requires a destination header. Henceforth, any messages received on the subscription are delivered as MESSAGE frames, from the server to the client. For example, the following frame shows a client subscribing to the destination, /queue/a:

SUBSCRIBE
destination: /queue/foo
ack: client
 
^@

In this case the ack header is set to client, which means that messages are considered delivered only after the client specifically acknowledges them with an ACK frame. The body of the SUBSCRIBE command is ignored.

The SUBSCRIBE command supports the following optional headers:

You must download and install the requisite packages to support the Ruby programming language before you can run the Stomp example. Install the following packages:

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

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 advance 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 a simple VM URI.


Example 5.5 creates and connects to an embedded broker configured using a broker configuration URI.


The peer protocol enables you to set up a peer-to-peer network by creating an embedded broker inside each peer endpoint. Figure 6.1 illustrates the peer-to-peer network topology for a simple two-peer network.


In this topology, a standalone broker is not required, because each peer instantiates its own embedded broker. As shown in Figure 6.1 , the producer sends messages to its embedded broker, broker1, by connecting to the local VM endpoint, vm://broker1—see VM Transport . The embedded brokers, broker1 and broker2, are linked together using a network connector, which allows messages to flow in either direction between the brokers. When the producer sends a message to the queue, TEST.FOO, the first embedded broker, broker1, automatically pushes the message across the network connector and on to the remote embedded broker, broker2. The consumer can then receive the message from its embedded broker, broker2.

Start a consumer that consumes messages from the TEST.FOO queue belonging to the group peer group. To start the consumer, run the consumer tool with a peer group URL as follows:

cd InstallDir/example
ant consumer -Durl="peer://group/broker1?persistent=false" -Dmax=100

Where the first component of the URL path, group, specifies that this peer belongs to the group peer group. The second component, broker1, specifies the name of the embedded broker and the setting, persistent=false, sets a broker option. When the consumer starts up, you should see output like the following in the command window:

While the consumer is starting up, it activates an embedded broker with broker name, broker1, and attempts to connect to its peers using a multicast discovery agent.

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

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.  

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

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