The following protocols can be used either for straightforward client-to-broker connections (transport connector) or broker-to-broker connections (network connector). For each wire protocol (that is, on-the-wire message encoding), Fuse Message Broker supports one or more associated transport protocols. Hence, you can configure connections with a wide variety of wire protocol/transport protocol combinations.

Table 1.1 shows the protocol combinations that messaging clients can use to connect directly to the message broker.

A discovery protocol builds a connection to a message broker in two steps, as follows:

Discovery protocols are particularly useful for clients that connect to a cluster of message brokers.

Table 1.2 describes the discovery protocols that clients can use.

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 .

The OpenWire protocol is a JMS compliant wire protocol (defining message types and message encodings) that is native to the Fuse Message Broker. The protocol is designed to be fully-featured, JMS-compliant, and highly performant. It is the default protocol of the Fuse Message Broker.

Table 2.1 shows the transport protocols supported by the OpenWire wire protocol:

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.

Fuse Message Broker currently supports the following client types for the OpenWire protocol:

If you want to develop an OpenWire client using other programming languages, try one of the following client types from the Apache ActiveMQ project:

The demonstration code required to run these examples is available only from the standalone Apache ActiveMQ package, which you must download and install in addition to Fuse ESB.

It is relatively straightforward to try out the various OpenWire+transport combinations using the sample code provided. After configuring the broker with the requisite transport connectors, you can use the sample producer tool and the consumer tool to propagate messages through the broker using the following protocols: OpenWire over TCP or OpenWire over HTTP.

To run these examples, you require:

The OpenWire examples depend on the sample producer and consumer clients located in the following directory:

ActiveMQInstallDir/fuse-message-broker-Version/example

To try out the OpenWire protocol, perform the following steps:

For full details of how to deploy a broker in the OSGi container, please read Deploying a JMS Broker in Deploying into the OSGi Container. If you have not already deployed a broker, you can create and deploy a new broker, broker1, by entering the following console command:

karaf@root> activemq:create-broker --name broker1

Add a HTTP transport connector by editing the broker configuration file (in InstallDir/deploy/broker1-broker.xml) as follows:

<beans>
  ...
  <transportConnectors>
    ...
    <transportConnector name="openwire" uri="tcp://localhost:61616"/>
    <transportConnector name="http"   uri="http://localhost:61620"/>
  </transportConnectors>
  ...
</beans>

To connect the consumer tool to the tcp://localhost:61616 endpoint (OpenWire over TCP), change directory to ActiveMQInstallDir/example and enter the following command:

ant consumer -Durl=tcp://localhost:61616 -Dmax=100

You should see some output like the following:

Buildfile: build.xml
init:
compile:
consumer:
     [echo] Running consumer against server at $url = tcp://localhost:61616
for subject $subject = TEST.FOO
     [java] Connecting to URL: tcp://localhost:61616
     [java] Consuming queue: TEST.FOO
     [java] Using a non-durable subscription
     [java] We are about to wait until we consume: 100 message(s) then
we will shutdown

To connect the producer tool to the tcp://localhost:61616 endpoint (OpenWire over TCP), open a new command prompt, change directory to ActiveMQInstallDir/example and enter the following command:

ant producer -Durl=tcp://localhost:61616

In the window where the consumer tool is running, you should see some output like the following:

[java] Received: Message: 0 sent at: Wed Sep 19 14:38:06 BST
2007  ...
     [java] Received: Message: 1 sent at: Wed Sep 19 14:38:06 BST
2007  ...
     [java] Received: Message: 2 sent at: Wed Sep 19 14:38:06 BST
2007  ...
     [java] Received: Message: 3 sent at: Wed Sep 19 14:38:06 BST
2007  ...
     [java] Received: Message: 4 sent at: Wed Sep 19 14:38:06 BST
2007  ...
     [java] Received: Message: 5 sent at: Wed Sep 19 14:38:06 BST
2007  ...
     [java] Received: Message: 6 sent at: Wed Sep 19 14:38:06 BST
