LibraryLink ToToggle FramesPrintFeedback

Introduction to the VM Protocol

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:

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.2 shows transport options that are valid only for the simple URI syntax.


Table 5.3 shows the broker options.


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 .

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