By Jos Dirksen

Mule is one of the most mature open source enterprise service busses (ESBs) out there. It provides an easy to use, lightweight ESB that can easily be integrated with a large amount of technologies. Mule also provides a rich set of routers, transformers, and filters which you can use in your own integration flows. This reference card will provide an overview of the architecture of Mule and show the different routers, transformers, and filters that are available, and will show how to use them by using example configurations.

To make it easier to understand Mule, let's first have a quick look at Mule's architecture.

As you can see, the basic concepts of Mule are pretty straight forward. In Mule's architecture we have the following main parts:

Basically what happens is:

1. A transport receives a message. For instance a message has been put on a JMS queue the transport is listening on.
2. Before the message is sent to the inbound router, it's first transformed (if needed) to the required format.
3. Then the message is processed by the inbound router. For instance we could have a "selective consumer" which only accepts messages that are sent by applications we trust.
4. After the inbound router, the message is sent to the component, which applies its business logic to it.
5. After the service is done processing, the message is sent to the outbound router. This router determines where to next send the message. We could for instance split this message into multiple parts and send those to different targets.
6. And finally we can transform the message once again, and let the transport handle all the connectivity details.

Mule's configuration is based on Spring and uses XML schemas to provide code completion. This makes it very easy to write your integration flows. Let's start with a very basic Mule configuration:

<mule xmlns="http://www.mulesource.org/
schema/mule/core/2.1" xmlns:xsi="http://www.
w3.org/2001/XMLSchema-instance" xmlns:vm="http://
www.mulesource.org/schema/mule/vm/2.1" xmlns:file="http://www.mulesource.org/schema/mule/file/2.1"
xsi:schemaLocation="

        http://www.mulesource.org/schema/mule/core/2.1
        http://www.mulesource.org/schema/mule/core/2.1/mule.xsd
        http://www.mulesource.org/schema/mule/vm/2.1
        http://www.mulesource.org/schema/mule/vm/2.1/mule-vm.xsd
        http://www.mulesource.org/schema/mule/file/2.1
        http://www.mulesource.org/schema/mule/file/2.1/mule-file.xsd">

<model name="refcheat-model">
 <service name="basic-service">
   <
     inbound>
      <file:inbound-endpoint name="example-in"
        path="work/example/in" />
  </inbound>
  <component>
      <singleton-object class="dzone.Reverser" />
  </component>
  <outbound>
     <pass-through-router>
       <file:outbound-endpoint name="example-out"

Configuring Mule, Continued

           path="work/example/out" />
        </pass-through-router>
      </outbound>
    </service>
  </model>
</mule>

You can see that at the top of the file we've declared a number of Mule specific namespaces. Mule provides XML schemas for all its features. We'll focus on Mule core sheets, but also show you a couple of features from the vm and file schemas. After the namespaces declaration we define a <model> element. A model in Mule is a container element for a number of services. In the model element you can see that we've defined a single service where the parts we've discussed in the introduction appear again. In this case we've configured a file transport which will read messages from the file system, pass it on to a component which will reverse the content of the input file, and finally use an outbound router, with a single transport to write the now reversed string back to the file system. We didn't specify an inbound-router. If we don't specify one, all the messages are simply processed by the specified component.

In this example the inbound endpoint uses the File transport. Mule provides several standard transports you can use, as described in the next section. For details on a specific transport, see http://www.mulesource.org/display/MULE2USER/Available+Transports

We won't go into the details of all the endpoints. We'll just provide an overview of the transports available.

Mule Transports

Here is an overview of the transports Mule provides.

Mule Expressions

With expressions Mule allows you to access certain properties from the message or from the payload, and based on these

Mule Expressions, Continued

properties, execute certain actions. There are, for instance, routers, filters, and transformers that work based on these expressions. Below are a couple of examples of how these expressions can be configured. The first one shows how to use an expression on a filter.

<expression-filter evaluator="header" expression="priority=1"/>

This one shows how you can use expressions for routing.

<expression-recipient-list-router
evaluator="xpath"
           expression="/header/routing/recipient" />

Available Evaluators

To use an expression, you specify an evaluator (the expression type) and the expression itself.

Mule provides a number of transformers which you can use in your own integration flows. Before we look at the transformers provided by Mule, let's first look at how you configure transformers. In the following listings you can see the different ways we can configure and reference a transformer:

<custom-transformer class="dzone.CustomTransformer"
                name="myCustomTransformer"/>
<xml:xslt-transformer name="xsltTransformer"
                xsl-file="resources/xslt/transform.xslt"/>
<file:file-to-string-transformer name="fileToString"/>
...
<file:inbound-endpoint name="example-in"
                path="work/example/in"
transformer-refs="fileToString
                myCustomTransformer xsltTransformer"/>

You can add transformers as a transformers-refs attribute to any endpoint. If you want to do this you first have to make sure you've already defined them. The transformers will be executed in the same sequence as they are listed in the attribute. Note that most of the transports have their own default transformer which is executed if you don't specify transformers yourself. If you do specify transformers yourself you have to make sure you also add the default one, which in this case is the fileToString transformer.

<file:inbound-endpoint name="example-in" path="work/
  example/in">
        <transformer ref="fileToString"/>
        <custom-transformer class="dzone.
     CustomTransformer"/>
        <transformer ref="xsltTransformer"/>
</file:inbound-endpoint>

In the previous listing we added the transformers as child elements of the endpoint. This has the same effect as the previous configuration, but now we don't have to define all the transformers before hand, but can define them inline.

<file:inbound-endpoint name="example-in" path="work/
 example/in">
  <transformers>
   <transformer ref="fileToString"/>
   <transformer ref="myCustomTransformer"/>
   <custom-transformer class="dzone.
     CustomTransformer"/>
  </transformers>
  <response-transformers>
   <base64-encoder-transformer/>
   <transformer ref="stringToFile"/>
 </response-transformers>