2007  ...
     [java] Received: Message: 7 sent at: Wed Sep 19 14:38:06 BST
2007  ...
     [java] Received: Message: 8 sent at: Wed Sep 19 14:38:06 BST
2007  ...
     [java] Received: Message: 9 sent at: Wed Sep 19 14:38:06 BST
2007  ...

To connect the producer tool to the http://localhost:61620 endpoint (OpenWire over HTTP), enter the following command from the example directory:

ant producer -Durl=http://localhost:61620

This command sends ten new messages to the consumer client.

The Stomp protocol is a simplified messaging protocol that is being developed as an open source project (http://stomp.codehaus.org/). The advantage of the stomp protocol is that you can easily improvise a messaging client—even when a specific client API is not available—because the protocol is so simple.

Table 3.1 shows the transport protocols supported by the Stomp wire protocol:

Stomp currently supports the following client types:

This section describes the format of Stomp data packets , as well as the semantics of the data packet exchanges. Stomp is a relatively simple wire protocol—it is even possible to communicate manually with a Stomp broker using a telnet client (see Stomp Tutorial ).

In principal, Stomp can be combined with any transport protocol, including connection-oriented and non-connection-oriented transports. In practice, though, Stomp is usually implemented over TCP and this is the only transport currently supported by Fuse Message Broker.

The Stomp specification is licensed under the Creative Commons Attribution v2.5

The Stomp specification defines the term frame to refer to the data packets transmitted over a Stomp connection. A Stomp frame has the following general format:

<StompCommand>
<HeaderName_1>:<HeaderValue_1>
<HeaderName_2>:<HeaderValue_2>
    
<FrameBody>
^@

A Stomp frame always starts with a Stomp command (for example, SEND) on a line by itself. The Stomp command may then be followed by zero or more header lines: each header is in a <key>:<value> format and terminated by a newline. A blank line indicates the end of the headers and the beginning of the body, <FrameBody>, (which is empty for many of the commands). The frame is terminated by the null character, which is represented as ^@ above (Ctrl-@ in ASCII)).

Most Stomp commands have oneway semantics (that is, after sending a frame, the sender does not expect any reply). The only exceptions are:

Any client frame, other than CONNECT, may specify a receipt header with an arbitrary value. This causes the server to acknowledge receipt of the frame with a RECEIPT frame, which contains the value of this header as the value of the receipt-id header in the RECEIPT frame. For example, the following frame shows a SEND command that includes a receipt header:

SEND
destination:/queue/a
receipt:message-12345
 
Hello a!^@

Table 3.2 lists the client commands for the Stomp protocol. The Reply column indicates whether or not the server sends a reply frame by default.

After opening a socket to connect to the remote server, the client sends a CONNECT command to initiate a Stomp session. For example, the following frame shows a typical CONNECT command, including a login header and a passcode header:

CONNECT
login: <username>
passcode:<passcode>
 
^@

After the client sends the CONNECT frame, the server always acknowledges the connection by sending a frame, as follows:

CONNECTED
session: <session-id> 
 
^@

The session-id header is a unique identifier for this session (currently unused).

The SEND command sends a message to a destination—for example, a queue or a topic—in the messaging system. It has one required header, destination, which indicates where to send the message. The body of the SEND command is the message to be sent. For example, the following frame sends a message to the /queue/a destination:

SEND
destination:/queue/a
hello queue a
 
^@

From the client’s perspective, the destination name, /queue/a, is an arbitrary string. Despite seeming to indicate that the destination is a queue it does not, in fact, specify any such thing. Destination names are simply strings that are mapped to some form of destination on the server; how the server translates these strings is up to the implementation.

The SEND command also supports the following optional headers:

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:

The UNSUBSCRIBE command removes an existing subscription, so that the client no longer receives messages from that destination. It requires either a destination header or an id header (if the previous SUBSCRIBE operation passed an id value). For example, the following frame cancels the subscription to the /queue/a destination:

UNSUBSCRIBE
destination: /queue/a
 
^@

The ACK command acknowledges the consumption of a message from a subscription. If the client issued a SUBSCRIBE frame with an ack header set to client, any messages received from that destination are not considered to have been consumed until the message is acknowledged by an ACK frame.

The ACK command has one required header, message-id, which must contain a value matching the message-id for the MESSAGE being acknowledged. Optionally, a transaction header may be included, if the acknowledgment participates in a transaction. For example, the following frame acknowledges a message in the context of a transaction:

ACK
message-id: <message-identifier>
transaction: <transaction-identifier>
 
^@

The BEGIN command initiates a transaction. Transactions can be applied to SEND and ACK commands. Any messages sent or acknowledged during a transaction can either be commited or rolled back at the end of the transaction.

BEGIN
transaction: <transaction-identifier>
 
^@

The transaction header is required and the <transaction-identifier> can be included in SEND, COMMIT, ABORT, and ACK frames to bind them to the named transaction.

The COMMIT command commits a specific transaction.

COMMIT
transaction: <transaction-identifier>
 
^@

The transaction header is required and specifies the transaction, <transaction-identifier>, to commit.

The ABORT command rolls back a specific transaction.

ABORT
transaction: <transaction-identifier>
 
^@

The transaction header is required and specifies the transaction, <transaction-identifier>, to roll back.

The DISCONNECT command disconnects gracefully from the server.

DISCONNECT
 
^@

Table 3.3 lists the commands that the server can send to a Stomp client. These commands all have oneway semantics.

The MESSAGE command conveys messages from a subscription to the client. The MESSAGE frame must include a destination header, which identifies the destination from which the message is taken. The MESSAGE frame also contains a message-id header with a unique message identifier. The frame body contains the message contents. For example, the following frame shows a typical MESSAGE command with destination and message-id headers:

MESSAGE
destination:/queue/a
message-id: <message-identifier>
 
hello queue a^@

The MESSAGE command supports the following optional headers:

A RECEIPT frame is issued from the server whenever the client requests a receipt for a given command. The RECEIPT frame includes a receipt-id, containing the value of the receipt-id from the original client request. For example, the following frame shows a typical RECEIPT command with receipt-id header:

RECEIPT
receipt-id:message-12345
 
^@

The receipt body is always empty.

The server may send ERROR frames if something goes wrong. The error frame should contain a message header with a short description of the error. The body may contain more detailed information (or may be empty). For example, the following frame shows an ERROR command with a non-empty body:

ERROR
message: malformed packet received
 
The message:
-----
MESSAGE
destined:/queue/a
Hello queue a!
-----
Did not contain a destination header, which is required for message
propagation.
^@

The ERROR command supports the following optional headers:

Because Stomp frames consist of plain text, it is possible to improvise a Stomp client by starting up a telnet session and entering Stomp frames directly at the keyboard. This can be a useful diagnostic tool and is also a good way to learn about the Stomp protocol.

While most characters in a Stomp frame are just plain text, there is one required character, null, that you might have difficulty typing at the keyboard. On some keyboards, you can type null as Ctrl-@. Other keyboards might require you to do a bit of research, however.

For example, to type a null character on the 101-key keyboard that is commonly used with a Windows PC, proceed as follows:

To send and receive messages over the Stomp protocol using telnet clients, perform the following steps:

For full details of how to deploy a broker in the OSGi container, please read Deploying a JMS Broker in Deploying into the OSGi Container. If you have not already deployed a broker, you can create and deploy a new broker, broker1, by entering the following console command:

karaf@root> activemq:create-broker --name broker1

Normally, the default broker is configured to initialize a Stomp connector that listens on port, 61613. Look for a line like the following in the broker’s log:

INFO  TransportServerThreadSupport   - Listening for connections at:
stomp://localhost:61613

If the Stomp connector is not present in the broker, you will have to configure it—see Configure the broker for details.

Open a new command prompt and start a new telnet session for the producer client, by entering the following command:

telnet

