Fuse ESB - Clustering Guide - Discovery Agents

Overview

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

Client side—the discovery agent URI resolves to a list of broker URIs. To use a discovery agent URI on the client side, you must insert it into a dynamic 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 necessary to configure a discovery agent in the broker as well (an exception to this requirement is the simple discovery agent).

	Note
	A discover agent URI resolves to a list of transport URIs, but the discovery agent URI is not itself a transport URI and cannot be used in place of a transport URI.

Configuring a discovery agent on the client side

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

discovery://(DiscoveryAgentUri)?TransportOptions

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

Configuring discovery agents on a message broker

For certain kinds of discovery agent (for example, multicast or rendezvous), it is necessary to enable the discovery agent in the message broker configuration. For example, to enable the multicast discovery agent on an Openwire endpoint, edit the relevant transportConnector element as follows:

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

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

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

Discovery agents

Fuse Message Broker currently supports the following discovery agents:

Simple (static) discovery agent

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

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

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

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

Or equivalently:

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

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

Example 1.4. Simple discovery agent URL

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

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

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

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

multicast://Address:Port?TransportOptions

The following transport options are supported:

Table 1.3. Multicast Discovery Agent Options

Option Name	Default	Description
`group`	`default`	Specify a unique group name that partitions multicast traffic.
`minimumWireFormatVersion`	`0`	The minimum wireformat version that is allowed.
`trace`	`false`	Causes all commands sent over the transport to be logged.
`useLocalHost`	`true`	When `true`, causes the local machine name to resolve to `localhost`.
`datagramSize`	`4 * 1024`	Specifies the size of a datagram.
`timeToLive`	`-1`	The datagram time-to-live. Set greater than `1` in order to send packts beyond the local network. Note: For IPv4 addresses, you must also set the Java system property, `java.net.preferIPv4Stack=true`. See the IPv6 User Guide for JDK.
`loopBackMode`	`false`	Specifies whether or not to use loopback mode.
`wireFormat`	`default`	The name of the wireformat to use.
`wireFormat.*`		All properties with this prefix are used to configure the wireformat.

All participants in the same discovery network must use the same group ID. To specify the IP adress, port number, and group ID explicitly, you can specify a URI like the following:

multicast://224.1.2.3:6255?group=mygroupname

For easy configuration, you could use the special default multicast URI, as follows:

multicast://default

This default URI is equivalent to the URI, multicast://239.255.2.3:6155?group=default.

	Note
	Your local network (LAN) must be configured appropriately for the IP/multicast protocol to work. If your clients fail to discover a broker using the `multicast` protocol, this could be because IP/multicast is not set up on your network.

Rendezvous discovery agent

The rendezvous discovery agent is derived from Apple’s Bonjour Networking technology, which defines the rendezvous protocol as a mechanism for discovering services on a network. To enable the protocol, a multicast discovery agent must be configured on each broker you want to advertise and messaging clients must be configured to use a discovery URI.

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

rendezvous://GroupID

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

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

discovery://(rendezvous://groupA)

	Note
	Your local network (LAN) must be configured appropriately for the IP/multicast protocol to work. If your clients fail to discover a broker using the `rendezvous` protocol, this could be because IP/multicast is not set up on your network.