VM Transport Reference

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

You can use the Java Virtual Machine (VM) transport for intra-JVM communication between Mule flows. This transport by default uses in-memory queues but can optionally be configured to use persistent queues. Note: VM file persistency does not work on clusters.

Note: VM queue persistence behaves differently on CloudHub. See the CloudHub Fabric documentation for more details.

VM Transport Info

Area Value Description

Area	Value	Description
Transport	`VM`	Lists the name or protocol of the transport
Doc	JavaDoc SchemaDoc	Links to the JavaDoc and SchemaDoc for the transport.
Inbound		Whether the transport can receive inbound events and can be used for an inbound endpoint.
Outbound		Whether the transport can produce outbound events and be used with an outbound endpoint.
Request		Whether this endpoint can be queried directly with a request call.
Transactions	`XA`	Whether transactions are supported by the transport. Transports that support transactions can be configured in either local or distributed two-phase commit (XA) transaction.
Streaming		Whether this transport can process messages that come in on an input stream. This allows for very efficient processing of large data. For more information, see Streaming.
Retries		Whether this transport supports retry policies. Note that all transports can be configured with Retry policies, but only the ones marked here are officially supported by MuleSoft.
MEPs	`one-way`, `request-response`	Message Exchange Patterns supported by this transport.
Default MEP	`one-way`	The default MEP for endpoints that use this transport that do not explicitly configure a MEP
Maven Artifact	See text	The group name a artifact name for this transport in Maven. Value: `org.mule.transports:mule-transport-vm`

Transport

VM

Lists the name or protocol of the transport

Doc

JavaDoc SchemaDoc

Links to the JavaDoc and SchemaDoc for the transport.

Inbound

check

Whether the transport can receive inbound events and can be used for an inbound endpoint.

Outbound

check

Whether the transport can produce outbound events and be used with an outbound endpoint.

Request

check

Whether this endpoint can be queried directly with a request call.

Transactions

XA

Whether transactions are supported by the transport. Transports that support transactions can be configured in either local or distributed two-phase commit (XA) transaction.

Streaming

check

Whether this transport can process messages that come in on an input stream. This allows for very efficient processing of large data. For more information, see Streaming.

Retries

Whether this transport supports retry policies. Note that all transports can be configured with Retry policies, but only the ones marked here are officially supported by MuleSoft.

MEPs

one-way, request-response

Message Exchange Patterns supported by this transport.

Default MEP

one-way

The default MEP for endpoints that use this transport that do not explicitly configure a MEP

Maven Artifact

See text

The group name a artifact name for this transport in Maven. Value:
org.mule.transports:mule-transport-vm

Namespace and Syntax

XML Namespace

xmlns:vm="http://www.mulesoft.org/schema/mule/vm"

XML Schema Location

http://www.mulesoft.org/schema/mule/vm
http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd

Connector Syntax

VM with persistent queues:

<vm:connector name="persistent">
   <vm:queue-profile maxOutstandingMessages="500">
       <default-persistent-queue-store/>
   </vm:queue-profile>
</vm:connector>

VM with in-memory queues:
```
<vm:connector name="memory" />
```

Endpoint Syntax

Prefixed endpoint:
```
<vm:outbound-endpoint path="out"/>
```
Non-prefixed URI:
```
<outbound-endpoint address="vm://out">
```

Transformers

There are no specific transformers for the VM transport.

Considerations

The VM transport has often been used to implement complex integrations made up of multiple applications. Improvements in Mule 3 obviate the need for VM in many cases. You can use Flow References to directly reference one flow from another without a transport in the middle.

VM is still useful in certain situations. Suppose, for instance, that most of the parts of your solution are local, but some need to be decoupled for testing, or because some need to be made remote.

WARNING

Each application in a Mule instance has its own, unique set of VM endpoints. Thus the VM transport can only handle communications within one same application, or between applications that share a VM connector defined in a same domain.

Features

The in memory (VM) transport has two modes of operation: One for use with request-response and another for use with one-way endpoints.

request-response:

When using request-response endpoints, messages are delivered directly from an outbound vm endpoint to the inbound vm endpoint that is listening on the same path. This delivery is blocking and occurs in the same thread. If there is no inbound request-response VM endpoint in the same Mule application that is listening on this path, then dispatching a message from the outbound endpoint fails.

one-way:

When using one-way endpoints, messages are delivered to the corresponding inbound endpoint via a queue. This delivery is non-blocking. If there is no inbound one-way endpoint in the same Mule application listening on this path, then, although dispatching of the message succeeds, the message remains in the queue. By default, this queue is in memory, but it is also possible to configure a persistent queue that uses the file system as its persistence mechanism.

Usage

To use VM endpoints, follow these three steps. Each of these steps is explained in further detail, below.

Add the MULE VM namespace to your configuration:
- Define the VM prefix using xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
- Define the schema location with http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd
Optionally, define one or more connectors for VM endpoints.
- Create a VM connector:
  <vm:connector name="vmConnector"/>
  If none is created, all VM endpoints use a default connector.
Create VM endpoints.
- Messages are received on inbound endpoints.
- Messages are sent to outbound endpoints.
- Both kinds of endpoints are identified by a path name or address.

Declaring the VM Namespace

To use the VM transport, you must declare the VM namespace in the header of the Mule configuration file. For example:

VM Transport Namespace Declaration

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:vm="http://www.mulesoft.org/schema/mule/vm"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/current/mule-vm.xsd">

Configuring VM Connectors

The configuration of the VM connector is optional. Configuring a connector allows you to configure a Queue Profile. See Managing Queues for more information.

How Queues are Used in VM Transports

By default, Mule uses queues in the asynchronous processing of messages that use the VM transport. The VM transport can be used for flows, where all the message processing is done in the JVM in which the Mule instance is running.

When requests come into a receiver for a flow that uses the VM transport, they are stored on a queue until threads from a thread pool can pick them up and process them. The receiver thread then releases back into the receiver thread pool so it can carry another incoming message. Each message waiting in the queue can be assigned a different thread from the pool of threads.

You can configure a queue for a VM transport through a queue profile. The queue profile specifies how the queue behaves. Typically, you do not need to configure the queue profile for performance, since the default configuration is usually sufficient, that is, the queue is not the bottleneck. (Performance is usually limited by the component or one of the endpoints.) For other reasons, you still might want to specify a maximum queue size, or enable persistence on the queue (which is disabled by default).

You configure the queue profile using the <queue-profile> element. For a VM transport, you specify the <queue-profile> element on the connector.

Attributes of the <queue-profile> element:

Name: maxOutstandingMessages:
- Type: integer
- Required: No
- Default: 0
- Defines the maximum number of messages that can be queued. The default, 0, means there is no limit on the number of messages that can be queued.
Name: persistent:
- Type: boolean
- Required: No
- Default: false
- Specifies whether Mule messages are persisted to a store. Primarily, this is used for persisting queued messages to disk so that the internal state of the server is mirrored on disk in case the server fails and needs to be restarted.

Based on the persistent attribute value you specify, Mule chooses a persistence strategy to use for the queue. By default, Mule use two persistence strategies:

MemoryPersistenceStrategy, which is a volatile, in-memory persistence strategy.
FilePersistenceStrategy, which uses a file store to persist messages to a (non-volatile) disk, and therefore maintains messages even if Mule is restarted.

Configuring Endpoints

Endpoints are configured as with all transports.

The VM transport specific endpoints are configured using the vm namespace and use a path or address attribute. For example:

<vm:outbound-endpoint path="out" exchange-pattern="one-way"/>

If you need to invoke a VM endpoint from Mule client, use an endpoint URI. The format of an endpoint uri for VM is as follows:

vm://<your_path_here>

Using Transactions

One-way VM queues can take part in distributed XA Transactions. To make a VM endpoint transactional, use a configuration like the following:

<flow>
  <vm:inbound-endpoint address="vm://dispatchInQueue">
    <vm:transaction action="BEGIN_OR_JOIN"/>
  </vm:inbound-endpoint>
</flow>

Using XA requires that you add a transaction manager to your configuration. For more information, see Transaction Management.

Transactional Inbound VM Queues

Inbound VM endpoints support fully transactional flows. For instance, the following configuration creates a VM queue (because the inbound endpoint is one-way), and processes messages read from this queue synchronously and transactionally:

<flow name="transactionalVM">
    <vm:inbound-endpoint path="orders" exchange-pattern="one-way">
        <vm:transaction action="ALWAYS_BEGIN"/>
    </vm:inbound-endpoint>
    <component class="com/mycomany.ProcessOrder"/>
</flow>

XA transactions are also supported:

<flow name="transactionalVM">
    <vm:inbound-endpoint path="orders" exchange-pattern="one-way">
        <xa-transaction action="ALWAYS_BEGIN"/>
    </vm:inbound-endpoint>
    <component class="com/mycomany.ProcessOrder"/>
    <jms:outbound-endpoint ref="processedOrders">
        <xa-transaction action="ALWAYS_JOIN"/>
    </jms:outbound-endpoint>
</flow>

Example Configurations

Example Usage of VM Endpoints

<vm:connector name="persistentVmConnector" queueTimeout="1000"> (1)
   <queue-profile maxOutstandingMessages="100" persistent="true"/>
</vm:connector>

<flow>
    <vm:inbound-endpoint path="in" exchange-pattern="request-response"/> (2)
    <component class="org.mule.ComponentClass"/>
    <vm:outbound-endpoint exchange-pattern="one-way" path="out" connector-ref="persistentVmConnector" /> (3)
</flow>

1	Customized connector configuration with a queue profile and queueTimeout.
2	The first VM endpoint (inbound) uses a request-response exchange pattern and the default connector configuration, thus no connector definition is needed.
3	The second VM endpoint (outbound) uses a one-way exchange pattern and the customized connector configuration in #1.

Configuration Reference

VM Transport

The VM transport is used for intra-VM communication between components managed by Mule. The transport provides options for configuring VM transient or persistent queues.

Connector

The following sections list attributes and child elements of the connector.

Attributes of connector

queueTimeout:

Type: positiveInteger
Required: Yes
The timeout setting for the queue used for asynchronous endpoints

Child Elements of connector

queueProfile, Cardinality: 0..1, DEPRECATED. USE "<queue-profile>" instead.
queue-profile, Cardinality: 0..1, Configures the properties of this connector’s queue (see Managing Queues).

Inbound Endpoint

The endpoint on which this connector receives messages from the transport.

Attributes of inbound-endpoint

Name: path
Type: string
Required: No
The queue path, such as dispatchInQueue to create the address vm://dispatchInQueue.

No child elements.

Outbound Endpoint

The endpoint to which this connector sends messages.

Attributes of outbound-endpoint

Name: path
Type: string
Required: No
The queue path, such as dispatchInQueue to create the address vm://dispatchInQueue.

No child elements.

Endpoint

An endpoint "template" that can be used to construct an inbound or outbound endpoint elsewhere in the configuration by referencing the endpoint name.

Attributes of endpoint

Name: path
Type: string
Required: No
The queue path, such as dispatchInQueue to create the address vm://dispatchInQueue.

No child elements.

Transaction

The transaction element configures a transaction. Transactions allow a series of operations to be grouped together so that they can be rolled back if a failure occurs. For more information, see Transaction Management.

No child elements.

Schema

Schemadocs

Javadoc API Reference

The Javadoc for this module can be found here:

VM JavaDoc

Maven

The In-Memory Transport can be included with the following dependency:

<dependency>
   <groupId>org.mule.transports</groupId>
   <artifactId>mule-transport-vm</artifactId>
</dependency>

Best Practices

Be certain that inbound request-response endpoints are paired with outbound request-response endpoints and inbound one-way endpoints are paired with outbound one-way endpoints.

Consider setting up your application following a reliability pattern.