Connectivity Guide

Fuse Message BrokerClient Connectivity Guide

Version 5.5September 2011

The experts in open source integration and messaging

Legal Notices

Progress Software Corporation and/or its subsidiaries may have patents, patent applications, trademarks, copyrights, or otherintellectual property rights covering subject matter in this publication. Except as expressly provided in any written license agreementfrom Progress Software Corporation, the furnishing of this publication does not give you any license to these patents, trademarks,copyrights, or other intellectual property. Any rights not expressly granted herein are reserved.

Progress, IONA, IONA Technologies, the IONA logo, Orbix, High Performance Integration, Artix;, Fuse, and Making SoftwareWork Together are trademarks or registered trademarks of Progress Software Corporation and/or its subsidiaries in the US andother countries.

Java and J2EE are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.CORBA is a trademark or registered trademark of the Object Management Group, Inc. in the US and other countries. All othertrademarks that appear herein are the property of their respective owners.

While the information in this publication is believed to be accurate Progress Software Corporation makes no warranty of any kindto this material including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.Progress Software Corporation shall not be liable for errors contained herein, or for incidental or consequential damages inconnection with the furnishing, performance or use of this material.

All products or services mentioned in this manual are covered by the trademarks, service marks, or product names as designatedby the companies who market those products.

No part of this publication may be reproduced, stored in a retrieval system or transmitted, in any form or by any means,photocopying, recording or otherwise, without prior written consent of Progress Software Corporation. No third-party intellectualproperty right liability is assumed with respect to the use of the information contained herein. Progress Software Corporationassumes no responsibility for errors or omissions contained in this publication. This publication and features described hereinare subject to change without notice. Portions of this document may include Apache Foundation documentation, all rights reserved.

Table of Contents1. Protocol Summary ............................................................................................................... 9

Simple Connections ........................................................................................................ 10Discovery Protocols ........................................................................................................ 12Peer-to-Peer Protocols ..................................................................................................... 14

2. OpenWire Protocol ............................................................................................................. 15Introduction to the OpenWire Protocol ................................................................................. 16OpenWire Example ......................................................................................................... 19

3. Stomp Protocol ................................................................................................................. 23Introduction to the Stomp Protocol ..................................................................................... 24Protocol Details ............................................................................................................. 25Stomp Tutorial .............................................................................................................. 33Stomp Example ............................................................................................................. 40

4. REST Protocols ................................................................................................................. 43Introduction to the REST Protocol ...................................................................................... 44Protocol Details ............................................................................................................. 45REST Example .............................................................................................................. 52

5. VM Transport .................................................................................................................... 616. Failover Protocol ................................................................................................................ 67

Static Failover ............................................................................................................... 68Dynamic Failover ........................................................................................................... 70

7. Discovery Protocols ............................................................................................................ 73Dynamic Discovery Protocol ............................................................................................. 74Discovery Agents ........................................................................................................... 76

8. Fanout Protocol ................................................................................................................. 819. Peer-to-Peer Protocols ........................................................................................................ 85

Peer Protocol ................................................................................................................ 86Peer Example ................................................................................................................ 89

A. Transport Options .............................................................................................................. 91TCP and NIO Transports .................................................................................................. 92SSL Transport ............................................................................................................... 95UDP Transport .............................................................................................................. 97Wire Format Options ....................................................................................................... 98

Index .................................................................................................................................. 99

5Fuse Message Broker Client Connectivity Guide Version 5.5

List of Figures3.1. Connecting to the ActiveMQ JMX Port .................................................................................... 363.2. Monitoring the Status of the FOO.BAR Queue .......................................................................... 374.1. Welcome Page for Web Examples ......................................................................................... 544.2. The Send a JMS Message Form ........................................................................................... 554.3. Default Option to Browse a Queue ........................................................................................ 564.4. Option to Browse a Queue as XML ........................................................................................ 574.5. Option to Browse a Queue as Atom ....................................................................................... 584.6. Option to Browse a Queue as RSS 1.0 ................................................................................... 595.1. Clients Connected through the VM Transport ........................................................................... 619.1. Peer Protocol Endpoints with Embedded Brokers ...................................................................... 86

Fuse Message Broker Client Connectivity Guide Version 5.56

List of Tables1.1. Protocols for Simple Connections .......................................................................................... 101.2. Summary of Discovery Protocols .......................................................................................... 121.3. Summary of Peer-to-Peer Protocols ....................................................................................... 142.1. Transport Protocols Supported by OpenWire ............................................................................ 162.2. Transport Options Supported by OpenWire Protocol ................................................................... 173.1. Transport Protocols Supported by Stomp ................................................................................ 243.2. Client Commands for the Stomp Protocol ................................................................................ 263.3. Server Commands for the Stomp Protocol ............................................................................... 314.1. HTTP RESTful Operations ................................................................................................... 464.2. URL Options Recognized by the Message Servlet ...................................................................... 474.3. Message Servlet RESTful HTTP Operations ............................................................................. 474.4. URL Options Recognized by the QueueBrowse Servlet ............................................................... 484.5. Form Properties Recognized by Message Servlet ....................................................................... 505.1. VM Transport Broker Configuration Options ............................................................................. 635.2. VM Transport Options ........................................................................................................ 645.3. Broker Options ................................................................................................................. 656.1. Failover Transport Options .................................................................................................. 686.2. Broker-side Failover Properties ............................................................................................. 717.1. Discovery Transport Options ................................................................................................ 758.1. Fanout Protocol Options ..................................................................................................... 829.1. Broker Options ................................................................................................................. 87A.1. TCP and NIO Transport Options ........................................................................................... 93A.2. SSL Transport Options ....................................................................................................... 95A.3. SSL Transport Options ....................................................................................................... 97A.4. Transport Options Supported by OpenWire Protocol ................................................................... 98

List of Examples4.1. Web Form for Sending a Message to a Queue or Topic ............................................................... 494.2. Configuration of an Embedded Servlet Engine .......................................................................... 525.1. Simple VM URI Syntax ...................................................................................................... 625.2. Basic VM URI ................................................................................................................. 635.3. Simple URI with broker options ............................................................................................ 635.4. Advanced VM URI Syntax ................................................................................................... 645.5. Advanced VM URI ............................................................................................................ 646.1. Simple Failover URI .......................................................................................................... 696.2. Broker for Dynamic Failover ................................................................................................ 716.3. Failover URI for Connecting to a Failover Cluster ....................................................................... 72

Chapter 1. Protocol SummaryFuse Message Broker supports a wide variety of protocols for client-to-broker, broker-to-broker, and client-to-clientconnections. The intention is that the variety of protocols will make it easier to connect to a range of client types.Different network topologies can also be supported with the help of special protocols, such as discovery andpeer-to-peer.

Simple Connections ................................................................................................................ 10Discovery Protocols ................................................................................................................ 12Peer-to-Peer Protocols ............................................................................................................. 14

Simple Connections

Overview The following protocols can be used either for straightforward client-to-brokerconnections (transport connector) or broker-to-broker connections (networkconnector). 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 wireprotocol/transport protocol combinations.

Protocols for simple connections Table 1.1 on page 10 shows the protocol combinations that messagingclients can use to connect directly to the message broker.

Table 1.1. Protocols for Simple Connections

DescriptionSample URLTransportProtocol

WireProtocol

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

tcp://Host:PortTCPOpenWire

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

Same as tcp, except that the New I/O (NIO)1 Java API is

used, which provides better performance in some scenarios.

nio://Host:PortTCPOpenWire

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

ssl://Host:PortSSLOpenWire

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

http://Host:PortHTTPOpenWire

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

https://Host:PortHTTPSOpenWire

1 http://en.wikipedia.org/wiki/New_I/O

Chapter 1. Protocol Summary

DescriptionSample URLTransportProtocol

WireProtocol

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

stomp://Host:PortTCPStomp

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

stomp+ssl://Host:PortSSLStomp

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

http://Host:Port/

demo/message/FOO/BAR

?timeout=10000

&type=queue

HTTPREST

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

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

http://Host:Port/

demo/message/FOO/BAR

HTTPSRESTs

?timeout=10000

&type=queue

Configure the transport connector in a message broker toaccept XMPP connections on Host:Port (for example, from

an Instant Messaging client).

xmpp://Host:PortTCPXMPP

Configure clients to connect to a broker embedded withinthe same Java Virtual Machine (JVM). The BrokerName is

the broker name of the embedded broker.

vm://BrokerNameN/AVM

Simple Connections

Discovery Protocols

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

1. Obtain a list of available broker endpoints (represented by URIs).

2. Connect to one or more endpoints from the discovered list, according tosome selection algorithm.

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

Summary of discovery protocols Table 1.2 on page 12 describes the discovery protocols that clients can use.

Table 1.2. Summary of Discovery Protocols

DescriptionSample URLProtocol

Configure clients to connect to one ofthe broker endpoints from the URI list,

failover://(uri1,...,uriN)?TransportOptionsFailover

uri1,...,uriN. The transport options,

?TransportOptions, are specified in

the form of a query list. If no transportoptions are required, you can omit theparentheses and the question mark, ?.

Configure clients to connect to one ofthe broker endpoints from a URI list that

discovery://(DiscoveryAgentUri)?TransportOptionsDiscovery

is dynamically discovered at runtime,using a discovery agent. The discoveryagent URI, DiscoveryAgentUri, is