This command starts telnet in interactive mode. Now enter the following telnet commands (the telnet prompt that begins each line is implementation dependent):

telnet> set localecho
Local echo on
telnet> open localhost 61613

After entering the open command, telnet should connect to the Stomp socket on your local ActiveMQ broker (where the Stomp port is presumed to be 61613 here). You should now see a blank screen, where you can directly type the contents of the Stomp frames you want to send over TCP.

Start a Stomp session for the producer by entering the following Stomp frame in the telnet window:

CONNECT
login:foo
passcode:bar
 
^@

The login and passcode headers are currently ignored by the ActiveMQ broker, so you can enter any values you like for these headers. Don’t forget to insert a blank line after the headers. Finally, you must terminate the frame by typing the null character, ^@ (for notes on how to type the null character at your keyboard, see Typing the null character ).

If all goes well, you will see a response similar to the following:

CONNECTED
session:ID:fboltond820-2290-1190810591249-3:0

Send a message to the FOO.BAR queue by entering the following frame:

SEND
destination:/queue/FOO.BAR
receipt:
 
Hello, queue FOO.BAR
^@

As soon as you have finished typing the null character, ^@, you should receive the following RECEIPT frame from the server:

RECEIPT
receipt-id:

It is a good idea to include a receipt header in the frames you send from a telnet client. It enables you to confirm that the connection is working normally.

The status of the ActiveMQ broker can be monitored through a JMX port. To monitor the broker, start a new command prompt and enter the following command:

jconsole

The jconsole utility is a standard JMX client that is included with Sun’s Java Development Kit (JDK). When you start the jconsole utility, a dialog appears and prompts you to connect to a JMX process, as shown in Figure 3.1.

Figure 3.1. Connecting to the ActiveMQ JMX Port

Select the ActiveMQ broker process and click Connect. The main jconsole window opens. To view the current status of the FOO.BAR message queue, click on the MBeans tab and use the tree on the left hand side to drill down to org.apache.activemq/localhost/Queue/FOO.BAR. Click on the FOO.BAR icon to view the current status, as shown in Figure 3.2.

Figure 3.2. Monitoring the Status of the FOO.BAR Queue

Open a new command prompt and start a new telnet session for the consumer client, by entering the following command:

telnet

Enter the following telnet commands to connect to the Stomp socket on the broker:

telnet> set localecho
Local echo on
telnet> open localhost 61613

Start a Stomp session for the consumer by entering the following Stomp frame in the consumer’s telnet window:

CONNECT
login:foo
passcode:bar
 
^@

If all goes well, you will see a response similar to the following:

CONNECTED
session:ID:fboltond820-2290-1190810591249-3:1

Subscribe to the FOO.BAR queue by entering the following Stomp frame in the consumer’s telnet window:

SUBSCRIBE
destination:/queue/FOO.BAR
ack:client
 
^@

The ack header is set to the value client, which implies that the consumer client is expected to acknowledge each message it receives from the broker. After typing the terminating null character, ^@, the broker dispatches the sole message on the FOO.BAR queue by sending a MESSAGE frame, as follows:

MESSAGE
destination:/queue/FOO.BAR
receipt:
timestamp:1190811984837
priority:0
expires:0
message-id:ID:fboltond820-2290-1190810591249-3:0:-1:1:1
 
Hello, queue FOO.BAR

To see what effect this has on the queue status, go to the jconsole window and click Refresh on the MBeans tab. The DispatchCount attribute is now equal to 1, indicating that the broker has dispatched the message to the consumer. The DequeueCount is equal to 0, however; this is because the message is not considered to be dequeued until the consumer client sends an acknowledgement.

Acknowledge the received message by entering the following Stomp frame in the consumer’s telnet window:

ACK
message-id:ID:fboltond820-2290-1190810591249-3:0:-1:1:1
 
^@

Where the message ID must match the value from the message-id header in the received MESSAGE frame. To check that the acknowledgement has been effective, go back to the jconsole window and click Refresh on the MBeans tab. You should now find that the DequeueCount has increased to 1.

