Chapter 9. VM Transport

Abstract

The VM transport allows clients to connect to each other inside the Java Virtual Machine (JVM) without the overhead of network communication.
The URI used to specify the VM transport comes in two flavors to provide maximum control over how the embedded broker is configured:
  • simple—specifies the name of the embedded broker to which the client connects and allows for some basic broker configuration
  • advanced—uses a broker URI to configure the embedded broker

9.1. Simple VM URI Syntax

URI syntax

The simple VM URI is used in most situations. It allows you to specify the name of the embedded broker to which the client will connect. It also allows for some basic broker configuration.
Example 9.1, “Simple VM URI Syntax” shows the syntax for a simple VM URI.

Example 9.1. Simple VM URI Syntax

vm://BrokerName?TransportOptions
  • BrokerName specifies the name of the embedded broker to which the client connects.
  • TransportOptions specifies the configuration for the transport. They are specified in the form of a query list. Table 9.2, “VM Transport Options” lists the available options.

Broker options

In addition to the transport options listed in Table 9.2, “VM Transport Options”, the simple VM URI can use the options described in Table 9.1, “VM Transport Broker Configuration Options” to configure the embedded broker.

Table 9.1. VM Transport Broker Configuration Options

OptionDescription
broker.useJmxSpecifies if JMX is enabled. Default is true.
broker.persistentSpecifies if the broker uses persistent storage. Default is true.
broker.populateJMSXUserIDSpecifies if the broker populates the JMSXUserID message property with the sender’s authenticated username. Default is false.
broker.useShutdownHook Specifies if the broker installs a shutdown hook, so that it can shut down properly when it receives a JVM kill. Default is true.
broker.brokerNameSpecifies the broker name. Default is localhost.
broker.deleteAllMessagesOnStartupSpecifies if all the messages in the persistent store are deleted when the broker starts up. Default is false.
broker.enableStatisticsSpecifies if statistics gathering is enabled in the broker. Default is true.
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.
Important
The broker configuration options specified on the VM URI are only meaningful if the client is responsible for instantiating the embedded broker. If the embedded broker is already started, the transport will ignore the broker configuration properties.

Example

Example 9.2, “Basic VM URI” shows a basic VM URI that connects to an embedded broker named broker1.

Example 9.2. Basic VM URI

vm://broker1
Example 9.3, “Simple URI with broker options” creates and connects to an embedded broker that uses a non-persistent message store.

Example 9.3. Simple URI with broker options

vm://broker1?broker.persistent=false