normally a multicast discoveryagent—for example,multicast://default.

Configure clients to connect to all of thebroker endpoints from a dynamicallydiscovered URI list.

fanout://(DiscoveryAgentUri)?TransportOptionsFanout

Discovery agents The discovery protocol supports a number of discovery agents, which are alsospecified in the form of a URI. For details of the supported discovery agents,see "Discovery Agents" on page 76 .

NoteAlthough discovery agent URIs look superficially like transport URIs,they are not the same thing. A discovery agent URI can only be usedin certain contexts and cannot be used directly in place of a transportURI.

Discovery Protocols

Peer-to-Peer Protocols

Overview Peer-to-peer protocols enable messaging clients to communicate with eachother directly, eliminating the requirement to route messages through anexternal message broker.

Summary of peer-to-peerprotocols

Table 1.3 on page 14 describes the peer-to-peer protocols that clients canuse.

Table 1.3. Summary of Peer-to-Peer Protocols

Configure clients to connect to their peers in the groupwith the group name, PeerGroup. The BrokerName

peer://PeerGroup/BrokerName?BrokerOptionsPeer

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 protocol supports a variety of broker options. For details, see thebroker options listed in Table 9.1 on page 87 .

Chapter 2. OpenWire ProtocolThe OpenWire protocol is the default on-the-wire protocol for Fuse Message Broker. This chapter provides a briefintroduction to the protocol, illustrating how to use OpenWire with a variety of transport protocols.

Introduction to the OpenWire Protocol ......................................................................................... 16OpenWire Example ................................................................................................................. 19

Introduction to the OpenWire Protocol

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

Transport protocols Table 2.1 on page 16 shows the transport protocols supported by theOpenWire wire protocol:

Table 2.1. Transport Protocols Supported by OpenWire

DescriptionURLTransportProtocol

Endpoint URL for OpenWire over TCP/IP. The broker listens for TCPconnections on the host machine, Host, and IP port, Port.

tcp://Host:PortTCP

Same as tcp, except that the New I/O (NIO)1 Java API is used, which

provides better performance in some scenarios.

nio://Host:PortTCP

(Java clients only) Endpoint URL for OpenWire over TCP/IP, where thesocket layer is secured using SSL (or TLS).

ssl://Host:PortSSL

For details of how to configure an SSL connection, see Security Guide.

(Java clients only) Endpoint URL for OpenWire over HTTP.http://Host:PortHTTP

(Java clients only) Endpoint URL for OpenWire over HTTP, where thesocket layer is secured by SSL (or TLS).

https://Host:PortHTTPS

For details of how to configure a HTTPS connection, see Security Guide.

Transport options OpenWire supports a number of transport options, which can be set as queryoptions on the transport URL. For example, to specify that error messagesshould omit the stack trace, use a URL like the following:

tcp://localhost:61616?wireformat.stackTraceEnabled=false

Chapter 2. OpenWire Protocol

Where the wireformat.stackTraceEnabled property is set to false todisable the inclusion of stack traces in error messages. Table 2.2 on page 17gives the complete list of transport options for OpenWire.

Table 2.2. Transport Options Supported by OpenWire Protocol

Negotiation policyDescriptionDefaultProperty

Set to false if eitherside is false.

Should the stack trace of an exceptionoccuring on the broker be sent to theclient?

truewireformat .stackTraceEnabled

Provides a hint to the peer that TCPnodelay should be enabled on thecommunications Socket.

falsewireformat .tcpNoDelayEnabled

Should commonly repeated values becached so that less marshalling occurs?

truewireformat .cacheEnabled

Use the smaller of thetwo values.

If cacheEnabled is true, this propertyspecifies the maximum number ofvalues to cache.

1024wireformat .cacheSize

Should wire size be optimized overCPU usage?

truewireformat .tightEncodingEnabled

Set to true if bothsides are true.

Should the size of the packet beprefixed before each packet ismarshalled?

truewireformat .prefixPacketSize

Use the smaller of thetwo values.

The maximum inactivity duration(before which the socket is considered

30000wireformat .maxInactivityDuration

dead) in milliseconds. On someplatforms it can take a long time for asocket to appear to die, so we allowthe broker to kill connections if theyare inactive for a period of time. Set toa value <= 0 to disable inactivitymonitoring.

wireformat

.maxInactivityDurationInitalDelay

Supported clients Fuse Message Broker currently supports the following client types for theOpenWire protocol:

• Java clients—the Java API conforms fully to the JMS specification.

Introduction to 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 ActiveMQ2 project:

• C++ clients—for C++ clients, Apache ActiveMQ provides the CMS (C++Messaging Service) API, which is closely modelled on the JMS specification.Only the TCP transport is supported for C++ clients.

2 http://activemq.apache.org/

OpenWire Example

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

NoteThe secure socket protocols—OpenWire over SSL, and OpenWireover HTTPS—are discussed in Security Guide.

Example prerequisites To run these examples, you require:

• Apache Ant3 build tool, version 1.6 or later.

Location of sample clients The OpenWire examples depend on the sample producer and consumer clientslocated in the following directory:

ActiveMQInstallDir/fuse-message-broker-Version/example

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

1. "Configure the broker" .

2. "Run the broker" .

3. "Run the consumer" .

4. "Run the producer with the TCP protocol" .

3 http://ant.apache.org/

OpenWire Example

5. "Run the producer with the HTTP protocol" .

Configure the broker Add a HTTP transport connector by editing the broker configuration file (inInstallDir/conf/activemq.xml) as follows:

</transportConnectors>...

</beans>

Run the broker Run the default broker by entering the following at a command line:

activemq

The default broker automatically takes its configuration from the defaultconfiguration file.

NoteThe activemq script automatically sets the ACTIVEMQ_HOME andACTIVEMQ_BASE environment variables toFuseInstallDir/fuse-message-broker-Version by default. Ifyou want the activemq script to pick up its configuration from anon-default conf directory, you can set ACTIVEMQ_BASE explicitlyin your environment. The configuration files will then be taken from$ACTIVEMQ_BASE/conf.

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

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

You should see some output like the following:

Buildfile: build.xmlinit:

compile:consumer:

[echo] Running consumer against server at $url = tcp://localhost:61616for 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)

thenwe will shutdown

Run the producer with the TCPprotocol

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

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

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

[java] Received: Message: 0 sent at: Wed Sep 19 14:38:06 BST2007 ...

Run the producer with the HTTPprotocol

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

OpenWire Example

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

This command sends ten new messages to the consumer client.

NoteThe JAR files for the HTTP protocol are currently located in thelib/optional subdirectory. If you construct the CLASSPATHmanually, you must be sure to include the JAR files from thissubdirectory.

Chapter 3. Stomp ProtocolThe Stomp protocol is a simplified messaging protocol that is specially designed for implementing clients usingscripting languages. This chapter provides a brief introduction to the protocol.

Introduction to the Stomp Protocol ............................................................................................. 24Protocol Details ..................................................................................................................... 25Stomp Tutorial ...................................................................................................................... 33Stomp Example ..................................................................................................................... 40

Introduction to the Stomp Protocol

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

Transport protocols Table 3.1 on page 24 shows the transport protocols supported by the Stompwire protocol:

Table 3.1. Transport Protocols Supported by Stomp

DescriptionURLTransport Protocol

Endpoint URL for Stomp over TCP/IP. The broker listens for TCPconnections on the host machine, Host, and IP port, Port.

stomp://Host:PortTCP

Endpoint URL for secure Stomp over SSL. The broker listens forTCP connections on the host machine, Host, and IP port, Port.

stomp+ssl://Host:PortSSL

Supported clients Stomp currently supports the following client types:

• C clients.

• C++ clients.

• C# and .NET clients.

• .NET clients.

• Delphi clients.

• Flash clients.

• Perl clients.

• PHP clients.

• Pike clients.

• Python clients.

Chapter 3. Stomp Protocol

Protocol Details

Overview This section describes the format of Stomp data packets , as well as thesemantics of the data packet exchanges. Stomp is a relatively simple wireprotocol—it is even possible to communicate manually with a Stomp brokerusing a telnet client (see "Stomp Tutorial" on page 33 ).

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

Licence The Stomp specification is licensed under the Creative Commons Attributionv2.51

Stomp frame format The Stomp specification defines the term frame to refer to the data packetstransmitted over a Stomp connection. A Stomp frame has the following generalformat:

<FrameBody>^@

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

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

1 http://creativecommons.org/licenses/by/2.5/

Protocol Details

• CONNECT command—after a client sends a CONNECT frame, it expects the

server to reply with a CONNECTED frame.

• Commands with a receipt header—a client can force the server to

acknowledge receipt of a command by adding a receipt header to the

outgoing frame.

• Erroneous commands—if a client sends a frame that is malformed, orotherwise in error, the server may reply with an ERROR frame. Note,

however, that the ERROR frame is not formally correlated with the original

frame that caused the error (Stomp frames are not required to include aunique identifier).

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

SENDdestination:/queue/areceipt:message-12345

Hello a!^@

Client commands Table 3.2 on page 26 lists the client commands for the Stomp protocol. TheReply column indicates whether or not the server sends a reply frame bydefault.

Table 3.2. Client Commands for the Stomp Protocol

DescriptionRoleReply?Command

Open a connection to a Stomp broker (server).Producer, ConsumerYes"CONNECT"

