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.
The embedded broker has the following lifecycle:
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.
Subsequent clients connect to the pre-existing embedded broker.
After all of the connections are closed by the clients, the embedded broker is automatically shut down.
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
.
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
.
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. |
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. |
You can construct the following example URIs using the simple syntax:
To connect to the embedded broker with broker name, broker1, you can use the following URI:
vm://broker1
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.
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.
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
.