Unsubscribe from the FOO.BAR queue by entering the following Stomp frame in the consumer’s telnet window:

UNSUBSCRIBE
destination:/queue/FOO.BAR
receipt:
 
^@

To shut down both the producer and consumer gracefully, enter the following DISCONNECT frame in each of their respective telnet windows:

DISCONNECT
 
^@

The demonstration code required to run these examples is available only from the standalone Apache ActiveMQ package, which you must download and install in addition to Fuse ESB.

Fuse Message Broker provides some sample code in ActiveMQInstallDir/example/ruby that enables you to experiment with the Stomp protocol in the Ruby programming language.

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:

If you have not already done so, you also need to download and install the standalone Fuse Message Broker package from fusesource.com.

To try out the Stomp protocol, perform the following steps:

For full details of how to deploy a broker in the OSGi container, please read Deploying a JMS Broker in Deploying into the OSGi Container. If you have not already deployed a broker, you can create and deploy a new broker, broker1, by entering the following console command:

karaf@root> activemq:create-broker --name broker1

Check that the the Stomp connector is present in the broker configuration file (in InstallDir/deploy/broker1-broker.xml) as follows:

<beans>
  ...
  <transportConnectors>
    ...
    <transportConnector name="stomp"   uri="stomp://localhost:61613"/>
  </transportConnectors>
  ...
</beans>

To connect the listener tool to the stomp://localhost:61613 endpoint (Stomp over TCP), change directory to ActiveMQInstallDir/example/ruby and enter the following command:

ruby listener.rb

They Ruby listener connects to the endpoint, stomp://localhost:61613, by default. You could change this endpoint address by editing the listener.rb script.

To connect the publisher tool to the stomp://localhost:61613 endpoint (Stomp over TCP), change directory to ActiveMQInstallDir/example/ruby and enter the following command:

ruby publisher.rb

You should see some output like the following:

Sent 1000 messages
Sent 2000 messages
Sent 3000 messages
Sent 4000 messages
Sent 5000 messages
Sent 6000 messages
Sent 7000 messages
Sent 8000 messages
Sent 9000 messages
Sent 10000 messages
Received report: Received 10000 in 4.567 seconds, remaining: 9

The REST protocol is a simple HTTP-based protocol that enables you to contact the message broker through a Web browser. You can contact the message broker by navigating to appropriately formatted URLs or by posting HTML forms.

The Fuse Message Broker's REST protocol is based on a subset of the HTTP protocol. Hence, HTTP is the only supported transport.

REST supports the following client types:

The REST protocol is implemented by the following servlets running in a Web container:

Representational State Transfer (REST) is a software architecture designed for distributed systems, like the World Wide Web. For details of the REST architecture and the philosophy underlying it, see the REST Wikipedia article.

One of the key concepts of a RESTful architecture is that the interaction between different network nodes should take on a very simple form. In particular, the number of operations in a RESTful protocol must be kept small: for example, the REST protocol in Fuse requires just three operations.

In general, a REST interaction consists of the following elements:

HTTP is a good example of a protocol demonstrating RESTful design principles. In fact, proponents of REST argue that it is precisely the RESTful qualities of HTTP that enabled the rapid expansion of the World Wide Web. In keeping with REST principles, HTTP has a restricted operation set, consisting of only eight operations: GET, POST, PUT, DELETE, OPTIONS, HEAD, TRACE, and CONNECT.

For the purpose of implementing a RESTful protocol, the first four HTTP operations—GET, POST, PUT, and DELETE—are the most important. The semantics of these operations are described briefly in Table 4.1 .

The following servlets—which are automatically deployed in the message broker Web console—implement RESTful access to the Fuse message queues:

The RESTful Web service implemented by the Fuse message servlet enables you to enqueue and dequeue messages over HTTP. You can, therefore, use the message servlet to implement message producers and message consumers as Web forms.

To interact with the Fuse message servlet, construct a URL of the following form:

http://Host:Port/WebContext/message/DestinationPath?Opt1=Val1&Opt2=Val2...

Where the URL is constructed from the following parts:

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 .

<html>
<head>
  <title>Send a JMS Message</title>
  <link rel="stylesheet" href="style.css" type="text/css">
</head>
<body>
<h1>Send a JMS Message</h1>
<form action="message/FOO/BAR" method="post">
  <p>
    <label for="destination">Destination name</label>
    <input type="text" name="destination"/>
  </p>
  <p>
    <label for="type">Destination Type: </label>
    <select name="type">
      <option selected value="queue">Queue</option>
      <option type" value="topic">Topic</option>
   </select>
  </p>
  <p>
    <textarea name="body" rows="30" cols="80">
Enter some text here for the message body...
    </textarea>
  </p>
  <p>
    <input type="submit" value="Send"/>
    <input type="reset"/>
  </p>
</form>
</body>
</html>

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

To consume a message from a topic or queue, send a HTTP GET operation (for example, by following a hypertext link) using the URL format described in message servlet . For example, to consume a message from the FOO.BAR queue, navigate to the following URL:

http://localhost:8161/demo/message/FOO/BAR?timeout=10000&type=queue

To browse a queue using the queueBrowse servlet, simply navigate to an URL of the appropriate form, as described in queueBrowse servlet .

For example, to browse the FOO.BAR queue in XML format:

http://localhost:8161/demo/queueBrowse/FOO/BAR?view=xml

To browse the FOO.BAR queue as an Atom 1.0 feed:

http://localhost:8161/demo/queueBrowse/FOO/BAR?view=rss&feedType=atom_1.0

To browse the FOO.BAR queue as an RSS 1.0 feed:

http://localhost:8161/demo/queueBrowse/FOO/BAR?view=rss&feedType=rss_1.0

This section describes how to run the REST example, which consists of a servlet engine integral to the message broker binary, and some demonstration servlets that run as a Web application. To connect to the Web applications, you can use your favorite Web browser.

You must ensure that the message broker is configured to instantiate an embedded servlet engine. In your broker configuration file, conf/activemq.xml, check that there is a jetty element configured as shown in Example 4.2 .

<!-- Embedded servlet engine for serving up the Admin console
-->
<jetty xmlns="http://mortbay.com/schemas/jetty/1.0">
  <connectors>
    <nioConnector port="8161" />
  </connectors>
  <handlers>
    <webAppContext contextPath="/admin" 
      resourceBase="${activemq.base}/webapps/admin" 
      logUrlOnStart="true" />
    <webAppContext contextPath="/demo" 
      resourceBase="${activemq.base}/webapps/demo" 
      logUrlOnStart="true" />
  </handlers>
</jetty>

With the configuration shown in Example 4.2 , the servlet engine opens up a HTTP port on IP port, 8161. The following Web applications are loaded:

To run the REST Web example, perform the following steps:

To run the embedded servlet engine, open a new command window and enter the following command to start the default message broker:

activemq

This step assumes that your broker is configured as described in Example prerequisites.

Open your favorite Web browser (for example, Firefox or Internet Explorer) and navigate to the following URL:

http://localhost:8161/demo

Your browser should now show the welcome page for the Web examples, as shown in Figure 4.1.

Figure 4.1. Welcome Page for Web Examples

To view the form for publishing messages, click the link, Send a message. The Send a JMS Message form now appears in your browser, as shown in Figure 4.2.

Figure 4.2. The Send a JMS Message Form

Using the history feature of your browser, navigate back to the example welcome page (see Figure 4.1 ). The queueBrowse servlet supports a variety of ways to browse the contents of a queue and these are listed at the bottom of the welcome page. The following browsing options are listed:

If you click on Browse a queue, you should see a page like Figure 4.3 .

Figure 4.3. Default Option to Browse a Queue

If you click on Browse a queue as XML, you should see a page like Figure 4.4 .

Figure 4.4. Option to Browse a Queue as XML

