The peer protocol enables you to set up a peer-to-peer network by creating an embedded broker inside each peer endpoint. Figure 7.1 illustrates the peer-to-peer network topology for a simple two-peer network.
In this topology, a standalone broker is not required,
because each peer instantiates its own embedded broker. As shown in Figure 7.1 , the producer sends messages to its embedded broker,
broker1, by connecting to the local VM
endpoint, vm://broker1—see Chapter 5 . The embedded brokers, broker1 and broker2, are linked
together using a network connector, which allows messages to flow in either
direction between the brokers. When the producer sends a message to the queue,
TEST.FOO, the first embedded broker,
broker1, automatically pushes the
message across the network connector and on to the remote embedded broker,
broker2. The consumer can then receive
the message from its embedded broker, broker2.
Implicitly, the peer protocol uses multicast discovery to locate active peers on the network. In order for this to work, you must ensure that the IP multicast protocol is enabled on your operating system. See Dynamic Discovery Protocol for details.
A peer URI must conform to the following
syntax:
peer://PeerGroup/BrokerName?BrokerOptions
Where the group name, PeerGroup, identifies the set
of peers that can communicate with each other. That is, a given peer can connect
only to the set of peers that specify the same
PeerGroup name in their URLs. The
BrokerName 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).
The peer URL supports the broker options described in Table 7.1 .
Table 7.1. Broker Options
| Option | Description |
|---|---|
useJmx
| If true, enables JMX.
Default is true. |
persistent
| If true, the broker
uses persistent storage. Default is true. |
populateJMSXUserID
| If true, the broker
populates the JMSXUserID
message property with the sender’s authenticated username.
Default is false. |
useShutdownHook
| If true, the broker
installs a shutdown hook, so that it can shut down properly
when it receives a JVM kill. Default is true. |
brokerName
| Specifies the broker name. Default is localhost. |
deleteAllMessagesOnStartup
| If true, deletes all
the messages in the persistent store as the broker starts
up. Default is false. |
enableStatistics
| If true, enables
statistics gathering in the broker. Default is true. |
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
To try out the peer protocol, perform the following steps:
Start a consumer that consumes messages from the TEST.FOO queue belonging to the group peer group. To start the consumer, run the consumer tool with a
peer group URL as follows:
cd InstallDir/example
ant consumer -Durl="peer://group/broker1?persistent=false" -Dmax=100
Where the first component of the URL path, group, specifies that this peer belongs to the group peer group. The second component, broker1, specifies the name of the embedded
broker and the setting, persistent=false,
sets a broker option. When the consumer starts up, you should see output like
the following in the command window:
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.multicast.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://localhost:1099/jmxrmi
[java] We are about to wait until we consume: 100 message(s) then we will shutdown
While the consumer is starting up, it activates an embedded broker with broker
name, broker1, and attempts to connect to its
peers using a multicast discovery agent.
Start a producer that sends messages to the TEST.FOO queue on the group peer
group. To start the producer, run the producer tool with a peer group URL as
follows:
cd InstallDir/example
ant producer -Durl="peer://group/broker2?persistent=false" -DsleepTime=1000
Where the name of the embedded broker is set to broker2 and the sleep time (time between successive messages) is
set to 1000 ms. When the producer starts up, the output log should include some
lines like the following:
[java] 15:43:27 INFO Establishing network connection between from vm://broker2 to tcp://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 successfully
established between the embedded brokers, broker1 and broker2. The consumer
should now be able to receive the messages sent by the producer.