JavaEnterprise JavaThe Fundamentals of Mule Configuration

The Fundamentals of Mule Configuration content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Mule, the open source messaging framework for enterprise integration, requires significant configuration using XML files. This article provides an introduction to Mule configuration. First, it covers the basics of Mule you will need to understand.

Author’s Note: Many of the links to further Mule documentation require a account.

What Is Mule?

Mule is a transport-agnostic, Java-based messaging framework that allows disparate applications to connect without having to call each other directly. Mule supports multiple threading/messaging models (staged event-driven architecture, or SEDA, is the default), input and output to various transports (email, files, databases, etc.), and web services through protocols such as SOAP (see Figure 1).

Mule Components

This section defines various components that make up the Mule messaging framework and explains how to configure them using XML. The discussion refers to Mule version 2.x.

Service Component

Services are the primary Mule artifact used to implement integration solutions. A service component is a piece of code that implements some business functionality (see Figure 3). One of the primary advantages of Mule is that service components can be simple POJOs with no pre-existing external interface other than the invocation of its methods. In early versions of Mule (1.x), service components were called universal message objects (UMO).

Using the Mule Client

The Mule client is a simple interface for Java clients to send and receive messages programmatically from a Mule server and other applications. In general, messages are triggered by an external occurrence such as a message being received on a queue or a file being copied to a directory.

The Mule client helps test the message flow by injecting messages for unit or load testing. If you use the Mule client in the same classloader (e.g., a web app or Mule standalone), the client will have access to the server configuration. For example, if you had this endpoint defined in your server configuration file:

<http:endpoint host=”″ port=”80″ path=”/services” name=”serviceEndpoint”/>
Then this endpoint would be accessible by the Mule client:
MuleClient client = new MuleClient();
client.dispatch(“serviceEndpoint”, dataObject, null);
If you are running the Mule client in standalone mode, you configure it with its own Mule XML configuration file and pass in these files when the client is created:
MuleClient client = new MuleClient(“http-client-config.xml, shared-client-config.xml”);

Putting It All Together