</file:inbound-endpoint>

<transformers> element. What you also see is that we've added a response-transformers element (which is also available as an attribute <response-transformers-refs>). A response-transformer does the same as a normal transformer, but is applied specifically on the response to a synchronous call.

Synchronous or asynchronous
Starting from Mule 2.1 you need to explicitly define whether a message is processed synchronously or asynchronously on both the inbound and outbound endpoints. You can do this by using the synchronous attribute on an endpoint. If you specify synchronous="true" Mule will return a result from the call. If you specify synchronous="false" no result will be returned. This value defaults to false. So by default Mule operates asynchronously. You can, however, override this by adding <configuration defaultSynchronousEndpoints="true"/> to your configuration file.

Available Transformers

The following table lists all the transformers from the Mule core and the Mule XML namespace. They can be used in the manner explained earlier.

Mule provides a set of default filters you can use to determine whether a message should be sent to a destination or whether it's read from a destination. Defining a filter works in the same manner as defining a transformer. You can define them globally and reference them from an endpoint.

<regex-filter name="regex" pattern="(^my)(.*)(txt$
  )"/>
<custom-filter name="custom" class="dzone.
  CustomFilter"/>
....
<file:inbound-endpoint name="example-in"
  path="work/example/in-1">
        <filter ref="regex"/>
</file:inbound-endpoint>
<file:inbound-endpoint name="example-in-2"
  path="work/example/in-2">
        <payload-type-filter expectedType="java.
         lang.String"/>
</file:inbound-endpoint>

In the previous example the message will only be received if it passes the filter. Mule also provides a set of logical filters which you can use to combine filters using NOT, AND and OR semantics.

<not-filter>
  <filter ref=”custom”/>
</not-filter>
<and-filter>
<payload-type-filter expectedType="java.lang.
   String"/>
  <filter ref="regex"/>
</and-filter>
<or-filter>
<payload-type-filter expectedType="java.lang.
    String"/>
  <payload-type-filter expectedType="java.lang.
    StringBuffer"/>
</or-filter>

Available Filters

The following table shows an overview of all the filters from the core and the XML schema. Note that certain transports have their own custom filters you can use.

Routers are used in Mule to determine how messages are received by a component and to where they are sent after the component has processed them. Mule implements most of the patterns from the Enterprise Integration Patterns book (Addison-Wesley), and for most uses the same names. We have inbound routers and outbound routers. In this section, we'll first look at the inbound routers, how to configure them, and which ones are available. After that, we'll look at the outbound routers and do the same thing. First let's look at how to configure an inbound router.

<inbound>
   <file:inbound-endpoint path="work/test/in"/>
   <idempotent-secure-hash-receiver-router/>
</inbound>

You define the inbound router on the inbound element in the Mule service configuration. This means that every message that is received on any of the inbound endpoints is processed by the inbound router, before it's processed by the configured component.

Available Inbound Routers

Outbound routers are configured on the outbound element:

<outbound>
  <static-recipient-list-router>
    <file:outbound-endpoint path="work/example/
     out" />
    <vm:outbound-endpoint path="example.out" />
  </static-recipient-list-router>
</outbound>

In this example we define an outbound router on the outbound element, and defined a static-recipient-list-router which sends the message that is received from the component to all the specified endpoints.

Available Outbound Routers

Available Outbound Routers, Continued

So far we've seen all the various parts that make up a Mule service except the component which contains the business logic. For this, Mule provides a number of options.

There are a number of different ways to configure Mule components. Here, we'll show you, and also explain how Mule determines which method to call on your component. Mule provides two types of elements to use in your configuration to specify the component you want to use. The first one is the <component> element: <component class="dzone.Reverser"/>

If you use this configuration, Mule will create a new instance of this class for each request which is received. You can also configure Mule to create objects that can be pooled. For this, don't use the <component> element, but use the <pooled-component> element: <pooled-component class="dzone.Reverser"/>

In the previous examples we directly specified the class as an attribute on the elements. We can also use a different way to specify the implementation of the component. You can do this by using any of the following elements inside the <component> or the <pooled-component> element:

Mule Components, Continued

<component class>
  <prototype-object class="dzone.Reverser"/>
</component>
<component class>
  <singleton-object class="dzone.Reverser"/>
</component>
<component class>
  <spring-object name="springBean"/>
</component>

The first two of these elements allow you to specify whether you want a new object for each message (the <propotype-object> element), or whether you want to create an object to be a singleton (<singleton-object> element), and reused for all the messages. The final option you can use to specify the implementation of the component is the <spring-object> element. Here you can directly reference a spring-bean from the application context.

One thing we haven't discussed yet is how Mule can determine which method to call on your component. Your component often is just a simple spring bean or POJO, which has multiple methods. The default configuration for Mule is to use a set of entry point resolvers to determine which method to call on your bean. Mule uses the following steps to determine which method to invoke on your POJO.

If the previous steps don't result in a single method, Mule will throw an exception. Beside the ones already mentioned, you can configure your own set of entry point resolvers, should the default configuration be insufficient. The following example shows a custom configuration, which you can configure on the model or on a component.

<entry-point-resolver-set>
  <array-entry-point-resolver
      acceptVoidMethods="true" transformFirst="true"/>
  <callable-entry-point-resolver/>
  <method-entry-point-resolver
      acceptVoidMethods="true"/>
</entry-point-resolver-set>

If you create a custom entry-point resolver, you can easily add to this entry point resolver set.

Entry Point Resolvers

The following table shows an overview of the entry point resolvers which are provided by Mule.

Resources