If you click on Browse a queue as Atom, you should see a page like Figure 4.5 .

Figure 4.5. Option to Browse a Queue as Atom

If you click on Browse a queue as RSS 1.0 or Browse a queue as RSS 2.0, you should see a page like Figure 4.6 .

Figure 4.6. Option to Browse a Queue as 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).

In static failover a client is configured to use a failover IRU that lists the URIs of the broker connections the client can use. When establishing a connection, the client randomly chooses a URI from the list and attempts to establish a connection to it. If the connection does not succeed, the client chooses a new URI from the list and tries again. The client will continue cycling through the list until a connection attempt succeeds.

If a client's connection to a broker fails after it has been established, the client will attempt to reconnect to a different broker in the list. Once a connection to a new broker is established, the client will continue to use the new broker until the connection to the new broker is severed.

The failover protocol supports the transport options described in Table 6.1.

Example 6.1 shows a failover URI that can connect to one of two message brokers.

failover://(tcp://localhost:61616,tcp://remotehost:61616)?initialReconnectDelay=100

Dynamic failover combines the failover protocol and a network of brokers to allow a broker to supply its clients with a list of broker connections to which the clients can failover. Clients use a failover URI to connect to a broker and the broker dynamically updates the clients' list of available URIs. The broker updates its clients' failover lists with the URIs of the other brokers in its network of brokers that are currently running. As new brokers join, or exit, the cluster, the broker will adjust its clients' failover lists.

From a connectivity point of view, dynamic failover works the same as static failover. A client randomly chooses a URI from the list provided in its failover URI. Once that connection is established, the list of available brokers is updated. If the original connection fails, the client will randomly select a new URI from its dynamically generated list of brokers. If the new broker is configured for dynamic failover, the new broker will update the client's list.

To use dynamic failover you must configure both the clients and brokers used by your application. The following must be configured:

See Failover URI and Transport options for more information about using failover URIs.

Table 6.2 describes the broker-side properties that can be used to configure a failover cluster. These properties are attributes on the broker's transportConnector element.

Example 6.2 shows the configuration for a broker that participates in dynamic failover.

<beans ... >
  <broker>
    ...
    <networkConnectors>
      <networkConnector uri="multicast://default" />
    </networkConnectors>
    ...
    <transportConnectors>
      <transportConnector name="openwire"
          uri="tcp://0.0.0.0:61616"
         discoveryUri="multicast://default"
         updateClusterClients="true"
         updateClusterFilter="*A*,*B*" />  
    </transportConnectors>
    ...
  </broker>
</beans>

The configuration in Example 6.2 does the following:

Example 6.3 shows the URI for a client that uses the failover protocol to connect to the broker and its cluster.

failover://(tcp://0.0.0.0:61616)?initialReconnectDelay=100

The dynamic discovery protocol combines reconnect logic with the capability to auto-discover broker endpoints in the local network. The discovery protocol invokes a discovery agent in order to build up a list of broker URIs. The protocol then randomly chooses a URI from the list and attempts to establish a connection to it. If it does not succeed, or if it subsequently fails, a new connection is established to one of the other URIs in the list.

A discovery agent is a bootstrap mechanism that enables a message broker, consumer, or producer to obtain a list of broker URIs, where the URIs represent connector endpoints. The broker, consumer, or producer can subsequently connect to one of the URIs in the list.

The following kinds of discovery agent are currently supported in Fuse Message Broker:

For more details, see Discovery Agents.

Before you can use the discovery protocol, you must make your broker’s endpoints discoverable by adding a discovery agent to each transport connector. For example, to make a TCP transport connector discoverable, set the discoveryUri attribute on the transportConnector element as follows:

<transportConnectors>
  <transportConnector name="openwire"
    uri="tcp://localhost:61716"
    discoveryUri="multicast://default"/>
</transportConnectors>

Where the TCP transport connector is configured to use the multicast discovery agent, multicast://default.

A discovery URI must conform to the following syntax:

discovery://(DiscoveryAgentUri)?TransportOptions

Where the discovery agent URI, DiscoveryAgentUri, identifies a discovery agent, as described in Discovery agents above. The transport options, ?TransportOptions, are specified in the form of a query list (where the supported options are described in Table 7.1 ). If no transport options are required, you can use the following alternative syntax:

discovery://DiscoveryAgentUri

The discovery protocol supports the transport options described in Table 7.1

The following is an example of a discovery URI that uses a multicast discovery agent:

discovery://(multicast://default)?initialReconnectDelay=100

The list of transport options, TransportOptions, in the discovery URI can also be used to set options on the discovered transports. If you set an option not listed in Table 7.1, the URI parser attempts to inject the option setting into every one of the discovered endpoints.

For example, if you set the TCP connectionTimeout option to 10 seconds, as follows:

discovery://(multicast://default)?connectionTimeout=10000

The 10 second timeout setting is injected into every discovered TCP endpoint.

A discovery agent is a bootstrap mechanism that enables a client or message broker to discover other broker instances on a network. A discover agent URI is used on the client side and on the broker side, as follows:

Since a discovery agent is not a transport protocol, you cannot use a discovery agent URI directly on the client side. To use a discovery agent on the client side, embed the agent URI,DiscoveryAgentUri, inside a discovery URL, as follows:

discovery://(DiscoveryAgentUri)?TransportOptions

The client recognizes the discovery URL as a transport. It first obtains a list of available endpoint URLs using the specified discovery agent and then connects to one of the discovered URLs. For more details about the discovery protocol, see Dynamic Discovery Protocol .

For certain kinds of discovery agent (for example, multicast or zeroconf), 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, edit the relevant transportConnector element as follows:

<transportConnectors>
  <transportConnector name="openwire"
    uri="tcp://localhost:61716"
    discoveryUri="multicast://default"/>
</transportConnectors>

Where the discoveryUri attribute on the transportConnector element is initialized to multicast://default. You can associate multiple endpoints with the same discovery agent. For example, to configure both an Openwire endpoint and a Stomp endpoint to use the multicast://default discovery agent:

<transportConnectors>
  <transportConnector name="openwire"
    uri="tcp://localhost:61716"
    discoveryUri="multicast://default"/>
  <transportConnector name="stomp"
    uri="stomp://localhost:61613"
    discoveryUri="multicast://default"/>
</transportConnectors>

Fuse Message Broker currently supports the following discovery agents:

The simple (static) discovery agent provides an explicit list of broker URLs for a client to connect to. For example:

simple://(tcp://localhost:61716,tcp://localhost:61816)

In general, the URI for a simple discovery agent must conform to the following syntax:

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

Or equivalently:

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

The two prefixes, simple: and static:, are exactly equivalent. In order to use the agent URI, it must be embedded inside a discovery URL—for example:

discovery://(static://(tcp://localhost:61716,tcp://localhost:61816))

This discovery agent is only used on the client side. No extra configuration is required in the broker.

The multicast discovery agent uses the IP multicast protocol to find any message brokers currently active on the local network. In order for the protocol to work, a multicast discovery agent must be enabled on each broker you want to advertise and messaging clients must be configured to use a discovery URI.

The URI for a multicast discovery agent must conform to the following syntax:

multicast://GroupID

Where the GroupID is an alphanumeric identifier. All participants in the same discovery network must use the same GroupID. For example, the Fuse Message Broker is usually configured to use the URI, multicast://default.

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 Message Broker 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. To enable the protocol, a multicast discovery agent must be configured on each broker you want to advertise and messaging clients must be configured to use a discovery URI.

The URI for a zeroconf discovery agent must conform to the following syntax:

zeroconf://GroupID

Where the GroupID is an alphanumeric identifier. All participants in the same discovery network must use the same GroupID.

For example, to use a zeroconf discovery agent on the client side, where the client needs to connect to the groupA group, you would construct a discovery URL like the following:

discovery://(zeroconf://groupA)