Mule uses the configuration file to determine the data flow, as well as which components, routers, transports, and transformers to use (see Figure 8). An endpoint defines the transport to use. Below is the flow of an event through a Mule application:

  1. A client initiates the process by invoking a URL (such as http://mycompany/order:8081).
  2. A declared HTTP Inbound transport picks up the message and checks if any transformation of the input (the URL in this case) is specified in the inbound router.
  3. If transformation is needed, a transformer such as HttpRequestToNameString is applied to the message.
  4. The message is dispatched to the service component for business processing.
  5. The Customer Data Service component retrieves customer information from a database.
  6. The outbound router routes the result of the service component to determine where the message should be dispatched. For example, an outbound router may specify a JMS endpoint so that the message is put on a queue or a topic.
  7. The outbound transport picks up the message and checks if any transformation is needed. The inbound router of the receiving service receives the message, and processing continues with the message as in step 2.

Configuration Settings

The knitting of service components into an application is done in a Mule configuration file. Mule configuration settings are the responsibility of the developer. They include:

  • The declaration of service components
  • The endpoint(s) on which the service will receive messages
  • Any transformers to use before presenting messages to a service component
  • The outbound endpoint(s) where messages will go next
  • Routing information for the message to dispatch it to the next service component

Declaring Service Components

  • <component> – A Mule component is configured by specifying the implementation class name. Mule creates a new instance of the class for each message the component receives. Note that it is the Java class that is specified, not a specific method.
    <component class=””/>

  • <pooled-component> – A Mule pooled component configures Mule to create a pool of that component. The object factory that creates a single instance of the object can also be specified.
    <pooled-component class=””/>
    <singleton-object class=””/>

  • <entry-point-resolver-set/> – Mule can be configured with an entry point resolver to dynamically choose the component method to invoke based on the payload of the message.
    <component class=””>

  • <callable-entry-point-resolver> – This entry point resolver is for components that implement the org.mule.api.lifecycle.Callable interface. A component can implement the Callable interface to override any dynamic resolution and call the interface method implementation instead.
  • <custom-entry-point-resolver-set> – This custom entry point resolver can be implemented with a class that implements the org.mule.api.model.EntryPointResolverSet interface. To specify the method explicitly on your endpoint, you can use the method argument on the endpoint, such as:
    <ejb:endpoint host=”localhost” port=”1099″ object=”SomeService” method=”remoteMethod”/>

  • Mule provides several simple components that are useful for testing and initial prototyping, such as <log-component/>, which outputs all received messages as strings to the console.

    Configuring Endpoints

  • <endpoint> – Use this to declare an endpoint having a global scope throughout the entire Mule application. Within a service, ref= is used to reference the global endpoint.
    <file:endpoint name=”fileReader” reverseOrder=”true” 
    <service name=”Priority1″>
    <file:inbound-endpoint ref=”fileReader” path=”/var/prio1″/>
    <service name=”Priority2″>
    <file:inbound-endpoint ref=”fileReader” path=”/var/prio2″/>

  • <inbound-endpoint> – This channel is where a service component receives events. It can include the transport to use, the address, the path, or the resource (any valid URI).
    <inbound-endpoint address=”udp://localhost:65432″/>
    <inbound-endpoint address=”jms://test.queue”/>

  • <outbound-endpoint> – This channel is where data returned by the component is sent.
    <outbound-endpoint address=”smtp://”/>
    <outbound-endpoint address=”smtp://”/>

    Configuring Inbound Routers

  • <selective-consumer-router> – This router applies one or more filters to the incoming message. If the filters match, the message is forwarded to the component.
    <mulexml:jxpath-filter expression=”msg/header/resultcode = ‘success'”/>
    <jms:endpoint topic=”error.topic”/>

  • <idempotent-receiver-router> – This router ensures that only unique messages are received by a service by checking the unique message ID of the incoming message. The ID can be generated from the message using an expression defined in the idExpression attribute.
    <secure-hash-idempotent-receiver-router messageDigestAlgorithm=”SHA26″>
    <simple-text-file-store directory=”./idempotent”/>

  • <secure-hash-idempotent-receiver> – This router ensures that only unique messages are received by a service by calculating a hash code of the message contents.
    <secure-hash-idempotent-receiver-router messageDigestAlgorithm=”SHA26″>
    <simple-text-file-store directory=”./idempotent”/>
    For an exhaustive list, refer to this link.

    Configuring Outbound Routers

  • <filtering-router> – This router uses filters to determine whether the message matches particular criteria.
    <outbound matchAll=”true”>
    <endpoint address=”jms://deposit.queue”/>
    <jms:outbound-endpoint queue=”large.deposit.queue”/>
    <mulexml:jxpath-filter expression=”deposit/amount >= 100000″/>

  • <pass-through-router> – This router matches all messages and simply sends or dispatches messages via the one endpoint that is configured.
    <smtp:outbound-endpoint to=””/>

  • <static-recipient-list-router> – This router can be used to send the same message to multiple endpoints over a single endpoint, or to implement routing-slip behavior where the next destination for the message is determined from message properties or the payload.
    <payload-type-filter expectedType=”javax.jms.Message”/>
    For an exhaustive list, refer to this link.

    Configuring a Transport/Connector

    You can declare values equivalent to an endpoint URI to describe the connection information for the transport.
    <rmi:endpoint name=”BadType” host=”localhost” port=”1099″ object=”MatchingUMO” method=”reverseString”/>
    <jms:inbound-endpoint queue=”test.queue”/>
    <ssl:endpoint name=”clientEndpoint” host=”localhost” port=”60198″ synchronous=”true”/>
    <quartz:endpoint name=”qEP6″ repeatCount=”10″ repeatInterval=”1000″ jobName=”job”/>
    Alternatively, you can define a connector configuration using the <connector> element. Mule uses standard components such as Work Manager for efficient pooling of thread resources and for more control over thread usage. For errors, you declare an exception strategy as well as transactional behavior.
    <vm:connector name=”VMConnector”>

    <vm:outbound-endpoint path=”systemErrorHandler”/>

    Configuring Transformers

    You can configure a transformer locally or globally. A local transformer is defined on the endpoint where it is applied, while a global transformer is referenced when needed. The following code defines two global transformers (see definitions below).
    <xm:xml-to-object-transformer name=”XMLToExceptionBean” 
    <custom-transformer name=”ExceptionBeanToErrorMessage”

    • <append-string-transformer> appends a string to an existing string.
      <append-string-transformer name=”myAppender” message=” … that’s good to know!”/>

    • <xslt-transformer> processes a XML payload through XSLT.
      <mulexml:xslt-transformer name=”xslt” xslFile=”./conf/xsl/cd-listing.xsl”>
      <mulexml:context-property key=”title” value=”#[header:ListTitle]”/>
      <mulexml:context-property key=”rating” value=”#[header:ListRating]”/>
    For exhaustive list, refer to this link.


    This article has covered the basics of Mule and how to configure Mule components using XML. As well as being a platform for SOA, Mule also offers a SOA governance (registry/repository) facility called Mule Galaxy. It also supports administering and managing Mule deployments within an enterprise via Mule HQ.


    Thanks to Ron Gates for proofreading this article.

    About the Author

    Thribhuvan Thakur is a senior software engineer/Architect at Southwest Airlines with 14 years of experience in design and development. He has been working with Java since its inception, and with JMS since 1999. Thakur is a Sun Certified Java Programmer, Sun Certified Java Developer and Sun Certified J2EE Architect. He holds a Masters in Computer Science from the University of North Texas.

  • Get the Free Newsletter!

    Subscribe to Developer Insider for top news, trends & analysis

    Latest Posts

    Related Stories