The Fundamentals of Mule Configuration, Page 4

June 10, 2009
By Thribhuvan Thakur, Thribhuvan Thakur

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="org.my.ServiceComponentImpl"/>

<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="org.my.ServiceComponentImpl"/>
<component>
     <singleton-object class="org.my.ServiceComponentImpl"/>
</component>

<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="org.my.PrototypeObjectWithMyLifecycle">
    <entry-point-resolver-set>
        <array-entry-point-resolver/>
        <callable-entry-point-resolver/>
    </entry-point-resolver-set>
</component>

<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" 
    comparator="org.mule.transport.file.comparator.OlderFirstComparator"/>
        ......
<model>
    <service name="Priority1">
        <file:inbound-endpoint ref="fileReader" path="/var/prio1"/>
        ......
    </service>
    <service name="Priority2">
        <file:inbound-endpoint ref="fileReader" path="/var/prio2"/>
        ......
    </service>
</model>

<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://user:secret@smtp.host"/>
<outbound-endpoint address="smtp://user:secret@smtp.host"/>

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.

<inbound>
  <selective-consumer-router>
    <mulexml:jxpath-filter expression="msg/header/resultcode = 'success'"/>
  </selective-consumer-router>
  <forwarding-catch-all-strategy>
    <jms:endpoint topic="error.topic"/>
  </forwarding-catch-all-strategy>
</inbound>

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

<inbound>
    <secure-hash-idempotent-receiver-router messageDigestAlgorithm="SHA26">
        <simple-text-file-store directory="./idempotent"/>
    </secure-hash-idempotent-receiver-router>
</inbound>

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

<inbound>
    <secure-hash-idempotent-receiver-router messageDigestAlgorithm="SHA26">
        <simple-text-file-store directory="./idempotent"/>
    </secure-hash-idempotent-receiver-router>
</inbound>

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">
    <filtering-router>
        <endpoint address="jms://deposit.queue"/>
    </filtering-router>
    <filtering-router>
        <jms:outbound-endpoint queue="large.deposit.queue"/>
        <mulexml:jxpath-filter expression="deposit/amount >= 100000"/>
    </filtering-router>
</outbound>

<pass-through-router> – This router matches all messages and simply sends or dispatches messages via the one endpoint that is configured.

<outbound>
  <pass-through-router>
    <smtp:outbound-endpoint to="ross@muleumo.org"/>
  </pass-through-router>
</outbound>

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

<outbound>
  <static-recipient-list-router>
    <payload-type-filter expectedType="javax.jms.Message"/>
    <recipients>
      <spring:value>jms://orders.queue</spring:value>
      <spring:value>jms://tracking.queue</spring:value>
    </recipients>
  </static-recipient-list-router>
</outbound>

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">
...
  <default-connector-exception-strategy>
    <vm:outbound-endpoint path="systemErrorHandler"/>
  </default-connector-exception-strategy>
</vm:connector>

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" 
    returnClass="org.mule.example.errorhandler.ExceptionBean"/>
<custom-transformer name="ExceptionBeanToErrorMessage" 
    class="org.mule.example.errorhandler.ExceptionBeanToErrorMessage"
returnClass="org.mule.example.errorhandler.ErrorMessage"/>

<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]"/>
</mulexml:xslt-transformer>

For exhaustive list, refer to this link.

Conclusion

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.

Acknowledgements

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.