## Introduction to the VM Protocol

### Overview

The VM protocol enables Java clients running inside the same JVM to communicate with each other inside the JVM, without having to resort to a using a network protocol. The clients still require a broker to mediate the exchange of messages, however. The VM protocol implicitly creates an embedded broker the first time it is accessed. Figure 5.1 shows the basic architecture of the VM protocol.

Figure 5.1. Clients Connected through the VM Protocol

### Embedded broker lifecycle

The embedded broker has the following lifecycle:

1. The first client that attempts to access a specific broker (for example, `broker1`) causes the broker to be instantiated. In some cases—for example, if the VM URI contains special broker configuration details—it might be important to control which client instantiates the broker.

2. Subsequent clients connect to the pre-existing embedded broker.

3. After all of the connections are closed by the clients, the embedded broker is automatically shut down.

### Simple URI syntax

A VM URI can be constructed with the following simple URI syntax:

    vm://BrokerName?TransportOptions

Where `BrokerName` specifies the name of the embedded broker to which the client connects. The transport options, `?``TransportOptions`, are specified in the form of a query list, where you can use any of the options shown in Table 5.1 and Table 5.2 .

### Advanced URI syntax

Alternatively, you can construct a VM URI using the following advanced URI syntax:

    vm://(BrokerConfigURI)?TransportOptions

Where `BrokerConfigURI` is a broker configuration URI (see Broker configuration URI ). With this syntax, you can use only the options shown in Table 5.1 .

### Transport options

Table 5.1 shows the transport options you can use with either the simple or advanced VM URI syntax.

Table 5.1. VM Transport Options (for All URI Syntaxes)

Option | Description
--- | ---
`marshal` | If `true`, forces each command sent over the transport to be marshalled and unmarshalled using the specified wire format. Default is `false`.
`wireFormat` | The name of the wire format to use.
`wireFormat.*` | Properties prefixed by `wireFormat.` configure the specified wire format.

Table 5.2 shows transport options that are valid only for the simple URI syntax.

Table 5.2. VM Transport Options (for Simple URI Syntax Only)

Option | Description
--- | ---
`broker.*` | Properties prefixed by `broker.` configure the embedded broker. You can specify any of the standard broker options (see TABLE) in this way.
`brokerConfig` | Specifies an external broker configuration file. For example, to pick up the broker configuration file, `activemq.xml`, you would set `brokerConfig` as follows: `brokerConfig=xbean:activemq.xml`.

### Broker options

Table 5.3 shows the broker options.

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

### Example URIs

You can construct the following example URIs using the simple syntax:

- Basic VM URI .

- Simple URI with broker options .

- Simple URI with external configuration file .

### Basic VM URI

To connect to the embedded broker with broker name, `broker1`, you can use the following URI:

    vm://broker1

### Simple URI with broker options

To create and connect to the embedded broker, `broker1`, where you want the broker to have a non-persistent message store, use the following URI:

    vm://broker1?broker.persistent=false

Evidently, the broker options (such as `broker.persistent`) can only be taken into account, if the VM URI makes the first connection to the embedded broker (thus causing the broker to be instantiated). If the VM URI connects to an existing embedded broker, it is too late to change the broker configuration.

### Simple URI with external configuration file

To create and connect to the embedded broker, `broker1`, where the broker is to be configured by the file, `activemq.xml`, use the following URI:

    vm://broker1?brokerConfig=xbean:activemq.xml

Where the `brokerConfig` option enables you to specify the location of the external configuration file, `activemq.xml`.

### Broker configuration URI

The broker configuration URI is the very same URI that you use on the command line to configure the standalone broker, `activemq`. There are three different URI schemes supported for broker configuration: `broker:`, `properties:`, and `xbean:`. Of these URI schemes, the `broker:` URI is the most useful one for constructing VM URIs.

The broker configuration URI has the following syntax:

    broker://(TransportURI, ..., network:NetworkURI,
    ...)/BrokerName?BrokerOptions

Where the `broker://` prefix is immediately followed by a list of URIs in parentheses. Inside the URI list you can put URIs, `TransportURI`, for the broker’s transport endpoints and URIs, `network:``NetworkURI`, for the broker’s network connectors. This is followed by the broker’s name, `BrokerName`, and any broker options from Table 5.3 .

### Advanced example URI

The following VM URI uses the advanced URI syntax to create and connect to an embedded broker, where the broker is configured using a broker configuration URI.

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