Send a message to a particular queue or topic on the server.ProducerNo"SEND"

Subscribe to a particular queue or topic on the server.ConsumerNo"SUBSCRIBE"

Cancel a subscription to a particular queue or topic.ConsumerNo"UNSUBSCRIBE"

Acknowledge receipt of one message.ConsumerNo"ACK"

DescriptionRoleReply?Command

Start a transaction (applies to SEND or ACK commands).Producer, ConsumerNo"BEGIN"

Commit a transaction.Producer, ConsumerNo"COMMIT"

Roll back a transaction.Producer, ConsumerNo"ABORT"

Shut down the existing connection gracefully.Producer, ConsumerNo"DISCONNECT"

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

CONNECTlogin: <username>passcode:<passcode>

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

CONNECTEDsession: <session-id>

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

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

SENDdestination:/queue/ahello queue a

Protocol Details

From the client’s perspective, the destination name, /queue/a, is an arbitrarystring. 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 aremapped to some form of destination on the server; how the server translatesthese strings is up to the implementation.

The SEND command also supports the following optional headers:

• transaction—specifies the transaction ID. Include this header, if the

SEND command partakes in a transaction (see "BEGIN" on page 30 ).

• content-length—specifies the byte count for the length of the message

body. If a content-length header is included, this number of bytes should

be read, regardless of whether or not there are null characters in the body.The frame still needs to be terminated with a null byte and if acontent-length is not specified, the first null byte encountered signals theend of the frame.

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

SUBSCRIBEdestination: /queue/fooack: client

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

The SUBSCRIBE command supports the following optional headers:

• ack—specify the acknowledgement mode for this subscription. The following

modes are recognized:

• auto—messages are considered delivered as soon as the server delivers

them to the client (in the form of a MESSAGE command). The server does

not expect to receive any ACK commands from the client for this

subscription.

• client—messages are considered delivered only after the client

specifically acknowledges them with an ACK frame.

• selector—specifies a SQL 92 selector on the message headers, which

acts as a filter for content based routing.

• id—specify an ID to identify this subscription. Later, you can use the ID

to UNSUBSCRIBE from this subscription (you may end up with overlapping

subscriptions, if multiple selectors match the same destination).

When an id header is supplied, the server should append a subscriptionheader to any MESSAGE commands sent to the client. When using wildcardsand selectors, this enables clients to figure out which subscription triggeredthe message.

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

UNSUBSCRIBEdestination: /queue/a

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

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

Protocol Details

ACKmessage-id: <message-identifier>transaction: <transaction-identifier>

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

BEGINtransaction: <transaction-identifier>

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

COMMIT The COMMIT command commits a specific transaction.

COMMITtransaction: <transaction-identifier>

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

ABORT The ABORT command rolls back a specific transaction.

ABORTtransaction: <transaction-identifier>

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

DISCONNECT The DISCONNECT command disconnects gracefully from the server.

DISCONNECT

Server commands Table 3.3 on page 31 lists the commands that the server can send to aStomp client. These commands all have oneway semantics.

Table 3.3. Server Commands for the Stomp Protocol

DescriptionCommand

Send a message to the client, where the client has previously registered a subscription with theserver.

"MESSAGE"

Acknowledges receipt of a client command, if the client requested a receipt by included areceipt-id header.

"RECEIPT"

Error message sent from the server to the client."ERROR"

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

MESSAGEdestination:/queue/amessage-id: <message-identifier>

hello queue a^@

The MESSAGE command supports the following optional headers:

be read, regardless of whether or not there are null characters in the body.The frame still needs to be terminated with a null byte and if a

Protocol Details

content-length is not specified, the first null byte encountered signals theend of the frame.

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

RECEIPTreceipt-id:message-12345

The receipt body is always empty.

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

ERRORmessage: malformed packet received

The message:-----MESSAGEdestined:/queue/aHello queue a!-----Did not contain a destination header, which is required formessagepropagation.^@

The ERROR command supports the following optional headers:

be read, regardless of whether or not there are null characters in the body.The frame still needs to be terminated with a null byte and if acontent-length is not specified, the first null byte encountered signals theend of the frame.

Stomp Tutorial

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

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

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

1. Enable NumLock on the numeric keypad (this is essential).

2. While holding down the Alt key, type zero, 0, four times in succession on

the numeric keypad.

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

1. "Start the broker" .

2. "Start a telnet session for the producer" .

3. "Start a Stomp session for the producer" .

4. "Send a message to a queue" .

5. "Check the queue status using JMX" .

6. "Start a telnet session for the consumer" .

7. "Start a Stomp session for the consumer" .

8. "Subscribe to a queue" .

9. "Acknowledge a message" .

10. "Unsubscribe from the queue" .

Stomp Tutorial

11. "Disconnect the clients" .

Start the broker Start the default broker by entering the following at a command prompt:

activemq

Normally, the default broker is configured to initialize a Stomp connector thatlistens 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 configureit—see "Configure the broker" on page 41 for details.

Start a telnet session for theproducer

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

telnet

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

telnet> set localechoLocal echo ontelnet> open localhost 61613

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

Start a Stomp session for theproducer

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

CONNECTlogin:foopasscode:bar

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

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

CONNECTEDsession:ID:fboltond820-2290-1190810591249-3:0

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

SENDdestination:/queue/FOO.BARreceipt:

Hello, queue FOO.BAR^@

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

RECEIPTreceipt-id:

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

Check the queue status usingJMX

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

jconsole

The jconsole utility is a standard JMX client that is included with Sun’sJava Development Kit (JDK). When you start the jconsole utility, a dialogappears and prompts you to connect to a JMX process, as shown inFigure 3.1 on page 36.

Stomp Tutorial

Figure 3.1. Connecting to the ActiveMQ JMX Port

Select the ActiveMQ broker process and click Connect. The main jconsolewindow 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 downto org.apache.activemq/localhost/Queue/FOO.BAR. Click on theFOO.BAR icon to view the current status, as shown in Figure 3.2 on page 37.

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

The status shows an EnqueueCount of 1, which tells you that the producerhas successfully enqueued one message in the FOO.BAR queue.

Start a telnet session for theconsumer

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

telnet

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

telnet> set localechoLocal echo ontelnet> open localhost 61613

Start a Stomp session for theconsumer

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

CONNECTlogin:foopasscode:bar

Stomp Tutorial

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

CONNECTEDsession:ID:fboltond820-2290-1190810591249-3:1

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

SUBSCRIBEdestination:/queue/FOO.BARack:client

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

MESSAGEdestination:/queue/FOO.BARreceipt:timestamp:1190811984837priority:0expires:0message-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 windowand click Refresh on the MBeans tab. The DispatchCount attribute is nowequal to 1, indicating that the broker has dispatched the message to theconsumer. The DequeueCount is equal to 0, however; this is because themessage is not considered to be dequeued until the consumer client sendsan acknowledgement.

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

ACKmessage-id:ID:fboltond820-2290-1190810591249-3:0:-1:1:1

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

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

UNSUBSCRIBEdestination:/queue/FOO.BARreceipt:

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

DISCONNECT

Stomp Tutorial

Stomp Example

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

Example prerequisites You must download and install the requisite packages to support the Rubyprogramming language before you can run the Stomp example. Install thefollowing packages:

• Ruby programming language—download and install the Ruby programminglanguage from http://www.ruby-lang.org/en/downloads. Add the Ruby /bin

directory to your PATH.

