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. |
Transport Info
| Transport | Doc | Inbound | Outbound | Request | Transactions | Streaming | Retries | MEPs | Default MEP | Maven Artifact |
|---|---|---|---|---|---|---|---|---|---|---|
VM |
|
|
|
XA |
|
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.6/mule-vm.xsdConnector 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">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 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/3.6/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/3.6/mule.xsd
http://www.mulesoft.org/schema/mule/vm http://www.mulesoft.org/schema/mule/vm/3.6/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 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.
Here are the attributes of the <queue-profile> element:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
|
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. |
|
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 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"> ❶
<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.
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
Endpoint
An endpoint "template" that can be used to construct an inbound or outbound endpoint elsewhere in the configuration by referencing the endpoint name.
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.
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.