## Peer Protocol

### Overview

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.

Figure 7.1. Peer Protocol Endpoints with Embedded Brokers

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

### Discovering peer endpoints

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.

### 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 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`).

### Broker options

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

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

### Example of using the peer protocol

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 with embedded broker

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 up producer with embedded broker

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.