Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.4)
  3. Reference
  4. Transports Reference

  5. VM Transport Reference

VM Transport Reference

The VM transport can be used 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, however, that VM file persistency does not work on clusters.)

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

Transport Info

Transport Doc Inbound Outbound Request Transactions Streaming Retries MEPs Default MEP Maven Artifact

VM

JavaDoc SchemaDoc

check

check

check

XA

check

one-way, request-response

one-way

org.mule.transports:mule-transport-vm

Legend

Transport - The name/protocol of the transport Docs - 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 (via MuleClient or the EventContext) Transactions - 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. Retry - 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 - Message Exchange Patterns supported by this transport Default MEP - The default MEP for endpoints that use this transport that do not explicitly configure a MEP Maven Artifact - The group name a artifact name for this transport in Maven

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/3.4/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 needs to be decoupled for testing, or because some needs to be made remote.

WARNING

Each application in a Mule instance has its own, unique set of VM endpoints. Thus the VM transport cannot be used to communicate between different Mule applications.

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 listening on this path, then dispatching of the 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.

  1. 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/3.4/mule-vm.xsd

  2. 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.

  3. 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/3.4/mule.xsd
               http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/3.4/mule-vm.xsd">

Configuring VM Connectors

The configuration of the VM connector is optional. Configuring a connector allows you to configure a Queue Profile.

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 is then released 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 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.

Here are the attributes of the <queue-profile> element:

Name Type Required Default Description

maxOutstandingMessages

integer

no

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.

persistent

boolean

no

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 process 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"> ❶
   <queue-profile maxOutstandingMessages="100" persistent="true"/>
</vm:connector>

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

The first vm endpoint ❷ (inbound) uses a request-response exchange pattern and the default connector configuration, thus no connector definition is needed.
The second vm endpoint ❸ (outbound) uses a one-way exchange pattern and a customized connector configuration ❶ with a queue profile and queueTimeout.

Configuration Reference

Element Listing

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

Table 1. Attributes of <connector…​>
Name Type Required Default Description

queueTimeout

positiveInteger

no

The timeout setting for the queue used for asynchronous endpoints
Table 2. Child Elements of <connector…​>
Name Cardinality Description

queueProfile

0..1

DEPRECATED. USE "<queue-profile>" instead.

queue-profile

0..1

Configures the properties of this connector’s queue (see Configuring Queues).

Inbound endpoint

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

Table 3. Attributes of <inbound-endpoint…​>
Name Type Required Default Description

path

string

no

The queue path, such as dispatchInQueue to create the address vm://dispatchInQueue.

Outbound endpoint

The endpoint to which this connector sends messages.

Table 4. Attributes of <outbound-endpoint…​>
Name Type Required Default Description

path

string

no

The queue path, such as dispatchInQueue to create the address vm://dispatchInQueue.

Endpoint

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

Table 5. Attributes of <endpoint…​>
Name Type Required Default Description

path

string

no

The queue path, such as dispatchInQueue to create the address vm://dispatchInQueue.

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.

Schema

Javadoc API Reference

The Javadoc for this module can be found here:

VM

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.