• RubyGems package manager—RubyGems (http://www.rubygems.org) isa utility for installing and managing add-ons to the Ruby language.Download and install RubyGems as follows:

1. Download a RubyGems archive file (.tgz, .zip, or .gem) from the

RubyForge (http://rubyforge.org/frs/?group_id=126).

2. Unzip the RubyGems archive.

3. Initialize RubyGems by entering the following command:

ruby GemsInstallDir/setup.rb

4. Add GemsInstallDir/bin to your PATH.

• Stomp package for Ruby—install the Stomp package for Ruby by runningthe following command:

gem install stomp

RubyGems downloads and installs the requisite package to support theRuby Stomp client API.

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

1. "Configure the broker" .

2. "Run the broker" .

3. "Run the Ruby listener" .

4. "Run the Ruby publisher" .

Configure the broker Check that the the Stomp connector is present in the broker configuration file(in InstallDir/conf/activemq.xml) as follows:

</beans>

Run the broker Run the default broker by entering the following at a command line:

activemq

The default broker automatically takes its configuration from the defaultconfiguration file.

NoteThe activemq script automatically sets the ACTIVEMQ_HOME andACTIVEMQ_BASE environment variables toFuseInstallDir/fuse-message-broker-Version by default. Ifyou want the activemq script to pick up its configuration from anon-default conf directory, you can set ACTIVEMQ_BASE explicitlyin your environment. The configuration files will then be taken from$ACTIVEMQ_BASE/conf.

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

Stomp Example

ruby listener.rb

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

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

ruby publisher.rb

You should see some output like the following:

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

Chapter 4. REST ProtocolsThe REST protocol is a simple HTTP-based protocol that enables you to interact with the message broker usingHTML forms and DHTML scripts. This chapter provides a brief introduction to the protocol, illustrating how tocontact the message broker from a Web browser.

Introduction to the REST Protocol .............................................................................................. 44Protocol Details ..................................................................................................................... 45REST Example ...................................................................................................................... 52

Introduction to the REST Protocol

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

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

Supported clients REST supports the following client types:

• Web forms—use conventional HTML forms to POST a message to a

destination (queue or topic) or to GET a message from a destination—see

"Example of posting a message" on page 49 .

• Ajax clients—an Asynchronous JavaScript And Xml (Ajax) library thatenables you to communicate with a REST endpoint using JavaScript in aDHTML Web page.

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

• message servlet—supports the sending and consuming of messages.

• queueBrowse servlet—enables you to view the current status of a particular

queue.

Chapter 4. REST Protocols

Protocol Details

What is REST? Representational State Transfer (REST) is a software architecture designedfor distributed systems, like the World Wide Web. For details of the RESTarchitecture and the philosophy underlying it, see the REST Wikipedia1 article.

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

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

• Operation—belongs to a restricted, well-known set of operations—forexample, in the HTTP protocol, the main operations are GET, POST, PUT,

and DELETE. The advantage of this approach is that, in contrast to RPC

architectures, there is no need to define interfaces for a RESTful protocol.The operations are all known in advance.

• URI—identifies the resource that the operation acts on. For example, aHTTP GET operation acts on the URI by fetching data from the resource

identified by the URI.

• Data (if required)—needed for operations that send data to the remoteresource.

HTTP as a RESTful protocol 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 ofHTTP that enabled the rapid expansion of the World Wide Web. In keepingwith REST principles, HTTP has a restricted operation set, consisting of onlyeight operations: GET, POST, PUT, DELETE, OPTIONS, HEAD, TRACE, andCONNECT.

For the purpose of implementing a RESTful protocol, the first four HTTPoperations—GET, POST, PUT, and DELETE—are the most important. Thesemantics of these operations are described briefly in Table 4.1 on page 46.

1 http://en.wikipedia.org/wiki/Representational_State_Transfer#REST.27s_Central_Principle:_Resources

Protocol Details

Table 4.1. HTTP RESTful Operations

DescriptionOperation

Fetch the remote resource identified by the URI.GET

Add/append/insert data to the remote resource identified by theURI.

Replace the remote resource identified by the URI with the datafrom this operation.

Delete the remote resource identified by the URI.DELETE

This simple set of operations—analogous to the classic CRUD (Create,Replace, Update, and Delete) operations for a database—turns out to beremarkably powerful and flexible.

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

• "message servlet"

• "queueBrowse servlet"

message servlet The RESTful Web service implemented by the Fuse message servlet enablesyou to enqueue and dequeue messages over HTTP. You can, therefore, usethe message servlet to implement message producers and message consumersas Web forms.

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

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

Where the URL is constructed from the following parts:

• Host:Port—the host and port of the servlet engine. For example, in the

default message broker configuration, a HTTP port is opened onlocalhost:8161.

• WebContext—in a Web application, it is usual to group related components

(servlets and so on) under a particular Web context, WebContext. For

example, for the REST demonstration servlets, the Web context is demo by

default.

• message—routes this URL to the message servlet.

• DestinationPath—specifies the compound name of a queue or topic in

the message broker. For example, the FOO.BAR queue has the destination

path, FOO/BAR.

• ?Opt1=Val1&Opt2=Val2—you can add some options in order to qualify

how the URL is processed.

For example, the following URL can be used to fetch a message from theFOO.BAR queue, where the Web console has the default configuration:

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

Table 4.2 on page 47 shows the URL options recognized by the messageservlet:

Table 4.2. URL Options Recognized by the Message Servlet

DescriptionURL Option

Can be either queue or topic.type

When consuming a message from a queue, specifies the lengthof time (in units of milliseconds) the client is prepared to wait.

timeout

Three HTTP operations—GET, POST, and DELETE—are recognized by themessage servlet. The semantics of these operations are described briefly inTable 4.3 on page 47 .

Table 4.3. Message Servlet RESTful HTTP Operations

DescriptionOperation

Consume a single message from the destination (queue or topic)specified by the URL.

Send a single message to the destination (queue or topic) specifiedby the URL.

Consume a single message from the destination (queue or topic)specified by the URL. This operation has the same effect as GET.

DELETE

Protocol Details

For details of the form properties recognized by the message servlet (forPOSTing a message), see "Example of posting a message" on page 49 .

queueBrowse servlet The RESTful Web service implemented by the queueBrowse servlet enablesyou to monitor the contents and status of any queue or topic in the Webconsole. Effectively, the queueBrowse servlet is a simple management tool.

To interact with the Fuse queueBrowse servlet, construct a URL of thefollowing 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" on page 46 ), except that the queueBrowse URL is builtfrom 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 on page 48 shows the URL options recognized by the queueBrowseservlet:

Table 4.4. URL Options Recognized by the QueueBrowse Servlet

Specifies the format for viewing the queue/topic. The followingviews are supported:

• simple—(default) displays a compact summary of the

queue in XML format, where each message is shown as amessage element with ID.

• xml—displays a detailed summary of the queue in XML

format, where each message is shown in full.

• rss—displays a compact summary of the queue in the

form of an RSS 1.0, 2.0 or Atom 0.3 feed. You canconfigure the type of feed using feedType.

In combination with the setting, view=rss, you can use thisoption to specify one of the following feeds:

feedType

• rss_1.0

• rss_2.0

• atom_0.3

Override the MIME content type of the view.contentType

The maximum number of messages to render.maxMessages

Example of posting a message Example 4.1 on page 49 shows an example of the Web form used to senda message to the FOO.BAR queue in the Web console, as demonstrated in"Send a message" on page 54 .

Example 4.1. Web Form for Sending a Message to a Queue or Topic

<html><head><title>Send a JMS Message</title><link rel="stylesheet" href="style.css" type="text/css">

</head><body><h1>Send a JMS Message</h1><form action="message/FOO/BAR" method="post"><p><label for="destination">Destination name</label><input type="text" name="destination"/>

</p><p><label for="type">Destination Type: </label><select name="type"><option selected value="queue">Queue</option><option type" value="topic">Topic</option>

</select></p><p><textarea name="body" rows="30" cols="80">

Enter some text here for the message body...</textarea>

Protocol Details

</p><p><input type="submit" value="Send"/><input type="reset"/>

</p></form></body></html>

Table 4.5 on page 50 describes the form properties that are recognized bythe message servlet.

Table 4.5. Form Properties Recognized by Message Servlet

DescriptionForm Property

The action attribute of the <form> tag has the format,message/DestinationPath, where DestinationPath is

Form action

the compound name of the queue or topic, using forwardslash, /, as the delimiter (for example, FOO/BAR).

The compound name of the destination queue or topic, usinga period, ., as the delimiter (for example, FOO.BAR). If this

destination

property is specified in the form, it overrides the value of theDestinationPath in the form action.

Destination type, equals queue or topic.type

Message body.body

Example of getting a message 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 describedin "message servlet" on page 46 . For example, to consume a message fromthe FOO.BAR queue, navigate to the following URL:

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

Examples of browsing a queue To browse a queue using the queueBrowse servlet, simply navigate to anURL of the appropriate form, as described in "queueBrowse servlet"on page 48 .

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

Protocol Details

REST Example

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

Example prerequisites You must ensure that the message broker is configured to instantiate anembedded servlet engine. In your broker configuration file,conf/activemq.xml, check that there is a jetty element configured asshown in Example 4.2 on page 52 .

Example 4.2. Configuration of an Embedded Servlet Engine

<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" />

</handlers></jetty>

With the configuration shown in Example 4.2 on page 52 , the servlet engineopens up a HTTP port on IP port, 8161. The following Web applications areloaded:

• Demonstration application (from webapps/demo),

• REST protocol servlets (from webapps/demo).

• Web console servlet (from webapps/admin),

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

1. "Run the servlet engine" .

2. "Open a Web browser" .

3. "Send a message" .

4. "Browse the message queue" .

5. "Receive a message from the queue" .

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

activemq

This step assumes that your broker is configured as described in "Exampleprerequisites" on page 52.

Open a Web browser 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, asshown in Figure 4.1 on page 54.

REST Example

Figure 4.1. Welcome Page for Web Examples

Send a messageTo view the form for publishing messages, click the link, Send a message2.The Send a JMS Message form now appears in your browser, as shown inFigure 4.2 on page 55.

Figure 4.2. The Send a JMS Message Form

In the Destination name text field, enter FOO.BAR to send a message to theFOO.BAR queue. Leave the Destination Type as Queue. Then enter an arbitrarytext message in the large message text box. Click the Send button at thebottom of the form to send the message.

Browse the message queue Using the history feature of your browser, navigate back to the examplewelcome page (see Figure 4.1 on page 54 ). The queueBrowse servletsupports a variety of ways to browse the contents of a queue and these arelisted at the bottom of the welcome page. The following browsing options arelisted:

• Browse a queue.3

• Browse a queue as XML4.

• Browse a queue as Atom5.

• Browse a queue as RSS 1.06.

• Browse a queue as RSS 2.07.

2 http://localhost:8080/activemq-web-demo/send.html3 http://localhost:8080/activemq-web-demo/queueBrowse/FOO/BAR4 http://localhost:8080/activemq-web-demo/queueBrowse/FOO/BAR?view=xml5 http://localhost:8080/activemq-web-demo/queueBrowse/FOO/BAR?view=rss&feedType=atom_1.06 http://localhost:8080/activemq-web-demo/queueBrowse/FOO/BAR?view=rss&feedType=rss_1.07 http://localhost:8080/activemq-web-demo/queueBrowse/FOO/BAR?view=rss&feedType=rss_2.0

REST Example

If you click on Browse a queue, you should see a page likeFigure 4.3 on page 56 .

Figure 4.3. Default Option to Browse a Queue

If you click on Browse a queue as XML, you should see a page likeFigure 4.4 on page 57 .

Figure 4.4. Option to Browse a Queue as XML

If you click on Browse a queue as Atom, you should see a page likeFigure 4.5 on page 58 .

REST Example

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 on page 59 .

Figure 4.6. Option to Browse a Queue as RSS 1.0

Receive a message from thequeue

To receive a message from the FOO.BAR queue, open the example welcomepage in your browser, http://localhost:8161/demo8, and click the link, Receivea message9.

8 http://localhost:8080/activemq-web-demo9 http://localhost:8080/activemq-web-demo/message/FOO/BAR?timeout=10000&type=queue

REST Example

You should now see the text of the message that you sent earlier. You willprobably also receive an error from your browser, if the message is notformatted as HTML or XML (which the browser expects).

Chapter 5. VM TransportThe VM transport allows clients to connect to each other inside the Java Virtual Machine (JVM) without theoverhead of network communication.

Overview The VM transport enables Java clients running inside the same JVM tocommunicate with each other inside the JVM, without having to resort to ausing a network connection. Because the clients require a broker tocommunicate, the VM transport can implicitly create an embedded brokerthe first time it is accessed. Figure 5.1 on page 61 shows the basicarchitecture of the VM protocol.

Figure 5.1. Clients Connected through the VM Transport

The URI used to specify the VM transport comes in two flavors to providemaximum control over how the embedded broker is configured:

• simple—specifies the name of the embedded broker to which the clientconnects and allows for some basic broker configuration

• advanced—uses a broker URI to configure the embedded broker

Embedded brokers The VM transport uses a broker embedded in the same JVM as the clients tofacilitate communication between the clients. The embedded broker can becreated in several ways:

• explicitly defining the broker in the application's configuration

• explicitly creating the broker using the Java APIs

• automatically when the first client attempts to connect to it using the VMtransport

The VM transport uses the broker name specified in either the simple URI orin the configuration provided by the advanced URI's broker URI to determineif an embedded broker needs to be created. When a client uses the VMtransport to connect to a broker, the transport checks to see if an embeddedbroker by that name already exists. If it does exist, the client is connected tothe broker. If it does not exist, the broker is created and then the broker isconnected to it.

When using explicitly created brokers there is a danger that your clients willattempt to connect to the embedded broker before it is started. If this happens,the VM transport will auto-create an instance of the broker for you. To avoidthis conflict you can set the waitForStart option or the create=falseoption to manage how the VM transport determines when to create a newembedded broker.

Simple URI syntax The simple VM URI is used in most situations. It allows you to specify thename of the embedded broker to which the client will connect. It also allowsfor some basic broker configuration.

Example 5.1 on page 62 shows the syntax for a simple VM URI.

Example 5.1. Simple VM URI Syntax

vm://BrokerName?TransportOptions

• BrokerName specifies the name of the embedded broker to which the clientconnects.

Chapter 5. VM Transport

• TransportOptions specifies the configuration for the transport. They are

specified in the form of a query list. Table 5.2 on page 64 lists the availableoptions.

In addition to the transport options listed in Table 5.2 on page 64, the simpleVM URI can use the options described in Table 5.1 on page 63 to configurethe embedded broker.

Table 5.1. VM Transport Broker Configuration Options

DescriptionOption

Properties prefixed by broker. configure the embedded broker. You can specify any of the

standard broker options described in Table 5.3 on page 65.

broker.*

Specifies an external broker configuration file. For example, to pick up the broker configurationfile, activemq.xml, you would set brokerConfig as follows:

brokerConfig=xbean:activemq.xml.

brokerConfig

ImportantThe broker configuration options specified on the VM URI are onlymeaningful if the client is responsible for instantiating the embeddedbroker. If the embedded broker is already started, the transport willignore the broker configuration properties.

Example 5.2 on page 63 shows a basic VM URI that connects to anembedded broker named broker1.

Example 5.2. Basic VM URI

vm://broker1

Example 5.3 on page 63 creates and connects to an embedded broker thatuses a non-persistent message store.

Example 5.3. Simple URI with broker options

vm://broker1?broker.persistent=false

Advanced URI syntax The advance VM URI provides you full control over how the embedded brokeris configured. It uses a broker configuration URI similar to the one used bythe administration tool to configure the embedded broker.

Example 5.4 on page 64 shows the syntax for a simple VM URI.

Example 5.4. Advanced VM URI Syntax

vm://(BrokerConfigURI)?TransportOptions

• BrokerConfigURI is a broker configuration URI. See "Broker URI" in

Administering a Broker for information about broker configuration URIs.

• TransportOptions specifies the configuration for the transport. They are

specified in the form of a query list. Table 5.2 on page 64 lists the availableoptions.

Example 5.5 on page 64 creates and connects to an embedded brokerconfigured using a broker configuration URI.

Example 5.5. Advanced VM URI

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

Transport options Table 5.2 on page 64 shows options for configuring the VM transport.

Table 5.2. VM Transport Options

DescriptionOption

If true, forces each command sent over the transport to be marshalled and unmarshalled using

the specified wire format. Default is false.

marshal

The name of the wire format to use.wireFormat

Properties prefixed by wireFormat. configure the specified wire format.wireFormat.*

Specifies if the VM transport will create an embedded broker if one does not exist. The defaultis true.

create

Specifies the time, in milliseconds, the VM transport will wait for an embedded broker to startbefore creating one. The default is -1 which specifies that the transport will not wait.

waitForStart

Broker options Table 5.3 on page 65 shows the options used to configure the broker usingthe simple VM URI.

Chapter 5. VM Transport

Table 5.3. Broker Options

DescriptionOption

Specifies if JMX is enabled. Default is true.useJmx

Specifies if the broker uses persistent storage. Default is true.persistent

Specifies if the broker populates the JMSXUserID message property with the

sender’s authenticated username. Default is false.

populateJMSXUserID

Specifies if the broker installs a shutdown hook, so that it can shut downproperly when it receives a JVM kill. Default is true.

useShutdownHook

Specifies the broker name. Default is localhost.brokerName

Specifies if all the messages in the persistent store are deleted when the brokerstarts up. Default is false.

deleteAllMessagesOnStartup

Specifies if statistics gathering is enabled in the broker. Default is true.enableStatistics

Chapter 6. Failover ProtocolThe failover protocol provides a simple mechanism for clients to failover to a secondary broker endpoint if theprimary connection fails. The failover protocol does not require that the brokers be configured as a network ofbrokers. However, when paired with a network of brokers it can be configured to use dynamic failover locations.

Static Failover ....................................................................................................................... 68Dynamic Failover ................................................................................................................... 70

The failover protocol facilitates quick recovery from network failures. Whena recoverable network error occurs the protocol catches the error andautomatically attempts to reestablish the JMS connection to an alternatebroker endpoint without the need to recreate all of the JMS objects associatedwith the JMS connection. The failover URI is composed of one or more URIsthat represent different broker endpoints. By default, the protocol randomlychooses a URI from the list and attempts to establish a network connectionto it. If it does not succeed, or if it subsequently fails, a new networkconnection is established to one of the other URIs in the list.

For true high-availability and failover capabilities, you will need to set up yourbrokers in a network of brokers or a master/slave cluster. See Broker ClusteringGuide.

The failover transport allows you to set up failover in one of two ways:

• Static—the client is configured with a static list of available URIs

• Dynamic—the brokers push information about the available brokerconnections

Static Failover

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

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

Failover URI A failover URI is a composite URI that uses one of the following syntaxes:

• failover://uri1,...,uriN

• failover://(uri1,...,uriN)?TransportOptions

The URI list(uri1,...,uriN) is a comma-separated list containing the list ofbroker endpoint URIs to which the client can connect. The transportoptions(?TransportOptions) specified in the form of a query list, allow youto configure some of the failoiver behaviors.

Transport options The failover protocol supports the transport options described inTable 6.1 on page 68.

Table 6.1. Failover Transport Options

DescriptionDefaultOption

Specifies the number of milliseconds to wait before the first reconnectattempt.

10initialReconnectDelay

Specifies the maximum amount of time, in milliseconds, to waitbetween reconnect attempts.

30000maxReconnectDelay

Specifies whether to use an exponential back-off between reconnectattempts.

trueuseExponentialBackOff

Specifies the exponent used in the exponential back-off algorithm.2backOffMultiplier

Chapter 6. Failover Protocol

Specifies the maximum number of reconnect attempts before anerror is returned to the client. -1 specifies unlimited attempts. 0

-1maxReconnectAttempts

specifies that an initial connection attempt is made at start-up, butno attempts to failover over to a secondary broker will be made.

Specifies the maximum number of reconnect attempts before anerror is returned to the client on the first attempt by the client tostart a connection. 0 specifies unlimited attempts.

0startupMaxReconnectAttempts

Specifies if a URI is chosen at random from the list. Otherwise, thelist is traversed from left to right.

truerandomize

Specifies if the protocol initializes and holds a second transportconnection to enable fast failover.

falsebackup

Specifies the amount of time, in milliseconds, to wait before sendingan error if a new connection is not established. -1 specifies an infinitetimeout value.

-1timeout

Specifies if the protocol keeps a cache of in-flight messages that areflushed to a broker on reconnect.

falsetrackMessages

Specifies the size, in bytes, used for the cache used to trackmessages.

131072maxCacheSize

Specifies whether the client accepts updates to its list of known URIsfrom the connected broker. Setting this to false inhibits the client'sability to use dynamic failover. See "Dynamic Failover" on page 70.

trueupdateURIsSupported

Example Example 6.1 on page 69 shows a failover URI that can connect to one oftwo message brokers.

Example 6.1. Simple Failover URI

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

Static Failover

Dynamic Failover

Overview Dynamic failover combines the failover protocol and a network of brokers toallow a broker to supply its clients with a list of broker connections to whichthe clients can failover. Clients use a failover URI to connect to a broker andthe broker dynamically updates the clients' list of available URIs. The brokerupdates its clients' failover lists with the URIs of the other brokers in itsnetwork 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 staticfailover. A client randomly chooses a URI from the list provided in its failoverURI. Once that connection is established, the list of available brokers isupdated. If the original connection fails, the client will randomly select a newURI from its dynamically generated list of brokers. If the new broker isconfigured for dynamic failover, the new broker will update the client's list.

Set-up To use dynamic failover you must configure both the clients and brokers usedby your application. The following must be configured:

• The client's must be configured to use the failover protocol when connectingwith its broker.

• The brokers must be configured to form a network of brokers.

See "Broker Networks" in Broker Clustering Guide.

• The broker's transport connector must set the failover properties needed toupdate its consumers.

Client-side configuration The client-side configuration for using dynamic failover is identical to theclient-side configuration for using static failover. The client uses a failoverURI to connect to a broker.

When using dynamic failover, the failover URI can include a single brokerURI. As long as the broker is available when the client attempts to make itsinitial connection, the client's list of failover brokers will get populated.

It is also important that the updateURIsSupported option not be set tofalse. If it is, the client will not be able to receive updates about what brokersare available for failover.

See "Failover URI" on page 68 and "Transport options" on page 68 for moreinformation about using failover URIs.

Broker-side configuration Configuring a broker to participate in dynamic failover requires two things:

• The broker must be configured to participate in a network of brokers thatcan be available for failovers.

See "Broker Networks" in Broker Clustering Guide for information aboutsetting up a network of brokers.

• The broker's transport connector must set the failover properties needed toupdate its consumers.

Table 6.2 on page 71 describes the broker-side properties that can be usedto configure a failover cluster. These properties are attributes on the broker'stransportConnector element.

Table 6.2. Broker-side Failover Properties

DescriptionDefaultProperty

Specifies if the broker passes information to connected clients aboutchanges in the topology of the broker cluster.

falseupdateClusterClients

Specifies if clients are updated when a broker is removed from thecluster.

falseupdateClusterClientsOnRemove

Specifies if connected clients are asked to rebalance across thecluster whenever a new broker joins.

falserebalanceClusterClients

Specifies a comma-separated list of regular expression filters, whichmatch against broker names to select the brokers that belong to thefailover cluster.

updateClusterFilter

Specifies a URL, or path to a local file, locating a text file thatcontains a comma-separated list of URIs to use for reconnect in thecase of failure.

updateURIsURL

Example Example 6.2 on page 71 shows the configuration for a broker that participatesin dynamic failover.

Example 6.2. Broker for Dynamic Failover

Dynamic Failover

...<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*" />

</broker></beans>

The configuration in Example 6.2 on page 71 does the following:

❶ Creates a network connector that connects to any discoverable brokerthat uses the multicast transport.

❷ Makes the broker discoverable by other brokers over the multicastprotocol.

❸ Makes the broker update the list of available brokers for clients thatconnect using the failover protocol.

NoteClients will only be updated when new brokers join the cluster,not when a broker leaves the cluster.

❹ Creates a filter so that only those brokers whose names start with theletter A or the letter B are considered to belong to the failover cluster.

Example 6.3 on page 72 shows the URI for a client that uses the failoverprotocol to connect to the broker and its cluster.

Example 6.3. Failover URI for Connecting to a Failover Cluster

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

Chapter 7. Discovery ProtocolsThis chapter introduces the simplest kind of broker cluster: a collection of isolated broker instances (no networkconnectors). When used in combination with the discovery protocols, such a cluster can be used as a simpleload balancing system.

Dynamic Discovery Protocol ..................................................................................................... 74Discovery Agents ................................................................................................................... 76

Dynamic Discovery Protocol

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

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

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

• Simple (static) discovery agent.

• Multicast discovery agent.

• Zeroconf discovery agent.

For more details, see "Discovery Agents" on page 76.

Configuring a transport connectorwith a discovery agent

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

</transportConnectors>

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

Configuration syntax A discovery URI must conform to the following syntax:

discovery://(DiscoveryAgentUri)?TransportOptions

Chapter 7. Discovery Protocols

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

discovery://DiscoveryAgentUri

Transport options The discovery protocol supports the transport options described inTable 7.1 on page 75

Table 7.1. Discovery Transport Options

DescriptionDefaultOption Name

How long to wait before the first reconnect attempt (in ms).10initialReconnectDelay

The maximum amount of time to wait between reconnect attempts (in ms).30000maxReconnectDelay

If true, use an exponential back-off between reconnect attempts.trueuseExponentialBackOff

The exponent used in the exponential back-off algorithm.2backOffMultiplier

If not 0, this is the maximum number of reconnect attempts before an error

is sent back to the client.

0maxReconnectAttempts

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

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

Setting options on the discoveredtransports

The list of transport options, TransportOptions, in the discovery URI canalso be used to set options on the discovered transports. If you set an optionnot listed in Table 7.1 on page 75, the URI parser attempts to inject theoption 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.

Dynamic Discovery Protocol

Discovery Agents

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

• Client side—the discovery agent URI resolves to a list of broker URIs. Touse a discovery agent URI on the client side, you must insert it into adynamic discovery URI, discovery://(...), which then opens a

connection to one of the URIs in the list.

• Broker side—in order to make a broker discoverable, it is usually necessaryto configure a discovery agent in the broker as well (an exception to thisrequirement is the simple discovery agent).

NoteA discover agent URI resolves to a list of transport URIs, but thediscovery agent URI is not itself a transport URI and cannot be usedin place of a transport URI.

Configuring a discovery agent onthe client side

Since a discovery agent is not a transport protocol, you cannot use a discoveryagent URI directly on the client side. To use a discovery agent on the clientside, 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 listof available endpoint URLs using the specified discovery agent and thenconnects to one of the discovered URLs. For more details about the discoveryprotocol, see "Dynamic Discovery Protocol" on page 74 .

Configuring discovery agents ona message broker

For certain kinds of discovery agent (for example, multicast or zeroconf), it isnecessary 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"/>

Where the discoveryUri attribute on the transportConnector elementis initialized to multicast://default. You can associate multiple endpointswith the same discovery agent. For example, to configure both an Openwireendpoint and a Stomp endpoint to use the multicast://default discoveryagent:

Discovery agents Fuse Message Broker currently supports the following discovery agents:

• "Simple (static) discovery agent"

• "Multicast discovery agent"

• "Zeroconf discovery agent"

Simple (static) discovery agent The simple (static) discovery agent provides an explicit list of broker URLsfor 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 followingsyntax:

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

Or equivalently:

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

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

Discovery Agents

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

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

Multicast discovery agent The multicast discovery agent uses the IP multicast protocol to find anymessage brokers currently active on the local network. In order for the protocolto work, a multicast discovery agent must be enabled on each broker youwant to advertise and messaging clients must be configured to use adiscovery 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 samediscovery network must use the same GroupID. For example, the FuseMessage Broker is usually configured to use the URI, multicast://default.

NoteYour local network (LAN) must be configured appropriately for theIP/multicast protocol to work. If your clients fail to discover a brokerusing the multicast protocol, this could be because IP/multicastis not set up on your network.

Zeroconf discovery agent The zeroconf discovery agent is derived from Apple’s Bonjour Networking1

technology, which defines the zeroconf protocol as a mechanism fordiscovering services on a network. Fuse Message Broker bases itsimplementation of the zeroconf discovery agent on JmDSN2, which is a servicediscovery protocol that is layered over IP/multicast and is compatible withApple Bonjour. To enable the protocol, a multicast discovery agent must beconfigured on each broker you want to advertise and messaging clients mustbe configured to use a discovery URI.

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

zeroconf://GroupID

1 http://developer.apple.com/networking/bonjour/2 http://sourceforge.net/projects/jmdns/

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

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

discovery://(zeroconf://groupA)

NoteYour local network (LAN) must be configured appropriately for theIP/multicast protocol to work. If your clients fail to discover a brokerusing the zeroconf protocol, this could be because IP/multicast isnot set up on your network.

Discovery Agents

Chapter 8. Fanout ProtocolThe fanout protocol allows clients to connect to multiple brokers at once and broadcast messages to consumersconnected to all of the brokers at once.

Overview The fanout protocol enables a producer client to auto-discover broker endpointsand broadcast topic messages to all of the discovered brokers. In other words,the fanout protocol gives producers a convenient mechanism for broadcastingmessages to multiple brokers, for those cases where the brokers themselvesare not linked together in a broker network.

The fanout protocol relies on a discovery agent to build up the list of brokerURIs that it connects to.

NoteThe fanout protocol is only meant to be used with producer endpoints,not with consumer endpoints.

Configuring a transport connectorwith a discovery agent

Before you can use the fanout protocol, you must make your broker’s endpointsdiscoverable by adding a discovery agent to each transport connector—see"Discovery Agents" on page 76.

For example, to make a TCP transport connector discoverable, set thediscoveryUri attribute on the transportConnector element as follows:

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

Configuration syntax A fanout URI must conform to the following syntax:

fanout://(DiscoveryAgentUri)?TransportOptions

Where the discovery agent URI, DiscoveryAgentUri, identifies a discoveryagent, as described in "Discovery agents" on page 74. The transport options,

?TransportOptions, are specified in the form of a query list (where thesupported options are described in Table 8.1 on page 82). If no transportoptions are required, you can use the following alternative syntax:

fanout://DiscoveryAgentUri

Transport options The fanout protocol supports the transport options described inTable 8.1 on page 82

Table 8.1. Fanout Protocol Options

DescriptionDefaultOption Name

How long to wait before the first reconnect attempt (in ms).10initialReconnectDelay

The maximum amount of time to wait between reconnect attempts (in ms).30000maxReconnectDelay

If true, use an exponential back-off between reconnect attempts.trueuseExponentialBackOff

The exponent used in the exponential back-off algorithm.2backOffMultiplier

If not 0, this is the maximum number of reconnect attempts before an error

is sent back to the client.

0maxReconnectAttempts

If true, queue messages (as well as topic messages) are replicated to every

connected broker. If false, queue messages are sent only to one of the

connected brokers.

falsefanOutQueues

The minimum number of brokers to which the client must connect. If theclient connects to fewer than this number of brokers, no messages are sent.

2minAckCount

Sample URI The following is an example of a fanout URI that uses a multicast discoveryagent:

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

Applying fanout to queuemessages

The fanout protocol replicates topic messages by sending each topic messageto all of the connected brokers. By default, however, the fanout protocol doesnot replicate queue messages. For queue messages, the fanout protocol picksone of the brokers at random and sends all of the queue messages to thatbroker. This is a sensible default, because under normal circumstances, youwould not want to create more than one copy of a queue message.

Chapter 8. Fanout Protocol

It is possible, though, to change the default behavior by setting thefanOutQueues option to true, so that the fanout protocol also replicatesqueue messages—for example:

fanout://(multicast://default)?fanOutQueues=true

Minimum number of brokers By default, the fanout protocol does not start sending messages until thefanout endpoint has connected to a minimum of two brokers. You cancustomize this minimum value by setting the minAckCount option equal tothe required minimum number of broker connections. By setting this optionequal to the expected number of discovered brokers, you can ensure that allof the available brokers start receiving messages from the producer client atthe same time. This ensures that no messages are missed when the clientstarts up.

For example, to ensure that a fanout endpoint does not start sending messagesuntil at least three brokers are connected, you can specify a URL like thefollowing:

fanout://(multicast://default)?minAckCount=3

Using fanout with a brokernetwork

You have to be careful when using the fanout protocol with brokers that areconnected together in a network. It is very likely that consumers will receiveduplicate messages in this case, because the fanout protocol would injectmultiple copies of each message into the broker network.

Chapter 9. Peer-to-Peer ProtocolsPeer-to-peer protocols enable messaging clients to communicate with each other directly, eliminating therequirement to route messages through an external message broker.

Peer Protocol ........................................................................................................................ 86Peer Example ........................................................................................................................ 89

Peer Protocol

Overview The peer protocol enables you to set up a peer-to-peer network by creatingan embedded broker inside each peer endpoint. Figure 9.1 on page 86illustrates the peer-to-peer network topology for a simple two-peer network.

Figure 9.1. Peer Protocol Endpoints with Embedded Brokers

In this topology, a standalone broker is not required, because each peerinstantiates its own embedded broker. As shown in Figure 9.1 on page 86, the producer sends messages to its embedded broker, broker1, byconnecting to the local VM endpoint, vm://broker1—see "VM Transport"on page 61 . The embedded brokers, broker1 and broker2, are linkedtogether using a network connector, which allows messages to flow in eitherdirection between the brokers. When the producer sends a message to the

Chapter 9. Peer-to-Peer Protocols

queue, TEST.FOO, the first embedded broker, broker1, automatically pushesthe message across the network connector and on to the remote embeddedbroker, broker2. The consumer can then receive the message from itsembedded broker, broker2.

Discovering peer endpoints Implicitly, the peer protocol uses multicast discovery to locate active peerson the network. In order for this to work, you must ensure that the IP multicastprotocol is enabled on your operating system. See "Dynamic DiscoveryProtocol" on page 74 for details.

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 cancommunicate with each other. That is, a given peer can connect only to theset of peers that specify the same PeerGroup name in their URLs. TheBrokerName specifies the broker name for the embedded broker. The brokeroptions, 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 9.1 on page 87.

Table 9.1. Broker Options

DescriptionOption

If true, enables JMX. Default is true.useJmx

If true, the broker uses persistent storage. Default is true.persistent

If true, the broker populates the JMSXUserID message property with the

sender’s authenticated username. Default is false.

populateJMSXUserID

If true, the broker installs a shutdown hook, so that it can shut down properly

when it receives a JVM kill. Default is true.

useShutdownHook

Specifies the broker name. Default is localhost.brokerName

If true, deletes all the messages in the persistent store as the broker starts

up. Default is false.

deleteAllMessagesOnStartup

Peer Protocol

DescriptionOption

If true, enables statistics gathering in the broker. Default is true.enableStatistics

Sample URI The following is an example of a peer URL that belongs to the peer group,groupA, and creates an embedded broker with broker name, broker1:

peer://groupA/broker1?persistent=false

Peer Example

Overview To try out the peer protocol, perform the following steps:

1. "Start up consumer with embedded broker" .

2. "Start up producer with embedded broker" .

Start up consumer withembedded broker

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

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

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

consumer:[echo] Running consumer against server at $url = peer://group/broker1?persistent=false

for subject $subject = TEST.FOO[java] Connecting to URL: peer://group/broker1?persistent=false[java] Consuming queue: TEST.FOO[java] Using a non-durable subscription[java] 15:43:10 INFO ActiveMQ null JMS Message Broker (broker1) is starting[java] 15:43:10 INFO For help or more information please see:

http://activemq.apache.org/[java] 15:43:10 INFO Using Persistence Adapter: MemoryPersistenceAdapter[java] 15:43:10 INFO Listening for connections at: tcp://fboltond820:2399[java] 15:43:10 INFO Connector tcp://fboltond820:2399 Started[java] 15:43:10 INFO Network Connector org.apache.activemq.transport.discovery.multic

ast.MulticastDiscoveryAgent@da4b71 Started[java] 15:43:10 INFO ActiveMQ JMS Message Broker (broker1, ID:fboltond820-2398-

1192200190327-2:0) started[java] 15:43:10 INFO Connector vm://broker1 Started[java] 15:43:10 INFO JMX consoles can connect to service:jmx:rmi:///jndi/rmi://local

host:1099/jmxrmi[java] We are about to wait until we consume: 100 message(s) then we will shutdown

Peer Example

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

Start up producer with embeddedbroker

Start a producer that sends messages to the TEST.FOO queue on the grouppeer group. To start the producer, run the producer tool with a peer groupURL as follows:

cd InstallDir/exampleant producer -Durl="peer://group/broker2?persistent=false" -DsleepTime=1000

Where the name of the embedded broker is set to broker2 and the sleeptime (time between successive messages) is set to 1000 ms. When theproducer starts up, the output log should include some lines like the following:

[java] 15:43:27 INFO Establishing network connection between from vm://broker2 totcp://fboltond820:2399

[java] 15:43:28 INFO Network connection between vm://broker2#2 and tcp://localhost/127.0.0.1:2399(broker1) has been established.

These lines indicate that a peer-to-peer connection was successfullyestablished between the embedded brokers, broker1 and broker2. Theconsumer should now be able to receive the messages sent by the producer.

Appendix A. Transport OptionsThis appendix is a reference guide for the TCP, NIO, SSL, UDP, and wire format URI options.

TCP and NIO Transports .......................................................................................................... 92SSL Transport ....................................................................................................................... 95UDP Transport ...................................................................................................................... 97Wire Format Options ............................................................................................................... 98

TCP and NIO Transports

Overview The TCP transport is used for creating OpenWire/TCP endpoints. The NIOtransport is similar to the TCP transport, except that it uses the Java New I/O(NIO)1 socket library, which can provide better scalability when used on theserver side. TCP and NIO have the same transport options.

Syntax A TCP URI has the following syntax:

tcp://Host[:Port]?transportOptions

An NIO URI has the following syntax:

nio://Host[:Port]?transportOptions

Where the transport options, transportOptions, are specified as follows:

?option=value&option=value&...

In XML configuration, you must escape the & symbol, replacing it with &.For example:

Setting client-side options When setting a client-side option, the name of the options is exactly as givenin Table A.1 on page 93. For example, to enable tracing on a client TCPendpoint, set the trace option as follows:

tcp://fusesource.com:61616?trace=true

Setting server-side options When setting a server-side option, there are two alternative option syntaxesas follows:

TCP listener socket optionsTo configure options on the TCP listener socket, add the transport.

prefix to the option names shown in Table A.1 on page 93. 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 optionsTo configure options on a TCP connection socket (which is spawned fromthe listener socket whenever the server accepts a new TCP connection),use the option name exactly as given in Table A.1 on page 93. Forexample, to enable tracing on a TCP connection socket, set the trace

option as follows:

tcp://fusesource.com:61616?trace=true

Options Table A.1 on page 93 shows the options supported by the TCP and the NIOURIs.

Table A.1. TCP and NIO Transport Options

The minimum wire format version that is allowed.0minmumWireFormatVersion

Causes all commands sent over the transport to be logged.falsetrace

Specifies whether the transport thread runs as a daemon or not.Useful to enable when embedding in a Spring container or in a webcontainer, to allow the container to shut down properly.

falsedaemon

When true, causes the local machine's name to resolve to

localhost.

trueuseLocalHost

Sets the socket buffer size in bytes.64*1024socketBufferSize

When true, enables TCP KeepAlive2 on the broker connection.

Useful to ensure that inactive consumers do not time out.

falsekeepAlive

Sets the socket timeout in milliseconds0soTimeout

A non-zero value specifies the connection timeout in milliseconds.A zero value means wait forever for the connection to be established.Negative values are ignored.

30000connectionTimeout

The false value causes all sockets to be closed synchronously.truecloseAsync

2 http://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html

When > -1, enables the SoLinger socket option with this value.

When equal to -1, disables SoLinger. (from 5.6.0).

MIN_INTEGERsoLinger

The maximum number of sockets the broker is allowed to create.MAX_VALUEmaximumConnections

(Client only) The preferred Differentiated Services traffic class to beset on outgoing packets, as described in RFC 2475. Valid integer

0diffServ

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 thejava.net.preferIPv4Stack system property to true. Cannot be

used at the same time as the typeOfService option.

(Client only) The preferred type of service value to be set on outgoingpackets. Valid integer values are [0,256). With JDK 6, only works

0typeOfService

when the Java Runtime uses the IPv4 stack, which can be done bysetting the java.net.preferIPv4Stack system property to true.

Cannot be used at the same time as the diffServ option.

All the properties with this prefix are used to configure thewireFormat. See Table A.4 on page 98 for more information.

wireFormat.*

SSL Transport

Overview The SSL transport is used for creating OpenWire/TCP endpoints with SSL/TLSenabled.

NoteThe URI transport options described here are not sufficient toconfigure an SSL endpoint completely. You must also associate X.509certificates with the endpoint. For more details, see "SSL/TLSSecurity" in Security Guide.

Syntax An SSL URI has the following syntax:

ssl://Host[:Port]?transportOptions

TCP transport options The SSL transport inherits all of the options supported by the TCP transportURI. See Table A.1 on page 93.

Options Table A.2 on page 95 shows the options supported by the SSL URI.

Table A.2. SSL Transport Options

Specifies the cipher suites accepted by this endpoint, in the formof a comma-separated list.

transport.enabledCipherSuites

Specifies the secure socket protocols accepted by this endpoint,in the form of a comma-separated list. If using Sun's JSSEprovider, possible values are: SSL, SSLv2, SSLv3, TLS, or TLSv1.

transport.enabledProtocols

(Server only) If true, the server requests (but does not require)

the client to send a certificate.

transport.wantClientAuth

(Server only) If true, the server requires the client to send its

certificate. If the client fails to send a certificate, the server willthrow an error and close the session.

falsetransport.needClientAuth

(Server only) If true, the server socket creates a new SSL session

every time it accepts a connection and spawns a new socket. If

truetransport.enableSessionCreation

false, an existing SSL session must be resumed when the server

socket accepts a connection.

UDP Transport

Overview The UDP transport enables you to send datagrams using the unreliable UDP/IPprotocol.

WarningBecause UDP does not keep track of IP packets, you can losemessages sent over a raw UDP connection. It is up to you to providea reliability layer to avoid message loss over UDP.

Syntax A UDP URI has the following syntax:

udp://Host[:Port]?transportOptions

Options Table A.3 on page 97 shows the options supported by the UDP URI.

Table A.3. SSL Transport Options

The minimum version wire format that is allowed.0minmumWireFormatVersion

Causes all commands sent over the transport to be logged.falsetrace

When true, causes the local machine's name to resolve to localhost.trueuseLocalHost

Specifies the size of a datagram.4*1024datagramSize

All options with this prefix are used to configure the wire format. SeeTable A.4 on page 98 for more information.

wireFormat.*

Wire Format Options

Overview The wire format options configure the OpenWire message layer and can bespecified as transport options with any of the preceding transports.

Options Table A.4 on page 98 shows the wire format options supported by theOpenWire protocol.

Table A.4. Transport Options Supported by OpenWire Protocol

Negotiation policyDescriptionDefaultOption

Should the stack trace of an exceptionoccuring on the broker be sent to theclient?

truewireformat .stackTraceEnabled

Provides a hint to the peer that TCPnodelay should be enabled on thecommunications Socket.

falsewireformat .tcpNoDelayEnabled

Should commonly repeated values becached so that less marshalling occurs?

truewireformat .cacheEnabled

Use the smaller ofthe two values.

If cacheEnabled is true, this propertyspecifies the maximum number ofvalues to cache.

1024wireformat .cacheSize

Should wire size be optimized over CPUusage?

truewireformat .tightEncodingEnabled

Set to true if bothsides are true.

Should the size of the packet be prefixedbefore each packet is marshalled?

truewireformat .prefixPacketSize

Use the smaller ofthe two values.

The maximum inactivity duration (beforewhich the socket is considered dead) in

30000wireformat .maxInactivityDuration

milliseconds. On some platforms it cantake a long time for a socket to appearto die, so we allow the broker to killconnections if they are inactive for aperiod of time. Set to a value <= 0 todisable inactivity monitoring.

The initial delay in starting themaximum inactivity checks. Note: The

10000wireformat

.maxInactivityDurationInitalDelaymis-spelling, Inital, is a typographic

error in the source code.

IndexBbroker properties

rebalanceClusterClients, 71updateClusterClients, 71updateClusterClientsOnRemove, 71updateClusterFilter, 71updateURIsURL, 71

Ddynamic failover, 70

broker configuration, 71client configuration, 70

Eembedded broker, 62

brokerName, 65configuration, 64deleteAllMessagesOnStartup, 65enableStatistics, 65persistent, 65populateJMSXUserID, 65useJmx, 65useShutdownHook, 65

Ffailover, 67

backOffMultiplier, 68backup, 69broker properties, 71dynamic, 70initialReconnectDelay, 68maxCacheSize, 69maxReconnectAttempts, 69maxReconnectDelay, 68randomize, 69startupMaxReconnectAttempts, 69static, 68timeout, 69

trackMessages, 69updateURIsSupported, 69useExponentialBackOff, 68

failover URI, 68transport options, 68

Sstatic failover, 68

advanced URI, 63broker configuration, 63broker name, 62broker.*, 63brokerConfig, 63create, 62, 64embedded broker, 62marshal, 64simple URI, 62waitForStart, 62, 64wireFormat, 64

VM URIadvanced, 63simple, 62

Connectivity Guide

Documents

Connectivity Guide ES

Connectivity Guide

TI Wireless Connectivity Guide

NiagaraAX SSL Connectivity Guide - VYKON

Astro B.yond VOD Connectivity Guide

Network Connectivity Monitor IP Discovery Guide · Network Connectivity Monitor IP Discovery Guide Cisco Network Connectivity Center Text Part Number: OL-6204-01 ... Networking Academy,

Specific Client Connectivity Guide - Youngtecftp.youngtec.com.tw/.../Client_Connectivity/...Connectivity_Guide.pdf · KepserverEx Client Connectivity Guide ... This OPC server has

SAP COD_Techincal Connectivity Guide

CONNECTIVITY GUIDE - sgcdn.startech.comsgcdn.startech.com/.../marketing/.../Connectivity-Guide-EN-web.pdf · TECHNOLOGY SOLUTIONS CONNECTIVITY GUIDE ... another surface, out of the

Texas Medicaid EDI CONNECTIVITY GUIDE - TMHP EDI Connectivity Guide.pdf · Texas Medicaid EDI Connectivity Guide . Texas Medicaid Proprietary & Confidential Page . 3. of . 29. Last

Vnx5500 windows connectivity guide

Ind Connectivity Study Guide

Niagara Networking and Connectivity Guide

SPARTAN-6 FPGA CONNECTIVITY KIT HARDWARE SETUP GUIDE · 2019-10-26 · HARDWARE SETUP GUIDE SPARTAN-6 FPGA CONNECTIVITY KIT HARDWARE SETUP GUIDE SPARTAN-6 FPGA CONNECTIVITY KIT HARDWARE

LCH Clearnet SA Connectivity Guide

LaGov ECC Connectivity Troubleshooting Guide

Amazon Aurora Connectivity Guide

SRDF Connectivity guide

EDI CONNECTIVITY GUIDE - TMHP

EMC Host Connectivity Guide for Windows · PDF fileFederated Live Migration ... DMX, VMAX 40K, ... Connectivity Guide for Windows. EMC Host Connectivity Guide for Windows. EMC Host