Mule 2.1.2 Users Guide

Space Details
Key: MULE2USER
Name: Mule 2.x User Guide
Description: Mule Users Guide for the 2.x release line
Creator (Creation Date): ross (Jan 30, 2008)

Last Modifier (Mod. Date): tcarlson (Apr 15, 2008)
Available Pages
• ActiveMQ Integration
• Example Archetype
• Home
• About Transports
• Available Transports
• BPM Transport
• CXF Transport
• Building a CXF Web Service
• CXF Transport Configuration Reference
• Enabling WS-Addressing
• Enabling WS-Security
• Supported Web Service Standards
• Using a Web Service Client as an Outbound Endpoint
• Using a Web Service Client Directly
• Using HTTP GET Requests
• Using MTOM
• EJB Transport
• Email Transport
• File Transport
• FTP Transport
• HTTPS Transport
• HTTP Transport
• IMAPS Transport
• IMAP Transport
• JDBC Transport
• JDBC Transport Examples
• JDBC Transport Performance Benchmark Results
• Jetty Transport
• Jetty SSL transport
• JMS Transport
• Mule WMQ Transport
• Multicast Transport
• POP3S Transport
• POP3 Transport
Document generated by Confluence on Jan 30, 2009 11:37 Page 1

• Quartz Transport
• RMI Transport
• Servlet Transport
• SMTPS Transport
• SMTP Transport
• SOAP Transport
• SSL Transport
• STDIO Transport
• TCP Transport
• UDP Transport
• VM Transport
• WSDL Transport
• XMPP Transport
• Bootstrapping the Registry
• Choosing the Right Topology
• Configuration Overview
• Configuration Reference
• Asynchronous Reply Router Configuration Reference
• Catch All Strategy Configuration Reference
• Component Configuration Reference
• Endpoint Configuration Reference
• Exception Strategy Configuration Reference
• Filters Configuration Reference
• Global Settings Configuration Reference
• Inbound Router Configuration Reference
• Model Configuration Reference
• Notifications Configuration Reference
• Outbound Router Configuration Reference
• Properties Configuration Reference
• Service Configuration Reference
• Transactions Configuration Reference
• Configuring a Mule Instance
• Configuring Endpoints
• Mule Endpoint URIs
• Using Filters
• Configuring a Transport
• Configuring Retry Policies
• Configuring Logging
• Configuring Queues
• Configuring Security
• Component Authorization Using Acegi
• Component Authorization Using Spring Security

• Configuring the Acegi Security Manager
• Configuring the Spring Security Manager
• Encryption Strategies
• Setting up LDAP Provider for Acegi
• Setting up LDAP Provider for Spring Security
• Upgrading from Acegi to Spring Security
• Controlling the Infrastructure with Mule Galaxy
• Creating a Custom XML Namespace
• Creating Custom Routers
• Creating Transports
• Transport Archetype
• Transport Service Descriptors
• Deployment Scenarios
• Deploying Mule to WebLogic
• Deploying Mule to WebSphere
• Embedding Mule in a Java Application or Webapp
• JBoss Integration
• Mule as MBean
• Developing Service Components
• Entry Point Resolver Configuration Reference
• Error Handling
• Functional Testing
• Internationalizing Strings
• Introduction to Extending Mule
• Introduction to Testing Mule
• Jmx Management
• Models
• Mule Agents
• Mule Server Notifications
• Profiling Mule
• Resource Adapter
• Suggested Reading
• Third-party Software in Mule
• Transaction Management
• Tuning Performance
• Unit Testing
• Using IDEs
• Using Mule HQ
• Installing Mule HQ with an External Database
• Mule HQ Agent Settings
• Using Mule Modules
• Acegi Module

• JAAS Module
• JBoss Transaction Manager
• Scripting Module
• Spring Extras Module
• SXC Module
• XML Module
• DomToXml Transformer
• JXPath Transformer
• XmlObject Transformers
• XmlToXMLStreamReader Transformer
• XSLT Transformer
• Using Mule with Spring
• Sending and Receiving Mule Events in Spring
• Spring Application Contexts
• Using Spring Beans as Service Components
• Using the Mule Client
• Using the Mule RESTpack
• Architecting RESTful HTTP applications
• Making Sense of REST
• Using Transformers
• Creating Custom Transformers
• Transformers Configuration Reference
• XmlPrettyPrinter Transformer
• Web Services
• Axis
• Axis SOAP Styles
• Axis SOAP Transports
• Axis Transport
• Axis Web Services and Mule
• Configuring Axis
• Proxying Web Services
• Using .NET Web Services with Mule
• Web Service Wrapper
• Working with Services
• Configuring Components
• Configuring Java Components
• Using Interceptors
• Configuring the Service
• MEPs
• Mule Messaging Styles
• Using Message Routers
• Component Bindings
• Using the WireTap Inbound Router

• XML Configuration
• Fiorano Integration
• Integrating SwiftMQ with Mule
• Jaas Security
• JavaRebel Integration
• JBoss Jms Integration
• Module Archetype
• OpenJms Integration
• PGP Security
• Project Archetype
• SeeBeyond JMS Server Integration
• SonicMQ Integration
• Streaming
• Sun JMS Grid Integration
• Tibco EMS Integration
• Using Expressions
• Creating Expression Evaluators
• Expressions Configuration Reference
• WebLogic JMS Integration
• WebSphere MQ Integration

ActiveMQ Integration
This page last changed on Jan 30, 2009 by jackie.wheeler.
ActiveMQ Integration
You can integrate Mule with Apache ActiveMQ. To configure a default embedded broker, you use the
<activemq-connector> or <activemq-xa-connector> (for transaction support) element in your Mule
configuration. These connectors take all the same attributes and elements as the JMS connector with the
additional attribute brokerURL.
<?xml version="1.0" encoding="UTF-8" ?>

<mule xmlns="http://www.mulesource.org/schema/mule/core/2.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:mule="http://www.mulesource.org/schema/mule/core/2.1"
xmlns:jms="http://www.mulesource.org/schema/mule/jms/2.1"
xmlns:test="http://www.mulesource.org/schema/mule/test/2.1"
xsi:schemaLocation="http://www.mulesource.org/schema/mule/test/2.1
http://www.mulesource.org/schema/mule/test/2.1/mule-test.xsd
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/jms/2.1
http://www.mulesource.org/schema/mule/jms/2.1/mule-jms.xsd">
<jms:activemq-connector name="jmsConnector" specification="1.1" brokerURL="vm://localhost"

connectionFactory-ref="activeMqConnectionFactory"/>
<--! or use the XA connector to support transactions -->

<jms:activemq-xa-connector name="xaConnector" maxRedelivery="1">
<dispatcher-threading-profile doThreading="false" />
</jms:activemq-xa-connector>
...
The specification attribute tells Mule to use the JMS 1.1 specification, which is the specification
ActiveMQ supports. The connectionFactory-ref attribute specifies a set of connection factory properties
you define in your Spring configuration.
<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/
schema/beans/spring-beans-2.5.xsd">
<bean id="activeMqConnectionFactory" class="org.activemq.ActiveMQConnectionFactory">

<property name="brokerXmlConfig"
value="classpath:/org/mule/test/activemq-config.xml"/>

</bean>
</beans>
Your ActiveMQ configuration file uses standard settings. For example, to use in-JVM messaging without
persistent queues (very useful for testing), the file might look like this:

<!DOCTYPE beans PUBLIC "-//ACTIVEMQ//DTD//EN" "http://activemq.org/dtd/activemq.dtd">

<beans>
<broker>
<connector>
<serverTransport uri="vm://localhost"/>
</connector>
<persistence>
<vmPersistence/>
</persistence>
</broker>
</beans>

Example Archetype
This page last changed on Dec 16, 2008 by jackie.wheeler.
Example Archetype
[ Configuring Maven ] [ Using the Archetype ] [ The Questions Explained ] [ Example Console Output ] [
Command Line Options ]
Mule provides Maven archetypes that you can use as code templates for your Mule projects. These
templates include a set of implementation notes and "todo" pointers that help you get started quickly.
The Mule example archetype will help you generate a tailored boilerplate example project in seconds. For
more information on using Maven, see Using Maven.
Follow the instructions below to create template files for a new Mule example, including all the necessary
Java boilerplate and detailed implementation instructions in comments.
Configuring Maven
Add the following to the file settings.xml (usually in your Maven conf or $HOME/.m2 directory) so that
Maven will allow you to execute Mule plug-ins.
<settings>
<pluginGroups>
<pluginGroup>org.mule.tools</pluginGroup>
</pluginGroups>
...
</settings>
Using the Archetype

First, open a command shell and change to the directory where you want to create your example project.
> cd yourDir
Next, you will execute the archetype and generate the code. If this is your first time running this
command, Maven will download the archetype for you.
> mvn mule-example-archetype:create -DartifactId=xxx -DmuleVersion=2.1.2
At minimum, you pass in two system parameters:
• artifactId: The short name for the project (such as 'myExample'). This must be a single word in
lower case with no spaces, periods, hyphens, etc.
• muleVersion: The version of the Mule project archetype you want to use. This will also be the
default Mule version used for the generated artifact.
artifactId
As of Mule 2.2 the artifactId can contain characters such as underscore or hyphen.
However, the plug-in will convert the name into a usable form suitable for Java. For
example, if the argument is specified as -DartifactId=My#Awesome-Mule_Project,
the project will be created in a directory of that name, but the project name will be
MyAwesomeMuleProject and the package name will be .myawesomemuleproject
The plug-in will ask various questions (described below) and then generate the files. You can also use
this plug-in without user prompts by entering all the arguments at the command line. For a full list of
arguments that can be passed in, see the Command Line Options.

After you have answered all the questions, the archetype creates a directory using the example project
name you specified that includes a POM file for building with Maven, a Mule configuration file (conf
\mule-config.xml) that includes the namespaces for the transports and modules you specified and
has placeholder elements for creating your first service, and a package.html file under src\main
\java using the package path you specified. It also creates files in the dist folder that you need to
distribute to users, including a readme file and a batch file for running the example. Lastly, it creates
some template files under src\test to help you get started creating a unit test for the example. A new
MULE-README.txt file will be created in the root of your project explaining what files were created.
The Questions Explained

The plug-in prompts you to answer several questions about the example you are creating. These may
vary according to the options you select. An example of the output is shown below.
Provide a description of what the example does:
You should provide an accurate description of the example with any high-level details of what you can or
cannot do with it. This text will be used where a description of the example is required.
Which version of Mule is this example targeted at?
The version of Mule you want to use for your example. This will default to the archetype version passed in
on the command line.
Will this project be hosted on MuleForge?
If the example will be hosted on MuleForge, additional information will be added to your example for
linking to its issue tracker, web site, build server, and deployment information.
Which Mule transports do you want to include in this project?
A comma-separated list of the transports you plan to use in this example (such as HTTP and VM). This
will add the namespaces for those transports to the configuration file.
Which Mule modules do you want to include in this project?
A comma-separated list of the modules you plan to use in this example (such as XML and Scripting). This
will add the namespaces for those modules to the configuration file.
Example Console Output

[INFO] description:
********************************************************************************
Provide a description of what the example does:
[default:]
********************************************************************************
[INFO] muleVersion:
********************************************************************************
Which version of Mule is this example targeted at?
[default: 2.1.2]
********************************************************************************
[INFO] forgeProject:
********************************************************************************
Will This project be hosted on MuleForge? [y] or [n]

[default: y]
********************************************************************************
[INFO] transports:
********************************************************************************

(options: axis,cxf,ejb,file,ftp,http,https,imap,imaps,jbpm,jdbc,
jetty,jms,multicast,pop3,pop3s,quartz,rmi,servlet,smtp,
smtps,servlet,ssl,tls,stdio,tcp,udp,vm,xmpp):
[default: cxf,file,http,jdbc,jms,stdio,vm]
********************************************************************************
[INFO] modules:
********************************************************************************
(options: bulders,client,jaas,jbossts,management,ognl,pgp,scripting,
spring-extras,sxc,xml):
[default: client,management,scripting,sxc,xml]
********************************************************************************
Command Line Options

By default, this plug-in runs in interactive mode, but it's possible to run it in 'silent' mode by using the
following option:
-Dinteractive=false
The following options can be passed in:
Name Example Default Value
groupId - org.mule.example.<artifactId>
DgroupId=org.mule.examplexxx
forgeProject -DforgeProject=n y
packagePath -DpackagePath=org/mule/ none

example
transports -Dtransports=http,vm cxf,file,http,jdbc,jms,stdio,vm
muleVersion -DmuleVersion2.1.2 none
packageName -DpackageName=myPkg none
description -Ddescription="some text" none
modules -Dmodules=xml,scripting client,management,scripting,sxc,xml
basedir -Dbasedir=/projects/mule/tools <current dir>

package -Dpackage=org/mule/example/ none
myPkg
artifactId -DartifactId=myMuleExample mule-application-<artifactId>
version -Dversion=1.0-SNAPSHOT <muleVersion>

Home

Some of the documentation on this site is under construction for the current release. If you have any
feedback on the content, or would like to sign up to become a site contributor or editor, please contact
us.
Getting Started Using Transports

(Click the arrow to expand the topics from the • About Transports
Getting Started guide, including an introduction • Available Transports
to Mule, steps to get started, and migration • Configuring a Transport
information.)
Mule Deployment
Click here to expand...
Architecture
• Introduction
° What is Mule?
• Deployment Scenarios
° Understanding the Messaging
• Choosing the Right Topology
Framework
° Understanding the Mule Architecture
° Understanding the Logical Data Flow Mule Administration
° Integrating Mule into Your Environment
° Summary
• Managing and Monitoring Deployments
• Getting Started °
° Quick Start Using Mule HQ
° Download Page Jmx Management
°
° Installing Mule • Controlling the Infrastructure with Mule
° Running Mule Galaxy
° Setting Up Eclipse
° Examples
° Basic Usage Extending Mule
° What's New in This Release
° Migrating Mule • Introduction to Extending Mule
• Creating a Custom XML Namespace
Using Mule • Creating Expression Evaluators
• Bootstrapping the Registry
• Internationalizing Strings
• Using MuleForge
• Configuring Mule
° Configuration Overview
° XML Configuration Testing Mule
° Configuring a Mule Instance
° Configuring Endpoints
° Using Transformers
• Introduction to Testing Mule
° About Models
• Functional Testing
• Unit Testing
• Working with Services
° Configuring the Service
• Running Benchmark Tests
° Configuring Components
• Profiling Mule
° Using Message Routers
° Using Filters Development Tools
° Mule Messaging Styles
° Using Web Services
° Using Spring Beans as Service
• Developer's Guide
• Using IDEs
Components
• Using Maven
• Customizing Behavior
° Developing Service Components
° Creating Custom Transformers
° Creating Custom Routers
° Creating Custom Filters

°Using Interceptors
°Configuring Retry Policies
Reference
• Beyond the Basics
° Using Expressions • Glossary
° Using Mule with Spring • Configuration Reference
° Using the Mule RESTpack • API Reference
° Using Mule Modules • Test API Reference
° Error Handling • Third-party Software in Mule
° Configuring Security • Suggested Reading
° Using the Mule Client • Distribution Contents
° Tuning Performance • PDF versions of the User's Guide for offline
° Configuring Queues reading
° Managing Transactions
° Using Agents
° Mule Server Notifications
Documentation for Previous
° Configuring Logging Releases
Click a link below to view the documentation for
that release.
Mule 1.x
• Getting Started
• User Guide

About Transports
This page last changed on Nov 19, 2008 by jackie.wheeler.
About Transports
A transport is responsible for carrying messages from application to application in the Mule framework.
A transport provides a set of functionality that handles messages on a specific channel. For example, the
HTTP transport handles messages sent via the HTTP protocol, whereas the File transport picks up files
placed on the server's file system.
The heart of a transport is the connector. The connector maintains the configuration and state for
the transport. When receiving messages, a connector uses a message receiver, which reads the
data, packages it as a message, and passes it to the service component's inbound router. When
sending messages, the connector uses a message dispatcher, which receives the messages and routing
instructions from the service component's outbound router and sends the message to the next service
component or application.
Related Topics
Available Transports
Configuring a Transport
Creating Transports

[ Mule Transports ] [ Transports Feature Matrix ]
Following is a list of known transports (also called "providers") for Mule. Some functionality is contained
within modules instead of transports--see Using Mule Modules. For more information on transports, see
the following topics:
• About Transports
• Configuring a Transport
If you have created a transport for Mule and would like to share it with the Mule community, please
contact us.
The following list includes some prominent transports from MuleForge (denoted by ). Transports that
are available only in Mule Enterprise Edition are denoted by .
Mule Transports
Transport Description
Connectivity to IBM AS400 Data Queue messaging

AS400 DQ Transport server. This transport is available on MuleForge.
Axis Transport Allows Mule managed components to be published

as Axis services and allows components to invoke
web services using Axis client calls.
BPM Transport Allows Mule events to initiate and/or advance

processes in a Business Process Management
System (BPMS) a.k.a. Process Engine.
CXF Transport Provides support for web service integration via

Apache CXF.
EJB Transport Allows EJB invocations to be made using outbound

endpoints.
Email Transport This transport supplies various email connectivity

options.
File Transport This transport allows files to be read and written

to directories on the local file system. The
connector can be configured to filter the file
it reads and the way files are written, such
as whether binary output is used or the file is
appended to.
FTP Transport Allows files to be read / written to a remote FTP

server.

HTTP Transport This transport supplies HTTP transport of Mule
messages between applications and other Mule
servers.
HTTPS Transport A secure version of the HTTP transport.
IMAP Transport Connectivity to IMAP mail folders.
IMAPS Transport A secure version of the IMAP transport.
A transport that reads from, writes to, and

JCR Transport observes JCR 1.0 containers. This transport is
available on MuleForge.
A transport for JDBC connectivity. Some of its

JDBC Transport features are available only in Mule Enterprise
Edition.
Jetty Transport Provides support for exposing services over HTTP

by embedding a light-weight Jetty server. For
inbound endpoints only.
Jetty SSL transport A secure version of the Jetty transport.
JMS Transport A Mule transport for JMS connectivity. Mule itself

is not a JMS server but can use the services of
any JMS 1.1 or 1.02b compliant server such
as ActiveMq, OpenJms, Joram, JBossMQ, and
commercial vendors such as WeblogicMQ,
WebsphereMQ, SonicMQ, SeeBeyond, etc.
Multicast Transport Allows your components to receive and send

events via IP multicast groups.
POP3 Transport Connectivity to POP3 inboxes.
POP3S Transport A secure version of the POP3 transport.
Quartz Transport Provides scheduling facilities with cron /

interval definitions and allows Mule events to be
scheduled/rescheduled.
RMI Transport Enables events to be sent and received over RMI

via JRMP.
Servlet Transport Provides facilities for Mule components to listen

for events received via a servlet request. There
is also a servlet implementation that uses the
Servlet transport to enable REST style services
access. This transport is now bundled with the
HTTP transport.
SMTP Transport Connectivity to SMTP servers.
SMTPS Transport A secure version of the SMTP transport.
SOAP Transport Enables your components to be exposed as web

services and to act as SOAP clients. The SOAP
transport supports CXF and Apache Axis.
SSL Transport Provides secure socket-based communication

using SSL or TLS.

STDIO Transport This transport provides connectivity to streams
such as System.in and System.out and is useful
for testing.
TCP Transport Enables events to be sent and received over TCP

sockets.
UDP Transport Enables events to be sent and received as

datagram packets.
VM Transport Enables event sending and receiving over VM,

embedded memory, or persistent queues.
A Mule transport for WebSphere MQ. This

WebSphere MQ Transport transport is available with Mule Enterprise version
1.6 and later.
WSDL Transport Invokes remote web services by obtaining the

service WSDL. Mule will create a dynamic proxy
for the service and then invoke it.
XMPP Transport Provides connectivity over the XMPP (Jabber)

instant messaging protocol.
Transports Feature Matrix

The following table shows the different messaging styles and options that each of the Mule transports
support. The headings are described below the table.
Transport Receive Dispatch Request Request/ Transactions

Streaming Inbound Outbound
Events Events Events Response MEPs MEPs
Events
Axis In- Out-Only

Only In- Out-
Out In- In Out-
Optional- Optional-
Out In
BPM In- Out-Only

Only In-
Out In-
Optional-
Out
CXF In- Out-Only

Only In- Out-
Out In- In Out-
Optional- Optional-
Out In
EJB In-Only Out-Only

Out-
In Out-
Optional-
In
Email In-Only Out-Only

File In-Only Out-Only
FTP In-Only Out-Only
HTTP In- Out-

Out In- In Out-
Optional- Optional-
Out In
HTTPS In- Out-

Out In- In Out-
Optional- Optional-
Out In
IMAP In-Only
IMAPS In-Only
JDBC In- Out-Only

Only In- Out-
Out In- In Out-
Optional- Optional-
Out In
Jetty In-
Only In-
Out In-
Optional-
Out
Jetty SSL In-

Only In-
Out In-
Optional-
Out
JMS In- Out-Only

Only In- Out-
Out In- In Out-
Optional- Optional-
Out In
Multicast In- Out-

Out In- In Out-
Optional- Optional-
Out In
POP3 In-Only
POP3S In-Only
Quartz In-Only Out-Only
RMI In-Only Out-Only

Out-In
Servlet In-
Only In-
Out In-

Optional-
Out
SMTP Out-Only
SMTPS Out-Only
SOAP In- Out-Only

Only In- Out-
Out In- In Out-
Optional- Optional-
Out In
STDIO In-Only Out-Only
TCP In- Out-

Out In- In Out-
Optional- Optional-
Out In
UDP In- Out-

Out In- In Out-
Optional- Optional-
Out In
VM In- Out-Only
Only In- Out-
Out In- In Out-
Optional- Optional-
Out In
XMPP In- Out-Only

Only In- Out-
Out In- In Out-
Optional- Optional-
Out In
Heading Descriptions
Transport - The name/protocol of the transport

Receive Events - Whether the transport can receive events and can be used for an inbound endpoint
Dispatch - Whether events can be sent asynchronously
Request - Whether this endpoint can be queried directly with a request
Request/Response - Whether this endpoint can be queried directly with a request and return a
response (implementation of the request() method in MessageRequester)
Transactions - Whether transactions are supported by the transport. Transports that support
transactions can be configured in a distributed two-phase commit (distributed) transaction.
Streaming - Whether this transport can stream data between endpoints. This allows for very efficient
processing of large data.
Inbound and Outbound MEPs - The messaging exchange patterns (MEPs) supported by the inbound
and outbound endpoints of the transport. See Mule Messaging Styles for more information on the
messaging styles Mule supports and how they map to MEPs.

BPM Transport
This page last changed on Oct 07, 2008 by jackie.wheeler.
BPM Transport
[ Features ] [ Usage ] [ Integration with BPM Engines ] [ Configuration ] [ Connector ]
The BPM transport allows Mule events to initiate and/or advance processes in a Business Process
Management System (BPMS), also known as a process engine. It also allows executing processes to
generate Mule events. For a high-level introduction to Business Process Management with Mule and the
concepts involved, see the presentation from MuleCon 2007.
To see the BPM Connector in action (with JBoss jBPM), take a look at the LoanBroker BPM example
(available in the full Mule distribution).
Javadocs for the BPM transport are available here .
Features
• Incoming Mule events can launch new processes, advance or terminate running processes.
• A running process can generate synchronous or asynchronous Mule events.
• Endpoints of type "bpm://MyProcess" are used to intelligently route process-generated events within
Mule.
• Synchronous responses from Mule are automatically fed back into the running process.
• Mule can interact with different running processes in parallel.
BPEL
The connector can only integrate with BPM engines that provide a Java API. If you need to
integrate with a BPEL engine that only exposes SOAP endpoints (i.e., "a black box"), you
will need to use standard web services. For an example, see MULE and Oracle SOA BPEL
Integration.
Usage
Sending events to the BPMS
The basic URI for a new process is:
bpm://ProcessType
For a running process, use:
bpm://ProcessType/ProcessID
Initiate a new process of type "MyBigProcess"
bpm://MyBigProcess
Advance an already running process with ID = 4561
bpm://MyBigProcess?processId=4561&action=advance
(advance is the default action for an already-running process) or just
bpm://MyBigProcess/4561
Update process variables (without advancing the process)
bpm://MyBigProcess/4561?action=update

Abort a running process (this might not be supported by every BPMS)
bpm://MyBigProcess/4561?action=abort
In a real system, you will most likely want to set the "processId" dynamically as a property
on the message.
Incoming Messages to the BPMS
When a message is received by the BPMS, two things automatically happen:
• The message payload is stored in a process variable named "incoming"

• The endpoint on which the message was originally received by Mule is stored in a process variable
named "incomingSource"
These process variables may then be used to drive the logic of the running process.
Generating Events from the BPMS
The actual syntax for generating events from a running process will depend on the BPMS used.
Messages generated by a running process will be received by Mule on the best-matching endpoint
available. For example, suppose a Mule message is generated by the running process called
"MyBigProcess" with ID = 4561. The incoming message would preferably be received by this endpoint:
bpm://MyBigProcess/4561
and if not, then by this endpoint:
bpm://MyBigProcess
and finally, if the "allowGlobalReceiver" property is true, by this endpoint:
bpm://*
The new message will then be routed from the component on which it is received (unless the
connector's allowGlobalDispatcher property is true). If the message is synchronous, the response will
automatically be sent back to the generating process.
Integration with BPM Engines

One of the basic design principles of Mule is to promote maximum flexibility for the user. Based on this,
the user should ideally be able to "plug in" any BPM engine to use with Mule. Unfortunately, there is no
standard JEE specification to enable this. JSR-207 was one attempt but has made no progress. BPEL has
also tried to solve this, but like JBI, is exclusive to SOAP web services and XML, which defeats Mule's
flexibility principle.
Therefore, until such a specification ever emerges, the Mule BPM Transport simply defines its own.
public interface BPMS

{
// Start a new process.
public Object startProcess(Object processType, Map processVariables);
// Advance an already-running process.

public Object advanceProcess(Object processId, Object transition, Map processVariables);
// Update the variables/parameters for an already-running process.

public Object updateProcess(Object processId, Map processVariables);
// Abort a running process (end abnormally).

public void abortProcess(Object processId);

// MessageService is a callback method used to generate Mule messages from your process.
public void setMessageService(MessageService msgService);
}
Any BPM engine that implements the interface ( org.mule.transport.bpm.BPMS ) can "plug in" to Mule via
the BPM transport. The JBoss jBPM engine is available with Mule.
Integration with JBoss jBPM
For general information on jBPM and how to configure it, refer to http://docs.jboss.com/jbpm/v3/
userguide
The org.mule.transport.bpm.jbpm.Jbpm
class implements the BPMS interface for jBPM and must be set as the bpms property on your connector.
You can browse the rest of the Javadocs for Mule's jBPM integration here .
Configuration
The recommended way to configure jBPM with Mule is using Spring and Spring's jBPM Module

xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:bpm="http://www.mulesource.org/schema/mule/bpm/2.1"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-
beans-2.5.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/
spring-context-2.5.xsd
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/bpm/2.1 http://www.mulesource.org/schema/mule/bpm/2.1/
mule-bpm.xsd">
<bpm:connector name="jBpmConnector" bpms-ref="jbpm" />


<spring:bean id="jbpm" class="org.mule.transport.bpm.jbpm.Jbpm" destroy-method="destroy">
<spring:property name="jbpmConfiguration">
<spring:ref local="jbpmConfig" />
</spring:property>
</spring:bean>


<spring:bean id="jbpmConfig"
class="org.springmodules.workflow.jbpm31.LocalJbpmConfigurationFactoryBean">
<spring:property name="sessionFactory">
<spring:ref local="jbpmSessionFactory" />
</spring:property>
<spring:property name="configuration">
<spring:value>jbpm.cfg.xml</spring:value>
</spring:property>
<spring:property name="processDefinitions">
<spring:list>
<spring:bean id="loanBroker"
class="org.springmodules.workflow.jbpm31.definition.ProcessDefinitionFactoryBean">
<spring:property name="definitionLocation">
<spring:value>loan-broker-process.xml</spring:value>
</spring:property>
</spring:bean>

</spring:list>
</spring:property>
<spring:property name="createSchema">
<spring:value>false</spring:value>
</spring:property>
</spring:bean>


<spring:bean id="jbpmSessionFactory"
class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
<spring:property name="dataSource">
<spring:ref local="jbpmDataSource" />
</spring:property>
<spring:property name="mappingLocations">
<spring:value>classpath*:/org/jbpm/**/*.hbm.xml</spring:value>
</spring:property>
<spring:property name="typeDefinitions">
<spring:ref local="jbpmTypes" />
</spring:property>
<spring:property name="hibernateProperties">
<spring:props>
<spring:prop key="hibernate.dialect">org.hibernate.dialect.DerbyDialect</spring:prop>
<spring:prop key="hibernate.cache.provider_class">org.hibernate.cache.HashtableCacheProvider</
spring:prop>

<spring:prop key="hibernate.hbm2ddl.auto">update</spring:prop>
</spring:props>
</spring:property>
</spring:bean>


<spring:bean id="jbpmDataSource"
class="org.springframework.jdbc.datasource.DriverManagerDataSource">
<spring:property name="driverClassName">
<spring:value>org.apache.derby.jdbc.EmbeddedDriver</spring:value>
</spring:property>
<spring:property name="url">
<spring:value>jdbc:derby:muleEmbeddedDB;sql.enforce_strict_size=true</spring:value>
</spring:property>
</spring:bean>


<spring:bean id="jbpmTypes" class="org.springframework.orm.hibernate3.TypeDefinitionBean">
<spring:property name="typeName">
<spring:value>string_max</spring:value>
</spring:property>
<spring:property name="typeClass">
<spring:value>org.jbpm.db.hibernate.StringMax</spring:value>
</spring:property>
</spring:bean>
</mule>
If you want to configure jBPM without using Spring, you create the org.mule.transport.bpm.jbpm.Jbpm
wrapper based on your jBPM instance and set it as the bpms property on the BPM connector:
ProcessConnector connector = new ProcessConnector();
BPMS bpms = new org.mule.transport.bpm.jbpm.Jbpm(yourJbpmInstance);

connector.setBpms(bpms);

MuleManager.getInstance().registerConnector(connector);
Generating a Mule Message from jBPM
Use the org.mule.transport.bpm.jbpm.actions.SendMuleEvent ActionHandler to generate a Mule message

from your jBPM process:
<process-definition name="sendMessageProcess">
<description>Generates a simple Mule event.</description>
<start-state name="start">
<transition to="sendMessage" />
</start-state>
<state name="sendMessage">
<event type="node-enter">
<action class="org.mule.transport.bpm.jbpm.actions.SendMuleEvent">
<endpoint>file:///tmp</endpoint>
<payload>Message in a bottle.</payload>
<synchronous>false</synchronous>
</action>
</event>
<transition to="end" />
</state>
<end-state name="end" />
</process-definition>
jBPM Action Handlers for Mule
The primary way of adding custom functionality to jBPM is via ActionHandlers. The BPM transport
provides a few such ActionHandlers, which are useful for integrating your jBPM process with Mule.
SendMuleEvent : Sends a Mule message to the specified endpoint. If the message is synchronous, the
response from Mule will be automatically stored in the "incoming" process variable.
StoreIncomingData : Stores the incoming message payload into the specified variable.
ValidateMessageSource : Throws an exception if the message's source is not as expected.
ValidateMessageType : Throws an exception if the incoming message's class is not as expected.
Configuration
Following is a simple configuration example:

xmlns:bpm="http://www.mulesource.org/schema/mule/bpm/2.1"
beans-2.5.xsd

mule.xsd
http://www.mulesource.org/schema/mule/bpm/2.1 http://www.mulesource.org/schema/mule/bpm/2.1/
mule-bpm.xsd">
<bpm:connector name="jBpmConnector" bpms-ref="jbpm" />
<model name="bpm_example">

<service name="ToBPMS">
<inbound>
<inbound-endpoint address="Incoming1"/>
<inbound-endpoint address="Incoming2"/>
</inbound>
<log-component/>
<outbound>
<filtering-router>
<outbound-endpoint address="bpm://MyProcess" synchronous="false" />
</filtering-router>
</outbound>
</service>


<service name="FromBPMS">
<inbound>
<inbound-endpoint address="bpm://MyProcess" />
</inbound>
<log-component/>
<outbound>
<bpm:outbound-router>
<outbound-endpoint address="Outgoing1"/>
</bpm:outbound-router>
</outbound>
</service>
</model>
</mule>
Message Properties
Property Description Default Required
processType The name of the yes

process
processId The unique ID of the yes, unless action =

running process "start"
action Action to perform on "advance" if processId no

the BPMS: "start" / exists, otherwise "start"
"advance" / "update" /
"abort"
transition Transition to take if no

more than one exit
path is available for the
current process state

Connector
Attributes of <connector...>
Name Type Required Default Description
bpms-ref name (no spaces) no A reference to

the underlying
BPMS, which must
implement the
org.mule.transport.bpm.BPMS
interface to
exchange
messages through
Mule using the
BPM transport.
allowGlobalReceiver boolean no false The global

receiver allows
an endpoint of
type "bpm://*"
to receive any
incoming message
to the BPMS,
regardless of the
process. If this is
false, the process
name must be
specified for each
endpoint. For
example, "bpm://
MyProcess" will
only receive
messages for
the process
"MyProcess".
allowGlobalDispatcherboolean no false If false, any

message
generated by
the process is
routed from
the component
on which it is
received. If true, a
process can send
messages to any
endpoint on any
component.
processIdField string no This field will be

used to correlate
messages with
processes.

CXF Transport
This page last changed on Dec 11, 2008 by dan.diephouse@mulesource.com.
CXF Transport
[ Introduction ] [ Features ] [ Using the CXF Transport ] [ Troubleshooting ] [ Suggested Reading ]
Introduction
The Mule CXF Transport provides support for web service integration via Apache CXF. Apache CXF is an
open source services framework that helps you build and develop services using front-end programming
APIs, like JAX-WS. These services can speak a variety of protocols such as SOAP, XML/HTTP, RESTful
HTTP, or CORBA and work over a variety of transports such as HTTP, JMS or JBI.
Note: The CXF transport requires Java 5.0.
Features
The CXF transport is an evolution of the XFire transport, which was available with earlier versions of Mule.
The CXF transport includes the following features:
• Integrated Installer: CXF and XFire have some conflicting libraries and therefore cannot both be
deployed in the same instance of Mule. The Mule Enterprise installer allows you to install CXF when
you're installing Mule and handles all library changes for you. This is an enhancement over the
snapshot version of the CXF transport on MuleForge.
• Bookstore Example: A complete example of using the CXF transport to send complex objects.
• MTOM Support: The CXF transport supports SOAP Message Transmission Optimization Mechanism
(MTOM), which specifies an optimized method for sending binary data as part of a SOAP message.
• Complete Functional Tests: The functional tests have been converted from XFire to CXF.
Using the CXF Transport

Use the following links for information on configuring and using the CXF transport with your
implementation of Mule.
Building a CXF Web Service

Using Web Services over Jetty
Using a Web Service Client as an Outbound Endpoint
Using a Web Service Client Directly
Using HTTP GET Requests
Using MTOM
Proxying Web Services
Supported Web Service Standards
Enabling WS-Addressing
Enabling WS-Security
Bookstore Example
Configuration Reference
Troubleshooting
This section includes common problems and solutions you might encounter when using the CXF transport.
I've received a "java.lang.IllegalArgumentException: wrong number of arguments" when

using the CXF outbound endpoint
The CXF outbound endpoint uses the CXF generated to client to send messages. Because of this, your
message payload must match the signature of the operation being invoked. This error results when the
payload does not match the signature.

Here's an example. If you have an operation on the client like this:
public void sendData(String data1, String data2, String data3);
Your message payload must be like this:
Object payload = new Object[] { "data1", "data2", "data3" };
My WSDL does not have the correct service address (i.e. its localhost instead of foo.com)
If you are doing WSDL-first development, ensure that your @WebService annotation on your service
implementation has the correct serviceName, targetNamespace, and portName attributes. If these are
not correct, CXF cannot navigate your WSDL, find the address, and replace it with the address currently
being used.
Your WebService annotation should look like this:
@WebService(serviceName = "YourServiceName",
portName = "YourPortName",
targetNamespace = "http://your-namespace",
endpointInterface = "your.endpoint.Interface",
wsdlLocation = "your.wsdl")
Suggested Reading
XFire->CXF Migration Guide

XFire and Celtix Merge FAQ

This page last changed on Oct 15, 2008 by dan.diephouse@mulesource.com.

[ Creating a JAX-WS Service ] [ Configuring Mule to Use the Web Service ] [ Using WSDL-first
Methodologies ] [ Changing the Data Binding ] [ Setting the Binding URI ] [ Changing the Default
Message Style ]
This page describes how to build a CXF web service and use it in Mule.
Creating a JAX-WS Service

The JAX-WS specification is a series of APIs and annotations to help you build web services. This section
describes how to create a very simple JAX-WS web service.
First, you write the service interface. For example, you could write an operation called "sayHello" that
says "Hello" to whoever submits their name.
package org.example;
import javax.jws.WebService;
@WebService
public interface HelloWorld {
String sayHi(String text);
}
Your implementation would then look like this:
package demo.hw.server;
import javax.jws.WebService;
@WebService(endpointInterface = "demo.hw.server.HelloWorld",
serviceName = "HelloWorld")
public class HelloWorldImpl implements HelloWorld {
public String sayHi(String text) {

return "Hello " + text;
}
}
Configuring Mule to Use the Web Service

To configure Mule to use the service, simply declare your service and use a CXF endpoint as shown in the
following example:
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.1" xmlns:xsi="http://www.w3.org/2001/

XMLSchema-instance"
xmlns:cxf="http://www.mulesource.org/schema/mule/cxf/2.1"
xsi:schemaLocation="http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.mulesource.org/schema/mule/cxf/2.1
http://www.mulesource.org/schema/mule/cxf/2.1/mule-cxf.xsd">
<model name="CxfExample">
<service name="helloService">
<inbound>
<inbound-endpoint address="cxf:http://localhost:63081/hello" />
</inbound>
<component>
<singleton-object class="org.example.HelloServiceImpl" />
</component>
</service>
...
If you go to "http://localhost:63081/hello?wsdl", you will see the WSDL that CXF generates for you.
If you want to use a POJO instead of creating a JAX-WS service, you could host the POJO as a service
component in Mule and use the simple front-end client with its CXF inbound endpoint. You would
configure the POJO as follows:
<inbound-endpoint address="cxf:http://localhost:63081/hello" frontend="simple" />
The frontend property can be "jaxws" (the default) or "simple".
Using WSDL-first Methodologies

In addition to the code-first approach outlined above, you can also use CXF to do WSDL-first services.
While the details are out of the scope of this guide, the CXF distribution includes many examples of how
to do this.
First, you generate your web service interface from your WSDL. You can do this using the WSDL to Java
tool from CXF or the Maven plugin.
Next, you write a service implementation class that implements your service interface. You can then use
this implementation class in the Mule configuration exactly as in the previous example.
Supplying the Original WSDL to CXF
You can supply your original WSDL to CXF by using the @WebService attribute:
WebService(endpointInterface = "demo.hw.server.HelloWorld",
serviceName = "HelloWorld",
wsdlLocation="foo/bar/hello.wsdl")
public class HelloWorldImpl implements HelloWorld
Another way is to specify the wsdlLocation property on the endpoint:
<cxf:inbound-endpoint address="http://localhost:63081/hello" wsdlLocation="foo/bar/hello.wsdl" />
CXF is able to locate this WSDL inside your webapp, on the classpath, or on the file system.

Changing the Data Binding
You can use the databinding property on an endpoint to configure the data binding to use with that
service. Following are the types of data bindings available with CXF:
1. AegisDatabinding
2. JAXBDatabinding (Default)
3. StaxDatabinding
You specify the databinding class to use as follows:
<cxf:inbound-endpoint address="cxf:http://localhost:18080/mule/CxfService">
<cxf:databinding>
<spring:bean class="org.apache.cxf.aegis.databinding.AegisDatabinding"/>
</cxf:databinding>
</cxf:inbound-endpoint>
Setting the Binding URI

The bindingUri attribute specifies how your service operations are mapped to resources. You configure
this attribute as follows:
<inbound-endpoint address="cxf:http://localhost:18080/mule/CxfService" bindingUri="http://

www.w3.org/2003/05/soap/bindings/HTTP/" />
Changing the Default Message Style

By default, CXF uses the Document/Literal message style. However, you can change the service to be
exposed as RPC instead of document or to send complex types as wrapped instead of literal. To change
the message style, you set the @SOAPBinding annotation on the service's interface, specifying the style,
use, and optionally the parameterStyle.
In the following example, the parameter style is set to BARE. This means that each parameter is placed
into the message body as a child element of the message root. This is WRAPPED by default.
@SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
use=SOAPBinding.Use.LITERAL,
parameterStyle=SOAPBinding.ParameterStyle.BARE)
@WebService
public interface Echo
{
String echo(String src);
}
For more information on the supported message styles, go to Optional Annotations.

CXF Transport Configuration Reference
This page last changed on Aug 05, 2008 by jackie.wheeler.
Table of Contents
• CXF Transport
• ° Connector
° - Attributes of <connector...>
° Inbound endpoint
° - Attributes of <inbound-endpoint...>
° Outbound endpoint
° - Attributes of <outbound-endpoint...>
° Endpoint
° - Attributes of <endpoint...>
° Features
° Wrapper component
° - Attributes of <wrapper-component...>
° Stax
CXF Transport
Apache CXF is an open source services framework. CXF helps you build and develop services using
frontend programming APIs, like JAX-WS. These services can speak a variety of protocols such as SOAP,
XML/HTTP, RESTful HTTP, or CORBA and work over a variety of transports such as HTTP, JMS or JBI.
The Mule CXF Transport is an evolution of Mule's XFire Transport which provides support for the use of
web service integration via Apache CXF. The Mule CXF connector also provides support for WS-Security,
WS-Addressing and WS-Reliable-Messaging.
Connector
defaultFrontend string no jaxws The CXF frontend

that is used
to build an
internal service
representation
from your Java
classes. The
default is "jaxws".
The "simple"
frontend is also
supported.
configurationLocationstring no The location of a

CXF configuration
file, if any needs
to be supplied.
initializeStaticBusInstance
boolean no Initialize the static
CXF Bus with a
Bus configured to
use Mule for all
transports. This

will affect any
CXF generated
clients that you
run standalone.
Defaults to false.
Inbound Endpoint
Attributes of <inbound-endpoint...>
frontend jaxws/simple no The CXF frontend

that is used
to build an
internal service
representation
from your Java
classes. The
default is "jaxws".
The "simple"
frontend is also
supported.
bindingUri string no The binding that

should be used
for this service.
It defaults to the
soap binding by
default.
endpointName string no The WSDL

endpoint name of
your service.
serviceClass string no The class CXF

should use to
construct it's
service model.
This is optional
and by default
it will use the
implementation
class of your
component.
serviceName string no The WSDL service

name of your
service.
applyFiltersToProtocolboolean no Whether or not to

apply the filters
to the protocol
endpoint.
applyTransformersToProtocol
boolean no Whether or not
to apply the
transformers
to the protocol
endpoint.

applySecurityToProtocol
to apply the
security filter
to the protocol
endpoint.
proxy boolean no Whether or not

this outbound
endpoint is acting
as a web service
proxy. If so, it
will expect raw
xml as the input
parameter and
return an XML
stream as the
output.
mtomEnabled boolean no Whether or

not MTOM
(attachment
support) is
enabled for this
endpoint.
wsdlLocation string no The location of

the WSDL for your
service. If this
is a server side
endpoint it will
served to your
users.
Outbound Endpoint
Attributes of <outbound-endpoint...>
wsdlPort string no The WSDL port

you wish to use to
communicate to
the service.
clientClass string no The name of the

client class that
CXF generated
using CXF's
wsdl2java tool.
You must use
wsdl2java if you
do not have both
the client and
the server in
the same JVM.
Otherwise, this
can be optional
if the endpoint
address is the

same in both
cases.
operation string no The operation you

wish to invoke
on the outbound
endpoint.

this outbound
endpoint is acting
as a web service
proxy. If so, it
will expect raw
xml as the input
parameter and
return an XML
stream as the
output.

not MTOM
(attachment
support) is
enabled for this
endpoint.

the WSDL for your
service. If this
is a server side
endpoint it will
served to your
users.
Endpoint
Attributes of <endpoint...>
frontend jaxws/simple no The CXF frontend

that is used
to build an
internal service
representation
from your Java
classes. The
default is "jaxws".
The "simple"
frontend is also
supported.
bindingUri string no The binding that

should be used
for this service.
It defaults to the
soap binding by
default.

endpointName string no The WSDL
endpoint name of
your service.
serviceClass string no The class CXF

should use to
construct it's
service model.
This is optional
and by default
it will use the
implementation
class of your
component.
serviceName string no The WSDL service

name of your
service.
applyFiltersToProtocolboolean no Whether or not to

apply the filters
to the protocol
endpoint.
applyTransformersToProtocol
to apply the
transformers
to the protocol
endpoint.
applySecurityToProtocol
to apply the
security filter
to the protocol
endpoint.

you wish to use to
communicate to
the service.
clientClass string no The name of the

client class that
CXF generated
using CXF's
wsdl2java tool.
You must use
wsdl2java if you
do not have both
the client and
the server in
the same JVM.
Otherwise, this
can be optional
if the endpoint
address is the
same in both
cases.

wish to invoke
on the outbound
endpoint.

this outbound
endpoint is acting
as a web service
proxy. If so, it
will expect raw
xml as the input
parameter and
return an XML
stream as the
output.

not MTOM
(attachment
support) is
enabled for this
endpoint.

the WSDL for your
service. If this
is a server side
endpoint it will
served to your
users.
Features
Wrapper Component
The WebServiceWrapperComponent class allows you to send
the result of a web service call to another endpoint.
Attributes of <wrapper-component...>
address string no TODO
addressFromMessageboolean no Specifies that the

URL of the web
service will be
obtained from the
message itself.

you wish to use to
communicate to
the service.

wish to invoke
on the outbound
endpoint.

Stax
Attributes of <stax...>
xmlInputFactory string no
xmlOutputFactory string no

This page last changed on Nov 04, 2008 by dan.diephouse@mulesource.com.
To enable your services to use WS-Addressing, you must configure the CXF endpoint to use the WS-
Adressing feature:
<cxf:inbound-endpoint address="http://localhost:63081/services/employee">
<cxf:features>
<wsa:addressing />
</cxf:features>
This works with outbound endpoints as well:
<cxf:outbound-endpoint address="http://localhost:63081/services/employee" ..... >

<cxf:features>
<wsa:addressing />
</cxf:features>
</cxf:outbound-endpoint>
Note that currently "decoupled" reply to endpoints are not supported with Mule.
Manipulating WS-Addressing Headers
To manipulate the WS-Addressing headers inside the messages, you can write a JAX-WS handler or a CXF
interceptor. For a quick start, see the WS-Addressing sample inside the CXF distribution.

This page describes how to configure a client and service to use WS-Security. You should already have a
basic client and server running. For further information on how to configure WS-Security with CXF, you
should consult the CXF documentation which goes into more detail on how to configure the CXF service
interceptors.
UsernameToken Scenario
The UsernameToken feature in WS-Security is an interoperable way to exchange security tokens inside
a SOAP message. The following section describes how to configure the client and server to exchange a
username/password security token.
Server Configuration
On the server side, you do the following:
• Create a Mule service for your component implementation

• Configure the WSS4JInInterceptor and the SAAJInInterceptor. The former is responsible for checking
the security of your message.
• Write a server PasswordCallback that verifies the password.
You configure the server in the Mule configuration file. Following is an example:
<service name="greeterService">
<inbound>
<cxf:inbound-endpoint address="http://localhost:63081/services/greeter">
<cxf:inInterceptors>
<spring:bean class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor" />
<spring:bean class="org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor">
<spring:constructor-arg>
<spring:map>
<spring:entry key="action" value="UsernameToken" />
<spring:entry key="passwordCallbackRef" value-ref="serverCallback" />
</spring:map>
</spring:constructor-arg>
</spring:bean>
</cxf:inInterceptors>
</inbound>
<component>
<singleton-object class="org.apache.hello_world_soap_http.GreeterImpl" />
</component>
</service>
The <cxf:inInterceptors> element configures the incoming interceptors on the service. The
WSS4JInInterceptor performs the security operations on the incoming SOAP message. The
"action" parameter controls which actions it performs on the incoming message - in this case the
"UsernameToken" action specifies that it will verify the username token via a specified password callback.
The password callback is specified by the "passwordCallbackRef" property, which is detailed in the next
section. The SAAJInInterceptor is also installed here. It enables the use of SAAJ, an in-memory DOM
document format, which is required by WSS4J.
Server callbacks verify passwords by supplying the password with which the incoming password will be
compared.

import java.io.IOException;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import org.apache.ws.security.WSPasswordCallback;
public class ServerPasswordCallback implements CallbackHandler

{
public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
WSPasswordCallback pc = (WSPasswordCallback) callbacks[0];
if (pc.getIdentifer().equals("joe")) {
// set the password on the callback. This will be compared to the
// password which was sent from the client.
pc.setPassword("password");
}
}
}
This allows you to write custom code which can load and compare passwords from custom backends,
such as databases or LDAP.
Client Configuration
On the client side, you do the following:
• Set up the CXF outbound endpoint

• Configure the CXF client so that it uses ws-security
• Set up a ClientPasswordCallback that supplies the password for the invocation
Following is a simple example that configures a CXF outbound endpoint:
<cxf:outbound-endpoint address="http://localhost:63081/services/greeter"
name="clientEndpoint"
clientClass="org.apache.hello_world_soap_http.SOAPService"
wsdlPort="SoapPort"
wsdlLocation="classpath:/wsdl/hello_world.wsdl"
operation="greetMe">
<cxf:outInterceptors>
<spring:bean class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor" />
<spring:bean class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor">
<spring:constructor-arg>
<spring:map>
<spring:entry key="action" value="UsernameToken" />
<spring:entry key="user" value="joe" />
<spring:entry key="passwordType" value="PasswordDigest" />

<spring:entry key="passwordCallbackRef" value-ref="clientCallback" />
</spring:map>
</spring:constructor-arg>
</spring:bean>
</cxf:outInterceptors>

Configure the CXF Client to Use WS-Security
To use WS-Security, you add a configuration section to your "my-cxf-config.xml" file.
Note: if your client and your server are on separate machines, you create two separate files and then a
CXF connector configuration on each one.
<jaxws:client name="{http://apache.org/hello_world_soap_http}SoapPort" createdFromAPI="true">

<jaxws:outInterceptors>
<bean class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor" />
<bean class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor">
<constructor-arg>
<map>
<entry key="action" value="UsernameToken" />
<entry key="user" value="joe" />
<entry key="passwordType" value="PasswordDigest" />

<entry key="passwordCallbackRef" value-ref="clientCallback" />
</map>
</constructor-arg>
</bean>
</jaxws:outInterceptors>
</jaxws:client>
<bean id="clientCallback" class="org.mule.providers.soap.cxf.wssec.ClientPasswordCallback"/>
The above configuration specifies the following:
• CXF should invoke the UsernameToken action.

• The user name is "joe"
• Send the password in digest form.
• Use the "clientCallback" bean to supply the password. (see below)
Client Password Callback
Following is a simple example client password callback that sets the password to use for the outgoing
invocation:
import java.io.IOException;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import org.apache.ws.security.WSPasswordCallback;
public class ClientPasswordCallback implements CallbackHandler

{
public void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException {
WSPasswordCallback pc = (WSPasswordCallback) callbacks[0];
// set the password for our message.

pc.setPassword("yourpassword");
}
}

Supported Web Service Standards
Web Service Standards

The CXF transport supports a variety of web service standards.
• SOAP 1.1 and 1.2

• WSDL 1.1
• WS Addressing
• WS Security 1.1
• WS Policy
• WS-I BasicProfile 1.1
• WS-I SecurityProfile
• SAML 1.0 (with WS-Security)
• MTOM
• SOAP with attachments
Future versions of Mule may support WS-ReliableMessaging. Although CXF currently supports it, it is not
easy to support "decoupled" WS-RM over non-native CXF transports, so it does not work well with Mule
transports. One-way channels might work but are currently untested.
Future Releases
In version 2.2, the CXF transport is slated to support the following additional standards:
• WS-Trust
• WS-SecureConversation
• WS-SecurityPolicy
• WS-Security

Using a Web Service Client as an Outbound Endpoint
Using a Web Service Client as an Outbound

Endpoint
You can use a CXF-generated client as an outbound endpoint. First, you generate a CXF client using the
WSDL to Java tool from CXF or the Maven plugin.
Next, you configure the client as an outbound endpoint using the following properties:
• clientClass: The client class generated by CXF, which extends javax.xml.ws.Service.

• port: The WSDL port to use for communicating with the service
• wsdlLocation: The location of the WSDL for the service. CXF uses this to configure the client.
• operation: The operation name to invoke on the web service. The objects that you pass to the
outbound router must match the signature of the method for this operation. If your method takes
multiple parameters, they must be put in an Object[] array.
Following is a simple example:
<service name="csvPublisher">
<inbound>
<inbound-endpoint address="file://./books?pollingFrequency=100000&autoDelete=false"/>
</inbound>
<component class="org.mule.example.bookstore.publisher.CsvBookPublisher"/>
<outbound>
<outbound-pass-through-router>
<cxf:outbound-endpoint
address="http://localhost:63081/services/greeter"
clientClass="org.apache.hello_world_soap_http.SOAPService"
wsdlPort="SoapPort"
wsdlLocation="classpath:/wsdl/hello_world.wsdl"
operation="greetMe"/>
</outbound-pass-through-router>
</outbound>
</service>


This page describes how to use a standalone CXF-generated client with Mule. This approach is different
from the outbound router approach, which is typically a more appropriate fit for most applications.
There are two ways to use CXF clients. First, you can generate a client from WSDL using the CXF WSDL
to Java tool. Second, if you've built your service via "code-first" methodologies, you can use the service
interface to build a client proxy object.
When using a CXF client, it automatically discovers the Mule instance (provided you're in the same JVM/
Classloader) and uses it for your transport. Therefore, if you've generated a client from WSDL, invoking a
service over Mule can be as simple as the following:
HelloWorldService service = new HelloWorldService();

HelloWorld hello = service.getSoapPort();
// Possibly set an alternate request URL:

// ((BindingProvider) greeter).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
"http://localhost:63081/greeter");
String sayHi = hello.sayHi();
Building a Client Proxy

Following is an example of how to construct a client using the service that was developed in Building a
CXF Web Service:
QName SERVICE_NAME = new QName("http://server.hw.demo/", "HelloWorld");

QName PORT_NAME = new QName("http://server.hw.demo/", "HelloWorldPort");
Service service = Service.create(SERVICE_NAME);
// Endpoint Address
String endpointAddress = http://localhost:63081/hello";
// Add a port to the Service

service.addPort(PORT_NAME, SOAPBinding.SOAP11HTTP_BINDING, endpointAddress);
HelloWorld hw = service.getPort(HelloWorld.class);
System.out.println(hw.sayHi("World"));
Additional Resources
• Developing a JAX-WS consumer
• WSDL to Java
• CXF Maven plugin


CXF has built-in support for understanding GET requests, which use the following format:
http://host/service/OPERATION/PARAM_NAME/PARAM_VALUE
For example:
@WebService(endpointInterface = "org.mule.samples.echo.components.EchoService",
serviceName = "echo")
public class EchoComponent implements EchoService
{
public String echo(String string)
{
return string;
}
}
The above Echo service is hosted in Mule on the endpoint cxf:http://localhost:65081/services/EchoUMO,

so you can access the service from a simple web browser by typing the following:
http://localhost:65081/services/EchoUMO/echo/string/hello
This will send the value "hello" for the string parameter to the echo() method.

Using MTOM
Using MTOM
[ Writing an MTOM-enabled WSDL ] [ Generating Server Stubs and/or a Client ] [ Configuring the CXF
Inbound Endpoint ] [ Configuring the CXF Outbound Endpoint ]
This page describes the basics of how to use MTOM inside your service. For more information, go to the
MTOM documentation for CXF. Portions of the examples on this page are from that guide.
For a WSDL-first service, the general process is as follows:
1. Write your WSDL

2. Generate your server stubs
3. Configure the CXF endpoint in Mule
Writing an MTOM-enabled WSDL

To get started, write a WSDL like you would normally. Use xsd:base64Binary schema types to represent
any binary data that you want to send.
Normally, when creating XML schema types for binary data, you would write a schema type like this:
<element name="yourData" type="xsd:base64Binary"/>
To tell CXF to treat this binary type as an attachment, you must add an xmime:expectedContentTypes
attribute to it:
<schema targetNamespace="http://mediStor.org/types/"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xmime="http://www.w3.org/2005/05/xmlmime">
<element name="yourData" type="xsd:base64Binary"

xmime:expectedContentTypes="application/octet-stream"/>
...
</schema>
Generating Server Stubs and/or a Client

After writing your WSDL, you run wsdl2java on it to generate server stubs and a client (if you are
creating outbound endpoints). To do this, download the CXF distribution, extract it, and then enter the
following command:
$ ./apache-cxf-2.1.2-incubator/bin/wsdl2java -d outputDirectory path/to/your.wsdl
Configuring the CXF Inbound Endpoint

The above command generates a server stub interface. This is the interface that your service must
implement. Each method will correspond to an operation in your WSDL. If the base64Binary type is an
argument to one of your operations, CXF will generate a method like this:

public void yourOperation(DataHandler handler) {
...
}
You can use this DataHandler method to access the attachment data by calling
"handler.getInputStream();".
When you configure the endpoint, set the mtomEnabled attribute to true to enable MTOM:
<service name="mtomService">
<inbound>
<cxf:inbound-endpoint address="http://localhost:63081/services/mtomService" mtomEnabled="true" />
</inbound>
<component>
<singleton-object class="org.mule.transport.cxf.testmodels.TestMtomImpl" />
</component>
</service>
Configuring the CXF Outbound Endpoint

The configuration of an MTOM client endpoint is exactly like the configuration of a normal CXF outbound
endpoint, except that you must specify the mtomEnabled attribute. For example:
<cxf:outbound-endpoint
name="outboundEmployeeDirectoryEndpoint"
address="http://localhost:63081/services/employeeDirectory"
clientClass="org.mule.example.employee.EmployeeDirectory_Service"
operation="addEmployee"
wsdlPort="EmployeeDirectoryPort"
wsdlLocation="classpath:employeeDirectory.wsdl"
mtomEnabled="true"/>
See the Using a Web Service Client as an Outbound Endpoint page for more information.

EJB Transport
EJB Transport
The EJB transport allows EJB session beans to be invoked as part of an event flow. Components can be
given an EJB outbound endpoint, which will invoke the remote object and optionally return a result.
The Javadoc for this transport can be found here .
Connector
The Mule EJB Connector provides connectivity for EJB beans.
pollingFrequency long no Period (ms)

between polling
connections.
securityManager- name (no spaces) no Bean reference

ref to the security
manager that
should be used.
securityPolicy string no The security

policy (file name)
used to enable
connections.
serverClassName name (no spaces) no The target class

name.
serverCodebase string no The target

method.
For example:
<ejb:connector name="ejb" jndiContext-ref="jndiContext" securityPolicy="rmi.policy" />
Using the EJB Connector

EJB endpoints are configured the same way as RMI endpoints. Note that only outbound endpoints can use
the EJB transport. For a given endpoint, you must provide the following information:
• registry host
• registry port
• remote home name
• remote method name
These values will be used to establish the dispatcher connection. For example:

<ejb:endpoint host="localhost" port="1099" object="SomeService" method="remoteMethod"/>
Alternatively, you could use URI-based configuration:
<outbound-endpoint address="ejb://localhost:1099/SomeService?method=remoteMethod"/>
If the method can take one or more input arguments, you configure their types as a comma-separated
list using the methodArgumentTypes attribute. Multiple arguments are passed in as an array of objects as
the payload of the Mule message.
Transformers
There are no specific transformers required for EJB.

Email Transport
Email Transport
The Email transport provides a standard email connector that is extended by each of the email protocols.
Protocols
Each email protocol has a dedicated transport and configuration schema. The transports can be used to
connect to POP3 and IMAP mailboxes and for sending messages over SMTP using the javax.mail API.
For each of the protocols, SSL is supported and is enabled using POP3S, IMAPS, and SMTPS.
The email transports support protocol features such as attachments, replyTo, CC and BCC addresses,
binary content types, and custom headers. Each email transport supports the following attributes for
connecting to the mail server:
Attribute Description
user The user name for connecting to the mail server
password The password for connecting to the mail server
host The host of the mail server
port The port of the mail server
The Javadoc for the email transports can be found here .
For information about configuring specific endpoints, see the following links:
• SMTP and SMTPS Transport

• POP3 and POP3S Transport
• IMAP and IMAPS Transport
Filters
Filters can be set on an endpoint to filter out any unwanted messages. The Email transport provides a
couple of filters that can either be used directly or extended to implement custom filtering rules.
Filter Description
org.mule.transport.email.filters.AbstractMailFilter A base filter implementation that must be

extended by any other mail filter.
org.mule.transport.email.filters.MailSubjectRegExFilter
Applies a regular expression to a Mail Message
subject.
For more information on filters, see Using Filters.
Transformers
These are transformers specific to this transport. Note that these are added automatically to the Mule
registry
at start up. When doing automatic transformations these will be included when searching for the correct

transformers.
Name Description
email-to-string-transformer Converts an email message to string format.
string-to-email-transformer Converts a string message to email format.
object-to-mime-transformer Converts an object to MIME format.
mime-to-bytes-transformer Converts a MIME message to a byte array.
bytes-to-mime-transformer Converts a byte array message to MIME format.

File Transport
File Transport
Table of Contents
• File Transport
• ° Connector
- Child Elements of <connector...>
° Endpoint
° Inbound Endpoint
° Outbound Endpoint
° File To Byte Array Transformer
° File To String Transformer
° Legacy Filename Parser
° Expression Filename Parser
° Custom Filename Parser
° - Attributes of <custom-filename-parser...>
° Abstract Filenameparser
° Expressing File Endpoints
The File transport allows files to be read and written to and from directories on the local file system. The
connector can be configured to filter the file it reads and the way files are written, such as whether the
output will be placed in a new file or if it should be appended.
Connector
The File connector configures the default behavior for File endpoints that reference the connector. If there
is only one File connector configured, all file endpoints will use that connector.
writeToDirectory string no The directory path

where the file
should be written
on dispatch. This
path is usually set
as the endpoint
of the dispatch
event, however
this allows you to
explicitly force a
single directory for
the connector.
readFromDirectory string no The directory

path where the
file should be

read from. This
path is usually set
as the inbound
endpoint, however
this allows you to
explicitly force a
single directory for
the connector.
autoDelete boolean no true If set to true (the

default), it will
cause the file
to be deleted
once it is read.
If streaming is
turned on, this
occurs when the
InputStream for
the file is closed.
Otherwise the
file will be read
into memory
and deleted
immediately.
To access the
java.io.File
object set this
property to false
and specify a
NoActionTransformer
transformer for
the connector.
Mule will not
delete the file,
so it is up to the
component to
delete it when
it is done. If the
moveToDirectory
is set, the file is
first moved, then
the File object of
the moved file
is passed to the
component. It is
recommended
that a
moveToDirectory
is specified when
turning autoDelete
off.
outputAppend boolean no false Whether the

output should
be appended to
the existing file.
Default is false.
serialiseObjects boolean no Determines

whether objects
should be
serialized to the
file. If false (the
default), the raw

bytes or text is
written.
streaming boolean no true Whether a

FileInputStream
should be sent
as the message
payload (if true)
or a file (if false).
The default is
true.
pollingFrequency long no The frequency in

milliseconds that
the read directory
should be checked
(default is 0).
Note that the
read directory
is specified by
the endpoint
of the listening
component.
fileAge long no Miniumum age

(ms) for a file to
be processed.
This can be useful
when consuming
large files. It tells
Mule to wait for
a period of time
before consuming
the file, allowing
the file to be
completely written
before the file is
processed.
moveToPattern string no The pattern to

use when moving
a read file to
a new location
determined by the
moveToDirectory
property. This can
use the patterns
supported by the
filename parser
configured for this
connector.
moveToDirectory string no The directory path

where the file
should be written
after it has been
read. If this is
not set, the file
is deleted after it
has been read.
comparator class name no Sorts incoming

files using
the specified

comparator,
such as
comparator="org.mule.transp
The class must
implement the
java.util.Comparator
interface.
reverseOrder boolean no Whether the

comparator
order should be
reversed. Default
is false.
outputPattern string no The pattern to use

when writing a file
to disk. This can
use the patterns
supported by the
filename parser
configured for this
connector.
Child Elements of <connector...>
Name Cardinality Description
abstract-filenameParser 0..1 A placeholder for flename parser

elements.
Endpoint
path string no A file directory

location.

milliseconds that
the read directory
should be checked
(default is 0).
Note that the
read directory
is specified by
the endpoint
of the listening
component.

(ms) for a file to
be processed.
This can be useful
when consuming
Mule to wait for

a period of time
before consuming
the file, allowing
the file to be
completely written
before the file is
processed.

use when moving
a read file to
a new location
determined by the
moveToDirectory
property. This can
use the patterns
supported by the
filename parser
configured for this
connector.

where the file
should be written
after it has been
read. If this is
not set, the file
is deleted after it
has been read.

files using
the specified
comparator,
such as
The class must
implement the
interface.

comparator
order should be
reversed. Default
is false.

when writing a file
to disk. This can
use the patterns
supported by the
filename parser
configured for this
connector.
Inbound Endpoint

location.

milliseconds that
the read directory
should be checked
(default is 0).
Note that the
read directory
is specified by
the endpoint
of the listening
component.

(ms) for a file to
be processed.
This can be useful
when consuming
Mule to wait for
a period of time
before consuming
the file, allowing
the file to be
completely written
before the file is
processed.

use when moving
a read file to
a new location
determined by the
moveToDirectory
property. This can
use the patterns
supported by the
filename parser
configured for this
connector.

where the file
should be written
after it has been
read. If this is
not set, the file
is deleted after it
has been read.

files using
the specified
comparator,
such as
The class must
implement the
interface.

comparator
order should be
reversed. Default
is false.
Outbound Endpoint

location.

when writing a file
to disk. This can
use the patterns
supported by the
filename parser
configured for this
connector.
File To Byte Array Transformer

Reads the contents of a java.io.File into a byte array (byte[]).
File To String Transformer

Reads the contents of a java.io.File into a java.lang.String.
Legacy Filename Parser

The default filename parser used by the File connector. It understands the following patterns:
• #[DATE] - the current date in the format dd-MM-yy_HH-mm-ss.SS

• #[DATE:yy-MM-dd] - the current date using the specified format
• #[SYSTIME] - The current system time milliseconds
• #[UUID] - A generated Universally unique id
• #[ORIGINALNAME] - The original file name if the file being written was read from another location
• #[COUNT] - An incremental counter.
Expression Filename Parser

ExpressionFilenameParser can use any expression language supported by Mule to construct a file name
for the current message. Expressions can be xpath, xquery, ognl, mvel, header, function, and more. For
example, an xpath expression can be defined to pull a message ID out of an XML message and use that
as the file name:
#[xpath:/message/header/@id]
This parser superseeds the legacy-filename-parser from previous releases of Mule. The following
demonstrates how to achieve the same results when using the expression-filename-parser over the
legacy-filename-parser.
• #[DATE] : #[function:dateStamp]

• #[DATE:yy-MM-dd] : #[function:dateStamp(yy-MM-dd)]
• #[SYSTIME] : #[function:systime]
• #[UUID] : #[function:uuid]
• #[ORIGINALNAME] : #[header:originalFilename]
• #[COUNT] : #[function:counter] - note that this is a global counter. If you want a local counter per
file connector then you should use the legacy-filename-parser.
• #[<Message Property Name>] : #[header:\<Message Property Name\>}
Custom Filename Parser

Allows the user to specify a custom filename parser. The implementation must implement
org.mule.transport.file.FilenameParser.
Attributes of <custom-filename-parser...>
class name (no spaces) no The

implementation
class name that
implements
org.mule.transport.file.Fil
Abstract Filenameparser
A placeholder for flename parser elements.
Expressing File Endpoints

File endpoints can be expressed using standard File URI syntax:
file://<path>[MULE:?params]
For example, to connect to a directory called /temp/files -
Unix
file:///temp/files
Note the extra slash to denote a path from the root (absolute path).
Windows
file:///C:/temp/files
The Unix style will still work in Windows if you map to a single drive (the one Mule was started from).
To specify a relative path use:
file://./temp
or
file://temp
Note only two slashes are used for the protocol, so it's a relative path.
or
file://?address=./temp
To connect to a windows network drive:

file:////192.168.0.1/temp/

FTP Transport
FTP Transport
Table of Contents
• FTP Transport
• ° Connector
-
Mule Enterprise Connector Attributes
° Endpoint
° Inbound Endpoint
° Generic FTP Endpoints
° Filename Filters
° - Property Overrides
The FTP transport provides connectivity to FTP servers to allow files to be read and written as messages
in Mule.
Connector
The FTP connector is used to configure the default behavior for FTP endpoints that reference the
connector. If there is only one FTP connector configured, all FTP endpoints will use that connector.
validateConnections boolean no Causes Mule

to validate
connections before
use.
connectionFactoryClass
class name no A class that
extends
FtpConnectionFactory.
The
FtpConnectionFactory
is responsible
for creating a
connection to
the server using
the credentials
provided by
the endpoint.
The default
implementation
supplied with
Mule uses the

Commons Net
project from
Apache.
pollingFrequency long no How frequently

in milliseconds
to check the
read directory.
Note that the
read directory
is specified by
the endpoint
of the listening
component.

when writing a file
to disk. This can
use the patterns
supported by the
filename-parser
configured for this
connector
binary boolean no Select/disable

binary file transfer
type.
passive boolean no Select/disable

passive protocol
(more likely to
work through
firewalls).
file:abstract-filenameParser 0..1 The filenameParser is used

when writing files to an FTP
server. The parser will convert
the outputPattern attribute to
a string using the parser and
the current message. To add a
parser to your configuration,
you import the file namespace
into your XML configuration.
For more information about
filenameParsers, see the File
Transport.
Mule Enterprise Connector Attributes
The following attributes are available on the FTP connector in Mule Enterprise only (as of version 1.6):
moveToDirectory The directory path where the file should be

written after it has been read. If this property is
not set, the file is deleted.

moveToPattern The pattern to use when moving a read file to a
new location as specified by the moveToDirectory
property. This property can use the patterns
supported by the filenameParser configured for
this connector.
fileAge Does not process the file unless it's older than the
specified age in milliseconds.
Endpoint
path string no A file location on

the remote server.
user string no If FTP is

authenticated,
this is the
username used for
authenitcation.
password string no The password for

the user being
authenticated.
host string no An IP address

(such as
www.mulesource.com,
localhost, or
192.168.0.1).
port port number no The port number

to connect on.

type.

passive protocol
(more likely to
work through
firewalls).

in milliseconds
to check the
read directory.
Note that the
read directory
is specified by
the endpoint
of the listening
component.

when writing a file

to disk. This can
use the patterns
supported by the
filename-parser
configured for this
connector
Inbound Endpoint

the remote server.

authenticated,
this is the
username used for
authenitcation.

the user being
authenticated.

(such as
www.mulesource.com,
localhost, or
192.168.0.1).

to connect on.

type.

passive protocol
(more likely to
work through
firewalls).

in milliseconds
to check the
read directory.
Note that the
read directory
is specified by
the endpoint
of the listening
component.

Outbound Endpoint

the remote server.

authenticated,
this is the
username used for
authenitcation.

the user being
authenticated.

(such as
www.mulesource.com,
localhost, or
192.168.0.1).

to connect on.

type.

passive protocol
(more likely to
work through
firewalls).

when writing a file
to disk. This can
use the patterns
supported by the
filename-parser
configured for this
connector
Generic FTP Endpoints

FTP endpoints can be expressed using standard FTP URI syntax:
ftp://<username>:<password>@<hostname[MULE::port]>/[MULE:address]
which would render a URI like this:
ftp://joe:123456@ftp.mycompany.com/~
This URI would connect to the FTP server at mycompany.com with a user name of joe with password
123456 and would work on Joe's home directory.

Escape Your Credentials
If you use a URI-style endpoint and you include the user name and password, escape any
characters that are illegal for URIs, such as the @ character. For example, if the user name
is user@myco.com, you should enter it as user%40myco.com.
Filename Filters
Filters can be set on the endpoint to control which files are received by the endpoint. The filters are
expressed in a comma-separated list. To set up a filter to only read .XML and .TXT files, you would use
the following code:
<ftp:endpoint user="joe" password="123456" host="ftp.mycompany.com" path="/ftp/incoming">

<file:filename-wildcard-filter pattern="*.txt,*.xml"/>
</ftp:endpoint>
Property Overrides
You can override certain properties when defining FTP endpoints to control the endpoint's configuration.
These properties can be set on the endpoint or the current message (see the appropriate endpoint
attributes).
For example, to set the output pattern:
<ftp:endpoint user="joe" password="123456" host="ftp.mycompany.com" path="/ftp/incoming"

outputPattern="FtpFile-${DATE}.done"/>
Or to specify the same endpoint using a URI:
ftp://joe:123456@ftp.mycompany.com/ftp/done?outputPattern=FtpFile-${DATE}.done
For more information about configuring endpoints, see Configuring Endpoints.

HTTPS Transport
This page last changed on Sep 19, 2008 by jackie.wheeler.
HTTPS Transport
[ HTTPS Connector ] [ Polling Connector ] [ HTTPS Endpoints ]
The Secure HTTP transport provides support for exposing services over HTTP and making HTTP client
requests from Mule services to external services as part of service event flows. Mule supports secure
inbound, secure outbound, and secure polling HTTP endpoints. These endpoints support all common
features of the HTTP spec, such as ETag processing, cookies, and keepalive. Both HTTP 1.0 and 1.1 are
supported.
HTTPS Connector
This connector provides Secure HTTP connectivity on top of what is already provided with the Mule HTTP
Transport. Secure connections are made on behalf of an entity, which can be anonymous or identified by
a certificate. The key store provides the certificates and associated private keys necessary for identifying
the entity making the connection. Additionally, connections are made to trusted systems. The public
certificates of trusted systems are stored in a trust store, which is used to verify that the connection
made to a remote system matches the expected identity.
Property Description
tls-client Configures the client key store with the following

attributes:
• path: The location (which will be resolved

relative to the current classpath and file
system, if possible) of the keystore that
contains public certificates and private keys
for identification
• storePassword: The password used to
protect the keystore
• class: The type of keystore used (a Java
class name)
tls-key-store Configures the direct key store with the following

attributes:

for identification
class name)
• keyPassword: The password used to protect
the private key
• algorithm: The algorithm used by the
keystore
tls-server Configures the trust store. The attributes are:


system, if possible) of the trust store that
contains public certificates of trusted servers
protect the trust store
• class: The type of trust store used (a Java
class name)
• algorithm: The algorithm used by the trust
store
• factory-ref: Reference to the trust manager
factory
• explicitOnly: Whether this is an explicit trust
store
• requireClientAuthentication: Whether client
authentication is required
tls-protocol-handler Configures the global Java protocol handler. It

has one attribute, property, which specifies the
java.protocol.handler.pkgs system property.
For example:
<https:connector name="httpConnector">
<https:tls-client path="clientKeystore" storePassword="mulepassword" />
<https:tls-key-store path="serverKeystore" keyPassword="mulepassword" storePassword="mulepassword" /
>
<https:tls-server path="trustStore" storePassword="mulepassword" />
</https:connector>
<https:endpoint name="clientEndpoint" host="localhost" port="60202" synchronous="true" connector-
ref="httpConnector" />
Polling Connector
The polling connector allows Mule to poll an external HTTP server and generate events from the
result. This is useful for pull-only web services. This connector provides a secure version of the
PollingHttpConnector. It includes all the properties of the HTTPS connector plus the following optional
attributes:
pollingFrequency The time in milliseconds to wait between each

request to the remote http server.
checkEtag Whether the ETag header from the remote server

is processed if the header is present.
discardEmptyContent Whether Mule should discard any messages

from the remote server that have a zero content
length. For many services, a zero length would
mean there was no data to return. If the remote
HTTP server does return content to say that the
request is empty, users can configure a content
filter on the endpoint to filter these messages out.
For example:

<http:polling-connector name="PollingHttpConnector" pollingFrequency="2000" />
HTTPS Endpoints
An inbound HTTPS endpoint exposes a service securely over HTTPS, essentially making it an HTTP server.
If polling of a remote HTTP service is required, this endpoint should be configured with a polling HTTPS
connector.
An outbound HTTPS endpoint allows Mule to send requests securely using SSL to external servers or Mule
inbound HTTP endpoints using HTTP over SSL protocol.
A global HTTPS endpoint can be referenced by services. Services can augment the configuration defined
in the global endpoint with local configuration elements.
For more information on configuring HTTP endpoints, see HTTP Transport.

HTTP Transport
HTTP Transport
Table of Contents
• HTTP Transport
• ° Connector
° Inbound Endpoint
° Endpoint
° Transformers
° Polling Connector
° - Attributes of <polling-connector...>
° Rest Service Component
° - Attributes of <rest-service-component...>
- Child Elements of <rest-service-component...>
° Security
° - Sending Credentials
° Cookies
° Polling HTTP Services
° Handling HTTP Content-Type and Encoding
° - Sending HTTP
- Receiving HTTP
° Including Custom Header Properties
° Handling Redirects
° Getting a Hash Map of Properties
The HTTP transport provides support for exposing services over HTTP and making HTTP client requests
from Mule services to external services as part of service event flows. Mule supports inbound, outbound,
and polling HTTP endpooints. These endpoints support all common features of the HTTP spec, such as
ETag processing, cookies, and keepalive. Both HTTP 1.0 and 1.1 are supported.
Connector
Allows Mule to communicate over HTTP. All parts of the HTTP spec are covered by Mule, so you can
expect ETags to be honored as well as keep alive semantics and cookies.
cookieSpec netscape/rfc2109 no The cookie

specification
to be used by
this connector
when cookies are
enabled.

proxyHostname string no The proxy host
name or address.
proxyPassword string no The password

to use for proxy
access.
proxyPort port number no The proxy port

number.
proxyUsername string no The username

to use for proxy
access.
enableCookies boolean no Whether to

support cookies.
Inbound Endpoint
An inbound HTTP endpoint exposes a service over HTTP, essentially making it an HTTP server. If polling of
a remote HTTP service is required, this endpoint should be configured with a polling HTTP connector.
user string no The user name

(if any) that
will be used to
authenticate
against.

the user.
host string no The host to

connect to.
For inbound
endpoints, this
should be an
address of a local
network interface.

to use when a
connection is
made.
path string no The path for the

HTTP URL.
contentType string no The HTTP

ContentType to
use.
method httpMethodTypes no The HTTP method

to use.
keep-alive boolean no Controls if the

socket connection

is kept alive. If set
to true, a keep-
alive header with
the connection
timeout specified
in the connector
will be returned.
If set to false,
a "Connection:
close" header will
be returned.
Outbound Endpoint
The HTTP outbound endpoint allows Mule to send requests to external servers or Mule inbound HTTP
endpoints using the HTTP protocol.

(if any) that
will be used to
authenticate
against.

the user.

connect to.
For inbound
endpoints, this
should be an
address of a local
network interface.

to use when a
connection is
made.

HTTP URL.

ContentType to
use.

to use.

socket connection
to true, a keep-
alive header with
the connection
timeout specified
in the connector

will be returned.
If set to false,
a "Connection:
close" header will
be returned.
Endpoint
Configures a 'global' HTTP endpoint that can be referenced by services. Services can augment the
configuration defined in the global endpoint with local configuration elements.

(if any) that
will be used to
authenticate
against.

the user.

connect to.
For inbound
endpoints, this
should be an
address of a local
network interface.

to use when a
connection is
made.

HTTP URL.

ContentType to
use.

to use.

socket connection
to true, a keep-
alive header with
the connection
timeout specified
in the connector
will be returned.
If set to false,
a "Connection:
close" header will
be returned.

Transformers
registry
transformers.
Name Description
http-client-response-to-object-transformer A transformer that converts an HTTP response to

a Mule Message. The payload may be a String,
stream, or byte array.
http-response-to-string-transformer Converts an HTTP response payload into a string.

The headers of the response will be preserved on
the message.
object-to-http-client-request-transformer This transformer will creat a valid HTTP request

using the current message and any HTTP headers
set on the current message.
message-to-http-response-transformer This transformer will creat a valid HTTP response

using the current message and any HTTP headers
set on the current message.
Polling Connector
Allows Mule to poll an external HTTP server and generate events from the result. This is useful for pull-
only web services.
Attributes of <polling-connector...>
cookieSpec netscape/rfc2109 no The cookie

specification
to be used by
this connector
when cookies are
enabled.
proxyHostname string no The proxy host

name or address.
proxyPassword string no The password

to use for proxy
access.
proxyPort port number no The proxy port

number.
proxyUsername string no The username

to use for proxy
access.
enableCookies boolean no Whether to

support cookies.

pollingFrequency long no The time in
milliseconds to
wait between
each request to
the remote HTTP
server.
checkEtag boolean no Whether the ETag

header from the
remote server is
processed if the
header is present.
discardEmptyContentboolean no Whether Mule

should discard
any messages
from the remote
server that have
a zero content
length. For many
services a zero
length would
mean there was
no data to return.
If the remote
HTTP server does
return content
to say that that
the request is
empty, users
can configure
a conent filter
on the endpoint
to filter these
messages out.
Rest Service Component

Built-in RestServiceWrapper can be used to proxy REST style services as local Mule components.
Attributes of <rest-service-component...>
httpMethod GET/POST no GET The HTTP method

to use when
making the
service request.
serviceUrl no The service URL to

use when making
the request. This
should not contain
any parameters,
since these should
be configured on
the component.
The service URL
can contain Mule
expressions, so

the URL can be
dynamic for each
message request.
Child Elements of <rest-service-component...>
error-filter 0..1 An error filter can be used to

detect whether the response
from the remote service resulted
in an error.
payloadParameterName 0..* If the payload of the message

is to be attached as a URL
parameter, this should be set
to the parameter name. If the
message payload is an array of
objects that multiple parameters
can be set to, use each element
in the array.
requiredParameter 0..* These are parameters that must

be available on the current
message for the request to be
successful. The Key maps to
the parameter name, the value
can be any one of the valid
expressions supported by Mule.
optionalParameter 0..* These are parameters that if

they are on the current message
will be added to the request,
otherwise they will be ignored.
The Key maps to the parameter
name, the value can be any
one of the valid expressions
supported by Mule.
Security
You can use the HTTPS Transport to create secure connections over HTTP. If you want to secure requests
to your HTTP endpoint, the HTTP connector supports HTTP Basic/Digest authentication methods (as well
as the Mule generic header authentication). To configure HTTP Basic, you configure a Security Endpoint
Filter on an HTTP endpoint.
<inbound-endpoint address="http://localhost:4567">
<acegi:http-security-filter realm="mule-realm" />
</inbound-endpoint>
You must configure the security manager on the Mule instance against which this security filter will
authenticate. For information about security configuration options and examples, see Configuring
Security.
If you want to make an HTTP request that requires authentication, you can set the credentials on the
endpoint:

<inbound-endpoint address="user:password@mycompany.com/secure">
<acegi:http-security-filter realm="mule-realm" />
</inbound-endpoint>
For general information about endpoint configuration, see Configuring Endpoints.
Sending Credentials
If you want to make an HTTP request that requires authentication, you can set the credentials on the
endpoint:
http://user:password@mycompany.com/secure
Cookies
If you want to send cookies along on your outgoing request, simply configure them on the endpoint:
<http:outbound-endpoint address="http://localhost:8080" method="POST">

<properties>
<spring:entry key="Content-Type" value="text/xml" />
<spring:entry key="cookies">
<spring:map>
<spring:entry key="customCookie" value="yes" />
</spring:map>
</spring:entry>
</properties>
</http:outbound-endpoint>
Polling HTTP Services

The HTTP transport supports polling an HTTP URL, which is useful for grabbing periodic data from a page
that changes or to invoke a REST service, such as polling an Amazon Queue.
To configure the HTTP Polling receiver, you include an HTTP polling-connector configuration in your Mule
configuration:
<http:polling-connector name="PollingHttpConnector" pollingFrequency="30000" reuseAddress="true" />
To use the connector in your endpoints, use:
<http:inbound-endpoint user="marie" password="marie" host="localhost" port="61205" connector-

ref="PollingHttpConnector" />
Handling HTTP Content-Type and Encoding
Sending HTTP
The following behavior applies when sending POST request bodies as a client and when returning a
response body:

For a String, char[], Reader, or similar:
• If the endpoint has encoding set explicitly, use that

• Otherwise, take it from the message's property Content-Type
• If none of these is set, use the Mule Context's configuration default.
• For Content-Type, send the message's property Content-Type but with the actual encoding set.
For binary content, encoding is not relevant. Content-Type is set as follows:
• If the Content-Type property is set on the message, send that.

• Send "application/octet-stream" as Content-Type if none is set on the message.
Receiving HTTP
When receiving HTTP responses, the payload of the MuleMessage will always be the InputStream of the
HTTP response.
Including Custom Header Properties

When making a new HTTP client request, Mule filters out any existing HTTP request headers because they
are often from a previous request. For example, if you have an HTTP endpoint that proxies another HTTP
endpoint, you wouldn't want to copy the Content-Type header property from the first HTTP request to
the second request.
If you do want to include HTTP headers, you can specify them using the http.custom.headers map
property as follows:
<outbound>
<outbound-endpoint address="http://localhost:9002/events" connector-ref="HttpConnector">
<property key="Content-Type" value="image/png"/>
<property key="Accept" value="*.*"/>
</outbound-endpoint>
</outbound>
Handling Redirects
To redirect an HTTP client, you must set two properties on the endpoint. First, set the http.status
property to '307', which instructs the client that the resource has be temporarily redirected. Alternatively,
you can set the property to '301' for a permanent redirect. Second, set the Location property, which
specifies the location where you want to redirect your client.
See the HTTP protocol specification for detailed information about status codes at http://
www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.
Following is an example of a service that is listening on the local address http://localhost:8080/

mine and will send a response with the redirection code, instructing the client to go to http://
mule.mulesource.org/.
<service name="redirecter">
<inbound>
<inbound-endpoint address="http://localhost:8080/mine" synchronous="true">
<property key="http.status" value="307"/>
<property key="Location" value="http://mule.mulesource.org/"/>
</inbound-endpoint>
<inbound>

</service>
Note that you must set the synchronous attribute to true. Otherwise, the service will be asynchronous,
and a response will be immediately returned while the request is placed on an internal queue.
Getting a Hash Map of Properties

You can use the custom transformer HttpRequestBodyToParamMap on your inbound endpoint to return
the message properties as a hash map of name-value pairs. This transformer handles GET and POST with
application/x-www-form-urlencoded content type.
For example:
<http:inbound-endpoint ...>
<custom-transformer name="myTransformer"
class="org.mule.transport.http.transformers.HttpRequestBodyToParamMap" />
</http:inbound-endpoint>

IMAPS Transport
IMAPS Transport
TLS/SSL connections are made on behalf of an entity, which can be anonymous or identified by a
certificate. The key store provides the certificates and associated private keys necessary for identifying
The IMAPS connector enables IMAP over SSL using the javax.mail APIs. It supports all the elements and
attributes of the IMAP connector plus some required properties for setting up the client key store and the
trust store for the SSL connection.

attributes:

for identification
class name)
tls-trust-store Configures the trust store. The attributes are:

For example:
<imaps:connector name="imapsConnector">
<imaps:tls-client path="clientKeystore" storePassword="mulepassword" />
<imaps:tls-trust-store path="greenmail-truststore" storePassword="password" />
</imaps:connector>
<model name="test">
<service name="relay">
<inbound>
<imaps:inbound-endpoint user="bob" password="password" host="localhost" port="65436" />
</inbound>
...
For information on configuring endpoints using the IMAPS connector, see IMAP Transport.
The IMAPS transport supports the same filters and transformers as the Email Transport.

IMAP Transport
IMAP Transport
The IMAP transport can be used for receiving messages from IMAP inboxes using the javax.mail API.
The IMAPS Transport uses secure connections over SSL/TLS. The IMAP transport uses the same filters
and transformers as the Email Transport.
The Javadoc for this provider can be found here .
IMAP Connector
The IMAP connector supports all the common connector attributes and properties and the following
additional attributes:
Attribute Description Default Required
backupEnabled Whether to save copies False No

to the backup folder.
backupFolder The folder where No

messages are moved
for audit purposes after
they have been read.
checkFrequency Determines how often 60000 Yes

(in milliseconds) the
IMAP mailbox is polled
for new messages.
mailboxFolder The remote folder to INBOX No

check for email.
deleteReadMessages Whether to delete true No

messages after they
have been downloaded.
If set to false, the
messages are set to
SEEN.
Endpoints
IMAP and IMAPS endpoints include details about connecting to an IMAP mailbox. You configure the
endpoints just as you would with any other transport, with the following additional attributes:
• user: the user name of the mailbox owner

• password: the password of the user
• host: the IP address of the IMAP server, such as www.mulesource.com, localhost, or 127.0.0.1
• port: the port number of the IMAP server. If not set for the IMAPS connector, the default port is 993.
For example:
<imap:inbound-endpoint user="bob" password="password" host="localhost" port="65433"

checkFrequency="3000"/>
or for IMAPS:

<imaps:inbound-endpoint user="bob" password="password" host="localhost" port="65433"
checkFrequency="3000"/>
This will log into the bob mailbox on localhost on port 65433 using password password and will check
the mailbox for new messages every 30 seconds. You can also specify the endpoint settings using a URI,
but the above syntax is easier to read.

JDBC Transport
JDBC Transport
[ Introduction ] [ Features ] [ Transactions ] [ API Documentation and Notes ] [ Runnable Examples ] [
Performance Results ]
Introduction
The JDBC Transport allows you to send and receive messages with a database using the JDBC protocol.
Common usage includes retrieving, inserting, updating, and deleting database records, as well as
invoking stored procedures (e.g., to create new tables dynamically).
Some features are available only with the Mule Enterprise version of the JDBC transport, which is
available with version 1.6 and later of Mule Enterprise Edition. These EE-only features are noted below.
Features
The Mule Enterprise JDBC Transport provides key functionality, performance improvements, transformers,
and examples not available in the Mule Community edition. The following table summarizes the feature
differences.
Feature Summary Mule Community Mule Enterprise
Inbound SELECT Retrieve records x x

Queries using the SQL SELECT
statement configured
on inbound endpoints.
Large Dataset Retrieval Enables retrieval x

arbitrarily large
datasets by consuming
records in smaller
batches.
Acknowledgment Supports ACK SQL x x

Statements statements that update
the source or other
table after a record is
read.
Basic Insert/Update/ Individual SQL INSERT, x x

Delete Statements UPDATE, and DELETE
queries specified on
outbound endpoints.
One statement is
executed at a time.
Batch Insert/Update/ Support for JDBC batch x

Delete Statements INSERT, UPDATE, and
DELETE statements, so
that many statements
can be executed
together.
Advanced JDBC-related XML and CSV x

Transformers transformers for easily

converting to and
from datasets in these
common formats.
Outbound SELECT Retrieve records using x

Queries SQL SELECT statement
configured on outbound
endpoints. Supports
synchronous queries
with dynamic runtime
parameters.
Stored Procedure Ability to invoke stored x x

Support - Basic procedures. Supports
IN parameters but not
OUT parameters.
Stored Procedure Same as Basic but x

Support - Advanced includes both IN
and OUT parameter
support. OUT
parameters can be
simple data types or
cursors
Unnamed Queries Queries that x x

can be invoked
programmatically
from within service
components or other
Java code. This is the
most flexible option,
but also requires
writing code.
Flexible Data Source Support for x x

Configuration configuration of data
sources through JNDI,
XAPool, or Spring.
Transactions Support for x x

transactions via
underlying Transaction
Manager.
Important Note on Namespaces
When using JDBC EE features, you will need to import the EE namespace for the JDBC transport, which
has .com instead of .org in the URL, and the XSD name is mule-jdbc-ee.xsd instead of mule-jdbc.xsd.
For example:
<mule
xmlns:jdbc="http://www.mulesource.com/schema/mule/jdbc/2.1"
xsi:schemaLocation="http://www.mulesource.com/schema/mule/jdbc/2.1 http://www.mulesource.com/
schema/mule/jdbc/2.1/mule-jdbc-ee.xsd">
As of Mule EE 2.2, the path will be slightly different (.org instead of .com, addition of /ee in path):
<mule
xmlns:jdbc="http://www.mulesource.org/schema/mule/ee/jdbc/2.2"
xsi:schemaLocation="http://www.mulesource.org/schema/mule/ee/jdbc/2.2 http://www.mulesource.org/
schema/mule/ee/jdbc/2.2/mule-jdbc-ee.xsd">
If you are not using JDBC EE features, then you can use the normal CE namespace:
<mule
xmlns:jdbc="http://www.mulesource.org/schema/mule/jdbc/2.1"
xsi:schemaLocation="http://www.mulesource.org/schema/mule/jdbc/2.1 http://www.mulesource.org/
schema/mule/jdbc/2.0/mule-jdbc.xsd">
Inbound SELECT Queries
Inbound SELECT queries are queries that are executed periodically (according to the pollingInterval
set on the connector).
Here is an example:
<spring:bean id="jdbcDataSource" class="org.enhydra.jdbc.standard.StandardDataSource" destroy-

method="shutdown">
<spring:property name="driverName" value="oracle.jdbc.driver.OracleDriver"/>
<spring:property name="url" value="jdbc:oracle:thin:user/pass@host:1521:db"/>
</spring:bean>
...
<jdbc:connector name="jdbcConnector" pollingFrequency="10000" dataSource-ref="jdbcDataSource">
<jdbc:query key="selectLoadedMules"
value="SELECT ID, MULE_NAME, RANCH, COLOR, WEIGHT, AGE from mule_source where ID
between 0 and 20"/>
</jdbc:connector>
...
<model name="ExampleModel">
<service name="InboundSelectExample">
<inbound>
<jdbc:inbound-endpoint queryKey="selectMules"/>
</inbound>
<outbound>
<pass-through-router>
<vm:outbound-endpoint path="out"/>
</pass-through-router>
</outbound>
</service>
</model>
...
In this example, the inboundSelectQuery would be invoked every 10 seconds (pollingFrequency=10000

ms). Each record from the result set is converted into a Map (consisting of column/value pairs), and this
payload is sent to the VM endpoint shown above.
Inbound SELECT queries are limited because (1) generally, they cannot be called synchronously
(unnamed queries are an exception), and (2) they do not support runtime parameters.

Large Dataset Retrieval
Overview
Large dataset retrieval is a strategy for retrieving large datasets by fetching records in smaller, more
manageable batches. Mule Enterprise Edition provides the key components and transformers needed to
implement a wide range of these strategies.
When To Use It
• When the dataset to be retrieved is large enough to overwhelm memory and connection resources.
• When preserving the order of messages is important.
• When resumable processing is desired (that is, retrieval of the dataset can pick up where it left off,
even after service interruption).
• When load balancing the data retrieval among clustered Mule nodes.
How It Works
Large dataset retrieval does not use conventional inbound SELECT queries to retrieve data. Instead, it
uses a Batch Manager component to compute ID ranges for the next batch of records to be retrieved. An
outbound SELECT query uses this range to actually fetch the records. The Batch Manager also controls
batch processing flow to make sure that it does not process the next batch until the previous batch has
finished processing.
Detailed usage of the large dataset retrieval feature is shown in JDBC Example #4.
Important Limitations
Large dataset retrieval requires that:
1. The source data contains a unique, sequential numeric ID. Records should also be fetched in
ascending order with respect to this ID.
2. There are no large gaps in these IDs (no larger than the configured batch size).
In Combination with Batch Inserts
Combining large dataset retrieval with batch inserts can support simple but powerful ETL use cases. See
Example #4 and JDBC Transport Performance Benchmark Results for more details on how Mule can be
used to transport millions of records an hour from one database table to another.
Acknowledgment (ACK) Statements
ACK statements are optional SQL statements that are paired with inbound SELECT queries. When an
inbound SELECT query is invoked by Mule, the ACK statement is invoked for each record returned by
the query. Typically, the ACK statement is an UPDATE, INSERT, or DELETE.
Continuing the inbound SELECT query example above, the ACK statement would be configured as follows:
...
<jdbc:query key="selectLoadedMules"
value="SELECT ID, MULE_NAME, RANCH, COLOR, WEIGHT, PROCESSED from mule_source where ID
between 0 and 20"/>
<jdbc:query key="selectMules.ack"
value="update mule_source set PROCESSED='Y' where ID = #[map-payload:ID] "/>
</jdbc:connector>
...

Notice the convention of appending an ".ack" extension to the query name. This convention lets Mule
know which inbound SELECT query to pair with the ACK statement.
Also, note that the ACK statement supports parameters. These parameters are bound to any of the
column values from the inbound SELECT query (such as #[ID] in the case above).
ACK statements are useful when you want an inbound SELECT query to retrieve records from a source
table no more than once. Be careful, however, when using ACK statements with larger result sets. As
mentioned earlier, an ACK statement gets issued for each record retrieved, and this can be very resource-
intensive for even a modest number of records per second (> 100).
Basic Insert/Update/Delete Statements
SQL INSERT, UPDATE, and DELETE statements are specified on outbound endpoints. These statements
are typically configured with parameters, which are bound with values passed along to the outbound
endpoint from an upstream component.
Basic statements execute just one statement at a time, as opposed to batch statements, which execute
multiple statements at a time. Basic statements are appropriate for low-volume record processing
(<20 records per second), while batch statements are appropriate for high-volume record processing
(thousands of records per second).
For example, when a message with a java.util.Map payload is sent to a basic insert/update/delete
endpoint, the parameters in the statement are bound with corresponding entries in the Map. In the
configuration below, if the message contains a Map payload with {ID=1,TYPE=1,DATA=hello,ACK=0}, the
following insert will be issued: "INSERT INTO TEST (ID,TYPE,DATA,ACK) values (1,1,'hello',0)".

<jdbc:query key="outboundInsertStatement"
value="INSERT INTO TEST (ID, TYPE, DATA, ACK) VALUES (#[map-payload:ID],
#[map-payload:TYPE],#[map-payload:DATA], #[map-payload:ACK])"/>
</jdbc:connector>
...
<service name="outboundInsertExample">
<inbound>
<inbound-endpoint address="vm://doInsert"/>
</inbound>
<outbound>
<jdbc:outbound-endpoint queryKey="outboundInsertStatement"/>
</outbound>
</service>
</model>
...
Batch Insert/Update/Delete Statements
As mentioned above, batch statements represent a significant performance improvement over their
basic counterparts. Records can be inserted at a rate of thousands per second with this feature.
Usage of batch INSERT, UPDATE, and DELETE statements is the same as for basic statements, except the
payload sent to the VM endpoint should be a List of Maps, instead of just a single Map.
Examples #1 and #4 demonstrate this feature. Batch statements are available in Mule Enterprise Edition
only.
Batch Callable Statements are also supported. Usage is identical to Batch Insert/Update/Delete.

Advanced JDBC-related Transformers
Common integration use cases involve moving CSV and XML data from files to databases and back. This
section describes the transformers that perform these actions. These transformers are available in Mule
Enterprise Edition only.
XML-JDBC Transformer
The XML Transformer converts between XML and JDBC-format Maps. The JDBC-format Maps can be used
by JDBC outbound endpoints (for select, insert, update, or delete operations).
Transformer Details:
Name Class Input Output
XML -> Maps org.mule.providers.jdbc.transformers.XMLToMapsTransformer

java.lang.String (XML) java.util.List
(List of Maps. Each
Map corresponds to a
"record" in the XML.)
Maps -> XML org.mule.providers.jdbc.transformers.MapsToXMLTransformer

java.util.List java.lang.String (XML)
(List of Maps. Each Map
will be converted into a
"record" in the XML)
Also, the XML message payload (passed in or out as a String) must adhere to a particular schema format:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:element name="table">
<xs:complexType>
<xs:sequence>
<xs:element ref="record"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="record">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" ref="field"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="field">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:NMTOKEN">
<xs:attribute name="name" use="required" type="xs:NCName"/>
<xs:attribute name="type" use="required" type="xs:NCName"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
Here is an example of a valid XML instance:
<table>

<record>
<field name="id" type="java.math.BigDecimal">0</field>
<field name="name" type="java.lang.String">hello</field>
</record>
</table>
The transformer converts each "record" element to a Map of column/value pairs using "fields". The
collection of Maps is returned in a List.
See Example #2, which uses the XML Transformer to convert results from a database query into an XML
document.
CSV-JDBC Transformer
The CSV Transformer converts between CSV data and JDBC-format Maps. The JDBC-format Maps can be
used by JDBC outbound endpoints (for select, insert, update, or delete operations).
Transformer Details:
Name Class Input Output
CSV -> Maps org.mule.providers.jdbc.transformers.CSVToMapsTransformer

java.lang.String java.util.List
(CSV data) (List of Maps. Each
Map corresponds to a
"record" in the CSV)
Maps -> CSV org.mule.providers.jdbc.transformers.MapsToCSVTransformer

java.util.List java.lang.String
(List of Maps. Each Map (CSV data)
will be converted into a
"record" in the CSV)
The following table summarizes the properties that can be set on this transformer:
delimiter The delimiter character used in the CSV file.

Defaults to comma.
qualifier The qualifier character used in the CSV file.

Used to signify if text contains the delimiter
character.Defaults to double quote.
ignoreFirstRecord Instructs transformer to ignore the first record.

Defaults to false.
mappingFile Location of Mapping file. Required. Can either

be physical file location or classpath resource
name. The DTD format of the Mapping File can
be found at: http://flatpack.sourceforge.net/
flatpack.dtd. For examples of this format, see
http://flatpack.sourceforge.net/documentation/
index.html.
For an example, see Example #1, which uses the CSV Transformer to load data from a CSV file to a
database table.

Outbound SELECT Queries
An inbound SELECT query is invoked on an inbound endpoint according to a specified polling interval. A
major improvement to the inbound SELECT query is the outbound SELECT query, which can be invoked
on an outbound endpoint. As a result, the outbound SELECT query can do many things that the inbound
SELECT query cannot, such as:
1. Support synchronous invocation of queries. For example, you can implement the classic use case of
a web page that serves content from a database using an HTTP inbound endpoint and an outbound
SELECT query endpoint.
2. Allows parameters so that values can be bound to the query at runtime. This requires that the
message contain a Map payload containing key names that match the parameter names. For
example, the following configuration could be used to retrieve an outbound SELECT query:
...
<jdbc:connector name="jdbcConnector" dataSource-ref="jdbcDataSource">
<jdbc:query key="selectMules"
value="select * from mule_source where ID between 0 and #[map-payload:ID]"/>
</jdbc:connector>
...
<service name="selectOutboundExample">
<inbound>
<inbound-endpoint address="vm://mapReceiver"/>
</inbound>
<outbound>
<jdbc:outbound-endpoint queryKey="selectMules"/>
</outbound>
</service>
</model>
In this scenario, if a Map is sent to the vm://mapReceiver endpoint containing this key/value pair:
key=ID
value=3
The following query is executed:
SELECT * FROM mule_source WHERE ID between 0 and 3
See Examples #2 and #3 for further outbound SELECT query examples. Note that this feature is
available in Mule Enterprise Edition only.
Stored Procedure Support - Basic
Like any other query, stored procedure queries can be listed in the "queries" map. Following is an
example of how stored procedure queries could be defined:

<jdbc:query key="storedProc" value="CALL addField()"/>

</jdbc:connector>
To denote that we are going to execute a stored procedure and not a simple SQL query, we must start off
the query by the text CALL followed by the name of the stored procedure.
Parameters to stored procedures can be forwarded by either passing static parameters in the
configuration or using the same syntax as for SQL queries. For example:
<jdbc:query key="storedProc1" value="CALL addFieldWithParams(24)"/>

<jdbc:query key="storedProc2" value="CALL addFieldWithParams(#[map-payload:value])"/>
...
<jdbc:outbound-endpoint queryKey="storedProc1"/>
...
<jdbc:outbound-endpoint address="jdbc://storedProc2?value=25"/>
...
Stored Procedure Support - Advanced
Mule Enterprise Edition provides advanced stored procedure support not available in Mule Community
Edition. This section describes the advanced support.
OUT Parameters
In Mule Enterprise, you can execute your stored procedures with out and inout scalar parameters. The
syntax for such parameters is:
<jdbc:query key="storedProc1" value="CALL myProc(#[a], #[b;int;inout], #[c;string;out])"/>
You must specify the type of each output parameter (OUT, INOUT) and its data type (int, string, etc.).
The result of such stored procedures is a map containing (out parameter name, value) entries.
See Example #3 for more examples.
Oracle Cursor Support
For Oracle databases only, an OUT parameter can return a cursor. The following example shows how this
works.
If you want to handle the cursor as a java.sql.ResultSet, see the "cursorOutputAsResultSet" service
below, which uses the "MapLookup" transformer to return the ResultSet.
If you want to handle the cursor by fetching the java.sql.ResultSet to a collection of Map objects,
see the "cursorOutputAsMaps" service below, which uses both the "MapLookup" and "ResultSet2Maps"
transformers to achieve this result.
<jdbc:connector name="jdbcConnector" pollingFrequency="1000" cursorTypeConstant="-10"

dataSource-ref="jdbcDataSource">
<jdbc:query key="SingleCursor" value="call TEST_CURSOR(#[mules;resultSet;out])"/>
</jdbc:connector>

<custom-transformer class="org.mule.transformer.simple.MapLookup" name="MapLookup">
<spring:property name="key" value="mules"/>
</custom-transformer>
<jdbc:resultset-to-maps-transformer name="ResultSet2Maps"/>
<model name="SPModel">
<service name="cursorOutputAsMaps">
<inbound>
<vm:inbound-endpoint path="returns.maps" responseTransformer-refs="MapLookup
ResultSet2Maps"/>
</inbound>
<outbound>
<jdbc:outbound-endpoint queryKey="SingleCursor"/>
</outbound>
</service>
<service name="cursorOutputAsResultSet">
<inbound>
<vm:inbound-endpoint path="returns.resultset" responseTransformer-refs="MapLookup"/>
</inbound>
<outbound>
<jdbc:outbound-endpoint queryKey="SingleCursor"/>
</outbound>
</service>
</model>
In the above example, note that it is also possible to call a function that returns a cursor ref. For
example, if TEST_CURSOR2() returns a cursor ref, the following statement could be used to get that
cursor as a ResultSet:
<jdbc:query key="SingleCursor" value="call #[mules;resultSet;out] := TEST_CURSOR2()"/>
Important note on transactions: When calling stored procedures or functions that return
cursors (ResultSet), it is recommended that you process the ResultSet within a transaction.
Unnamed Queries
SQL statements can also be executed without configuring queries in the Mule configuration file. For a
given endpoint, the query to execute can be specified as the address of the URI.
MuleMessage msg = eventContext.receiveEvent("jdbc://SELECT * FROM TEST", 0);
Flexible Data Source Configuration
You can use any JDBC data source library with the JDBC Connector. The "myDataSource" reference below
refers to a DataSource bean created in Spring:
<jdbc:connector name="jdbcConnector" pollingFrequency="10000" dataSource-ref="myDataSource">

...

</jdbc:connector>
You can also create a JDBC connection pool so that you don't create a new connection to the database for
each message. You can easily create a pooled data source in Spring using xapool. The following example
shows how to create the Spring bean right in the Mule configuration file.
<spring:bean id="pooledDS" class="org.enhydra.jdbc.standard.StandardDataSource" destroy-

method="shutdown">
<spring:property name="driverName" value="oracle.jdbc.driver.OracleDriver"/>
<spring:property name="url" value="jdbc:oracle:thin:user/pass@host:1521:db"/>
</spring:bean>
If you need more control over the configuration of the pool, you can use the standard JDBC classes. For
example, you could create the following beans in the Spring configuration file (you could also create them
in the Mule configuration file by prefixing everything with the Spring namespace):
//create the data source that will establish the connection

<bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
<property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/>
<property name="url" value="jdbc:oracle:thin:@mydb:1521:orcl"/>
<property name="username" value="my_user"/>
<property name="password" value="xyz123"/>
</bean>
//create the pool

<bean id="pool" class="org.apache.commons.pool.impl.GenericObjectPool">
<property name="minEvictableIdleTimeMillis" value="300000" />
<property name="timeBetweenEvictionRunsMillis" value="60000"/>
<property name="maxActive" value="256"/>
<property name="maxIdle" value="100"/>
<property name="whenExhaustedAction" value="2"/>
</bean>
//create a connection factory for the data source

<bean id="dsConnectionFactory" class="org.apache.commons.dbcp.DataSourceConnectionFactory">
<constructor-arg><ref bean="dataSource"/></constructor-arg>
</bean>
//create a poolable connection factory based on the above pool and connection factory
<bean id="poolableConnectionFactory" class="org.apache.commons.dbcp.PoolableConnectionFactory">
<constructor-arg index="0"><ref bean="dsConnectionFactory"/></constructor-arg>
<constructor-arg index="1"><ref bean="pool"/></constructor-arg>
<constructor-arg index="2"><null/></constructor-arg>
<constructor-arg index="3"><null/></constructor-arg>
<constructor-arg index="4"><value>false</value></constructor-arg>
<constructor-arg index="5"><value>true</value></constructor-arg>
</bean>
//create pooling data source based on the poolable connection factory and pool
<bean id="pooledDS" class="org.apache.commons.dbcp.PoolingDataSource" depends-
on="poolableConnectionFactory">
<constructor-arg><ref bean="pool"/></constructor-arg>
</bean>
You could then reference the pooledDS bean in your Mule configuration:

<jdbc:connector name="jdbcConnector" dataSource-ref="pooledDS"/>
To retrieve the data source from a JNDI repository, you would configure the connector as follows:
<spring:beans>
<jee:jndi-lookup id="myDataSource" jndi-name="yourJndiName" environment-ref="yourJndiEnv" />
<util:map id="jndiEnv">
<spring:entry key="java.naming.factory.initial" value="yourJndiFactory" />
</util:map>
</spring:beans>
The above example shows how to create the Spring beans right in the Mule configuration file. This
approach would require the following namespaces:
xmlns:jee="http://www.springframework.org/schema/jee"
xmlns:util="http://www.springframework.org/schema/util"
xmlns:jdbc="http://www.mulesource.org/schema/mule/jdbc/2.1"
beans-2.0.xsd
http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-
jee-2.0.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-
util-2.0.xsd
mule.xsd
http://www.mulesource.org/schema/mule/jdbc/2.1 http://www.mulesource.org/schema/mule/jdbc/2.1/
mule-jdbc.xsd">
Transactions
Transactions are supported on JDBC Endpoints. See Transaction Management for details.
API Documentation and Notes
Connector Properties
dataSource-ref Reference to the Yes

JDBC data source
to use. When using
XA transactions, an
XADataSource object
must be provided.
pollingFrequency The delay in No

milliseconds that will

be used during two
subsequent polls to the
database
resultSetHandler-ref Reference to org.apache.commons.dbutils.

No
ResultSetHandler used handlers.MapListHandler
to pass back query
results. For more
information about
this object, see the
examples.
queryRunner-ref Reference to the org.apache.commons.dbutils.

no
QueryRunner to use QueryRunner
when executing a
Query. For more
information about
this object, see the
examples.
Notes on Configuring Queries
SQL queries are used by endpoints and should be configured on the connector using the "query" element:
<jdbc:query key="myQuery" value="select * from blah"/>
The queries can be parameterized using the #[...] pattern that follows the Expression Evaluation
Framework.
Runnable Examples
For examples of using the Mule Enterprise version of the JDBC transport, see JDBC Transport Examples.
Performance Results
For information on performance testing on the Mule Enterprise version of the JDBC transport, see JDBC
Transport Performance Benchmark Results.

JDBC Transport Examples
JDBC Transport Examples
Setup
The Mule Enterprise JDBC Examples are located in your installation at $MULE_HOME/examples/jdbc.
1. Before running any examples, do the following:
• Run the statements in scripts/tables.ddl to create tables in your favorite database.

• Edit the conf/db.properties file with your database connection configuration.
• Copy your database driver to your $MULE_HOME/lib/user directory.
2. Run the examples using the "jdbc.bat" or "jdbc" shell script provided in this directory. After running the
script, you will see the following:
$ ./jdbc.bat
Examples require that you set up your database first. See README for more details.
After your database is set up, choose one of the following examples to run:
1. Mules are born. Read in 50 baby mules from a CSV File and create records in mule_source table.
2. View Mules. Generate an XML report of Mules. (http://localhost:8080/first20)
3. Clone Mules. Clone mules using a Stored Procedure. (http://localhost:8080/clone)
4. Retire Mules. Send mules to a retirement ranch (a.k.a the mule_target table).
5. Cleanup Mules. Reset tables to run examples again (http://localhost:8080/cleanup).
Select the one you wish to execute and press Enter...
3. Choose the number of the Example you want to run.
The examples are designed to be run in order.
Example 1 - Mules Are Born

This example loads records from a CSV file to the database. The CSV file ("data/mules.csv") contains
information about 50 baby mules born at various local ranches. The goal is to upload these records into a
database table called "mule_source".
Configuration
See conf/jdbc-csv.xml
Features Used
This example uses the CSV Transformer to convert the CSV file into JDBC-format Maps and inserts these
records into the database using a batch INSERT.
Running the Example
To run the example, choose option "1" after starting the Mule server. When the server starts, Mule will
immediately load all the records.
To verify that the example loaded correctly, use your favorite database tool to see that there were 50
records inserted into the mule_source table.
SQL> select count(1) from mule_source;
COUNT(1)
----------

50
If you want to run the example again, first delete the records from mule_source.
Example 2 - See the Baby Mules

This example displays the mule records loaded into the database in Example 1.
Configuration
See conf/jdbc-xml-report.xml
Features Used
This example uses an outbound SELECT query to synchronously query the database. The results are
transformed into XML using the XML transformer.
Running the Example
Start the Mule server and choose Example 2. Then, enter the URL http://localhost:8080/first20 into your
web browser. You should see the first 20 mule records presented in XML format.
Example 3 - Mule Cloning
The following example assumes that you are using an Oracle database. However, you can
adapt the stored procedure for other database platforms.
This example shows how to invoke a stored procedure in Mule. This particular stored procedure clones
the records in the mule_source database (doubling the size of the table each time it is run). The goal is to
create a large dataset that we can use in Example 4.
Configuration
See conf/jdbc-stored-procedure.xml
Features Used
This page uses an outbound SELECT query and stored procedure support to synchronously call a stored
procedure.
Running the Example
Before running this example, run the statements in the scripts/oracle_procs.ddl to create the stored
procedure and sequence.
Start the Mule server and choose Example 3. Then, enter the URL http://localhost:8080/clone into
your web browser. You should see the current count of the number of mules in mule_source. Each time
you refresh the page, the number of mules should double. Try refreshing several times until there are
thousands or even millions of mules or more in the table. The mules multiply quickly!
Example 4 - Mass Mule Retirement

This example retires all our mules by transferring them from one database table (mule_source) to
another (mule_target). We can think of this as a simple ETL use case.

Configuration
See conf/jdbc-etl.xml
Features Used
This page uses large dataset retrieval, an outbound SELECT query, and batch INSERT statements to
transfer arbitrarily large numbers of records from one table another.
Running the Example
Before running this example, you can optionally change the location of the ID store in jdbc-etl.xml:
<spring:bean id="idStore" class="org.mule.transport.jdbc.util.IdStore">

<spring:property name="fileName" value="/tmp/eg-batches.txt"/>
</spring:bean>
The default location is /tmp/eg-batches.txt on Linux/Unix and c:/tmp/eg-batches.txt on Windows.
Next, for better visibility into batch activity, add the following line to your log4j.properties file (in
$MULE_HOME/conf):
log4j.logger.org.mule.providers.jdbc.components=DEBUG
Finally, start the server and choose Example 4. You should see the batches of records being processed in
the logs:
DEBUG 2008-04-10 20:20:03,625 \[next_batch.2\] org.mule.providers.jdbc.components.BatchManager:

Processing next batch
DEBUG 2008-04-10 20:20:03,625 \[next_batch.2\] org.mule.providers.jdbc.components.BatchManager: Next
range: {lowerId=1, upperId=3000}
In this example, batches are configured to occur every 1 second, with a batch size of 3000.
Note that if you stop and restart the Mule server, the batches should resume processing where they left
off.
Re-running the Examples

If you want to run these examples again, just delete all records from both mule_source and mule_target
tables, and remove the file "/tmp/eg-batches.txt". In Oracle, this may be most efficiently done by using
truncate, e.g. truncate table mule_source.
Alternatively, if on Oracle, start the server choose "Example 5" to cleanup the tables mule_source and
mule_target. You still need to manually remove the file "/tmp/eg-batches.txt".

JDBC Transport Performance Benchmark Results
This page last changed on May 21, 2008 by jackie.wheeler.
JDBC Transport Performance Benchmark

Results
This page describes the performance benchmark results for the Mule Enterprise JDBC transport.
Configuration
Mule Enterprise 1.6 (default 512mb max heap size)
JDK 1.5.0.11
OS Red Hat Enterprise 4.0
Mule CPUs 4-CPU Dell
Database Oracle 10g (separate 4-CPU host)
Mule Configuration See Examples in $MULE_HOME/examples/jdbc.

Used "Simple ETL" use case for this benchmark
Scenario Details
The ETL use case from the Examples directory was used for this benchmark. This example retrieves
records from a table called mule_source and inserts them into a table called mule_target.
The scenario involves processing a backlog of 10 million records in the mule_source table. Records are
read from the source table once every 1 second, at a batch size of 3000 records per read and 3000
records per commit.
Results
Mule took 55 minutes to complete processing of the 10 million record backlog. Therefore, with this
configuration, the Mule Enterprise JDBC Transport could move over 10 million records an hour.
Comparison to Mule Community Edition

Jetty Transport
Jetty Transport
[ Connector ] [ Endpoints ] [ Using Web Services over Jetty ]
The Jetty transport provides support for exposing services over HTTP by embedding a light-weight Jetty
server. The Jetty SSL transport works the same way but over SSL. You can only define inbound endpoints
with this transport.
Connector
Allows Mule to expose Mule Services over HTTP using a Jetty HTTP server. A single Jetty server is created
for each connector instance. One connector can serve many endpoints. Users should rarely need to have
more than one Jetty connector. The Jetty connector can be configured using a Jetty XML config file, but
the default configuration is sufficient for most scenarios.
configFile string no The location of the

Jetty config file
to configure this
connector with.
useContinuations boolean no Whether to use

continuations
to free up
connections
in high load
situations.
For example:

xmlns:jetty="http://www.mulesource.org/schema/mule/jetty/2.1" xsi:schemaLocation="http://
www.mulesource.org/schema/mule/jetty/2.1
http://www.mulesource.org/schema/mule/jetty/2.1/mule-jetty.xsd http://www.mulesource.org/schema/mule/
core/2.1
http://www.mulesource.org/schema/mule/core/2.1/mule.xsd">
<jetty:connector name="httpConnector" useContinuations="true" />
...
Endpoints
Jetty endpoints are configured the same way as HTTP endpoints. Note that only inbound endpoints can
use the Jetty transport.
For example:

<jetty:endpoint name="serverEndpoint" host="localhost" port="60203" path="services/Foo"
synchronous="false" />
<model name="main">
<service name="testComponent">
<inbound>
<inbound-endpoint ref="serverEndpoint" />
</inbound>
<test:component appendString="Received" />
</service>
</model>
Using Web Services over Jetty

Mule supports using web services over Jetty. This allows you to achieve improved HTTP performance and
scalability due to Jetty's NIO support.
Using the Jetty transport simply requires that you use the "jetty://" URL scheme as opposed to the
regular HTTP scheme. For example:
<service name="greeterService">
<inbound>
<cxf:inbound-endpoint address="jetty://localhost:63081/services/greeter" synchronous="true" />
</inbound>
<component>
<singleton-object class="org.apache.hello_world_soap_http.GreeterImpl"/>
</component>
</service>
Due to limitations of the CXF and HTTP transports, if you are talking to outbound endpoints
that do not use a CXF client underneath and are of the form "cxf:http://locahost/service?
method=echo", this will not work. We hope to address this during a future refactoring of
the HTTP transport.

Jetty SSL transport
Jetty SSL Transport

The Jetty SSL transport works exactly the same way as the HTTPS Transport with one additional optional
attribute, configFile, which allows you to specify the location of the Jetty config file to configure this
connector with.
For example, the following configuration specifies the HTTPS and Jetty-SSL connectors:

xmlns:https="http://www.mulesource.org/schema/mule/https/2.0"
xmlns:jetty="http://www.mulesource.org/schema/mule/jetty-ssl/2.0"
xsi:schemaLocation="http://www.mulesource.org/schema/mule/test/2.0
http://www.mulesource.org/schema/mule/test/2.0/mule-test.xsd
http://www.springframework.org/schema/beans
http://www.mulesource.org/schema/mule/https/2.0
http://www.mulesource.org/schema/mule/https/2.0/mule-https.xsd
http://www.mulesource.org/schema/mule/jetty-ssl/2.0
http://www.mulesource.org/schema/mule/jetty-ssl/2.0/mule-jetty-ssl.xsd">
<https:connector name="httpConnector">
<https:tls-client path="clientKeystore" storePassword="mulepassword" />
<https:tls-key-store path="serverKeystore" keyPassword="mulepassword" storePassword="mulepassword"
/>
<https:tls-server path="trustStore" storePassword="mulepassword" />
</https:connector>
<jetty:connector name="jettyConnector">
<jetty:tls-client path="clientKeystore" storePassword="mulepassword" />
<jetty:tls-key-store path="serverKeystore" keyPassword="mulepassword" storePassword="mulepassword" /
>
<jetty:tls-server path="trustStore" storePassword="mulepassword" />
</jetty:connector>
<https:endpoint name="clientEndpoint" host="localhost" port="60202" synchronous="true" connector-
ref="httpConnector" />
<model name="main">
<custom-service name="testComponent" class="org.mule.tck.testmodels.mule.TestSedaService">
<inbound>
<jetty:inbound-endpoint host="localhost" port="60202" synchronous="true" connector-
ref="jettyConnector" />
</inbound>
</custom-service>
</model>
</mule>
If you do not need this level of security, you can use the Jetty Transport instead.

JMS Transport
JMS Transport
Table of Contents
• JMS Transport
• ° JMS Configuration
° - Using Topics, Queues, or Both
- Specifying Credentials
- Specifying Additional Information
- JMS Selectors
- Durable Subscribers
- Overloading JMS Behavior
- Looking Up JMS Objects from JNDI
- JMS Transformers
- JMS Header Properties
° Configuring Specific JMS Servers
° Schema Reference
° Connector
° Custom Connector
° - Attributes of <custom-connector...>
° Activemq Connector
° - Attributes of <activemq-connector...>
° Activemq Xa Connector
° - Attributes of <activemq-xa-connector...>
° Weblogic Connector
° - Attributes of <weblogic-connector...>
° Websphere Connector
° - Attributes of <websphere-connector...>
° Transaction
° Client Ack Transaction
° Jmsmessage To Object Transformer
° Object To Jmsmessage Transformer
° Inbound Endpoint
° Endpoint
° Property Filter
° - Attributes of <property-filter...>
This page describes the JMS transport, which provides a standard JMS 1.0.2b and 1.1 connector. This
connector exposes all features defined in the 1.0.2b/1.1 specification. It also provides links to information
on configuring various types of JMS, such as ActiveMQ. Note that if you are using Oracle AQ, you can use
the JMS transport without any special configuration if you are using Oracle 10 or later. For details, see the
example on the Mule Cookbook.
For information on managing JMS local and distributed (XA) transactions, as well as multi-resource
transactions (for Mule Enterprise Edition users), see Transaction Management.
Additionally, the Error Handler Example and Loan Broker Example demonstrate using the Active MQ
connector and various JMS transformers.
The Javadoc for the JMS transport can be found here .

JMS Configuration
This section provides general information about JMS configuration with Mule. For links to information on
specific JMS servers, see Configuring Specific JMS Servers below.
Using Topics, Queues, or Both
When specifying a destination name in a URI, and JNDI destinations are not being used, the default
destination created is a queue. For example, the following JMS endpoint will manifest itself as a JMS
queue called my.destination.
jms://my.destination
To make this destination a topic instead of a queue, you must prepend the destination name with
topic: in the URI. In transport-specific endpoints, you set the topic and queue attributes explicitly. For
example:
jms://topic:my.destination
or
<jms:inbound-endpoint topic="my.destination"/>
<jms:outbound-endpoint queue="my.destination"/>
If you are using a JMS 1.1 compliant server, you can use the same JMS connector for both queues
and topics. If you are using a JMS 1.0.2b server, and you want to use both queues and topics in your
Mule configuration, you must create two JMS connectors: one with a JNDI connection factory that
references a QueueConnectionFactory, and another that references a TopicConnectionfactory. Each
JMS endpoint must reference the correct connector depending on whether the destination is a topic or a
queue. To specify the connector on a JMS endpoint, you add the connector parameter to the URI or the
connector-ref attribute on a transport-specific endpoint:
jms://my.destination?connector=jmsQueueConnector
jms://topic:my.destination?connector=jmsTopicConnector
or
<jms:outbound-endpoint queue="my.destination" connector-ref="jmsQueueConnector"/>

<jms:inbound-endpoint topic="my.destination" connector-ref="jmsTopicConnector"/>
Specifying Credentials
Client connections might require a username and password when creating a connection. This information
can be specified on the URI or transport-specific endpoint as follows:

jms://ross:secret@topic:my.destination
or
<jms:inbound-endpoint topic="my.destination" username="ross" password="secret"/>
Specifying Additional Information
When creating JMS connectors, more information is needed such as ConnectionFactory JNDI details.
This information can be set as parameters on the URI, but this can get difficult to manage and read.
The recommend approach is to set default properties on the connector as described in Looking Up JMS
Objects from JNDI below.
JMS Selectors
You can set a JMS selector as a filter on an endpoint. The JMS selector simply sets the filter expression on
the consumer.
<jms:endpoint queue="important.queue" connector-ref="...">

<jms:selector expression="JMSPriority=9"/>
</jms:endpoint>
Durable Subscribers
You can use durable subscribers by setting the durable attribute on the JMS connector. This attribute
tells the connector to make all topic subscribers durable (it does not apply to queues). You can override
the connector's durable attribute at the endpoint level. For example, you can set durable to false on the
connector and set it to true just on the endpoints that require it.
<jms:connector name="jmsTopicConnector" durable="false"/>

...
<jms:inbound-endpoint topic=durable.topic" connector-ref="jmsTopicConnector">
<property key="durable" value="true"/>
</endpoint>
When using a durable subscription, the JMS server requires a durable name to identify this subscriber. By
default, Mule generates the durable name in the following format:
mule.<connector name>.<topic name>
If you want to set the durable name yourself, you can set the durableName property on the endpoint.
<jms:inbound-endpoint topic="durable.topic" connector-ref="jmsTopicConnector">

<property key="durable" value="true"/>
<property key="durableName" value="myDurableSubscription"/>
</jms:inbound-endpoint>
The URI equivalent would be:

jms://topic:durable.topic?durableName=myDurableSubscription
Overloading JMS Behavior
Some JMS servers require a different sequence of calls when creating JMS resources. For example,
Oracle's Advanced Queuingrequires that the connection is started before listeners can be registered.
In this scenario the user can overload the JmsSupport class to customize the way JMS resources are
initialized. Configuring this customization requires that you tell the JMS connector to use a custom
JmsSupport class.
<spring:bean id="customJmsSupport" class="org.foo.jms.CustomJmsSupport"/>
<jms:connector name="jmsConnector">
<property key="jmsSupport" ref="customJmsSupport"/>
</jms:connector>
For more information about configuring specific JMS servers, see Configuring Specific JMS Servers below.
Looking Up JMS Objects from JNDI
Mule can be configured to look up connection factories, queues, and topics from JNDI. Use the following
connector attributes to configure your JNDI connection:
Connector Attribute Description
jndiInitialFactory Class name of the InitialContextFactory
jndiProviderUrl URL for the JNDI connection
jndiProviderProperties-ref Reference to a Spring map with additional

properties that will be passed on when creating
the InitialContext
connectionFactoryJndiName JNDI lookup name of the connection factory
jndiDestinations Set this flag to true to look up queues or

topics from JNDI. If a queue cannot be found
on JNDI, it well be created using the existing
JMS session (you can prevent this by using the
forceJndiDestinations attribute). The default is
false.
forceJndiDestinations Set this connector property to false if you want

Mule to fail if a queue or topic could not be looked
up in JNDI. The default is false.
Note that JNDI configuration on the connector takes precedence over a Spring-configured connection
factory.
Configuration example:
<jms:connector name="jmsJndiConnector"
jndiInitialFactory="com.sun.jndi.ldap.LdapCtxFactory"
jndiProviderUrl="ldap://localhost:10389/"
connectionFactoryJndiName="cn=ConnectionFactory,dc=example,dc=com"
jndiDestinations="true"

forceJndiDestinations="true"/>
JMS Transformers
Transformers for the JMS provider can be found at org.mule.transport.jms.transformers .
Transformer Description
AbstractJmsTransformer This is a base class that provides general JMS

message transformation support. You can
extend this class to create your own specialized
JMS transformers, but usually the defaults are
sufficient.
JMSMessageToObject Converts a javax.jms.Message or sub-type into

an object by extracting the message payload.
Users of this transformer can set different return
types on the transformer to control the way it
behaves:
javax.jms.TextMessage - java.lang.String
javax.jms.ObjectMessage - java.lang.Object
javax.jms.BytesMessage - Byte[]. Note that
the transformer will check if the payload is
compressed and automatically decompress the
message.
javax.jms.MapMessage - java.util.Map
javax.jms.StreamMessage - java.util.Vector of
objects from the Stream Message.
ObjectToJMSMessage Converts any object to a javax.jms.Message

or sub-type. One of the following types of JMS
messages will be created based on the type of
object passed in:
java.lang.String - javax.jms.TextMessage
byte[] - javax.jms.BytesMessage
java.util.Map - javax.jms.MapMessage
java.io.InputStream - javax.jms.StreamMessage
javalang.Object - javax.jms.ObjectMessage
JMS Header Properties
When the message is received and transformed, all the message properties are still available via the
MuleMessage object. To access standard JMS properties such as JMSCorrelationID and JMSRedelivered,
simply use the property name, as shown in the following example:
String corrId = (String) muleMessage.getProperty("JMSCorrelationID");

boolean redelivered = muleMessage.getBooleanProperty("JMSRedelivered");
You can access any custom header properties on the message in the same way.
Configuring Specific JMS Servers

The following links describe how to set up various JMS servers in Mule. Note that the configurations
provided are just examples. Configuration values will change depending on your application environment.
• ActiveMQ

• FioranoMQ
• JBoss MQ
• OpenJms
• Oracle AQ
• SeeBeyond
• SonicMQ
• Sun JMS Grid
• SwiftMQ
• Tibco EMS
• WebLogic JMS
• WebSphere MQ
Schema Reference
Connector
A generic connector for sending and receiving messages over JMS queues.
connectionFactory- name (no spaces) no Reference to

ref the connection
factory, which
is required for
non-vendor JMS
configurations.
redeliveryHandlerFactory-
name (no spaces) no Reference to the
ref redelivery handler.
acknowledgementMode
AUTO_ACKNOWLEDGE/
no AUTO_ACKNOWLEDGE
The
CLIENT_ACKNOWLEDGE/ acknowledgement
DUPS_OK_ACKNOWLEDGE mode to use:
AUTO_ACKNOWLEDGE,
CLIENT_ACKNOWLEDGE,
or
DUPS_OK_ACKNOWLEDGE.
clientId string no The ID of the JMS

client.
durable boolean no Whether to

make all topic
subscribers
durable.
noLocal boolean no If set to true,

a subscriber
will not receive
messages that
were published
by its own
connection.
persistentDelivery boolean no If set to true, the

JMS provider logs
the message to
stable storage as

it is sent so that it
can be recovered
if delivery is
unsuccessful.
honorQosHeaders boolean no If set to true,

the message's
QoS headers are
honored. If false
(the default), the
connector settings
override the
message headers.
maxRedelivery integer no The maximum

number of times
to try to redeliver
a message.
cacheJmsSessions boolean no Whether to cache

and re-use the
JMS session
object instead
of recreating the
connection each
time.
recoverJmsConnections
boolean no Deprecated. This
attribute is no
longer relevant
for the new retry
policies.
eagerConsumer boolean no Whether to create

a consumer
right when the
connection is
created instead
of using lazy
instantiation in the
poll loop.
specification 1.0.2b/1.1 no 1.0.2b The JMS

specification to
use: 1.0.2b (the
default) or 1.1
username string no The user name for

the connection

the connection
numberOfConsumersinteger no The number

of concurrent
consumers that
will be used
to receive JMS
messages.
(Note: If you use
this attribute,
you should not
configure the
'numberOfConcurrentTransacted

which has the
same effect.)
jndiInitialFactory string no The initial factory

class to use when
connecting to
JNDI.
jndiProviderUrl string no The URL to use

when connecting
to JNDI.
jndiProviderProperties-
string no Feference to a
ref Map that contains
additional provider
properties.
connectionFactoryJndiName
string no The name to use
when looking up
the connection
factory from JNDI.
jndiDestinations boolean no Set this attribute

to true if you want
to look up queues
or topics from
JNDI instead of
creating them
from the session.
forceJndiDestinationsboolean no If set to true, Mule

fails when a topic
or queue cannot
be retrieved from
JNDI. If set to
false, Mule will
create a topic or
queue from the
JMS session if the
JNDI lookup fails.
Custom Connector
A custom connector for sending and receiving messages over JMS queues.
Attributes of <custom-connector...>
acknowledgementMode
AUTO_ACKNOWLEDGE/
no AUTO_ACKNOWLEDGE
The
AUTO_ACKNOWLEDGE,
CLIENT_ACKNOWLEDGE,
or

client.

make all topic
subscribers
durable.

a subscriber
will not receive
messages that
were published
by its own
connection.

JMS provider logs
the message to
stable storage as
can be recovered
if delivery is
unsuccessful.

the message's
QoS headers are
honored. If false
(the default), the
connector settings
override the
message headers.

number of times
to try to redeliver
a message.

and re-use the
JMS session
object instead
of recreating the
connection each
time.
attribute is no
longer relevant
for the new retry
policies.

a consumer
right when the
connection is
created instead
of using lazy
poll loop.

specification to
use: 1.0.2b (the
default) or 1.1

the connection

the connection

of concurrent
consumers that
will be used
to receive JMS
messages.
(Note: If you use
this attribute,
you should not
configure the
which has the
same effect.)

class to use when
connecting to
JNDI.

when connecting
to JNDI.
additional provider
properties.
when looking up
the connection
factory from JNDI.

to true if you want
to look up queues
or topics from
JNDI instead of
creating them
from the session.

fails when a topic
or queue cannot
be retrieved from
JNDI. If set to
false, Mule will
create a topic or
queue from the
JMS session if the
JNDI lookup fails.

Activemq Connector
ActiveMQ version of the JMS connector.
Attributes of <activemq-connector...>
connectionFactory- name (no spaces) no Optional reference

ref to the connection
factory. A default
connection factory
is provided
for vendor-
specific JMS
configurations.
acknowledgementMode
AUTO_ACKNOWLEDGE/
no AUTO_ACKNOWLEDGE
The
AUTO_ACKNOWLEDGE,
CLIENT_ACKNOWLEDGE,
or

client.

make all topic
subscribers
durable.

a subscriber
will not receive
messages that
were published
by its own
connection.

JMS provider logs
the message to
stable storage as
can be recovered
if delivery is
unsuccessful.

the message's
QoS headers are
honored. If false
(the default), the
connector settings
override the
message headers.

number of times
to try to redeliver
a message.

and re-use the
JMS session
object instead
of recreating the
connection each
time.
attribute is no
longer relevant
for the new retry
policies.

a consumer
right when the
connection is
created instead
of using lazy
poll loop.

specification to
use: 1.0.2b (the
default) or 1.1

the connection

the connection

of concurrent
consumers that
will be used
to receive JMS
messages.
(Note: If you use
this attribute,
you should not
configure the
which has the
same effect.)

class to use when
connecting to
JNDI.

when connecting
to JNDI.

additional provider
properties.
when looking up
the connection
factory from JNDI.

to true if you want
to look up queues
or topics from
JNDI instead of
creating them
from the session.

fails when a topic
or queue cannot
be retrieved from
JNDI. If set to
false, Mule will
create a topic or
queue from the
JMS session if the
JNDI lookup fails.
brokerURL string no The URL used to

connect to the
JMS server. If not
set, the default is
vm://localhost?
broker.persistent=false&broker.
Activemq Xa Connector
ActiveMQ version of the JMS connector with XA transaction support.
Attributes of <activemq-xa-connector...>

factory. A default
connection factory
is provided
for vendor-
specific JMS
configurations.
acknowledgementMode
AUTO_ACKNOWLEDGE/
no AUTO_ACKNOWLEDGE
The
AUTO_ACKNOWLEDGE,

CLIENT_ACKNOWLEDGE,
or

client.

make all topic
subscribers
durable.

a subscriber
will not receive
messages that
were published
by its own
connection.

JMS provider logs
the message to
stable storage as
can be recovered
if delivery is
unsuccessful.

the message's
QoS headers are
honored. If false
(the default), the
connector settings
override the
message headers.

number of times
to try to redeliver
a message.

and re-use the
JMS session
object instead
of recreating the
connection each
time.
attribute is no
longer relevant
for the new retry
policies.

a consumer
right when the
connection is
created instead
of using lazy

poll loop.

specification to
use: 1.0.2b (the
default) or 1.1

the connection

the connection

of concurrent
consumers that
will be used
to receive JMS
messages.
(Note: If you use
this attribute,
you should not
configure the
which has the
same effect.)

class to use when
connecting to
JNDI.

when connecting
to JNDI.
additional provider
properties.
when looking up
the connection
factory from JNDI.

to true if you want
to look up queues
or topics from
JNDI instead of
creating them
from the session.

fails when a topic
or queue cannot
be retrieved from
JNDI. If set to
false, Mule will
create a topic or
queue from the

JMS session if the
JNDI lookup fails.
brokerURL string no The URL used to

connect to the
JMS server. If not
set, the default is
vm://localhost?
broker.persistent=false&broker.
Weblogic Connector
WebLogic version of the JMS connector.
Attributes of <weblogic-connector...>

factory. A default
connection factory
is provided
for vendor-
specific JMS
configurations.
acknowledgementMode
AUTO_ACKNOWLEDGE/
no AUTO_ACKNOWLEDGE
The
AUTO_ACKNOWLEDGE,
CLIENT_ACKNOWLEDGE,
or

client.

make all topic
subscribers
durable.

a subscriber
will not receive
messages that
were published
by its own
connection.

JMS provider logs
the message to
stable storage as
can be recovered

if delivery is
unsuccessful.

the message's
QoS headers are
honored. If false
(the default), the
connector settings
override the
message headers.

number of times
to try to redeliver
a message.

and re-use the
JMS session
object instead
of recreating the
connection each
time.
attribute is no
longer relevant
for the new retry
policies.

a consumer
right when the
connection is
created instead
of using lazy
poll loop.

specification to
use: 1.0.2b (the
default) or 1.1

the connection

the connection

of concurrent
consumers that
will be used
to receive JMS
messages.
(Note: If you use
this attribute,
you should not
configure the
which has the
same effect.)

class to use when
connecting to
JNDI.

when connecting
to JNDI.
additional provider
properties.
when looking up
the connection
factory from JNDI.

to true if you want
to look up queues
or topics from
JNDI instead of
creating them
from the session.

fails when a topic
or queue cannot
be retrieved from
JNDI. If set to
false, Mule will
create a topic or
queue from the
JMS session if the
JNDI lookup fails.
Websphere Connector
WebSphere version of the JMS connector.
Attributes of <websphere-connector...>

factory. A default
connection factory
is provided
for vendor-
specific JMS
configurations.

acknowledgementMode
AUTO_ACKNOWLEDGE/
no AUTO_ACKNOWLEDGE
The
AUTO_ACKNOWLEDGE,
CLIENT_ACKNOWLEDGE,
or

client.

make all topic
subscribers
durable.

a subscriber
will not receive
messages that
were published
by its own
connection.

JMS provider logs
the message to
stable storage as
can be recovered
if delivery is
unsuccessful.

the message's
QoS headers are
honored. If false
(the default), the
connector settings
override the
message headers.

number of times
to try to redeliver
a message.

and re-use the
JMS session
object instead
of recreating the
connection each
time.
attribute is no
longer relevant
for the new retry
policies.

a consumer

right when the
connection is
created instead
of using lazy
poll loop.

specification to
use: 1.0.2b (the
default) or 1.1

the connection

the connection

of concurrent
consumers that
will be used
to receive JMS
messages.
(Note: If you use
this attribute,
you should not
configure the
which has the
same effect.)

class to use when
connecting to
JNDI.

when connecting
to JNDI.
additional provider
properties.
when looking up
the connection
factory from JNDI.

to true if you want
to look up queues
or topics from
JNDI instead of
creating them
from the session.

fails when a topic
or queue cannot
be retrieved from
JNDI. If set to

false, Mule will
create a topic or
queue from the
JMS session if the
JNDI lookup fails.
Transaction
Transactions allow a series of operations to be grouped together so that they can be rolled back if a
failure occurs. Set the action (such as ALWAYS_BEGIN or JOIN_IF_POSSIBLE) and the timeout setting for
the transaction.
Client Ack Transaction

Identical to a transaction but for message acknowledgements. There is no notion of rollback with client
acknowledgement, but this transaction can be useful for controlling how messages are consumed from a
destination.
Jmsmessage To Object Transformer

Converts a JMS message into an object by extracting the message payload.
Object To Jmsmessage Transformer

Converts an object into one of five types of JMS messages, depending on the object passed in:
java.lang.String -> javax.jms.TextMessage, byte[] -> javax.jms.BytesMessage, java.util.Map ->
javax.jms.MapMessage, java.io.InputStream -> javax.jms.StreamMessage, and java.lang.Object ->
javax.jms.ObjectMessage.
Inbound Endpoint
An endpoint on which JMS messages are received.
queue string no The queue name.

This attribute
cannot be used
with the topic
attribute (the two
are exclusive).
topic string no The topic name.

The "topic:" prefix
will be added
automatically.
This attribute
cannot be used
with the queue
attribute (the two
are exclusive).

Outbound Endpoint
An endpoint to which JMS messages are sent.

This attribute
cannot be used
with the topic
attribute (the two
are exclusive).

The "topic:" prefix
will be added
automatically.
This attribute
cannot be used
with the queue
attribute (the two
are exclusive).
Endpoint
A global JMS endpoint definition.

This attribute
cannot be used
with the topic
attribute (the two
are exclusive).

The "topic:" prefix
will be added
automatically.
This attribute
cannot be used
with the queue
attribute (the two
are exclusive).
Property Filter
Allows you to filter messages based on a JMS property.

Attributes of <property-filter...>
propertyName string no The name of the

JMS property.
propertyClass string no The class type of

the JMS property.
expression string no The expression to

search for in the
property.
pattern string no The regular

expression pattern
to search for in
the property. In
most cases, if
you set both the
expression and
pattern attributes,
only the pattern is
used.

Mule WMQ Transport
This page last changed on Nov 25, 2008 by tcarlson.
Mule WMQ Transport

[ Messaging Use Cases ] [ Sending Messages on a Local Queue ] [ Sending Messages on a Remote Queue
] [ Inbound Message Handling ] [ Outbound Message Handling ] [ Retrieving the Connection Factory from
JNDI ] [ Known Limitations ]
The Mule Enterprise transport for IBM® WebSphere® MQ (Mule WMQ transport) provides the following
functionality:
• Bi-directional request-response messaging between Websphere MQ and Mule JMS using native MQ
point-to-point.
• Synchronous and asynchronous request-response communications using JMSReplyTo.
This page describes how to configure and use this transport and its connector. It assumes that you
already understand how to configure and use WebSphere MQ. For complete information on MQ, refer to
the MQ Information Center.
Note that the Mule WMQ transport is available only with Mule Enterprise Edition version 1.6 or later. For
information on connecting to WebSphere MQ using the JMS transport, which does not support native MQ
but does provide more functionality and is available with the community edition of Mule, see WebSphere
MQ Integration.
Messaging Use Cases

This section describes the typical use cases for using the Mule WMQ transport.
Sending Messages on a Local Queue
The configuration describes a flow where a service mqSender takes input interactively from the
command line and sends it to a native WebSphere MQ endpoint (mqs://REQUEST.QUEUE). Another
service, mqReceiver, picks up the message from this endpoint and echoes it back to another native
WebSphere MQ endpoint, mqs://RESPONSE.QUEUE.
Configuring request-response behavior requires the following settings:
• The JMSReplyTo property must be set on the outbound side of the mqSender.
• The message type (JMS_IBM_MsgType) property must be set to
com.ibm.mq.MQC.MQMT_REQUEST on the outbound side of the mqSender service.
• The message type (JMS_IBM_MsgType) property must be set to
com.ibm.mq.MQC.MQMT_REPLY on the inbound side of the mqReceiverservice.
• To support local queues, the transportType property in the MQJMSConnector declaration must be
set to JMSC.MQJMS_TP_BINDINGS_MQ.
By default, messages sent from Mule to MQ are sent in native format, and JMS (RFH2) headers are
suppressed. This configuration is applied transparently to the configuration below by the connector
appending a parameter to the MQ destination URI (?targetClient=1). To force JMS behaviour
on the receiving MQ (that is, to use non-native format), use the following attribute setting in the
MQJMSConnector declaration:
<mqs:connector name="..."
...
targetClient="JMS_COMPLIANT"
...

/>
Note the following additional points about the configuration:
• The mqs URI scheme for endpoints indicates that the MQ transport should be used.
• The queueManager property in the MQJMSConnector declaration matches the MQ QueueManager
set up previously.
• The local queues REQUEST.QUEUE and RESPONSE.QUEUE were set up previously using the
runmqsc utility.

xmlns:stdio="http://www.mulesource.org/schema/mule/stdio/2.1"
xmlns:vm="http://www.mulesource.org/schema/mule/vm/2.1"
xmlns:mqs="http://www.mulesource.com/schema/mule/mqseries/2.1"
http://www.mulesource.com/schema/mule/mqseries/2.1 http://www.mulesource.com/schema/mule/
mqseries/2.1/mule-mqseries-ee.xsd
beans-2.0.xsd
mule.xsd
http://www.mulesource.org/schema/mule/stdio/2.1 http://www.mulesource.org/schema/mule/stdio/2.1/
mule-stdio.xsd
http://www.mulesource.org/schema/mule/vm/2.1 http://www.mulesource.org/schema/mule/vm/2.1/mule-
vm.xsd">
<spring:bean name="connectionFactory" class="com.ibm.mq.jms.MQConnectionFactory"/>
<mqs:connector name="mqSeriesConnector"
hostName="winter"
port="1414"
queueManager="HELLO.QMGR"
transportType="BINDINGS_MQ"
targetClient="NONJMS_MQ"
specification="1.1"
username=""
password=""
disableReplyToHandler="true"
connectionFactory-ref="connectionFactory">
</mqs:connector>
<stdio:connector name="stdioConnector" messageDelayTime="1000" promptMessage="Please enter

something: "/>
<model name="MQ_Series_Example">
<service name="mqSender">
<inbound>
<stdio:inbound-endpoint system="IN"/>
</inbound>
<echo-component/>
<outbound>
<outbound-endpoint address="mqs://REQUEST.QUEUE">
<property key="JMSReplyTo" value="RESPONSE.QUEUE"/>
<property key="JMS_IBM_MsgType" value="1"/> 
</outbound>
</service>

<service name="mqReceiver">
<inbound>
<inbound-endpoint address="mqs://REQUEST.QUEUE">
<property key="JMS_IBM_MsgType" value="2"/> 
</inbound-endpoint>
</inbound>
<echo-component/>
</service>
</model>
</mule>
The following log output demonstrates the message flow:
INFO 2008-04-10 13:59:21,472 [WrapperListener_start_runner] org.mule.MuleServer: Mule Server initialized.
Please enter something:

Hello
INFO 2008-04-10 13:59:56,450 [mqSender.2] org.mule.components.simple.LogComponent:
********************************************************************************
* Message received in component: mqSender. Content is: 'Hello' *
********************************************************************************
INFO 2008-04-10 13:59:56,464 [MQJMSConnector.dispatcher.1]
org.mule.providers.mqseries.MQSeriesMessageDispatcher: Connected:
MQSeriesMessageDispatcher{this=504ec1, endpoint=mqs://REQUEST.QUEUE}
INFO 2008-04-10 13:59:56,486 [mqReceiver.2] org.mule.components.simple.LogComponent:
********************************************************************************
* Message received in component: mqReceiver. Content is: 'Hello' *
********************************************************************************
INFO 2008-04-10 13:59:56,487 [mqReceiver.2]
org.mule.providers.DefaultReplyToHandler: Reply Message sent to: queue://HELLO.QMGR/RESPONSE.QUEUE?
targetClient=1
The following environment variable needs to be set for Mule to run successfully when MQSeries connector
functionality has been configured.
export LD_LIBRARY_PATH=/opt/mqm/java/lib
You must set this variable to the location of the Java library directory shipped with the MQ server
installation.
Sending Messages on a Remote Queue
This use case describes sending a Mule message to a WebSphere MQ QueueManager on a different
machine. After configuring WebSphere MQ with the appropriate queue and channel definitions, you
configure Mule as follows:

xmlns:mqs="http://www.mulesource.com/schema/mule/mqseries/2.1"

http://www.mulesource.com/schema/mule/mqseries/2.1 http://www.mulesource.com/schema/mule/
mqseries/2.1/mule-mqseries-ee.xsd
beans-2.0.xsd
mule.xsd
mule-stdio.xsd
http://www.mulesource.org/schema/mule/vm/2.1 http://www.mulesource.org/schema/mule/vm/2.1/mule-
vm.xsd">
<mqs:connector name="mqSeriesConnector"
hostName="winter"
port="1414"
queueManager="HELLO.QMGR"
channel="HELLO.CHANNEL"
transportType="CLIENT_MQ_TCPIP"
targetClient="NONJMS_MQ"
specification="1.1"
username=""
password=""
disableReplyToHandler="true"
connectionFactory-ref="connectionFactory">
</mqs:connector>
<stdio:connector name="stdioConnector" messageDelayTime="1000" promptMessage="Please enter

something: "/>
<model name="MQ_Series_Example">
<service name="mqSender">
<inbound>
</inbound>
<echo-component/>
<outbound>
<outbound-endpoint address="mqs://REQUEST.QUEUE">
<property key="JMSReplyTo" value="RESPONSE.QUEUE"/>
<property key="JMS_IBM_MsgType" value="1"/> 
</outbound>
</service>
</model>
</mule>
Note the channel configuration. This is how WebSphere MQ knows to send it to the remotely hosted
queue.
Mule sends the message as follows:
INFO 2008-04-14 15:29:27,572 [WrapperListener_start_runner] org.mule.MuleServer: Mule Server initialized.

Hello
INFO 2008-04-14 15:29:30,389 [mqSender.2] org.mule.components.simple.LogComponent:
********************************************************************************
* Message received in component: mqSender. Content is: 'Hello' *
********************************************************************************

INFO 2008-04-14 15:29:30,403 [MQJMSConnector.dispatcher.1]
org.mule.providers.mqseries.MQSeriesMessageDispatcher: Connected:
MQSeriesMessageDispatcher{this=1672bbb, endpoint=mqs://LOCAL.DEF.OF.REMOTE.QUEUE}
On the receiving side:
[mqm@spring ~]$ /opt/mqm/samp/bin/amqsget ORANGE.QUEUE

Sample AMQSGET0 start
message <Hello>
no more messages
Sample AMQSGET0 end
You can use a the WebSphere MQ utility amqsget to verify the message was received on the remote
queue.
Inbound Message Handling

The inbound messages are received by the connector and delivered to the component. If the
disableReplyToHandler property of the connector is not set to true and the inbound message type is
MQMT_REQUEST, the message returned by the component will be sent to the queue specified in the
JMSReplyTo property of the original message. However, if the outbound MQ endpoint exists in the
component, it will override the replyToHandler functionality. By default, disableReplyToHandler is set to
false.

Outbound Message Handling
The outbound endpoint behavior depends on the MQ message type specified in the JMS_IBM_MsgType
endpoint property. If the value of the property is set to MQMT_REPLY or MQMT_DATAGRAM, other
properties will be copied over from the original message and the message will be dispatched to the
queue.
If the message type is MQMT_REQUEST, the connector will check the existence of JMSReplyTo property on
the endpoint. If the property is not set, the temporary queue will be created.
If the remoteSync property is set on the endpoint, the connector will wait for the response on the queue
specified by JMSReplyTo. The timeout can be set using the remoteSyncTimeout setting. If a response is
received by the connector, it will be returned by the component.

Retrieving the Connection Factory from JNDI
The connection factory can be loaded explicitly by the connector or from a JNDI registry. To support the
explicit case, the following configuration must be included in the connector declaration:
<mqs:connector ...
connectionFactory-ref="connectionFactory"/>

To support the case where a JNDI registry has been configured to store the connection factory, the
connector declaration should include the following parameters. This is the same as the regular JMS
transport documented here .
<mqs:connector ...
jndiInitialFactory="com.sun.jndi.ldap.LdapCtxFactory"
jndiProviderUrl="ldap://localhost:10389/"
connectionFactoryJndiName="cn=ConnectionFactory,dc=example,dc=com"
Known Limitations
The Mule WMQ transport has been implemented as an extension to the JMS transport and has limited
functionality and support for native WebSphere MQ. Following are the features that the Mule WMQ
transport does not currently support:
• Durable topic subscription support

• Local and XA transactions
• Exit handler support
• MQMT_REPORT message type support
• Native WMQ connection pool support
• SSL connection support
• Data compression over channels (for performance throughput gain)
• JMS persistent delivery
• JMS 1.1 feature set certification

Multicast Transport
Multicast Transport
The Multicast transport sends and receives Mule events using IP multicasting. The Javadoc for this
transport can be found here .
Connector
The Multicast connector extends the UDP connector with additional optional attributes:
timeToLive Set the time-to-live value for Multicast packets to

control their scope. It must be in the range 0 to
255 (inclusive).
loopback Whether to enable local loopback of Multicast

datagrams. The option is used by the platform
networking code as a hint for setting whether
Multicast data will be looped back to the local
socket.
Endpoints
You configure Multicast endpoints just as you would with any other transport, with the following additional
attributes:
• host: the IP address of the server, such as www.mulesource.com, localhost, or 127.0.0.1

• port: the port number of the server.
For example, you could configure a global endpoint as follows:
<multicast:endpoint host="224.0.0.1" port="60131" name="serverEndpoint" />
Transformers
The following transformers are used by default for this connector unless a transformer is explicitly set on
the provider.
ByteArrayToString Converts a byte array to a String
StringToByteArray Converts a String to a byte array

POP3S Transport
POP3S Transport
The POP3s connector enables POP3 over SSL using the javax.mail APIs. It supports all the elements and
attributes of the POP3 connector plus some required properties for setting up the client key store and the
trust store for the SSL connection.

attributes:

for identification
class name)

For example:
<pop3s:connector name="pop3sConnector">
<pop3s:tls-client path="clientKeystore" storePassword="mulepassword" />
<pop3s:tls-trust-store path="greenmail-truststore" storePassword="password" />
</pop3s:connector>
<model name="test">
<inbound>
<pop3s:inbound-endpoint user="bob" password="password" host="localhost" port="65436" />
</inbound>
...
For information on configuring endpoints using the POP3S connector, see POP3 Transport.
The POP3S transport supports the same filters and transformers as the Email Transport.

POP3 Transport
POP3 Transport
The POP3 transport can be used for receiving messages from POP3 inboxes. The POP3S Transport
connects to POP3 mailboxes using SSL (POP3s) using the javax.mail API. The POP3 transport uses the
same filters and transformers as the Email Transport.
The Javadoc for this provider can be found here .
POP3 Connector
The POP3 connector supports all the common connector attributes and properties and the following
additional attributes:
Attribute Description Default Required
backupEnabled Whether to save copies False No

to the backup folder.
backupFolder The folder where No

messages are moved
for audit purposes after
they have been read.
checkFrequency Determines how often 60000 Yes

(in milliseconds) the
POP3 mailbox is polled
for new messages.
mailboxFolder The remote folder to INBOX No

check for email.
deleteReadMessages Whether to delete true No

messages after they
have been downloaded.
If set to false, the
messages are set to
SEEN.
Endpoints
POP3 and POP3S endpoints include details about connecting to a POP3 mailbox. You configure the
endpoints just as you would with any other transport, with the following additional attributes:
• user: the user name of the mailbox owner

• password: the password of the user
• host: the IP address of the POP3 server, such as www.mulesource.com, localhost, or 127.0.0.1
• port: the port number of the POP3 server. If not set for the POP3S connector, the default port is 995.
For example:
<pop3:inbound-endpoint user="bob" password="foo" host="pop.gmail.com" checkFrequency="3000" />
or:
<pop3s:inbound-endpoint user="bob" password="foo" host="pop.gmail.com" checkFrequency="3000" />

This will log into the bob mailbox on pop.gmail.com using password foo (using the default port 995 for
the POP3S endpoint) and will check the mailbox for new messages every 30 seconds. You can also specify
the endpoint settings using a URI, but the above syntax is easier to read.

Quartz Transport
This page last changed on Jul 31, 2008 by jackie.wheeler.
Table of Contents
• Quartz Transport
• ° Connector
° Inbound endpoint
- Child Elements of <inbound-endpoint...>
- Child Elements of <outbound-endpoint...>
° Endpoint
- Child Elements of <endpoint...>
• Jobs
• ° Event generator job
° - Child Elements of <event-generator-job...>
- Example Configurations
° Endpoint polling job
° - Child Elements of <endpoint-polling-job...>
° Scheduled dispatch job
° - Child Elements of <scheduled-dispatch-job...>
° Custom job
° - Attributes of <custom-job...>
° Custom job from message
° - Attributes of <custom-job-from-message...>
Quartz Transport
The Quartz transport provides support for scheduling events and for triggering new events. An inbound
quartz endpoint can be used to trigger inbound events that can be repeated, such as every second.
Outbound quartz endpoints can be used to schedule an existing event to fire at a later date. Users can
create schedules using cron expressions, and events can be persisted in a database.
This transport makes use of the Quartz Project at Open Symphony. The Quartz site has more generic
information about how to work with Quartz.
This transport becomes very powerful when using cron expressions to trigger events, and some of the
examples below provide examples of cron expressions. If you are not familiar with cron syntax, here is a
good tutorial.
Connector
The Quartz connector is used to configure the default behavior for Quartz endpoints that reference
the connector. Note if there is only one Quartz connector configured, all Quartz endpoints will use that
connector.

scheduler-ref name (no spaces) no Provides an

implementation
of the Quartz
Scheduler
interface. If no
value is provided,
a scheduler is
retrieved from the
StdSchedulerFactory.
If no properties
are provided, the
getDefaultScheduler
method is called.
Otherwise, a new
factory instance is
created using the
given properties,
and a scheduler
is retrieved using
the getScheduler
method.
factory-property 0..* Set a property on the factory

(see scheduler-ref).
Inbound Endpoint
A Quartz inbound endpoint can be used to generate events. It is most useful when you want to trigger a
service at a given interval (or cron expression) rather than have an external event trigger the service.
jobName string no The name to

associate with
the job on the
endpoint. This is
only really used
internally when
storing events.
cronExpression string no The cron

expression to
schedule events
at specified
dates/times.
This attribute or

repeatInterval is
required. A cron
expression is a
string comprised
by 6 or 7 fields
separated by
white space.
Fields can contain
any of the allowed
values, along
with various
combinations
of the allowed
special characters
for that field.
The fields are
as follows:
Field Name
MandatoryAllowed
ValuesAllowed
Special Chars
SecondsYES0-59,
-*/
MinutesYES0-59, -
* / HoursYES0-23,
- * / Day of
MonthYES1-31,
-*?/LWC
MonthYES1-12
or JAN-DEC,
- * / Day of
WeekYES1-7 or
SUN-SAT, - * ? / L
C # YearNOempty,
1970-2099, - * /
Cron expressions
can be as simple
as this: * * *
* ? * or more
complex, like
this: 0 0/5
14,18,3-39,52 ?
JAN,MAR,SEP
MON-FRI
2002-2010 Some
examples: 0 0 12
* * ? Fire at 12pm
(noon) every day
0 15 10 ? * * Fire
at 10:15am every
day 0 15 10 * * ?
Fire at 10:15am
every day 0 15
10 * * ? * Fire at
10:15am every
day 0 15 10 *
* ? 2005 Fire at
10:15am every
day during the
year 2005 0 * 14
* * ? Fire every
minute starting at
2pm and ending
at 2:59pm, every

day 0 0/5 14 *
* ? Fire every 5
minutes starting
at 2pm and
ending at 2:55pm,
every day
repeatInterval long no The number of

milliseconds
between two
events. This
attribute or
cronExpression is
required.
repeatCount integer no The number of

events to be
scheduled. This
value defaults to
-1, which means
that the events
will be scheduled
indefinitely.
startDelay long no The number of

milliseconds that
will elapse before
the first event is
fired.
Child Elements of <inbound-endpoint...>
abstract-job 1..1 A placeholder for Quartz jobs

that can be set on the endpoint.
Outbound Endpoint
An outbound Quartz endpoint allows existing events to be stored and fired at a later time/date. If you
are using a persistent event store, the payload of the event must implement java.io.Serializable.
You configure an org.quartz.Job implementation on the endpoint to tell it what action to take. Mule has
some default jobs, but you can also write your own.

associate with
the job on the
endpoint. This is
only really used
internally when
storing events.

expression to

schedule events
at specified
dates/times.
This attribute or
repeatInterval is
required. A cron
expression is a
string comprised
by 6 or 7 fields
separated by
white space.
Fields can contain
any of the allowed
values, along
with various
combinations
of the allowed
special characters
for that field.
The fields are
as follows:
Field Name
MandatoryAllowed
ValuesAllowed
Special Chars
SecondsYES0-59,
-*/
MinutesYES0-59, -
* / HoursYES0-23,
- * / Day of
MonthYES1-31,
-*?/LWC
MonthYES1-12
or JAN-DEC,
- * / Day of
WeekYES1-7 or
SUN-SAT, - * ? / L
C # YearNOempty,
1970-2099, - * /
Cron expressions
can be as simple
as this: * * *
* ? * or more
complex, like
this: 0 0/5
14,18,3-39,52 ?
JAN,MAR,SEP
MON-FRI
2002-2010 Some
examples: 0 0 12
* * ? Fire at 12pm
(noon) every day
0 15 10 ? * * Fire
at 10:15am every
day 0 15 10 * * ?
Fire at 10:15am
every day 0 15
10 * * ? * Fire at
10:15am every
day 0 15 10 *
* ? 2005 Fire at
10:15am every
day during the
year 2005 0 * 14

* * ? Fire every
minute starting at
2pm and ending
at 2:59pm, every
day 0 0/5 14 *
* ? Fire every 5
minutes starting
at 2pm and
ending at 2:55pm,
every day

milliseconds
between two
events. This
attribute or
cronExpression is
required.

events to be
scheduled. This
value defaults to
-1, which means
that the events
will be scheduled
indefinitely.

milliseconds that
will elapse before
the first event is
fired.
Child Elements of <outbound-endpoint...>

Endpoint
A global endpoint that can be used as a template to create inbound and outbound Quartz endpoints.
Common configuration can be set on a global endpoint and then referenced using the @ref attribute on
the local endpoint. Note that because jobs sometimes only work on inbound or outbound endpoints, they
have to be set on the local endpoint.

associate with
the job on the
endpoint. This is
only really used

internally when
storing events.

expression to
schedule events
at specified
dates/times.
This attribute or
repeatInterval is
required. A cron
expression is a
string comprised
by 6 or 7 fields
separated by
white space.
Fields can contain
any of the allowed
values, along
with various
combinations
of the allowed
special characters
for that field.
The fields are
as follows:
Field Name
MandatoryAllowed
ValuesAllowed
Special Chars
SecondsYES0-59,
-*/
MinutesYES0-59, -
* / HoursYES0-23,
- * / Day of
MonthYES1-31,
-*?/LWC
MonthYES1-12
or JAN-DEC,
- * / Day of
WeekYES1-7 or
SUN-SAT, - * ? / L
C # YearNOempty,
1970-2099, - * /
Cron expressions
can be as simple
as this: * * *
* ? * or more
complex, like
this: 0 0/5
14,18,3-39,52 ?
JAN,MAR,SEP
MON-FRI
2002-2010 Some
examples: 0 0 12
* * ? Fire at 12pm
(noon) every day
0 15 10 ? * * Fire
at 10:15am every
day 0 15 10 * * ?
Fire at 10:15am
every day 0 15
10 * * ? * Fire at
10:15am every

day 0 15 10 *
* ? 2005 Fire at
10:15am every
day during the
year 2005 0 * 14
* * ? Fire every
minute starting at
2pm and ending
at 2:59pm, every
day 0 0/5 14 *
* ? Fire every 5
minutes starting
at 2pm and
ending at 2:55pm,
every day

milliseconds
between two
events. This
attribute or
cronExpression is
required.

events to be
scheduled. This
value defaults to
-1, which means
that the events
will be scheduled
indefinitely.

milliseconds that
will elapse before
the first event is
fired.
Child Elements of <endpoint...>

Jobs
Jobs are used to perform an action when a time trigger occurs from the Quartz transport. Mule provides a
number of jobs for generating and scheduling events. These are detailed below. Users can also write their
own jobs and hook them in using the custom-job type included with Mule.
Event Generator Job

An inbound endpoint job that will trigger a new event for the service according to the schedule on the
endpoint. This is useful for periodically triggering a service without the need for an external event to
occur.

Child Elements of <event-generator-job...>
payload 0..1 The payload of the newly

created event. The payload can
be a reference to a file, fixed
string, or object configured
as a Spring bean. If this
value is not set, an event
will be generated with an
org.mule.transport.NullPayload
instance.
Example Configurations
Note that the documentation for this example should be embedded within the code.
<service name="testService1">
<description>
This configuration will create an inbound event for testService1 at 12 noon every day. The event payload
will always have the same value 'foo'.
</description>
<inbound>
<quartz:inbound-endpoint name="qEP1" cronExpression="0 0 12 * * ?" jobName="job1" connector-
ref="quartzConnector1">
<quartz:event-generator-job>
<quartz:payload>foo</quartz:payload>
</quartz:event-generator-job>
</quartz:inbound-endpoint>
</inbound>
</service>
<description>
This configuration will create an inbound event for testService2 every 1 second indefinitely. The event
payload
will always have the same value, which the contents of the file 'payload-data.txt'. The file can be on
the classpath of on the local file system.
</description>
<inbound>
<quartz:inbound-endpoint name="qEP2" repeatCount="10" repeatInterval="1000" jobName="job2"
connector-ref="quartzConnector1">
<quartz:event-generator-job >
<quartz:payload file="payload-data.txt"/>
</quartz:event-generator-job>
</inbound>

</service>
Endpoint Polling Job

An inbound endpoint job that can be used to periodically read from an external source (via another
endpoint). This can be useful for triggering time-based events from sources that do not support polling or
for simply controlling the rate in which events are received from the source.
Child Elements of <endpoint-polling-job...>
job-endpoint 0..1 A reference to another

configured endpoint from which
events will be received.
<description>
The endpoint polling Job will try and perform a 'request' on any Mule endpoint. If a result is received
it will be handed off to this 'testService5' service for processing.
The trigger will fire every 5 minutes starting at 2pm and ending at 2:55pm, every day. during this
period the job will check the file directory /N/drop-data/in every 5 minutes to see if any event data is
available. The request will timeout after 4 seconds if there are no files in the directory.
</description>
<inbound>
<quartz:inbound-endpoint name="qEP5" cronExpression="0 0/5 14 * * ?" jobName="job5"

<quartz:endpoint-polling-job>
<quartz:job-endpoint address="file:///N/drop-data/in" timeout="4000"/>
</quartz:endpoint-polling-job>
</inbound>
</service>
Scheduled Dispatch Job

An outbound job that will schedule a job for dispatch at a later time/date. The event will get dispatched
using the configured endpoint reference.
Child Elements of <scheduled-dispatch-job...>

job-endpoint 0..1 The endpoint used to dispatch
the scheduled event.
<description>
This outbound Quartz endpoint will receive an event after the component has processed it and store it in
the event store. When the trigger kicks in at 10:15am everyday it will dispatch the event on the
endpoint referenced as 'scheduledDispatchEndpoint'. Since the 'repeatCount' is set to 0, the event will
only be sent out once.
</description>
<inbound>
<inbound-endpoint address="test://inbound6"/>
</inbound>
<test:component/>
<outbound>
<quartz:outbound-endpoint name="qEP6" repeatCount="0" cronExpression="0 15 10 * * ? *"
jobName="job6" connector-ref="quartzConnector1">
<quartz:scheduled-dispatch-job>
<quartz:job-endpoint ref="scheduledDispatchEndpoint"/>
</quartz:scheduled-dispatch-job>
</quartz:outbound-endpoint>
</outbound>
</service>
Custom Job
A custom job can be configured on inbound or outbound endpoints. You can create and configure your
own job implementation and use it on a Quartz endpoint. A custom job can be configured as a bean in
the XML configuration and referenced using this job.
Attributes of <custom-job...>
groupName string no The group name

of the scheduled
job
jobGroupName string no The job group

name of the
scheduled job.
job-ref string no The bean name or

ID of the custom
job to use when
this job gets
executed.

<description>
This configuration will store the outbound event in the local event store (this can be a database). Then
on the 1st November at 8am the Job will be triggered and the custom job will get invoked. Notice that
the repeatCount is set to 0, this mean the even will only happen once. If you wanted to fire an even
every year at this time for the next 3 years then set the 'repeatCount' to 2.
The 'job-ref' refers to a bean configured inside the XML.
</description>
<inbound>
</inbound>
<test:component/>
<outbound>
<quartz:outbound-endpoint name="qEP4" repeatCount="0" cronExpression="0 11 1 8 * ?"
jobName="job4"
<quartz:custom-job job-ref="custJob"/>
</outbound>
</service>
Custom Job From Message

Allows a job to be stored on the current message. This can only be used on outbound endpoints. When
the message is received, the job is read and the job is added to the scheduler with the current message.
This allows for custom scheduling behavior determined by the message itself. Usually the service or a
transformer would create the job on the message based on application-specific logic. Any Mule-supported
expressions can be used to read the job from the message. Typically, you add the job as a header, but an
attachment could also be used.
Attributes of <custom-job-from-message...>
groupName string no The group name

of the scheduled
job
jobGroupName string no The job group

name of the
scheduled job.

<description>
This configuration will process a message and find a Job configured as a header called 'jobConfig' on
the current message. We're using the test component here, but a real implementation will need to set a
custom {{org.quartz.Job}}
implementation as a header on the current message.
Note that other expressions could be used to extract the job from an attachment or even a property
within the payload itself.
</description>
<inbound>
</inbound>
<test:component/>
<outbound>
<quartz:outbound-endpoint name="qEP3" repeatInterval="1000" jobName="job3"
<quartz:custom-job-from-message evaluator="header" expression="jobConfig"/>
</outbound>
</service>

RMI Transport
RMI Transport
The RMI transport can be used to send and receive Mule events over JRMP. This transport has a
dispatcher that invokes an RMI method and a polling receiver that repeatedly does the same.
You configure the RMI transport as follows:
xmlns:rmi="http://www.mulesource.org/schema/mule/rmi/2.1"
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/
spring-beans-2.5.xsd
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/rmi/2.1 http://www.mulesource.org/schema/mule/
rmi/2.1/mule-rmi.xsd">
<spring:bean name="jndiFactory" class="org.mule.transport.rmi.MuleRMIFactory"/>
<spring:bean name="jndiContext" factory-bean="jndiFactory" factory-method="create"/>
<rmi:connector name="rmi" jndiContext-ref="jndiContext" securityPolicy="rmi.policy"/>
<rmi:endpoint name="hello" host="localhost" port="1099" object="HelloServer"

method="hello" methodArgumentTypes="java.lang.String"/>
The connector looks for the method and methodArgumentTypes. It uses the payload as the argument.
JNP Connector
If you want to use the Java naming protocol to bind to remote objects, you can use the JNP connector
instead simply by using the jnp namespace.
xmlns:jnp="http://www.mulesource.org/schema/mule/jnp/2.1"
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/
spring-beans-2.5.xsd
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/jnp/2.1 http://www.mulesource.org/schema/mule/
jnp/2.1/mule-jnp.xsd">
<spring:bean name="jndiFactory" class="org.mule.transport.rmi.MuleRMIFactory"/>

<spring:bean name="jndiContext" factory-bean="jndiFactory" factory-method="create"/>
<jnp:connector name="jnp" jndiContext-ref="jndiContext" securityPolicy="rmi.policy"/>

<jnp:endpoint name="Sender2" host="localhost" port="1099" object="MatchingUMO"
method="reverseString"/>
...
Connector
pollingFrequency long no Period (ms)

between polling
connections.
securityManager- name (no spaces) no Bean reference

ref to the security
manager that
should be used.
securityPolicy string no The security

policy (file name)
used to enable
connections.
serverClassName name (no spaces) no The target class

name.
serverCodebase string no The target

method.
Endpoint
host string no The endpoint host

name.

to use when a
connection is
made.
object string no The class name

of the object that
is being invoked
over RMI.
method string no The name of the

method to invoke.

methodArgumentTypes
string no Comma separated
argument types
of the method
to invoke.
For example,
"java.lang.String".

Servlet Transport
Servlet Transport
The Servlet transport provides integration with a servlet implementation. The implementing servlet does
the work of receiving a request, and the Servlet transport then hands off the request to any receivers
registered with it. There is no notion of a dispatcher for this connector, as it is triggered by a request and
may or may not return a response. You specify the servlet URL as part of the connector configuration and
then specify the endpoints just like any other HTTP endpoints.
The Javadoc for this transport can be found here . For more information about using Mule with servlet
containers, see Embedding Mule in a Java Application or Webapp. For information on using the RESTlet
connector, click here.
Connector
Servlet connector is a channel adapter between Mule and a servlet engine. It allows the
MuleReceiverServlet to look up components interested in requests it receives via the servlet container.
servletUrl no The real URL

on which the
servlet container
is bound. If this
is not set, the
WSDL may not
be generated
correctly.
For example:
<servlet:connector name="servletConnector" servletUrl="http://localhost:8180/path/" />
You can also specify the servlet URL as part of the endpoint:
<servlet:inbound-endpoint path="foo" />
or:
<inbound-endpoint address="servlet://foo" />
Servlet endpoints are identical to HTTP endpoints with the exception that they use the servlet: prefix
instead of http:. For more information, see HTTP Transport.

SMTPS Transport
SMTPS Transport
The SMTPS connector enables SMTP over SSL using the javax.mail APIs. It supports all the elements
and attributes of the SMTP connector plus some required properties for setting up the client key store and
the trust store for the SSL connection.

attributes:

for identification
class name)

For example:
<smtps:connector name="smtpsConnector">
<smtps:tls-client path="clientKeystore" storePassword="mulepassword" />
<smtps:tls-trust-store path="greenmail-truststore" storePassword="password" />
</smtps:connector>
<model name="test">
<inbound>
<vm:inbound-endpoint path="send" />
</inbound>
<outbound>
<smtps:outbound-endpoint host="localhost" port="65439" to="bob@example.com" />
</outbound>
...
For information on configuring endpoints using the SMTPS connector, see SMTP Transport.

The SMTPS transport supports the same filters and transformers as the Email Transport.

SMTP Transport
SMTP Transport
The SMTP transport can be used for sending messages over SMTP using the javax.mail API. See
the SMTPS Transport for a secure version. The implementation supports CC/BCC/ReplyTo addresses,
attachments, custom Header properties, and customizable authentication. It also provides support for
javax.mail.Message transformation.
SMTP Connector
The SMTP connector supports all the common connector attributes and properties and the following
optional element and attributes:
<connector ...>
Attributes
bccAddresses string no Comma separated

list of addresses
for blind copies.
ccAddresses string no Comma separated

list of addresses
for copies.
contentType string no Mime type for

the outgoing
message.
fromAddress string no The from address

for the outgoing
message.
replyToAddresses string no The reply-to

address for
the outgoing
message.
subject string no The default

subject for the
outgoing message
if none is set in
the message.

Child Elements
header 1..1 Additional header name and

value, added to the message.
For example:
<smtp:connector name="smtpConnector" bccAddresses="abc@example.com"

ccAddresses="bcd@example.com" contentType="foo/bar"
fromAddress="cde@example.com" replyToAddresses="def@example.com"
subject="subject">
<smtp:header key="foo" value="bar" />
<smtp:header key="baz" value="boz" />
</smtp:connector>
Endpoints
SMTP endpoints describe details about the SMTP server and the recipients of messages sent from
the SMTP endpoint. You configure the endpoints just as you would with any other transport, with the
following additional attributes:
user The user name of the mailbox owner
password The password of the user
host The IP address of the SMTP server, such as

www.mulesource.com, localhost, or 127.0.0.1
port The port number of the SMTP server
to The destination for the email
from The address of the sender of the email
subject The email subject
cc A comma-separated list of email addresses to

copy on this email
bcc A comma-separated list of email addresses to

blind-copy on this email
replyTo The address used by default if someone replies to

the email
For example:
<outbound>
<smtp:outbound-endpoint host="localhost" port="65437" from="steve@mycompany.com"
to="bob@example.com" subject="Please verify your account details"/>

</outbound>
If you only need a few attributes, you can specify the endpoint as a URI. However, the above syntax is
recommended for easier readability. The URI syntax is as follows:
smtp://[user:password@]<smtp server>[MULE::port]?address=<recipient address>
The format is the same for SMTPS:
smtps://[user:password@]<smtp server>[MULE::port]?address=<recipient address>
For example:
smtp://muletestbox:123456@smtp.mail.yahoo.co.uk?address=dave@mycompany.com
This will send mail using smtp.mail.yahoo.co.uk (using the default SMTP port) to the address
dave@mycompany.com. The SMTP request is authenticated using the username muletestbox and the
password 123456.
So far, all configuration has been static, in that you define all the information in the configuration of the
endpoint. However, you can set the connector properties to control the settings of the outgoing message.
These properties will override the endpoint properties. If you always want to set the email address
dynamically, you can leave out the to attribute (or the address parameter if you're using URIs} on the
SMTP endpoint.

SOAP Transport
SOAP Transport
The SOAP transport is deprecated and will be desupported in a future release. We
recommend that you either use the CXF Transport or the Axis Transport to build web
services from now on.
The SOAP transport enables your components to be exposed as web services and to act as SOAP clients.
The SOAP transport provides support for the CFX and Axis transports.
The Javadoc for the SOAP transport can be found here .
Endpoints
You configure a SOAP endpoint as follows:
soap:http://localhost:1234/MyService
The actual SOAP stack used to execute this service will be discovered based on the first SOAP stack
available on the class path. Alternatively, an implementation can be specified directly.
Transformer
The SOAP transport provides a single transformer, http-to-soap-request-transformer, which converts
an HTTP GET request into a SOAP request. It does so according to the following template:
<?xml version=\"1.0\" encoding=\"{0}\"?>

<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"
xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"
xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">
<soap:Body>
<NAMESPACE:METHOD>
<NAMESPACE:PROPERTY1>VALUE1</NAMESPACE:PROPERTY1>
<NAMESPACE:PROPERTY2>VALUE1</NAMESPACE:PROPERTY2>
...
</NAMESPACE:METHOD>
</soap:Body>
</soap:Envelope>
...where namespace is a property on the endpoint, the method is the "method" property set on the
message, and the properties are from the HTTP GET request.
For example, given the following transformer configuration:
<custom-transformer class="org.mule.transport.soap.transformers.HttpRequestToSoapRequest">
<spring:property name="namespace" value="http://acme.com/hello">

...and a GET request of "http://foo.com/hello?method=sayHello&name=Dan&salutation=Bonjour", the
following SOAP message would be generated:
<?xml version=\"1.0\" encoding=\"{0}\"?>

<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"
xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"
xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">
<soap:Body>
<sayHello xmlns="http://acme.com/hello">
<name>Dan</name>
<salutation>Bonjour</salutation>
</sayHello>
</soap:Body>
</soap:Envelope>

SSL Transport
SSL Transport
The SSL transport can be used for secure socket communication using SSL or TLS.
Connector
Connects Mule to an SSL socket to send or receive data via the network.
client 0..1 The client key store. SSL and

TLS connections are made on
behalf of an entity, which can
be anonymous or identified
by a certificate. This interface
specifies how a keystore can be
used to provide the certificates
(and associated private keys)
necessary for identification.
key-store 0..1 The key store information,

including location, key store
type, and algorithm.
server 0..1 The server trust store. TLS

connections are made to trusted
systems - the public certificates
of trusted systems are stored in
a keystore (called a trust store)
and used to verify that the
connection made to a remote
system really is the expected
identity.
protocol-handler 0..1 Configures the global Java

protocol handler by setting
the java.protocol.handler.pkgs
system property.
Endpoint
host string no

port port number no
Inbound Endpoint
host string no
port port number no
Outbound Endpoint
host string no
port port number no
To configure the SSL connector:

xmlns:ssl="http://www.mulesource.org/schema/mule/ssl/2.0"
xsi:schemaLocation="http://www.mulesource.org/schema/mule/core/2.0
http://www.mulesource.org/schema/mule/ssl/2.0
http://www.mulesource.org/schema/mule/ssl/2.0/mule-ssl.xsd">
<ssl:connector name="SslConnector" keepSendSocketOpen="true">
<ssl:client path="clientKeyStore" storePassword="mulepassword" />
<ssl:key-store path="serverKeystore" storePassword="mulepassword" keyPassword="mulepassword" />
<ssl:server path="trustStore" storePassword="mulepassword" />
</ssl:connector>
<endpoint name="sendEndpoint" address="ssl://localhost:60198" synchronous="true" />
...
To configure the TLS connector instead of the SSL connector, specify the tls namespace and schema,
configure the connector, and then use the tls prefix for endpoints:

xmlns:tls="http://www.mulesource.org/schema/mule/tls/2.0"
xsi:schemaLocation="http://www.mulesource.org/schema/mule/core/2.0
http://www.mulesource.org/schema/mule/tls/2.0
http://www.mulesource.org/schema/mule/tls/2.0/mule-tls.xsd">
<tls:connector name="tlsConnector" keepSendSocketOpen="true">
<tls:client path="clientKeyStore" storePassword="mulepassword" />

<tls:key-store path="serverKeystore" storePassword="mulepassword" keyPassword="mulepassword" />
<tls:server path="trustStore" storePassword="mulepassword" />
</tls:connector>
<tls:endpoint name="sendEndpoint" connector-ref="tlsConnector" address="tls://localhost:60198"
synchronous="true" />
...

STDIO Transport
This page last changed on Jan 12, 2009 by dan.diephouse@mulesource.com.
STDIO Transport
The STDIO Transport allows the reading and writing of streaming data to Java's System.out and
System.in objects for debugging.
Connector
messageDelayTime long no Delay in

milliseconds
before printing the
prompt to stdout.
outputMessage string no Text printed to

stdout when a
message is sent.
promptMessage string no Text printed to

stdout when
waiting for input.
promptMessageCode string no Code used to

retrieve prompt
message from
resource bundle.
outputMessageCode string no Code used to

retrieve output
message from
resource bundle.
resourceBundle string no Resource bundle

to provide
prompt with
promptMessageCode.
To configure the STDIO connector:

http://www.mulesource.org/schema/mule/stdio/2.1
http://www.mulesource.org/schema/mule/stdio/2.1/mule-stdio.xsd">
<stdio:connector name="stdioConnector" messageDelayTime="1234" outputMessage="abc"
promptMessage="bcd" promptMessageCode="456" resourceBundle="dummy-messages" />

<model name="model">
<service name="service">
<inbound>
<stdio:inbound-endpoint name="in" system="IN" connector-ref="stdioConnector" />
</inbound>
<outbound>
<multicasting-router>
<stdio:outbound-endpoint name="out" system="OUT" connector-ref="stdioConnector" />
<stdio:outbound-endpoint name="err" system="ERR" connector-ref="stdioConnector" />
</multicasting-router>
</outbound>
</service>
</model>
</mule>
Transformers
There are no built-in transformers for the STDIO transport.
Internationalizing Messages
If you are internationalizing your application, you can also internationalize the promptMessages and
outputMessages for the STDIO connector. (This assumes that you have already created a resource bundle
that contains your messages as described on that page.)
To internationalize, you must specify both the resourceBundle parameter and the promptMessageCode
and/or outputMessageCode parameters. The resourceBundle parameter will contain the key to the
resource bundle itself. The promptMessageCode provides the key to the message in the bundle for
the prompt message. In the snippet above, the "dummy-messages" resource bundle means that the
prompt message "456" will be expected in the bundle META-INF/services/org/mule/i18n/dummy-
messages<langCode>.properties.

TCP Transport
Table of Contents
• TCP Transport
• ° Connector
° - Child Elements of <connector...>
° Inbound endpoint
° Endpoint
° Streaming protocol
° Xml protocol
° Xml eof protocol
° Eof protocol
° - Attributes of <eof-protocol...>
° Direct protocol
° - Attributes of <direct-protocol...>
° Safe protocol
° - Attributes of <safe-protocol...>
° Length protocol
° - Attributes of <length-protocol...>
° Custom protocol
° - Attributes of <custom-protocol...>
° Transformers
TCP Transport
The TCP transport enables events to be sent and received over TCP sockets.
Connector
Connects Mule to a TCP socket to send or receive data via the network.
abstract-protocol 0..1 The class name for the protocol

handler. This controls how the
raw data stream is converted
into messages. By default,
messages are constructed
as dara is received, with no
correction for multiple packets
or fragmentation. Typically,
change this value, or use
a transport that includes a
protocol like HTTP.

Inbound Endpoint
host string no
port port number no
Outbound Endpoint
host string no
port port number no
Endpoint
host string no
port port number no
Streaming Protocol
TCP does not guarantee that data written to a socket is transmitted in a single packet, so if you want to
transmit entire Mule messages reliably, you must specify an additional protocol. However, this is not an
issue with streaming, so this is an alias for the "direct" (null) protocol.
Xml Protocol
TCP does not guarantee that data written to a socket is transmitted in a single packet, so if you want to
transmit entire Mule messages reliably, you must specify an additional protocol. This protocol uses XML
syntax to isolate messages from the stream of bytes received, so it will only work with well-formed XML.
Xml Eof Protocol

Similar to "xml-protocol", but it will also use socket closure to terminate a message (even if the XML is
not well-formed).

Eof Protocol
TCP does not guarantee that data written to a socket is transmitted in a single packet, so if you want
to transmit entire Mule messages reliably, you must specify an additional protocol. This protocol simply
accumulates all data until the socket closes and places it in a single message.
Attributes of <eof-protocol...>
payloadOnly boolean no Sends only the

payload, not
the entire Mule
message object or
its properties. This
defaults to true
when the protocol
is not specified
explicitly (when
the safe protocol
is used).
Direct Protocol
TCP does not guarantee that data written to a socket is transmitted in a single packet. Using this "null"
protocol does not change the normal TCP behavior, so message fragmentation may occur. For example, a
single sent message may be received in several pieces, each as a separate received message. Typically,
it is not a good choice for messaging within Mule, but it may be necessary to interface with external TCP-
based protocols.
Attributes of <direct-protocol...>

payload, not
the entire Mule
message object or
defaults to true
when the protocol
is not specified
explicitly (when
the safe protocol
is used).
Safe Protocol
Similar to "length-protocol", but it also includes a prefix. Verification of the prefix allows mis-matched
protocols to be detected and avoids interpreting "random" data as a message length (which may give
out-of-memory errors). This is the default protocol in Mule 2.x.

Attributes of <safe-protocol...>

payload, not
the entire Mule
message object or
defaults to true
when the protocol
is not specified
explicitly (when
the safe protocol
is used).
maxMessageLength integer no An optional

maximum length
for the number
of bytes in a
single message.
Messages larger
than this will
trigger an error in
the receiver, but it
give an assurance
that no out-of-
memory error will
occur.
Length Protocol
This protocol precedes each message with the number of bytes sent so that an entire message can be
constructed on the received.
Attributes of <length-protocol...>

payload, not
the entire Mule
message object or
defaults to true
when the protocol
is not specified
explicitly (when
the safe protocol
is used).
maxMessageLength integer no An optional

maximum length
for the number
of bytes in a
single message.
Messages larger
than this will

trigger an error in
the receiver, but it
give an assurance
that no out-of-
memory error will
occur.
Custom Protocol
The user may supply their own protocol implementation via this element.
Attributes of <custom-protocol...>
class class name no A class that

implements
the TcpProtocol
interface.
Transformers
The following transformers are used by default for the TCP transport unless a transformer is explicitly set
on the connector or service.
ByteArrayToString Converts a byte array to a String
StringToByteArray Converts a String to a byte array

UDP Transport
UDP Transport
The UDP transport enables events to be sent and received as Datagram packets.
Connector
receiveBufferSize integer no The size of the

receiving buffer
for the socket.
receiveTimeout long no The amount of

time after which
a Receive call will
time out.
sendBufferSize integer no The size of the

sending buffer for
the socket.
sendTimeout long no The amount of

time after which a
Send call will time
out.
socketLinger long no The amount of

time the socket
will remain open
after a closesocket
call.
broadcast boolean no Whether to enable

the socket to send
broadcast data.
keepSendSocketOpenboolean no Whether to keep

the Sending
socket open.
Endpoints
You configure UDP endpoints just as you would with any other transport, with the following additional
attributes:
• host: the IP address of the server, such as www.mulesource.com, localhost, or 127.0.0.1

• port: the port number of the server.
For example:

<udp:inbound-endpoint host="${hostname}" port="61000" />
Message Payload
The default message payload of the UDP transport for incoming messages is a byte[] array.

VM Transport
VM Transport
The VM transport is used for intra-VM communication between components managed by Mule. The
connector provides options for configuring VM transient or persistent queues.
Using VM Queues
When using a synchronous VM endpoint, messages are delivered in memory from one component to
another (asynchronous endpoints introduce a queue that threads can consume from). However, when the
queueEvents property is set, messages can be stored in arbitrary memory queues and consumed later by
clients or components. Furthermore, these queues can be persistent and XA transactional (see below).
To use VM queues, the queueEvents property must be set on the connector, and all VM endpoints that
should queue messages must use a VM connector that has queueEvents enabled. You cannot set the
queueEvents property on the endpoint. For example:

beans-2.5.xsd
mule.xsd
http://www.mulesource.org/schema/mule/test/2.1 http://www.mulesource.org/schema/mule/test/2.1/
mule-test.xsd
http://www.mulesource.org/schema/mule/vm/2.1 http://www.mulesource.org/schema/mule/vm/2.1/
mule-vm.xsd">
<vm:connector name="asynchVm" queueEvents="true"/>

<model>
<service name="myAsynchService">
<inbound>
<vm:inbound-endpoint path="in" connector-ref="asynchVm"/>
</inbound>
<test:component>
<test:return-data>Polo</test:return-data>
</test:component>
<outbound>
<vm:outbound-endpoint path="out" connector-ref="asynchVm"/>
</outbound>
</service>
</model>
</mule>
Notice that the inbound endpoint explicitly tells Mule to use the asynchVm connector. Otherwise, Mule will
look for the first connector that matches the protocol for the endpoint.

For more information on queues, see Configuring Queues.
Using Persistent Queues
A VM queue can be made persistent so that its state can be maintained between server shutdowns. To
make VM queues persistent, you enable the persistent property in the queue profile on the model or
service.
Using Transactions
VM queues can take part in distributed XA transactions. To make a VM endpoint transactional, use the
following configuration:
<inbound>
<vm:inbound-endpoint address="vm://dispatchInQueue" connector-ref="vmQueue">
<vm:transaction action="BEGIN_OR_JOIN"/>
</vm:inbound-endpoint>
</inbound>
You must add a transaction manager to your configuration. For more information, see Transaction
Management.
Transformers
There are no specific transformers for the VM transport.
Following are the elements and attributes you can set for the VM transport.
Connector
queueEvents boolean no Determines

whether queues
should be set up
for listeners on
the connector.
If set to false,
the connector
simply forwards
messsages to
components via
the Mule server.
If it is set to
true, the queues
are configured
using the queuing
profile.

queueTimeout positiveInteger no The timeout
setting for the
queue.
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.
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.

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.


path, such as
dispatchInQueue
to create the
address vm://
dispatchInQueue.
Transaction
The transaction configuration.

WSDL Transport
WSDL Transport
[ Generic WSDL Endpoints ] [ Transformers ] [ Specifying an Alternate WSDL Location ] [ Example of the
CXF WSDL Endpoint ]
The WSDL transport can be used to for invoking remote web services by obtaining the service WSDL.
Mule will create a dynamic proxy for the service and then invoke it.
The Javadoc for this transport can be found here for the Axis version and here for the CXF version.
Generic WSDL Endpoints

A WSDL endpoint enables you to easily invoke web services without generating a client. At startup, it
reads the WSDL to determine how to invoke the remote web service during runtime. When a message is
sent through the WSDL endpoint, it is able to construct a SOAP message using the message payload and
its knowledge of the expected payload format from the WSDL.
You must provide the full URL to the WSDL of the service to invoke, and you must supply a 'method'
parameter that tells Mule which operation to invoke on the service:
wsdl:http://www.webservicex.net/stockquote.asmx?WSDL&method=GetQuote
The WSDL URL is prepended with the wsdl: prefix. Mule checks your class path to see if there is a WSDL
provider that it can use to create a client proxy from the WSDL. Mule supports both Axis and CXF as
WSDL providers. If you want to use a specific one, you can specify it on the URL as follows:
wsdl-cxf:http://www.webservicex.net/stockquote.asmx?WSDL&method=GetQuote
or
wsdl-axis:http://www.webservicex.net/stockquote.asmx?WSDL&method=GetQuote
In general, you should use the CXF WSDL endpoint. The one limitation of the CXF WSDL provider is
that it does not allow you to use non-Java primitives (objects that are not a String, int, double, and so
on). Sometimes the Axis WSDL generation will not work (incorrect namespaces are used), so you can
experiment with each one to see which works best.
Transformers
There are no specific transformers to set on WSDL endpoints.
Specifying an Alternate WSDL Location

By default, the WSDL provider will look for your WSDL by taking the endpoint address and appending
?wsdl to it. With the CXF transport, you have the option of specifying a location for the WSDL that is
different from that specified with the ?wsdl parameter. This may be useful in cases where the WSDL isn't
available the normal way, either because the SOAP engine doesn't provide it or the provider does not
want to expose the WSDL publicly.

In these cases, you can specify the wsdlLocation property of the CXF endpoint as follows:
<endpoint
address="wsdl-cxf:http://localhost:8080/book/services/BookService?method=getBooks">
<properties>
<property name="wsdlLocation" value="file:///c:/BookService.wsdl"/>
</properties>
</endpoint>
In this case, the WSDL CXF endpoint works as it normally does, except that it reads the WSDL from the
local drive.
Example of the CXF WSDL Endpoint

This example demonstrates how to take multiple arguments from the console, invoke a web service, and
print the output to the screen. It uses the Currency Convertor web service on www.webservicex.net.
This service requires two arguments: the "from" currency code and the "to" currency code. When the CXF
dispatcher prepares arguments for the invocation of the service, it expects to find a message payload of
Object[] - that is, an Object array. In the case of the Currency Convertor, this should be an array of two
Objects - the "from" currency and the "to" currency.
There are several ways to construct this object array, but the easiest way is to use the custom
transformer StringToObjectArrayTransformer , which translates a delimited String into an Object array. In
the example below, you simply type in a String in the format of <fromCurrency>,<toCurrency>.

beans-2.5.xsd
mule.xsd">
<model name="sample">
<service name="inputService">
<inbound>
<inbound-endpoint address="stdio://System.in?promptMessage=Enter from and to currency
symbols, separated by a comma:"
synchronous="true">
<transformers>

<custom-transformer class="org.mule.transformer.simple.StringToObjectArray">
<spring:property name="delimiter" value=","/>
</transformers>
</inbound-endpoint>
</inbound>
<outbound>
<chaining-router>
<outbound-endpoint address="wsdl-cxf:http://www.webservicex.net/CurrenyConvertor.asmx?
WSDL&method=ConversionRate"
synchronous="true"/>
<outbound-endpoint address="stdio://System.out"/>
</chaining-router>
</outbound>

</service>
</model>
</mule>
For example, type "EUR,USD" to get the conversion rate for Euros to US Dollars, and you'll get something
like this:
Enter from and to currency symbols, separated by a comma:

EUR,USD
1.3606

XMPP Transport
XMPP Transport
[ Inbound Endpoint ] [ Outbound Endpoint ] [ Endpoint ] [ Transformers ] [ Filters ]
The XMPP transport enables the XMPP (Jabber) instant messaging protocol. The XMPPS connector
provides a secure implementation.
The Javadoc for the XMPP transport can be found here .
Inbound Endpoint
The endpoint on which this connector receives messages from the transport.
user string no The user name to

use to connect to
the XMPP server.
password string no The password to

use with the user
name.
host string no The host of

the XMPP
server, such as
www.mulesource.com,
localhost, or
127.0.0.1.

of the XMPP
server, such as
5222.
recipient string no The ID of

the intended
recipient of the
messages, such as
ross@myco.com.
groupChat boolean no Whether to start a

group chat.
nickname string no The user's

nickname.
resource string no The resource

portion of the
address, such
as user@host/
resource or
domain/resource.

thread string no The thread
to which the
message belongs.
to string no The user to whom

the message was
sent.
from string no The user who sent

the message.
Outbound Endpoint
The endpoint to which this connector sends messages.

use to connect to
the XMPP server.

use with the user
name.

the XMPP
server, such as
www.mulesource.com,
localhost, or
127.0.0.1.

of the XMPP
server, such as
5222.

the intended
recipient of the
messages, such as
ross@myco.com.

group chat.

nickname.

portion of the
address, such
as user@host/
resource or
domain/resource.

to which the
message belongs.

the message was
sent.

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

use to connect to
the XMPP server.

use with the user
name.

the XMPP
server, such as
www.mulesource.com,
localhost, or
127.0.0.1.

of the XMPP
server, such as
5222.

the intended
recipient of the
messages, such as
ross@myco.com.

group chat.

nickname.

portion of the
address, such
as user@host/
resource or
domain/resource.

to which the
message belongs.

the message was
sent.

the message.
You configure the XMPP connector as follows:

xmlns:xmpp="http://www.mulesource.org/schema/mule/xmpp/2.1"
beans-2.5.xsd
mule.xsd
http://www.mulesource.org/schema/mule/xmpp/2.1 http://www.mulesource.org/schema/mule/xmpp/2.1/
mule-xmpp.xsd">
<xmpp:endpoint name="noNicknameEndpoint" host="localhost" port="1234" user="mule"

password="secret" recipient="recipient" groupChat="true"/>
</mule>
If you want to use secure XMPP, specify the xmpps namespace instead, specifying the schema as follows,
and then use the xmpps prefix on the endpoints:
http://www.mulesource.org/schema/mule/xmpps/2.1 http://www.mulesource.org/schema/mule/xmpps/2.1/
mule-xmpps.xsd
Transformers
There are two transformers provided with the XMPP transport:
org.mule.transport.xmpp.transformers.XmppPacketToString
Converts an XMPP Packet to a String, returning a
java.lang.String object.
org.mule.transport.xmpp.transformers.ObjectToXmppPacket
Accepts a String or an XMPP Packet and returns
an XMPP Packet. This transformer doesn't accept
all objects, only Strings and XMPP Packets.
Filters
There are several filters in the org.mule.transport.xmpp.filters package that filter XMPP messages.
AbstractXmppFilter is an abstract filter adapter that allows Smack filters to be configured as Mule
filters. The following filter classes extend the abstract filter:

• XmppAndFilter
• XmppFromContainsFilter
• XmppMessageTypeFilter
• XmppNotFilter
• XmppOrFilter
• XmppPacketIDFilter
• XmppPacketTypeFilter
• XmppThreadFilter
• XmppToContainsFilter

Bootstrapping the Registry
Bootstrapping the Registry

Mule provides a mechanism for adding objects to the Mule registry as soon as a module or transport is
loaded. This is useful for registering shared transformers or expression evaluators.
All objects you add to the registry using this mechanism must have a default constructor. They can
implement injection interfaces such as org.mule.MuleContextAware and lifecycle interfaces such as
org.mule.api.lifecycle.Initialisable .
Specifying the Objects to Bootstrap

To load an object into the Mule registry using the bootstrap mechanism, you specify the object in the
properties file registry-bootstrap.properties, which you then store in the META-INF directory for the
transport or module. For example:
src/main/resources/META-INF/services/org/mule/config/registry-bootstrap.properties
Each entry in the registry-bootstrap.properties file is a simple key/value pair that defines the
object:
myobject=org.foo.MyObject
If this file is in a module or transport's META-INF directory, Mule will register an instance of
org.foo.MyObject with a key of 'myobject' into the local registry when that module or transport is
loaded.
If you want to ensure that the object gets a unique ID in the local registry, you can use object.n for the
key, where n is a sequential number:
object.1=org.foo.MyObject
object.2=org.bar.MyObject
Adding Transformers
When adding transformers, you can also define the returnClass and name of the transformer as
parameters:
transformer.1=org.mule.transport.jms.transformers.JMSMessageToObject,returnClass=byte[]
transformer.2=org.mule.transport.jms.transformers.JMSMessageToObject,returnClass=java.lang.String,
name=JMSMessageToString
transformer.3=org.mule.transport.jms.transformers.JMSMessageToObject,returnClass=java.util.Hashtable)
Note that the key used for transformers must be transformer.n where n is a sequential number.

If the transformer name is not specified, Mule will automatically generate the name as JMSMessageToXXX
where XXX is the return class name, such as JMSMessageToString. If no returnClass is specified, the
default value in the transformer will be used.

Choosing the Right Topology
Choosing the Right Topology

[ About Clustering ] [ JMS Queues ] [ Load Balancers ] [ Maintaining State in a Database ] [ Handling
Stateful Components ] [ Example Architectures ] [ Related Topics ]
As you build your Mule application, it is important to think critically about how best to architect your
application to achieve the desired availability, fault tolerance, and performance characteristics. This page
outlines some of the solutions for achieving the right blend of these characteristics through clustering
and other techniques. There is no one correct approach for everyone, and designing your system is both
an art and a science. If you need more assistance, MuleSource Professional Services can help you by
reviewing your architecture plan or designing it for you. For more information, contact us.
About Clustering
Clustering an application is useful for achieving the following:
• High availability (HA): Making your system continually available in the event that one or more
servers or a data center fails.
• Fault tolerance (FT): The ability to recover from failure of an underlying component. Typically, the
recovery is achieved through transaction rollback or compensating actions.
This page describes several possible clustering solutions. Please note that as of the current release,
MuleSource does not support any specific clustering solution, although many users have successfully set
up Mule in a clustered environment.
JMS Queues
JMS can be used to achieve HA & FT by routing messages through JMS queues. In this case, each
message is routed through a JMS queue whenever it moves from component to component.
Pros:
• Easy to do
• Well understood by developers
Cons:
• Requires lots of transactions, and transactions can be complicated

• Performance hit if you're using XA
Load Balancers
Load balancers simply route requests to different servers based on the the current load of each server
and which servers are currently up. Load balancers can be software or hardware based. This approach is
commonly used with clustered databases (see below).

Pros:
• Straightforward to do
Cons:
• Not a complete solution on its own, doesn't provide fault tolerance.
Maintaining State in a Database

If you have a clustered database, one option for your application is to simply store all state in the
database and rely on it to replicate the data consistently across servers.
Pros:
• Straightforward to do
Cons:
• Not all state is amenable to being stored in the database
Handling Stateful Components

While most applications can be supported by the above techniques, some require sharing state between
JVMs more deeply.
One common example of this is an aggregator component. For example, assume you have an aggregator
that is aggregating messages from two different producers. Producer #1 sends a message to the
aggregator, which receives it and holds it in memory until Producer #2 sends a message.
Producer #1 ---> |----------|

|Aggregator| --> Some other component
Producer #2 ---> |----------|
If the server with the aggregator goes down between Producer #1 sending a message and Producer #2
sending a message, Producer #2 can't just send its message to a different server because that server will
not have the message from Producer #1.
The solution to this is to share the state of the aggregator component across different machines through
clustering software such as Terracotta, Tangosol Coherence, JGroups, etc. By using one of these tools,
Producer #2 can simply fail over to a different server. Note that MuleSource has not tested Mule with
these tools and does not officially support them.
Pros:
• Works for all clustering cases

• Can work as a cache as well
Cons:
• Not officially supported by MuleSource

• Requires performance tuning to get things working efficiently

Example Architectures
HTTP + JMS Queues
In this example architecture, HTTP requests come in through a load balancer and are immediately put on
a JMS queue. The JMS queue is clustered between the different servers. A server will start processing a
message off the JMS queue and wrap everything in a transaction.
If the server goes down, the transaction will roll back and another server will pick up the message and
start processing it.
Note: If the HTTP connection is open for the duration of this process, this approach will not work, as the
load balancer will not transparently switch connections between servers. In this case, the HTTP client will
need to retry the request.
Terracotta
Terracotta is an open source JVM clustering technology. It is able to replicate the state of your
components across JVMs. In this example architecture, there is a load balancer that is proxying requests
between multiple servers.
If one of the servers goes down, the load balancer automatically routes requests to a server that is up.
Because all the state of your components is shared between the different servers, your internal process
can continue on another server.

Note: If the HTTP connection is open for the duration of this process, this approach will not work, as the
load balancer will not transparently switch connections between servers. In this case, the HTTP client will
need to retry the request.
Related Topics
As you design your topology, there are several other topics to keep in mind that are beyond the scope of
this documentation:
• Maintaining geo-distributed clusters

• Data partitioning
• ACID vs. BASE transactions
• Compensation and transactions

Configuration Overview
Configuration Overview
[ Configuration Files ] [ Configuration Builders ] [ Accessing the Configuration Programmatically ] [
Configuring System Properties ]
By default, Mule starts up with a simple configuration in which only some system-level services are
configured. You must configure services, transports, and the rest of the elements required for your
application. Following is an overview of configuration in Mule.
Configuration Files
In most cases, you will configure Mule using XML files. These files are based on Spring and make it very
easy to set up your Mule instance in a short time. For complete information on setting the options in the
configuration file, see XML Configuration.
When you start Mule from the command line, you simply specify the configuration file(s) with the -
config parameter:
mule -config foo-config.xml
mule -config foo-config.xml,bar-config.xml
If you want to start Mule by calling it from your code, you specify the configuration file as a parameter to
the ConfigurationBuilder:
MuleContext context = new DefaultMuleContextFactory().createMuleContext(new

SpringXmlConfigurationBuilder("foo-config.xml"));
context.start();
If you have multiple configuration files, you can also import them into one configuration file so that you
only have to specify one configuration file at the command line or from your code. For example:

<mule xmlns=http://www.mulesource.org/schema/mule/core/2.1 ....>
<spring:beans>
<spring:import resource="mule-sub-config1.xml" />
<spring:import resource="mule-sub-config2.xml" />
</spring:beans>
...
Configuration Builders
The configuration builder is responsible for creating the configuration that's used at run time from the
configuration files you provide. Mule provides two standard configuration builders, or you can create your
own.

SpringXmlConfigurationBuilder
The default configuration builder used to configure Mule is the SpringXmlConfigurationBuilder. This
configuration builder uses Spring 2.0 to configure Mule based on one or more XML files leveraging custom
Mule namespaces. For more information, see XML Configuration.
ScriptConfigurationBuilder
This configuration builder allows a JSR-223 compliant script engine (e.g., Groovy, Jython) to configure
Mule. For more information, see Scripting Module.
Custom Configuration Builders
You can easily create your own custom configuration builder by implementing the ConfigurationBuilder
interface, which has a method configure. Typically, you call configure(MuleContext
muleContext.getRegistry()) to get access to Mule's internal registry, which contains the configuration
information, and to register services and other elements.
In most cases, you will want to inherit from the class AbstractResourceConfigurationBuilder , which
will make any configuration files specified on the command line available in an instance variable called
configResources.
Specifying the Configuration Builder
SpringXmlConfigurationBuilder is the default configuration builder. If you want to use another

configuration builder, you can specify it on the command line at startup with the -builder parameter:
mule -builder org.mule.module.scripting.builders.ScriptConfigurationBuilder -config mule-config.groovy
You can also specify the configuration builder as a parameter to the MuleContextFactory when starting
Mule programatically:
MuleContext context = new DefaultMuleContextFactory().createMuleContext(new

ScriptConfigurationBuilder("mule-config.groovy"));
context.start();
Accessing the Configuration Programmatically

All Mule configuration is accessible from a single object: org.mule.api.config.MuleConfiguration .
Configurations in a MuleConfiguration are set when a MuleContext is created. The object becomes
immutable after it is started and can be accessed using the following:
MuleContext context = MuleServer.getMuleContext();

MuleConfiguration configuration = context.getConfiguration();
Configuring System Properties

There are several system properties that are immutable after startup, such as the server ID. To
specify these properties, you can use the -M-Dmule.<propertyName> command (such as -M-
Dmule.serverId=YOUR_MULE_SERVER_ID) or by setting -Dmule.<propertyName> in wrapper.conf if you
are running Mule from the command line. To set these properties programmatically, you customize the

MuleConfiguration using the set method for the property (such as setId for the system ID), create a
MuleContextBuilder, load the configuration to the builder, and then create the context from the builder.
For example:
SpringXmlConfigurationBuilder configBuilder = new

SpringXmlConfigurationBuilder("my-config.xml");
DefaultMuleConfiguration muleConfig = new DefaultMuleConfiguration();
muleConfig.setId("MY_SERVER_ID");
MuleContextBuilder contextBuilder = new DefaultMuleContextBuilder();
contextBuilder.setMuleConfiguration(muleConfig);
MuleContextFactory contextFactory = new DefaultMuleContextFactory();
MuleContext muleContext =
contextFactory.createMuleContext(configBuilder, contextBuilder);
muleContext.start();
For more information on the system properties you can set programmatically, see
DefaultMuleConfiguration .

• Global Settings Configuration Reference
• Model Configuration Reference
• Service Configuration Reference
• Endpoint Configuration Reference
• Routers
° Inbound Router Configuration Reference
° Outbound Router Configuration Reference
° Asynchronous Reply Router Configuration Reference
° Catch All Strategy Configuration Reference
• Filters Configuration Reference

• Transformers Configuration Reference
• Component Configuration Reference
• Entry Point Resolver Configuration Reference
• Exception Strategy Configuration Reference
• Properties Configuration Reference
• Notifications Configuration Reference
• Transactions Configuration Reference
• Expressions Configuration Reference
For configuration reference on transports, see Available Transports. For modules, see Using Mule Modules.
For transports and modules contributed by the community, see MuleForge Active Projects.

Asynchronous Reply Router Configuration Reference
Asynchronous Reply Router Configuration

Reference
This page provides details on the elements you configure for asynchronous reply routers. This information
is pulled directly from mule.xsd and is cached. If the information appears to be out of date, refresh the
page. For more information on routers, see Using Message Routers.
<single-async-reply-router ...>
Configures a Single Response Router. This will return the first message it receives on a reply endpoint and
will discard the rest.
Attributes
Child Elements
abstract-inbound- 0..* A placeholder for

endpoint inbound endpoint
elements. Inbound
endpoints receive
messages from
the underlying
transport. The
message payload
is then delivered
to the component
for processing.
abstract-message- 0..1 Maps the

info-mapping attributes of the
current message
to known message
elements in
Mule, namely
Message ID and
CorrrelationID.
<collection-async-reply-router ...>
Configures a Collection Response Router. This will return a MuleMessageCollection message type that will
contain all messages received for the current correlation.

Attributes
Child Elements
abstract-inbound- 0..* A placeholder for

endpoint inbound endpoint
elements. Inbound
endpoints receive
messages from
the underlying
transport. The
message payload
is then delivered
to the component
for processing.
abstract-message- 0..1 Maps the

info-mapping attributes of the
current message
to known message
elements in
Mule, namely
Message ID and
CorrrelationID.
<custom-async-reply-router ...>
Attributes
class class name no
Child Elements
abstract-inbound-endpoint 0..* A placeholder for inbound

endpoint elements. Inbound
endpoints receive messages
from the underlying transport.
The message payload is then
delivered to the component for
processing.
abstract-message-info-mapping 0..1 Maps the attributes of the

current message to known
message elements in Mule,
namely Message ID and
CorrrelationID.

spring:property 0..*

Catch All Strategy Configuration Reference
Catch All Strategy Configuration Reference

This page provides details on the elements you configure for catch-all strategies. This information is
pulled directly from mule.xsd and is cached. If the information appears to be out of date, refresh the
page.
<logging-catch-all-strategy ...>
Does nothing with the message but simply logs (using the WARN log level) the fact that the message was
not dispatched because no routing path was defined.
Attributes
Child Elements
<custom-catch-all-strategy ...>
Attributes
class class name no Fully qualified

class name of the
custom catch-
all strategy to be
used.
Child Elements
<forwarding-catch-all-strategy ...>
Forwards the message to the specified endpoint if no outbound routers match.

Attributes
Child Elements
abstract- 0..* A placeholder for

outbound- outbound endpoint
endpoint elements.
Outbound
endpoints dispatch
messages to
the underlying
transport.
<custom-forwarding-catch-all-strategy ...>
Attributes

class name of the
custom forwarding
catch-all strategy
to be used.
Child Elements
abstract-outbound-endpoint 0..* A placeholder for outbound

endpoint elements. Outbound
endpoints dispatch messages to
the underlying transport.

Component Configuration Reference
Component Configuration Reference

This page provides details on the elements you configure for components. This information is pulled
directly from mule.xsd and is cached. If the information appears to be out of date, refresh the page. For
more information on components, see Configuring Components.
<component ...>
A simple POJO (Plain Old Java Object) component that will be invoked by Mule when a message is
received. The class or object instance to be used can be specified using a child object factory element,
or via the 'class' attribute. If the 'class' attribute is used, an object factory cannot be configured as well.
Using the 'class' attribute is equivilant to using the propotype object factory ('prototype-object' child
element).
Attributes
class class name no Specifies a

component class.
This is a shortcut
that is equivalent
to providing a
'prototype-object'
element.
Child Elements
abstract-interceptor 1..1 A placeholder for an interceptor

element.
interceptor-stack 1..1 A reference to a stack of

intereceptors defined globally.
abstract-object-factory 0..1 Object factory used to obtain

the object instance that will
be used for the component
implementation. The object
factory is responsible for object
creation and may implement
different patterns, such as
singleton or prototype, or look
up an instance from other object
containers.
abstract-lifecycle-adapter- 0..1
factory
binding 0..* A binding associates a Mule

endpoint with an injected Java

interface. This is like using
Spring to inject a bean, but
instead of calling a method on
the bean, a message is sent to
an endpoint.
abstract-entry-point-resolver-set 0..1 A placeholder for entry point

resolver set elements. These
combine a group of entry point
resolvers, trying them in turn
until one succeeds.
abstract-entry-point-resolver 0..1 A placeholder for an entry point

resolver element. Entry point
resolvers define how payloads
are delivered to Java code by
choosing the method to call.
<pooled-component ...>
A pooled POJO (Plain Old Java Object) component that will be invoked by Mule when a message is
received. The instance can be specified via a factory or a class.
Attributes
class class name no Specifies a

component class.
This is a shortcut
that is equivalent
to providing a
'prototype-object'
element.
Child Elements

element.
interceptor-stack 1..1 A reference to a stack of

intereceptors defined globally.
abstract-object-factory 0..1 Object factory used to obtain

the object instance that will
be used for the component
implementation. The object
factory is responsible for object
creation and may implement
different patterns, such as
singleton or prototype, or look
up an instance from other object
containers.
abstract-lifecycle-adapter- 0..1
factory

binding 0..* A binding associates a Mule
interface. This is like using
the bean, a message is sent to
an endpoint.

until one succeeds.

abstract-pooling-profile 0..1 Characteristics of the object

pool.
<pooling-profile ...>
A pooling profile is used to configure the pooling behaviour of Mule components. Each component can
have its own pooling profile.
Attributes
maxActive string no Controls the

maximum
number of Mule
components that
can be borrowed
from a session
at one time.
When set to a
negative value,
there is no limit
to the number of
components that
may be active at
one time. When
maxActive is
exceeded, the
pool is said to be
exhausted.
maxIdle string no Controls the

maximum
number of Mule
components that
can sit idle in the
pool at any time.
When set to a
negative value,
there is no limit

to the number of
Mule components
that may be idle
at one time.
initialisationPolicy INITIALISE_NONE no INITIALISE_ONE Determines how

/ components in
INITIALISE_ONE a pool should
/ be initialized.
INITIALISE_ALL The possible
values are:
INITIALISE_NONE
(will not load
any components
into the pool
on startup),
INITIALISE_ONE
(will load one
initial component
into the pool
on startup), or
INITIALISE_ALL
(will load all
components in the
pool on startup)
exhaustedActionWHEN_EXHAUSTED_GROW no WHEN_EXHAUSTED_GROW
Specifies the
/ behavior of the
WHEN_EXHAUSTED_WAIT Mule component
/ pool when the
WHEN_EXHAUSTED_FAIL pool is exhausted.
Possible
values are:
"WHEN_EXHAUSTED_FAIL",
which will throw a
NoSuchElementException,
"WHEN_EXHAUSTED_WAIT",
which will block
by invoking
Object.wait(long)
until a new or
idle object is
available, or
WHEN_EXHAUSTED_GROW,
which will create a
new Mule instance
and return
it, essentially
making maxActive
meaningless. If a
positive maxWait
value is supplied,
it will block for at
most that many
milliseconds,
after which a
NoSuchElementException
will be thrown. If
maxThreadWait
is a negative
value, it will block
indefinitely.

maxWait string no Specifies the
number of
milliseconds to
wait for a pooled
component to
become available
when the pool is
exhausted and the
exhaustedAction
is set to
WHEN_EXHAUSTED_BLOCK.
Child Elements
<bridge-component ...>
Transfers a message from inbound to outbound endpoints. This element is provided for backward
compatibility - it is equivalent to not specifying any component.
Attributes
Child Elements
abstract- 1..1 A placeholder for

interceptor an interceptor
element.
interceptor-stack 1..1 A reference

to a stack of
intereceptors
defined globally.
<echo-component ...>
Logs the message and returns the payload as the result.
Attributes
Child Elements

element.

to a stack of
intereceptors
defined globally.
<log-component ...>
Logs the message content (or content length if it is a large message).
Attributes
Child Elements

element.

to a stack of
intereceptors
defined globally.
<null-component ...>
Throws an exception if it receives a message.
Attributes
Child Elements

element.

to a stack of
intereceptors
defined globally.
<spring-object ...>
Object factory used to obtain Spring bean instances. This object factory does not create any instances but
rather looks them up from Spring.

Attributes
bean name (no spaces) no Name of Spring

bean to look up.
Child Elements
property 0..* Sets a Mule property. This is a

name/value pair that can be set
on components, services, etc.,
and which provide a generic
way of configuring the system.
Typically, you shouldn't need to
use a generic property like this,
since almost all functionality
is exposed via dedicated
elements. However, it can be
useful in configuring obscure
or overlooked options and in
configuring transports from the
generic endpoint elements.
properties 0..1 A map of Mule properties.
<singleton-object ...>
Object factory that creates and always returns a singleton object instance.
Attributes
class class name no Class name
Child Elements


<prototype-object ...>
Object factory that creates and returns a new 'prototype' object instance every time it is called.
Attributes
class class name no Class name
Child Elements

<custom-lifecycle-adapter-factory ...>
Attributes
class class name no An

implementation
of the
LifecycleAdapter
interface.

Child Elements
<binding ...>
A binding associates a Mule endpoint with an injected Java interface. This is like using Spring to inject a
bean, but instead of calling a method on the bean, a message is sent to an endpoint.
Attributes
interface class name no The interface

to be injected.
A proxy will be
created that
implements this
interface by
calling out to the
endpoint.
method no The method on

the interface
that should be
used. This can
be omitted if the
interface has a
single method.
Child Elements

Interceptors
See Using Interceptors.
Entry Point Resolvers

See Entry Point Resolver Configuration Reference.

Endpoint Configuration Reference
Endpoint Configuration Reference

This page provides details on the elements you configure for endpoints. This information is pulled directly
from mule.xsd and is cached. If the information appears to be out of date, refresh the page. For more
information on endpoints, see Configuring Endpoints.
<inbound-endpoint ...>
An inbound endpoint receives messages via the associated transport. As with global endpoints, each
transport implements its own inbound endpoint element.
Attributes
name name (no spaces) no Identifies the

endpoint in the
registry. There is
no need to set the
'name' attribute
on inbound
or outbound
endpoints, only on
global endpoints.
ref name (no spaces) no A reference to a

global endpoint,
which is used
as a template
to construct
this endpoint. A
template fixes the
address (protocol,
path, host, etc.),
and may specify
initial values for
various properties,
but further
properties can be
defined locally (as
long as they do
not change the
address in any
way).
address string no The generic

address for this
endpoint. If this
attribute is used,
the protocol must
be specified as
part of the URI.
Alternatively,
most transports
provide their own

attributes for
specifying the
address (path,
host, etc.). Note
that the address
attribute cannot
be combined with
'ref' or with the
transport-provided
alternative
attributes.
synchronous boolean no If true, the

result from the
component
processing the
incoming message
will be returned as
a response.
remoteSync boolean no If true, the

component
will wait for a
response to the
outgoing message
before replying
to the incoming
message.
remoteSyncTimeout integer no The timeout for

the remoteSync
wait (ms).
encoding string no String encoding

used for
messages.
connector-ref name (no spaces) no The name of

the connector
associated with
this endpoint. This
must be specified
if more than
one connector is
defined for this
transport.
transformer-refs list of names no A list of the

transformers that
will be applied
(in order) to the
message before it
is delivered to the
component.
responseTransformer- list of names no A list of the

refs transformers that
will be applied
(in order) to the
synchronous
response before it
is returned via the
transport.

Child Elements
abstract-transaction 0..1 A placeholder for transaction

elements. Transactions allow
a series of operations to be
grouped together.
abstract-filter 0..1 A placeholder for filter elements,

which control which messages
are handled.
abstract-security-filter 0..1 A placeholder for security filter

elements, which control access
to the system.
abstract-retry-policy 0..1 A placeholder for a retry policy

element. Retry policies define
how Mule should retry a failed
message send/dispatch/request.
abstract-transformer 0..* A placeholder for transformer

elements. Transformers convert
message payloads.
transformers 0..1 A list of transformer elements

that will be applied to the
message before it is delivered
to the component. Note that
a list of transformers can
also be specified directly
(without the 'transformers'
element), but then it is
not possible to also specify
response transformers (using
the 'response-transformers'
element).
response-transformers 0..1 A list of transformer elements

response message returned
from the component.


<outbound-endpoint ...>
An outbound endpoint sends messages via the associated transport. As with global endpoints, each
transport implements its own outbound endpoint element.
Attributes

endpoint in
the registry.
There is not
need to set the
'name' attribute
on inbound
or outbound
endpoints, only on
global endpoints.

global endpoint,
which is used
as a template
to construct
this endpoint. A
template fixes the
address (protocol,
path, host, etc.),
and may specify
initial values for
various properties,
but further
properties can be
defined locally (as
long as they do
not change the
address in any
way).

address for this
endpoint. If this
attribute is used,
the protocol must
be specified as
part of the URI.
Alternatively,
most transports
provide their own
attributes for
specifying the
address (path,
host, etc.). Note
that the address
attribute cannot
be combined with
'ref' or with the
transport-provided
alternative
attributes.

result from the
component
processing the
incoming message
will be returned as
a response.

component
will wait for a
response to the
outgoing message
before replying
to the incoming
message.

the remoteSync
wait (ms).

used for
messages.

the connector
associated with
this endpoint. This
must be specified
if more than
one connector is
defined for this
transport.

transformers that
will be applied
(in order) to the
message before it
is delivered to the
component.

will be applied
(in order) to the
synchronous
response before it
is returned via the
transport.
Child Elements

grouped together.

are handled.

to the system.


message payloads.

element).

from the component.

<endpoint ...>
A global endpoint, which acts as a template that can be used to construct an inbound or outbound
endpoint elsewhere in the configuration by referencing the global endpoint name. Each transport
implements its own endpoint element, with a more friendly syntax, but this generic element can be
used with any transport by supplying the correct address URI. For example, "vm://foo" describes a VM
transport endpoint.

Attributes

endpoint so that
other elements
can reference it.
This name can
also be referenced
in the MuleClient.

global endpoint,
which is used
as a template
to construct
this endpoint. A
template fixes the
address (protocol,
path, host, etc.),
and may specify
initial values for
various properties,
but further
properties can be
defined locally (as
long as they do
not change the
address in any
way).

address for this
endpoint. If this
attribute is used,
the protocol must
be specified as
part of the URI.
Alternatively,
most transports
provide their own
attributes for
specifying the
address (path,
host, etc.). Note
that the address
attribute cannot
be combined with
'ref' or with the
transport-provided
alternative
attributes.

result from the
component
processing the
incoming message
will be returned as
a response.

component
will wait for a
response to the
outgoing message
before replying
to the incoming
message.

the remoteSync
wait (ms).

used for
messages.

the connector
associated with
this endpoint. This
must be specified
if more than
one connector is
defined for this
transport.

transformers that
will be applied
(in order) to the
message before it
is delivered to the
component.

will be applied
(in order) to the
synchronous
response before it
is returned via the
transport.
Child Elements

grouped together.

are handled.

to the system.


message payloads.

element).

from the component.


Exception Strategy Configuration Reference
Exception Strategy Configuration Reference

This page provides details on the elements you configure for exception strategies. This information is
page. For more information on exception strategies, see Error Handling.
<default-service-exception-strategy ...>
Provide default exception handling for a service via an endpoint.
Attributes
enableNotifications boolean no Determines

whether
ExceptionNotifications
will be fired from
this strategy when
an exception
occurs.
Child Elements
commit-transaction 0..1 Defines when a current

transaction gets committed
based on the name of the
exception caught. You can
set a comma-separated list
of wildcard patterns that will
be matched against the fully
qualified classname of the
current exception. Patterns
defined for this element will
leave the current transaction (if
any) untouched and allow it to
be committed.
rollback-transaction 0..1 Defines when a current

transaction gets rolled back
defined for this element will roll
back the current transaction (if
any).

<default-connector-exception-strategy ...>
Provide default exception handling for a connector via an endpoint.
Attributes

whether
will be fired from
this strategy when
an exception
occurs.
Child Elements

be committed.

any).


<custom-exception-strategy ...>
A user-defined exception strategy.
Attributes

whether
will be fired from
this strategy when
an exception
occurs.

implements the
ExceptionListener
interface. In
addition, if an
'outbound-
endpoint' element
is specified,
it is set as an
"endpoint" bean
property.
Child Elements

be committed.

any).


Filters Configuration Reference
Filters Configuration Reference

[ Filter ] [ Not Filter ] [ And Filter ] [ Or Filter ] [ Wildcard Filter ] [ Expression Filter ] [ Regex Filter ] [
Message Property Filter ] [ Exception Type Filter ] [ Payload Type Filter ] [ Custom Filter ] [ Encryption
Security Filter ] [ Is Xml Filter ] [ Jxpath Filter ] [ Jaxen Filter ]
Filter
A filter that is defined elsewhere (at the global level, or as a Spring bean).
Attributes of <filter...>

filter so that
other elements
can reference it.
Required if the
filter is defined at
the global level.
not boolean no Inverts the filter

condition.
ref name (no spaces) no The name of the

filter to use.
Not Filter
Inverts the enclosed filter. For example, if the filter would normally return true for a specific message, it
will now return false, and vice versa.
Child Elements of <not-filter...>

are handled.
And Filter
Returns true only if all the enclosed filters return true.

Child Elements of <and-filter...>
abstract-filter 2..* A placeholder for filter elements,

are handled.
Or Filter
Returns true if any of the enclosed filters returns true.
Child Elements of <or-filter...>
abstract-filter 2..* A placeholder for filter elements,

are handled.
Wildcard Filter
A filter that matches string messages against wildcards. It performs matches with "", for example,
"jms.events." would catch "jms.events.customer" and "jms.events.receipts". This filter accepts a
comma-separated list of patterns, so more than one filter pattern can be matched for a given argument:
"jms.events., jms.actions." will match "jms.events.system" and "jms.actions" but not "jms.queue".
Expression Filter
A filter that can evaluate a range of expressions. It supports some base expression types such as header,
payload (payload type), regex, and wildcard.
Attributes of <expression-filter...>

filter so that
other elements
can reference it.
Required if the
the global level.

condition.
evaluator header/payload- no The expression

type/exception- evaluator
type/wildcard/ to use. The
regex/ognl/xpath/ expression filter
jxpath/groovy/ supports some
bean/custom types such as
header, payload,

exception,
wildcard, and
regex, that are
built-in filters
not registered
with the
ExpressionEvaluatorManager.
All others are
registered
with the
Where XPath,
bean, and ONGL
are used, the
expression should
be a boolean
expression.
expression string no The expression

that will be
evaluated. This
should always
be a boolean
expression. The
syntax of the
expression will
be determined by
the expression
language being
used.
customEvaluator name (no spaces) no Must be set if

the evaluator is
set to custom.
The custom
evaluator must
be registered
with the
ExpressionEvaluatorManager
if it is to be used
here.
nullReturnsTrue boolean no Whether the filter

should return true
if the specified
expression returns
null.
Regex Filter
A filter that matches string messages against a regular expression. The Java regular expression engine
(java.util.regex.Pattern) is used.
Attributes of <regex-filter...>

filter so that
other elements
can reference it.

Required if the
the global level.

condition.
pattern string no The property

name and
optionally a value
to use when
matching. If the
expression is just
a property name,
the filter will check
that the property
exists. Users can
also use '=' and '!
=' to determine a
specific value for a
property.
Message Property Filter

A filter that matches properties on a message. This can be very useful, as the message properties
represent all the meta information about the message from the underlying transport, so for a message
received over HTTP, you can check for HTTP headers and so forth. The pattern should be expressed as a
key/value pair, such as "propertyName=value". If you want to compare more than one property, you can
use the logic filters for And, Or, and Not expressions. By default, the comparison is case sensitive, which
you can override with the 'caseSensitive' property.
Attributes of <message-property-filter...>

filter so that
other elements
can reference it.
Required if the
the global level.

condition.
pattern string no The property

name and
optionally a value
to use when
matching. If the
expression is just
a property name,
the filter will check
that the property
exists. Users can
also use '=' and '!
=' to determine a
specific value for a
property.

caseSensitive boolean no true If false, the
comparison
ignores case.
Exception Type Filter

A filter that matches the type of an exception.
Attributes of <exception-type-filter...>

filter so that
other elements
can reference it.
Required if the
the global level.

condition.
expectedType class name no The expected

class used in the
comparison.
Payload Type Filter

A filter that matches the type of the payload.
Attributes of <payload-type-filter...>

filter so that
other elements
can reference it.
Required if the
the global level.

condition.
expectedType class name no The expected

class used in the
comparison.
Custom Filter
A user-implemented filter.

Attributes of <custom-filter...>

filter so that
other elements
can reference it.
Required if the
the global level.

condition.

implementation
of the Filter
interface.
Child Elements of <custom-filter...>
Encryption Security Filter

A filter that provides password-based encyption.
Attributes of <encryption-security-filter...>
strategy-ref name (no spaces) no The name of

the encryption
strategy to use.
This should be
configured using
the 'password-
encryption-
strategy' element,
inside a 'security-
manager' element
at the top level.
Is Xml Filter
Accepts XML messages only. Alternatively, you can set the "not" attribute to filter out XML messages.
Jxpath Filter
Filters messages based on XPath expressions using JXPath.

Attributes of <jxpath-filter...>
lenient boolean no true Whether errors

are thrown if the
XPath expression
doesn't exist.
expectedValue string no The expected

value of the
XPath expression
evaluation. If
the expected
value matches the
evaluation, the
filter returns true.
Child Elements of <jxpath-filter...>
namespace 0..* A namespace declaration,

expressed as prefix and uri
attributes. The prefix can then
be used inside the expression.
context-property 0..* A property that will be made

available to the filter context.
Expression Evaluators can be
used to grab these properties
from the message at runtime.
Jaxen Filter
The Jaxen filter allows you to route messages based on XPath expressions. The Jaxen filter is generally
faster than the JXPath filter and should be considered the first choice when using an XPath filter.
Attributes of <jaxen-filter...>
expectedValue string no The expected

value of the
XPath expression
evaluation. If
the expected
value matches the
evaluation, the
filter returns true.
Child Elements of <jaxen-filter...>

namespace 0..* A namespace declaration,
expressed as prefix and uri
attributes. The prefix can then
be used inside the expression.
context-property 0..* A property that wil be made

available to the filter context.
Expression Evaluators can be
used to grab these properties
from the message at runtime.

Global Settings Configuration Reference
Global Settings Configuration Reference

This page provides details on the global settings you configure at the root level of a Mule configuration.
Some of this information is pulled directly from mule.xsd and is cached. If the information appears to
be out of date, refresh the page. For more information on configuration, see XML Configuration. For
information on threading profiles, see Tuning Performance.
<configuration ...>
Specifies defaults and general settings for the Mule instance.
Attributes
defaultSynchronousEndpoints
boolean no false If true, all
requests to
endpoints will wait
for a response.
defaultRemoteSync boolean no false If true, all

requests to
endpoints will wait
for a response
from the remote
service.
defaultSynchronousEventTimeout
string no 10000 The default period
(ms) to wait for
a synchronous
response.
defaultTransactionTimeout string no 30000 The default

timeout (ms)
for transactions.
This can also
be configured
on transactions,
in which case
the transaction
configuration is
used instead of
this default.
Child Elements
default-threading-profile 0..1 The default threading profile,

used by components and by
endpoints for dispatching and

receiving if no more specific
configuration is given.
default-dispatcher-threading- 0..1 The default dispatching

profile threading profile, which modifies
the default-threading-profile
values and is used by endpoints
for dispatching messages.
This can also be configured on
connectors, in which case the
connector configuration is used
instead of this default.
default-receiver-threading- 0..1 The default receiving threading

profile profile, which modifies the
default-threading-profile values
and is used by endpoints for
receiving messages. This
can also be configured on
default-service-threading-profile 0..1 The default service threading

profile, which modifies the
default-threading-profile
and is used by services for
processing messages. This can
also be configured on models
or services, in which case these
configurations will be used
abstract-retry-policy 0..1 The default retry policy, used

by connectors and endpoints.
This can also be configured on
A placeholder for a retry policy


Inbound Router Configuration Reference
Inbound Router Configuration Reference

This page provides details on the elements you configure for inbound routers. This information is pulled
more information on routers, see Using Message Routers.
<idempotent-receiver-router ...>
Ensures that only unique messages are received by a service by checking the unique ID of the
incoming message. Note that the ID used can be generated from the message using an expression
defined in the 'idExpression' attribute. By default, the expression used is '#[message:id]', which
means the underlying endpoint must support unique message IDs for this to work. Otherwise, a
UniqueIdNotSupportedException is thrown.
Attributes
idExpression string no Defines one or

more expressions
to use when
extracting the ID
from the message.
For example, it
would be possible
to combine to
headers as the ID
of the message
to provide
idempotency:
'#[headers:foo,bar]'.
Or, you could
combine the
message ID
with a header:
'#[message:id]-
#[header:foo]'.
If this property
is not set,
'#[message:id]'
will be used by
default.
Child Elements

are handled.

abstract-object-store 0..1 A placeholder for an object store
that can be used by routers to
maintain state.
<idempotent-secure-hash-receiver-router ...>
Ensures that only unique messages are received by a service by calculating the hash of the message
itself using a message digest algorithm. This provides a value with an infinitesimally small chance of a
collision. This can be used to filter message duplicates. Keep in mind that the hash is calculated over
the entire byte array representing the message, so any leading or trailing spaces or extraneous bytes
(like padding) can produce different hash values for the same semantic message content. Care should be
taken to ensure that messages do not contain extraneous bytes. This class is useful when the message
does not support unique identifiers.
Attributes
messageDigestAlgorithm string no The secure

hashing algorithm
to use. If not set,
the default is
SHA-256.
Child Elements

are handled.
abstract-object-store 0..1 A placeholder for an object store

that can be used by routers to
maintain state.
<wire-tap-router ...>
The WireTap inbound router allows you to route certain messages to a different endpoint as well as to the
component.
Attributes
Child Elements
abstract-filter 0..1 A placeholder for

filter elements,
which control
which messages
are handled.

outbound- outbound endpoint
endpoint elements.
Outbound
endpoints dispatch
messages to
the underlying
transport.
<forwarding-router ...>
Allows messages to be forwarded to the outbound routers without first being processed by a component.
Attributes

transformers that
will be applied to
the message (in
order) before it is
delivered to the
component.
transformFirst boolean no true Specifies whether

transformations
are applied before
filtering occurs.
The default is
true.
Child Elements

are handled.

message payloads.
<selective-consumer-router ...>
Applies one or more filters to the incoming message. If the filters match, the message is forwarded to the
component. Otherwise, the message is forwarded to the catch-all strategy on the router. If no catch-all
strategy is configured, the message is ignored and a warning is logged.

Attributes

transformers that
will be applied to
the message (in
order) before it is
delivered to the
component.
transformFirst boolean no true Specifies whether

transformations
are applied before
filtering occurs.
The default is
true.
Child Elements

are handled.

message payloads.
<correlation-resequencer-router ...>
Holds back a group of messages and resequences them using each message's correlation sequence
property.
Attributes
timeout integer no The time (ms)

the router waits
for messages
to complete the
group.
Child Elements

are handled.

<message-chunking-aggregator-router ...>
Combines two or more messages into a single message by matching messages with a given Correlation
ID. Correlation IDs are set on messages when they are dispatched by certain outbound routers, such as
the Recipient List and Message Splitter routers. These messages can be aggregated back together again
using this router.
Attributes

the router waits
for messages
to complete the
group.
Child Elements

are handled.

CorrrelationID.
<custom-correlation-aggregator-router ...>
Configures a custom message aggregator. Mule provides an abstract implementation that has a template
method that performs the message aggregation. A common use of the aggregator router is to combine
the results of multiple requests such as "ask this set of vendors for the best price of X".
Attributes

the router waits
for messages
to complete the
group.

class name of the
custom correlation
aggregator router
to be used.

Child Elements

are handled.

CorrrelationID.
<collection-aggregator-router ...>
Configures a Collection Response Router. This will return a MuleMessageCollection message type that will
contain all messages received for a each correlation group.
Attributes

the router waits
for messages
to complete the
group.
Child Elements

are handled.
<custom-inbound-router ...>
Allows for custom inbound routers to be configured.
Attributes

implementation
of InboundRouter
(fully qualified
Java class name)

Child Elements

are handled.


Model Configuration Reference
Model Configuration Reference

This page provides details on the elements you configure for models. Some of this information is pulled
more information on models, see Models.
<model ...>
The container for a set of services, providing basic settings and processing for all the services it contains.
Attributes
name name no The name used

to identify this
model.
inherit boolean no If true, this model

element is an
extension of a
previous model
element with the
same name.
Child Elements
abstract-exception-strategy 0..1 A placeholder for an exception

strategy element. Exception
strategies define how Mule
should react to errors.
abstract-service 0..* A placeholder for a service

element. Services combine
message routing with a
component (typically a POJO).

until one succeeds.


abstract-queue-profile 0..1 A placeholder for a queue
profile, which controls how
messages are queued.
Queue Profile
Specifies the properties of an internal Mule queue. Internal queues are used to queue messages for each
component managed by Mule.
Attributes of <queue-profile...>
maxOutstandingMessages
integer no Defines the
maximum number
of messages that
can be queued.
persistent boolean no false 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.
Default is false.
Exception Strategy
See Exception Strategy Configuration Reference.
Service
See Service Configuration Reference.
Entry Point Resolver

See Entry Point Resolver Configuration Reference.

Notifications Configuration Reference
Notifications Configuration Reference

This page provides details on the elements you configure for notifications. Some of this information is
page. For more information on notifications, see Mule Server Notifications.
Notifications
Registers listeners for notifications and associates interfaces with particular events.
Attributes of <notifications...>
dynamic boolean no If the notification

manager is
dynamic, listeners
can be registered
dynamically at
runtime via the
MuleContext, and
the configured
notification can
be changed.
Otherwise, some
parts of Mule will
cache notification
configuration
for efficiency
and will not
generate events
for newly enabled
notifications or
listeners. The
default value is
false.
Child Elements of <notifications...>
notification 0..* Associates an event with

an interface. Listeners that
implement the interface will
receive instances of the event.
disable-notification 0..* Blocks the association of

an event with a particular
interface. This filters events
after the association with a
particular interface (and so
takes precedence).

notification-listener 0..* Registers a bean as a listener
with the notification system.
Events are dispatched by
reflection - the listener will
receive all events associated
with any interfaces it
implements. The relationship
between interfaces and events
is configured by the notification
and disable-notification
elements.
Notification
Associates an event with an interface. Listeners that implement the interface will receive instances of the
event.
Attributes of <notification...>
event-class class name no The class

associated with
a notification
event that will
be delivered to
the interface.
This can be used
instead of the
'event' attribute to
specify a custom
class.
event notificationTypes no The notification

event to deliver.
interface-class class name no The interface

(class name) that
will receive the
notification event.
interface notificationTypes no The interface that

will receive the
notification event.
Disable Notification
Blocks the association of an event with a particular interface. This filters events after the association with
a particular interface (and so takes precedence).
Attributes of <disable-notification...>
event-class class name no The class

associated with

an event that
will no longer
be delivered to
any interface.
This can be used
instead of the
'event' attribute to
specify a custom
class.
event notificationTypes no The event you no

longer want to
deliver.
interface-class class name no The interface

(class name) that
will no longer
receive the event.
interface notificationTypes no The interface that

will no longer
receive the event.
Notification Listener
Registers a bean as a listener with the notification system. Events are dispatched by reflection - the
listener will receive all events associated with any interfaces it implements. The relationship between
interfaces and events is configured by the notification and disable-notification elements.
Attributes of <notification-listener...>
ref name (no spaces) no The bean that

will receive
notifications.
subscription string no An optional string

that is compared
with the event
resource identifier.
Only events
with matching
identifiers will be
sent. If no value
is given, all events
are sent.
Notification Types
You can specify the following types of notifications using the event attribute of the <notification> and
<disable-notification> element:
"CONTEXT"
"MODEL"
"SERVICE"
"SECURITY"
"ENDPOINT-MESSAGE"
"COMPONENT-MESSAGE"
"MANAGEMENT"
"CONNECTION"

"REGISTRY"
"CUSTOM"
"EXCEPTION"
"TRANSACTION"
"ROUTING"

Outbound Router Configuration Reference
Outbound Router Configuration Reference

This page provides details on the elements you configure for outbound routers. This information is pulled
directly from the schema files and is cached. If the information appears to be out of date, refresh the
page. For more information on routers, see Using Message Routers.
<pass-through-router ...>
This router always matches and simply sends or dispatches message via the endpoint that is configured.
Attributes
enableCorrelation ALWAYS no IF_NOT_SET Specifies whether

/ NEVER / Mule should
IF_NOT_SET give outgoing
messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
Child Elements
abstract-outbound-endpoint 1..1 A placeholder for outbound

reply-to 0..1 Defines where the message

should be routed after the
recipient of the message to
which this service dispatches
has finished with it.

grouped together.


CorrrelationID.
<filtering-router ...>
Uses filters to determine whether the message matches a particular criteria and if so will route the
message to the endpoint configured on the router.
Attributes

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
Child Elements

abstract-filter 0..1 Filters the messages to be

processed by this router.
A placeholder for filter elements,

are handled.
abstract-transformer 0..* Filters are applied before

message transformations. A
transformer can be configured
here to transform messages
before they are filtered.
A placeholder for transformer

message payloads.


grouped together.

CorrrelationID.
<template-endpoint-router ...>
Allows endpoints to be altered at runtime based on properties set on the current message or fallback
values set on the endpoint properties. Templated values are expressed using square braces around a
property name.
Attributes

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
Child Elements
abstract-outbound-endpoint 1..1 A placeholder for outbound



are handled.


message payloads.


grouped together.

CorrrelationID.
<chaining-router ...>
Sends the message through multiple endpoints using the result of the first invocation as the input for the
next.
Attributes

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't

already have one,
so that existing
correlation IDs are
maintained.
Child Elements



are handled.


message payloads.


grouped together.

CorrrelationID.
<exception-based-router ...>
Sends a message over an endpoint by selecting the first endpoint that can connect to the transport.
Attributes

transformers that
will be applied to

the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
Child Elements



are handled.


message payloads.


grouped together.

CorrrelationID.

<multicasting-router ...>
Sends the same message over multiple endpoints.
Attributes

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
Child Elements



are handled.


message payloads.



grouped together.

CorrrelationID.
<endpoint-selector-router ...>
Selects the outgoing endpoint based on an expression evaluator ("header:endpoint" by default). It will
first try to match the endpoint by name and then by address. The endpoints to use can be set on the
router itself or be global endpoint definitions.
Attributes

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
evaluator groovy / header no The expression

/ headers / evaluator to
headers-list / use. Expression
attachment / evaluators must
attachments / be registered
attachments- with the
list / message / ExpressionEvaluatorManager
map-payload / before they can
payload / xpath be used. Using the
/ jxpath / bean custom evaluator
/ ognl / function allows you to
/ custom define your own
evaluator with the
'custom-evaluator'
attribute. Note

that some
evaluators such as
xpath, groovy, and
bean are loaded
from other Mule
modules (XML
and Scripting,
respectively).
These modules
must be on your
classpath before
the evaluator can
be used.

to evaluate. The
syntax of this
attribute changes
depending on the
evaluator being
used.
custom-evaluator name (no spaces) no The name of

the custom
evaluator to use.
This attribute is
only used when
the 'evaluator'
attribute is set
to "custom". You
can plug in your
own expression
evaluators by
registering
them with the
Child Elements



are handled.


message payloads.


grouped together.

CorrrelationID.
<list-message-splitter-router ...>
Accepts a list of objects that will be routed to different endpoints. The actual endpoint used for each
object in the list is determined by a filter configured on the endpoint itself.
Attributes

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
Child Elements



are handled.


message payloads.


grouped together.

CorrrelationID.
<expression-splitter-router ...>
Splits the message based on an expression. The expression must return one or more message parts in
order to be effective.
Attributes

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't

already have one,
so that existing
correlation IDs are
maintained.

evaluator with the
'custom-evaluator'
attribute. Note
that some
evaluators such as
xpath, groovy, and
bean are loaded
from other Mule
modules (XML
and Scripting,
respectively).
These modules
must be on your
classpath before
the evaluator can
be used.

to evaluate. The
syntax of this
attribute changes
depending on the
evaluator being
used.

the custom
evaluator to use.
This attribute is
only used when
the 'evaluator'
attribute is set
to "custom". You
can plug in your
own expression
evaluators by
registering
them with the

Child Elements



are handled.


message payloads.


grouped together.

CorrrelationID.
Filter Based Splitter

The filter-based splitter router will select the endpoint where you want to send part of a message by
filtering parts using the endpoint filters.
Attributes of <filter-based-splitter...>
splitExpression string no The XPath

expression used to
split the message.
externalSchemaLocation
string no The location of a
schema location
that should be

used to validate
the current
message. This is
not required if the
message contains
the location of the
schema.
validateSchema boolean no Whether to enable

schema validation
when processing
the XML message.
Note that this can
have a serious
performance
hit on high-
throughput
systems.
failIfNoMatch boolean no Whether this

router should
fail if none of
the endpoint
filters match the
payload. The
default is true.
Round Robin Splitter

The round robin message splitter will split a DOM4J document into nodes based on the splitExpression
property. It will then send these document fragments to the list of specified endpoints in a round-
robin fashion. Optionally, you can specify a namespaces property map that contain prefix/namespace
mappings.
Attributes of <round-robin-splitter...>
splitExpression string no The XPath

expression used to
split the message.
externalSchemaLocation
string no The location of a
schema location
that should be
used to validate
the current
message. This is
not required if the
message contains
the location of the
schema.
validateSchema boolean no Whether to enable

schema validation
when processing
the XML message.
Note that this can
have a serious
performance
hit on high-

throughput
systems.
deterministic boolean no If there is no

endpoint filtering
and this attribute
is true (the
default), the first
message part
is routed to the
first endpoint, the
second part routes
to the second
endpoint, and so
on with the nth
part going to the
(n modulo number
of endpoints)
endpoint. If false,
the messages will
be distributed
equally among all
endpoints.
<message-chunking-router ...>
Allows you to split a single message into a number of fixed-length messages that will all be routed to the
same endpoint.
Attributes

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
messageSize integer no The size (bytes)

that fixed-length
message chunks
should have.

numberOfMessages integer no CURRENTLY NOT
SUPPORTED.
Child Elements



are handled.


message payloads.


grouped together.

CorrrelationID.
<static-recipient-list-router ...>
Sends the same message to multiple endpoints over the same endpoint, or implements routing-slip
behavior where the next destination for the message is determined from message properties or the
payload. It uses a static list of recipient endpoints.
Attributes
recipientsProperty string no CURRENTLY NOT

SUPPORTED.

recipientsDelimiter string no CURRENTLY NOT
SUPPORTED.
synchronous boolean no If true, messages

will be sent
synchronously,
and the router
will wait for a
response.

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
Child Elements
recipients 0..1 Static list of recipients that the

outgoing message is sent to.
The default delimiter is ','.


are handled.


message payloads.



grouped together.

CorrrelationID.
<expression-recipient-list-router ...>
Sends the same message to multiple endpoints over the same endpoint, or implements routing-slip
behavior where the next destination for the message is determined from message properties or the
payload. The recipients can be extracted from the message using an expression, or you can specify a
static list of recipient endpoints. (As of version 2.1)
Attributes
synchronous boolean no If true, messages

will be sent
synchronously,
and the router
will wait for a
response.

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is
to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.


evaluator with the
'custom-evaluator'
attribute. Note
that some
evaluators such as
xpath, groovy, and
bean are loaded
from other Mule
modules (XML
and Scripting,
respectively).
These modules
must be on your
classpath before
the evaluator can
be used.

to evaluate. The
syntax of this
attribute changes
depending on the
evaluator being
used.

the custom
evaluator to use.
This attribute is
only used when
the 'evaluator'
attribute is set
to "custom". You
can plug in your
own expression
evaluators by
registering
them with the
Child Elements
recipients 0..1 List of recipient endpoints that

the outgoing message will be
sent to. The default delimiter
is ','. If you do not specify this
attribute, the recipients will be
extracted from the message
itself.


are handled.


message payloads.


grouped together.

CorrrelationID.
<custom-outbound-router ...>
Allows you to configure a custom outbound router by specifying the custom router class and by using
Spring properties.
Attributes

implementation of
OutboundRouter
(fully qualified
Java class name)

transformers that
will be applied to
the message in
order before it is
delivered to the
component.

messages a
correlation ID. The
default behavior is

to give messages
a correlation ID
only if they don't
already have one,
so that existing
correlation IDs are
maintained.
Child Elements



are handled.


message payloads.


grouped together.

CorrrelationID.

Properties Configuration Reference
Properties Configuration Reference

This page provides detailed reference information for property elements in Mule. The information below is
pulled directly from the source code, so it reflects the latest data since you loaded the page. If something
appears to be out of date, you can refresh the page to reload the information.
Global Property
A global property is a named string. It can be inserted in most attribute values using standard (ant-style)
Spring placeholders.
Attributes of <global-property...>
name name (no spaces) no The name of the

property. This is
used inside Spring
placeholders.
value string no The value of

the property.
This replaces
each occurence
of a Spring
placeholder.
Property
Sets a Mule property. This is a name/value pair that can be set on components, services, etc., and which
provide a generic way of configuring the system. Typically, you shouldn't need to use a generic property
like this, since almost all functionality is exposed via dedicated elements. However, it can be useful
in configuring obscure or overlooked options and in configuring transports from the generic endpoint
elements.
Attributes of <property...>
key string no
value string no
value-ref name (no spaces) no
Properties
A map of Mule properties.

Jndi Provider Property
Direct setting of a JNDI property.
Attributes of <jndi-provider-property...>
key string no
value string no
value-ref name (no spaces) no
Jndi Provider Properties

Direct setting of JNDI properties (allows access to the full Spring map entry).

Service Configuration Reference
Service Configuration Reference

This page provides details on the elements you configure for services. This information is pulled directly
from mule.xsd and is cached. If the information appears to be out of date, refresh the page. For more
information on services, see Configuring the Service.
<service ...>
Describes how to receive messages, deliver them to a component, and handle the results (if any).
Attributes

to identify this
service.
initialState started / no started The initial

stopped state of the
/ paused service. Usually a
service is started
automatically
("started"), but
this attribute can
be used to disable
initial startup
("stopped") or
start the service
in a paused state
("paused").
queueTimeout integer no The timeout used

when taking
messages from
the service queue.
Child Elements
description 0..1 This can hold any kind of

documentation related to the
service. It is intended to be
"human readable" only and is
not used by the system.
inbound 0..1 The elements within 'inbound'

describe how a service receives
messages.

abstract-component 0..1 The service component that
is invoked when incoming
messages are received. If this
element is not present, the
service simply bridges the
inbound and outbound using a
pass-through component.
A placeholder for a component

element. A component is
invoked when inbound messages
are received by the service.
outbound 0..1 The elements within 'outbound'

describe how a service sends or
dispatches messages.
async-reply 0..1 The elements within

'async-reply' describe how
asynchronous replies are
handled.

abstract-service-threading- 0..1 A placeholder for the service

profile threading profile element.
Threading profiles define how
thread pools are used by a
service.
abstract-queue-profile 0..1 A placeholder for a queue

profile, which controls how
messages are queued.
<custom-service ...>
A user-implemented service (typically used only in testing).
Attributes

to identify this
service.
initialState started / no started The initial

stopped state of the
/ paused service. Usually a
service is started
automatically
("started"), but
this attribute can
be used to disable
initial startup
("stopped") or
start the service

in a paused state
("paused").
class class name no The class to use

for the service.
Child Elements
description 0..1 This can hold any kind of

documentation related to the
service. It is intended to be
"human readable" only and is
not used by the system.
inbound 0..1 The elements within 'inbound'

describe how a service receives
messages.
abstract-component 0..1 The service component that

is invoked when incoming
messages are received. If this
element is not present, the
service simply bridges the
inbound and outbound using a
pass-through component.
A placeholder for a component

element. A component is
invoked when inbound messages
are received by the service.
outbound 0..1 The elements within 'outbound'

describe how a service sends or
dispatches messages.
async-reply 0..1 The elements within

'async-reply' describe how
asynchronous replies are
handled.

<description ...>
Holds any kind of documentation that accompanies this configuration file. It is intended to be "human
readable" only and is not used by the system.

Attributes
Child Elements
<description ...>
This can hold any kind of documentation related to the service. It is intended to be "human readable"
only and is not used by the system.
Attributes
Child Elements
<inbound ...>
The elements within 'inbound' describe how a service receives messages.
Attributes
matchAll boolean no true If true, the input

message will
be passed to all
inbound routers.
Otherwise, only
the first matching
router is used.
Child Elements

processing.
abstract-inbound-router 0..* A placeholder for inbound router

elements, which control how
incoming messages are handled.

abstract-catch-all-strategy 0..1 A placeholder for catch-all
strategy elements.
<outbound ...>
The elements within 'outbound' describe how a service sends or dispatches messages.
Attributes
matchAll boolean no false If true, the output

message will be
sent to all routers.
Otherwise, only
the first matching
router is used.
Child Elements
abstract-outbound-router 1..* A placeholder for outbound

router elements, which control
how outgoing messages are
delivered to the outbound
endpoints.
abstract-catch-all-strategy 0..1 A placeholder for catch-all

strategy elements.
<async-reply ...>
The elements within 'async-reply' describe how asynchronous replies are handled.
Attributes
timeout integer no The timeout (ms)

to wait for a reply.
failOnTimeout boolean no If the router

times out before
all expected
events have been
received, specifies
whether an
exception should
be thrown (true)
or the current
events should
be returned for
processing (false).

The default is
false.
Child Elements

processing.
abstract-async-reply-router 0..1 A placeholder for an async reply

router element. Asynchronous
replies are handled via this
router.
<queue-profile ...>
Attributes
maxOutstandingMessages integer no Defines the

maximum number
of messages that
can be queued.

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.
Default is false.

Child Elements
Exception Strategy
See Exception Strategy Configuration Reference.
Catch All Strategy

See Catch All Strategy Configuration Reference.
Component
See Component Configuration Reference.

Transactions Configuration Reference
Transactions Configuration Reference

Abstract Transaction
A placeholder for transaction elements. Transactions allow a series of operations to be grouped together.
Attributes of <abstract-transaction...>
action NONE/ no The type of action

ALWAYS_BEGIN/ the transaction
BEGIN_OR_JOIN/ should take, one
ALWAYS_JOIN/ of the following:
JOIN_IF_POSSIBLE NONE - Never
participate in
a transaction.
ALWAYS_BEGIN
- Always start a
new transaction
when receiving
a message. An
exception will
be thrown if
a transaction
already exists.
BEGIN_OR_JOIN
- If a transaction
is already in
progress when
a message is
received, join
the transaction
if possible.
Otherwise, start a
new transaction.
ALWAYS_JOIN -
Always expects a
transaction to be
in progress when
a message is
received. If there
is no transaction,
an exception
is thrown.
JOIN_IF_POSSIBLE
- Join the current
transaction if
one is available.
Otherwise, no
transaction is
created.
timeout integer no Timeout for the

transaction (ms).

Custom Transaction
A user-defined or otherwise unsupported third-party transactions.
Attributes of <custom-transaction...>
action NONE/ no The type of action

ALWAYS_BEGIN/ the transaction
BEGIN_OR_JOIN/ should take, one
ALWAYS_JOIN/ of the following:
JOIN_IF_POSSIBLE NONE - Never
participate in
a transaction.
ALWAYS_BEGIN
- Always start a
new transaction
when receiving
a message. An
exception will
be thrown if
a transaction
already exists.
BEGIN_OR_JOIN
- If a transaction
is already in
progress when
a message is
received, join
the transaction
if possible.
Otherwise, start a
new transaction.
ALWAYS_JOIN -
Always expects a
transaction to be
in progress when
a message is
received. If there
is no transaction,
an exception
is thrown.
JOIN_IF_POSSIBLE
- Join the current
transaction if
one is available.
Otherwise, no
transaction is
created.
timeout integer no Timeout for the

transaction (ms).
factory-class class name no A class that

implements the
TransactionFactory
interface that will
be instantiated
and used to
generate a

transaction. This
attribute and
the 'factory-
ref' attribute
are mutually
exclusive; one
of the two is
required.
factory-ref name (no spaces) no A bean that

implements the
TransactionFactory
interface that
will be used
to generate a
transaction. This
attribute and
the 'factory-
class' attribute
are mutually
exclusive; one
of the two is
required.
Xa Transaction
An XA transaction.
Websphere Transaction Manager

The WebSphere transaction manager.
Attributes of <websphere-transaction-manager...>
name name (no spaces) no transactionManager An optional name

for the transaction
manager. The
default value is
"transactionManager".
Jboss Transaction Manager

The JBoss transaction manager.
Attributes of <jboss-transaction-manager...>

for the transaction
manager. The
default value is

Weblogic Transaction Manager
The WebLogic transaction manager.
Child Elements of <weblogic-transaction-manager...>
environment 0..1 The JNDI environment.
Jrun Transaction Manager

The JRun transaction manager.
Attributes of <jrun-transaction-manager...>

for the transaction
manager. The
default value is
Resin Transaction Manager

The Resin transaction manager.
Attributes of <resin-transaction-manager...>

for the transaction
manager. The
default value is
Jndi Transaction Manager

Retrieves a named transaction manager factory from JNDI.
Attributes of <jndi-transaction-manager...>
jndiName string no The name of

the manager
factory to retrieve

(such as java:/
TransactionManager).
Custom Transaction Manager

A user-implemented transaction manager.
Attributes of <custom-transaction-manager...>
class class name no The class to

instantiate
to create a
transaction
manager.
Child Elements of <custom-transaction-manager...>
environment 0..1 The JNDI environment.

Configuring a Mule Instance
Configuring a Mule Instance

A Mule configuration file can become an elaborate tree of elements, however, the basic things to
configure at the top level are:
• Connectors - Non-default configuration of any transports used

• Endpoints - Global definition of endpoints is encouraged to clearly describe where your integration
channels are
• Transformers - Transformers may be defined globally and later referenced from your services
• Filters - Filters may be defined globally and later referenced from your services
• Models - One or more models that logically group together your services
• Services - One or more services that wrap your components and configure routers, endpoints,
transformers, and filters specifically for that service
Following is an example of a simple Mule configuration file:
mule.xsd
mule-vm.xsd">
<vm:connector name="vmConnector" queueEvents="true" queueTimeout="5000"/>
<vm:endpoint name="CustomerRequests" path="customer.requests"/>

<vm:endpoint name="CustomerResponses" path="customer.responses"/>
<custom-transformer name="ThisToThat" class="com.acme.transformer.ThisToThat"/>
<model name="main">
<service name="myBasicService">
<inbound>
<inbound-endpoint ref="CustomerRequests"/>
</inbound>
<component class="com.acme.service.BasicService"/>
<outbound>
<outbound-endpoint ref="CustomerResponses" transformer-refs="ThisToThat"/>
</outbound>
</service>

</model>
</mule>
Advanced Configuration
Other, more advanced things you may configure at this level:
• Agents - Agents are typically used for cross-cutting concerns such as logging or management
• Notifications - Be notified upon certain lifecycle events
• Security Manager - Authenticates requests based on one or more security providers
• Transaction Management - Mule transactions are configured on inbound endpoints, where an
endpoint can be configured to start a new transaction or join an existing one.
• Global Configuration Options - Miscellaneous global settings
• Global Properties - Placeholder values

Configuring Endpoints
Configuring Endpoints
[ Basic Configuration ] [ Endpoint Usage ] [ Global Endpoints ]
Endpoints are used to connect services. An endpoint is a specific channel on which a service can send
messages and from which another service can receive messages. For example, a purchasing component
may receive an order request over HTTP. Once the order has been processed by the component, a JMS
message may be sent over a topic to notify an auditing system, and a response can be sent back over
HTTP.
This page describes how to configure an endpoint. For details on the various attributes and elements you
can configure on an endpoint, see Endpoint Configuration Reference.
Basic Configuration
In its most basic form, an endpoint consists of a transport and a transport-specific channel/destination/
resource used to identify the channel and location where two services can exchange information. For
example:
<inbound-endpoint address="udp://localhost:65432"/>
<jetty:inbound-endpoint address="http://localhost:60211/mycomponent1" synchronous="true" />
<outbound-endpoint address="smtp://user:secret@smtp.host"/>
<inbound-endpoint address="jms://test.queue"/>
Traditionally, endpoints in Mule have been specified as a URI such as the examples above. This form is
still supported, and indeed may prove to be more practical depending on your application. However, as of
Mule 2.0, the recommended way to specify endpoints is via transport-specific namespaces, as shown in
the following examples.
<file:inbound-endpoint path="./.mule/in"
comparator="org.mule.transport.file.comparator.OlderFirstComparator" reverseOrder="true"/>
<ssl:endpoint name="clientEndpoint" host="localhost" port="60198" synchronous="true"/>
<jetty:endpoint name="serverEndpoint" host="localhost" port="60203" path="services/Foo"
synchronous="false" />
<imaps:endpoint name="global1s" host="localhost" password="secret" port="123" user="bob"/>
<rmi:endpoint name="BadType" host="localhost" port="1099" object="MatchingUMO"
method="reverseString"/>
<quartz:endpoint name="qEP6" repeatCount="10" repeatInterval="1000" jobName="job"/>
<jms:inbound-endpoint queue="test.queue"/>
Properties
Properties on endpoints can be used to customize behavior. Any properties set on the endpoint can
be used to overload default properties on the associated transport's connector. For example, an SMTP
outbound endpoint might set the fromAddress property to workflow1 to override a default connector
value of sysadmin. Any standard properties for an endpoint will be available as attributes in the XML
schema if transport-specific endpoints are used. It is also possible to specify a non-standard property. For
example:


<quartz:endpoint name="qEP6" repeatCount="10" repeatInterval="1000" jobName="job"/>


<quartz:endpoint name="qEP7" jobName="job2">
<property key="actionOnTimeout" value="self-destruct"/>
<property key="precision" value="2.5"/>
</quartz:endpoint>
Connector
In many cases, the connector associated with an endpoint can simply be assumed based on the transport
and created implicitly. However, if more than one connector of the same transport exists, or if non-
default settings are used for the connector, you must refer to the connector from the endpoint using the
connector-ref attribute.
<inbound-endpoint address="tcp://localhost:65432" connector-ref="tcpConnector1"/>

<tcp:inbound-endpoint host="localhost" port="65433" connector-ref="tcpConnector2"/>
Filter
An endpoint can contain a filter to selectively ignore certain messages. The filter can be transport-specific
such as a JMS selector or file filter or can be a general-purpose filter such as JXPath. Filtering is not
supported by all transports, and setting a filter on an endpoint using some transports will result in an
UnsupportedOperationException. For more information, see Using Filters.
<jms:endpoint queue="in.queue">
<jms:selector expression="JMSPriority > 5"/>
</jms:endpoint>
<vm:endpoint name="fruitBowlEndpoint" path="fruitBowlPublishQ">

<message-property-filter pattern="foo=bar"/>
</vm:endpoint>
Transaction
A transaction can begin or commit when an event is received or sent via an endpoint. The endpoint must
be synchronous, and transaction support depends largely on the particular transport being used. For
more information see Transaction Management.
<jms:inbound-endpoint queue="in">
<jms:transaction action="BEGIN_OR_JOIN"/>
Endpoint Usage
Endpoints can be used in the following places:
• Inbound Routers
• Outbound Routers
• Services
• Catch-all Strategies
• Exception Strategies

Inbound Routers
See Using Message Routers.
<service name="Receiver">
<inbound>
<vm:inbound-endpoint path="inbound.channel"/>
<wire-tap-router>
<vm:outbound-endpoint path="tapped.channel"/>
</wire-tap-router>
</inbound>
<component class="com.acme.SomeService"/>
</service>
Outbound Routers
See Using Message Routers.
<service name="MessageChunker">
<inbound>
<jms:inbound-endpoint queue="big.messages"/>
</inbound>
<outbound>
<message-chunking-router messageSize="10">
<jms:outbound-endpoint queue="small.chunks"/>
</message-chunking-router>
</outbound>
</service>
<service name="LenderGatewayService">
<inbound>
<inbound-endpoint ref="LenderGateway" />
</inbound>
<outbound>
<chaining-router>
<outbound-endpoint remoteSync="true" ref="LenderService" />
<outbound-endpoint ref="BankingGateway" transformer-refs="SetLendersAsRecipients
ObjectToJMSMessage" />
</chaining-router>
</outbound>
</service>
Services
As a shortcut, endpoints can be configured directly on the service without a router in some cases.
<service name="Echo">
<inbound>

</inbound>
<echo-component/>
<outbound>

<stdio:outbound-endpoint system="OUT"/>

</outbound>
</service>
Catch-all Strategies
A single "catch-all" endpoint can be configured for certain types of routers. See Using Message Routers.
<service name="dataService">
<inbound>
<inbound-endpoint ref="dataIn">
<payload-type-filter expectedType="java.lang.String"/>
</inbound-endpoint>
<forwarding-catch-all-strategy>
<jms:outbound-endpoint queue="error.queue"/>
</forwarding-catch-all-strategy>
</inbound>
...cut...
</service>
Exception Strategies
A single error endpoint can be configured on an exception strategy. See Error Handling.
<inbound>
...cut...
</inbound>
<component class="com.acme.DataProcessor"/>
<outbound>
...cut...
</outbound>
<default-service-exception-strategy>
</default-service-exception-strategy>
</service>
Global Endpoints
Global endpoints, while not required, are a recommended best practice for having a nicely organized
configuration file. A global endpoint can be thought of as a template for shared endpoint configuration.
Global endpoints can be used as they are defined globally, or they can be extended by adding more
configuration attributes or elements.
To reference a global endpoint, use the usual <inbound-endpoint> and <outbound-endpoint> elements,
and specify the global endpoint name using the ref attribute.
<file:endpoint name="fileReader" reverseOrder="true"

comparator="org.mule.transport.file.comparator.OlderFirstComparator"/>
...cut...
<model>
<service name="Priority1">
<file:inbound-endpoint ref="fileReader" path="/var/prio1"/>
...cut...
</service>

<service name="Priority2">
<file:inbound-endpoint ref="fileReader" path="/var/prio2"/>
...cut...
</service>
</model>
In the above example, the "fileReader" endpoint is used as a template for the inbound endpoints. The
properties reverseOrder and comparator only need to be declared once, and the property path changes
for each inbound endpoint.

Mule Endpoint URIs
Mule Endpoint URIs

Although URI-based endpoints are still supported in Mule 2.0, transport-specific endpoints
are generally recommended instead.
Mule Endpoint URIs are any valid URI and describe how to connect to the underlying transport. Most
connectors in Mule can be created from an endpoint URI except where not enough connection information
can be expressed clearly in a URI, such as JMS connection properties. Endpoint URIs are set on Mule
Endpoints, which manage other connection instance information such as filters and transactions.
Mule Endpoint URIs usually appear in one of the following forms, although other provider
implementations can introduce their own schemes.
scheme://host[:port]//[address][?params]
The scheme must always be set. The host and port are set for endpoints that use unwrapped socket
based communications such as the TCP, UDP, HTTP, or multicast.
udp://localhost:65432
scheme://[username][:password]@host[:port][?params]
The user name and password are used to log in to the remote server specified by the host and port
parameters. The POP3 and SMTP connectors use this format or URI.
pop3://ross:secret@pop3.mycompany.com
smtp://ross:secret@smtp.mycompany.com
scheme://address[?params]
Here we only define a protocol and an address. This tells Mule to get a connector that handles the
specified scheme, or create one if needed, and to create a new endpoint using the specified address.
vm://my.queue
URI Parameters
There are two types of parameters you can set on the URI:
1. Known Mule parameters that control the way the endpoint is configured, such as transformers for
the endpoint.
2. Properties to be set on the connector or to be associated with the transport. This allows you to
set properties on a connector used by this endpoint. Additionally, all properties will be associated
with the transport, so you can mix connector and transport properties. For more information, see
Configuring Endpoints.
Known Parameters
connector The name of an existing connector to use for this

endpoint URI

transformers Defines a comma-separated list of transformers to
configure on the endpoint
address Explicitly sets the endpoint address to the

specified value and ignores all other info in the
URI.
For example:
file:///C:/temp?transformers=FileToString,XmlToDom
jms://jmsEndpoint/topic:my.topic?connector=WMQConnector
Other Parameters
Any other parameters set on the URI will be set on the connector if a connector is created and also set on
the endpoint itself as properties.
Endpoint Encoding
When using XML configuration, certain character entities defined in the W3C SGML specification need
to be escaped to their SGML code. The most relevant are listed here. Don't forget to remove the space
before the ';'.
For characters such as > < " % #, the notation will be resolved and cause the constructor for the URI to
throw an exception. To use one of these characters, you can specify %HEXNUMBER
Text code Numerical code What it looks like Description, extras
%22 #34 " quotation mark =

APL quote, U+0022
ISONEW
&amp ; #38 & ampersand, U+0026

ISOnum
%3C #60 < less-than sign, U+003C

ISOnum
%3E #62 > greater-than sign, U

+003E ISOnum
%25 #37 % percentage sign, U

+0023 ISOnum
%23 #35 # hash sign, U+0025

ISOnum
Additionally, for connectors such as Axis, FTP, and the Email connectors, if your login credentials include
@, you must escape it using %40. For example, instead of these URIs:
axis:http://wsuser@username:password@localhost/services/services/Version?method=getVersion
ftp://username:password@ftpserver
smtp://'sender@mydomain.com':'123456'@mailserver?address=QA
You must use these:
axis:http://wsuser%40username:password%40localhost/services/services/Version?method=getVersion
ftp://username:password%40ftpserver
smtp://'sender%40mydomain.com':'123456'%40mailserver?address=QA

Using Filters
Using Filters
[ Standard Filters ] [ Transport and Module Filters ] [ Creating Custom Filters ]
Filters specify conditions that must be met for a message to be routed to a service. There are several
standard filters that come with Mule that you can use, or you can create your own filters.
You can create a global filter and then reference it from your services. Global filters require the "name"
attribute, whereas filters configured on endpoints or routers do not.


<payload-type-filter name="payloadFilter" expectedType="java.lang.String">
<model>
<service>
<inbound>
<tcp:inbound-endpoint host="locahost" port="1234">

<filter ref="payloadFilter"/>
</tcp:inbound-endpoint>
</inbound>
<echo-component/>
<service>
</model>
For reference to the configuration of each filter, see Filters Configuration Reference.
Standard Filters
Mule includes the following standard filters that you can apply to your routers:
• Payload Type Filter

• Expression Filter
• ° Using JXPath Expressions
° Using OGNL Expressions
• RegEx Filter
• Wildcard Filter
• Exception Type Filter
• Message Property Filter
• Logic Filters
• ° And Filter
° Or Filter
° Not Filter
Payload Type Filter
Checks the class type of the payload object inside a message.
<payload-type-filter expectedType="java.lang.String">

Expression Filter
Evaluates a range of expressions. Use the evaluator attribute to specify the expression evaluator to
use, one of the following: header, payload-type, exception-type, wildcard, regex, ognl, xpath, jxpath,
bean, groovy, or custom. Use the expression attribute to set the actual expression. If the expression
type is xpath, bean, or ognl, the expression should be a boolean. If the expression type is custom, set
the customEvaluator attribute to the name of the custom evaluator, which must be registered with the
ExpressionEvaluatorManager (see Creating Custom Filters). For more information on using expression
evaluators, see Using Expression Evaluators.
Optionally, set the nullReturnsTrue attribute to true if you want to return true whenever the
expression is null.
Using JXPath Expressions
JXPath is an XPath interpreter that can apply XPath expressions to XML DOM objects or any other object
graph. For more information about JXPath, see the JXpath user guide, JXPath tutorial, or XPath tutorial.
<expression-filter evaluator="jxpath" expression="(msg/header/resultcode)='success'">
You can also use the JXPath filter from the XML Module, which supports some additional properties.
Using OGNL Expressions
OGNL is a simple yet very powerful expression language for plain Java objects. Similar to JXPath, it
works on object graphs, and thus the corresponding filter enables simple and efficient content routing for
payloads. For example:
<expression-filter evaluator="ognl" expression="[MULE:0].equals(42)"/>
or more simply:
<ognl-filter expression="[MULE:0].equals(42)"/>
This filter would block any messages whose payloads are not arrays or lists and do not contain the value
42 as the first element.
RegEx Filter
Applies a regular expression pattern to the message payload. The filter applies toString() to the
payload, so you might also want to apply a PayloadTypeFilter to the message using an AndFilter to make
sure the payload is a String.
<regex-filter pattern="the quick brown (.*)"/>
Wildcard Filter
Applies a wildcard pattern to the message payload. The filter applies toString() to the payload, so you
might also want to apply a PayloadTypeFilter to the message using an AndFilter to make sure the payload
is a String.

For the string "the quick brown fox jumped over the lazy dog", the following patterns would match:
• *x jumped over the lazy dog

• the quick*
• *fox*
<wildcard-filter pattern="the quick brown *"/>
Exception Type Filter
A filter that matches an exception type.
<exception-type-filter expectedType="java.lang.RuntimeException"/>
Message Property Filter
This filter allows you add logic to your routers based on the value of one or more properties of a
message. This filter can be very powerful because the message properties are exposed, allowing you to
reference any transport-specific or user-defined property. For example, you can match one or more HTTP
headers for an HTTP event, match properties in JMS and email messages, and more.
By default, the comparison is case sensitive. You can set the caseSensitive attribute to override this
behavior.
<message-property-filter pattern="Content-Type=text/xml" caseSensitive="false"/>
The expression is always a key value pair. If you want to use more complex expressions, you can use the
logic filters. The following example shows two filters :
<and-filter>
<message-property-filter pattern="JMSCorrelationID=1234567890"/>
<message-property-filter pattern="JMSReplyTo=null"/>
</and-filter>
Logic Filters
There are three logic filters that can be used with other filters: And, Or, and Not. Logic filters can be
nested so that more complex logic can be expressed.
And Filter
An And filter combines two filters and only accepts the message if it matches the criteria of both filters.
<and-filter>

</and-filter>
Or Filter
The Or filter considers two filters and accepts the message if it matches the criteria of either one of the
filters.
<or-filter>
<payload-type-filter expectedType="java.lang.StringBuffer"/>
</or-filter>
Not Filter
A Not filter accepts the message if it does not match the criteria in the filter.
<not-filter>
</not-filter>
Transport and Module Filters

Several Mule transports and modules provide their own filters. For example, the XML Module includes a
filter to determine if a message is XML. For more information, see Available Transports and Using Mule
Modules. Also, there are filters on MuleForge that have been contributed by the community.
Creating Custom Filters

The standard filters handle most filtering requirements, but you can also create your own filter. To create
a filter, implement the Filter interface , which has a single method:
public boolean accept(MuleMessage message);
This method returns true if the message matches the criteria that the filter imposes. Otherwise, it returns
false.
You can then use this filter with the <custom-filter...> element, using the class attribute to specify
the custom filter class you created and specifying any necessary properties using the <spring:property>
child element. For example:
<outbound>
<filtering-router>
<cxf:outbound-endpoint address="http://localhost:65071/services/EnterOrder?method=create"
synchronous="true"/>
<custom-filter class="org.mule.transport.http.filters.HttpRequestWildcardFilter">
<spring:property name="pattern" value="/services/EnterOrder?wsdl"/>
</custom-filter>
</filtering-router>

</outbound>

You can configure a transport in the following ways:
• Define a connector configuration using the <connector> element in the Mule XML configuration file.
• Set transport properties on endpoints to customize the transport behavior for a single endpoint
instance.
• Use an endpoint URI that defines the scheme and connection information for the transport, such
as tcp://localhost:12345. See Mule Endpoint URIs for more information. The URI consists of the
protocol followed by transport-specific information, and then zero or more parameters to set as
properties on the connector.
This page describes the common properties for all transports. The actual configuration parameters for
each transport type are described separately for each transport. To see the details of a specific transport,
see Available Transports.
Common Connector Attributes and Properties
Attribute Description Required
name The identifying name of the Yes

connector
createMultipleTransactedReceivers Whether to create multiple No

concurrent receivers for this
connector. This property is
used by transports that support
transactions, specifically
receivers that extend the
TransactedPollingMessageReceiver,
and provides better throughput.
numberOfConcurrentTransactedReceivers
If No
createMultipleTransactedReceivers
is set to true, the number of
concurrent receivers that will be
launched.
dynamicNotification Whether to enable dynamic No

notification.
abstract-exception- The exception strategy The default exception No

strategy to use when errors strategy set on the
occur in the connector. Mule Configuration.
receiver-threading- The threading The default receiver Yes

profile properties and threading profile set on
WorkManager to use the Mule Configuration
when receiving events
from the connector.

dispatcher-threading- The threading The default dispatcher Yes
profile properties and threading profile set on
WorkManager to use the Mule Configuration.
when dispatching
events from the
connector.
connection-strategy The object responsible org.mule.transport. Yes

for controlling how SingleAttemptConnectionStrategy
connection failures and
retries are handled.
The connection strategy
can attempt to make
a connection based
on frequency, retry
attempts, Jmx, or some
other trigger. NOTE:
this feature is not yet
available for 2.0.
service-overrides A map of service No

configuration values
that can be used to
override the default
configuration for this
transport.
Retry Policies
Retry policies are used to configure how a connector behaves when its connection fails. For complete
information, see Configuring Retry Policies.
Creating Your Own Transport

For information on creating a custom transport for Mule, see Creating Transports.
Detailed Configuration Information

• Threading profiles
° Receiver threading profile
° Dispatcher threading profile
• Service overrides
Receiver Threading Profile

The threading profile to use when a connector receives messages.
Attributes of <receiver-threading-profile...>
maxThreadsActive integer no The maximum

number of threads
that will be used.

maxThreadsIdle integer no The maximum
number of idle or
inactive threads
that can be in the
pool before they
are destroyed.
threadTTL integer no Determines how

long an inactive
thread is kept in
the pool before
being discarded.
poolExhaustedAction WAIT/DISCARD/ no When the

DISCARD_OLDEST/ maximum pool
ABORT/RUN size or queue size
is bounded, this
value determines
how to handle
incoming tasks.
Possible values
are: WAIT
(wait until a
thread becomes
available; don't
use this value
if the minimum
number of threads
is zero, in which
case a thread
may never
become available),
DISCARD
(throw away the
current request
and return),
DISCARD_OLDEST
(throw away the
oldest request
and return),
ABORT (throw a
RuntimeException),
and RUN (the
default; the
thread making the
execute request
runs the task
itself, which helps
guard against
lockup).
threadWaitTimeout integer no How long to wait

in milliseconds
when the pool
exhausted
action is WAIT.
If the value is
negative, it will
wait indefinitely.
doThreading boolean no true Whether threading

should be used
(default is true).

maxBufferSize integer no Determines how
many requests
are queued when
the pool is at
maximum usage
capacity and the
pool exhausted
action is WAIT.
The buffer is used
as an overflow.
Dispatcher Threading Profile

The threading profile to use when a connector dispatches messages.
Attributes of <dispatcher-threading-profile...>

number of threads
that will be used.

number of idle or
inactive threads
that can be in the
pool before they
are destroyed.

long an inactive
thread is kept in
the pool before
being discarded.

is bounded, this
value determines
how to handle
incoming tasks.
Possible values
are: WAIT
(wait until a
thread becomes
available; don't
use this value
if the minimum
number of threads
is zero, in which
case a thread
may never
become available),
DISCARD
(throw away the
current request
and return),
DISCARD_OLDEST

(throw away the
oldest request
and return),
ABORT (throw a
RuntimeException),
and RUN (the
default; the
thread making the
execute request
runs the task
itself, which helps
guard against
lockup).

in milliseconds
when the pool
exhausted
action is WAIT.
If the value is
negative, it will
wait indefinitely.

should be used
(default is true).

many requests
are queued when
the pool is at
maximum usage
capacity and the
pool exhausted
action is WAIT.
The buffer is used
as an overflow.
Service Overrides
Service overrides allow the connector to be further configured/customized by allowing parts of
the transport implementation to be overridden, for example, the message receiver or dispatcher
implementation, or the message adaptor that is used.
Attributes of <service-overrides...>
messageReceiver name (no spaces) no
transactedMessageReceiver
name (no spaces) no
xaTransactedMessageReceiver
name (no spaces) no
dispatcherFactory name (no spaces) no
inboundTransformer name (no spaces) no
outboundTransformername (no spaces) no

responseTransformer name (no spaces) no
endpointBuilder name (no spaces) no
messageAdapter name (no spaces) no
streamMessageAdapter
name (no spaces) no
serviceFinder name (no spaces) no
sessionHandler name (no spaces) no

Configuring Retry Policies
Configuring Retry Policies
[ Configuring Retry Policies with the Retry Schema ] [ Simple Policy ] [ Forever Policy ] [ Custom
Policy ] [ Connect Notifier ] [ Custom Notifier ] [ Creating a Custom Retry Policy ] [ Configuring Retry
Policies with the Spring Schema ]
Retry policies configure how a connector behaves when its connection fails. Different policies can be used
to control how a reconnection is made based on type of exception, number and/or frequency of retry
attempts, notifications, and more. Retry policies are available for JMS connectors as of Mule 2.1 (as of
Mule 2.1.2, it has been officially tested with Active MQ only).
If you are using the Enterprise Edition of Mule, there are several standard retry policies available that you
can configure using the Retry schema. If you are using the Community Edition of Mule, you must create
your own policies and configure them using standard Spring syntax rather than the Retry schema.
Configuring Retry Policies with the Retry Schema

This section describes the retry policies you can configure directly in your XML by including the mule-
retry-ee.xsd schema. You import the schema as follows:
xmlns:retry="http://www.mulesource.com/schema/mule/retry/2.1"
mule.xsd
http://www.mulesource.com/schema/mule/retry/2.1 http://www.mulesource.com/schema/mule/retry/2.1/
mule-retry-ee.xsd">
Simple Policy
This policy allows the user to configure how many times a retry should
be attempted and how long to wait between retries.
Attributes of <simple-policy...>
frequency long no 2000 How often (in ms)

to retry
count integer no 2 How many retry

attempts to make
For example:
<jms:activemq-connector name="AMQConnector" brokerURL="tcp://localhost:61616" specification="1.1"

durable="true" clientId="C1"
numberOfConcurrentTransactedReceivers="1" maxRedelivery="-1" persistentDelivery="true">

<retry:simple-policy count="5" frequency="1000"/>
</jms:activemq-connector>
Forever Policy
Retry an infinite amount of times at the specified frequency.
Attributes of <forever-policy...>
frequency long no 2000 How often (in ms)

to retry
For example (most of the connector information is truncated as ...):
<jms:activemq-connector name="AMQConnector" ...>

<retry:forever-policy frequency="5000"/>
Custom Policy
A user-defined retry policy.
Attributes of <custom-policy...>

implements the
RetryPolicyTemplate
interface.
Child Elements of <custom-policy...>
For example:

<retry:custom-policy class="org.mule.retry.test.TestRetryPolicyTemplate">
<spring:property name="fooBar" value="true"/>
<spring:property name="revolutions" value="500"/>
</retry:custom-policy>

Asynchronous Retry (As of Mule 2.2)
By default, a retry policy will block until it is able to connect/reconnect. Enabling asynchronous retry
means the application does not need to wait for all endpoints to connect before it can start up, and if a
connection is lost, the reconnection will happen in a separate thread from the application thread. Note
that such behavior may or may not be desirable depending on your application.
Any retry policy can be made asynchronous by simply setting the attribute asynchronous="true". For
example:

<retry:simple-policy frequency="3000" asynchronous="true" />
Transactions
If transactions are properly configured, any messages being routed by Mule at the time a retry policy
goes into effect will not be dropped. Instead, the transaction will roll back and only commit once the
transport finally reconnects successfully via the retry policy.
Retry Notifiers
A retry notifier is called upon each retry attempt and is also configurable.
Connect Notifier
Fires a ConnectionNotification upon each retry attempt.
For example:

<retry:simple-policy>
<retry:connect-notifier/>
</retry:simple-policy>
Custom Notifier
A user-defined retry notifier.
Attributes of <custom-notifier...>

implements the
RetryNotifier
interface.

Child Elements of <custom-notifier...>
For example:

<retry:simple-policy>
<retry:custom-notifier class="org.mule.retry.test.TestRetryNotifier">
<spring:property name="color" value="red"/>
</retry:custom-notifier>
</retry:simple-policy>
Configuring Separate Connectors for Inbound and Outbound
The retry policy for a connector is used for both inbound and outbound connections. If you require
a different behavior for inbound and outbound connections, you can achieve this by configuring two
connectors with the different policies and reference them from the inbound and outbound endpoints,
respectively.
Default Retry Policy
The default retry policy is used for any connector that does not have retry explicitly configured. You can
set the default policy using the <configuration> element:
<configuration>
<retry:simple-policy count="3"/>
</configuration>
Creating a Custom Retry Policy

To create a custom retry policy, you implement the interface RetryPolicy , where the method
PolicyStatus applyPolicy(Throwable cause) takes some action based on the type of exception
and returns PolicyStatus to indicate whether the policy has been exhausted or should continue to retry.
You also create a RetryPolicyTemplate , which is what you actually configure on the connector. The
template should generally inherit from AbstractPolicyTemplate and have the method RetryPolicy
createRetryInstance() return an instance of your custom RetryPolicy. At runtime, a new instance
of the RetryPolicy will be created each time the policy goes into effect, thereby resetting any state
information it may contain, such as counters.
For example:
package com.acme.retry;
public class AstronomicalRetryPolicyTemplate extends AbstractPolicyTemplate

{
int totalPlanets;
public RetryPolicy createRetryInstance()

{
return new AstronomicalRetryPolicy(totalPlanets);
}
protected static class AstronomicalRetryPolicy implements RetryPolicy

{
int totalPlanets;
public AstronomicalRetryPolicy(int totalPlanets) { this.totalPlanets = totalPlanets; }
public PolicyStatus applyPolicy(Throwable cause)

{
if (AstronomyUtils.getPlanetsAligned() == totalPlanets)
{
return PolicyStatus.policyExhausted(cause);
}
else
{
Thread.sleep(5000);
return PolicyStatus.policyOk();
}
}
}
public int getTotalPlanets() { return totalPlanets; }

public void setTotalPlanets(int totalPlanets) { this.totalPlanets = totalPlanets; }
}
Configuring Retry Policies with the Spring Schema

Because the retry schema is available in Mule Enterprise Edition only, Mule Community users must use
standard Spring syntax for configuring a custom retry policy. For example:

<spring:property name="retryPolicyTemplate">
<spring:bean class="com.acme.retry.AstronomicalRetryPolicyTemplate">
<spring:property name="totalPlanets" value="8"/>
</spring:bean>
</spring:property>

Configuring Logging
Configuring Logging
[ Troubleshooting Logging ] [ Controlling Logging from JMX ]
For logging, Mule uses slf4j, which is a logging facade that discovers and uses a logging strategy from the
classpath, such as Log4J or the JDK Logger. By default, Mule includes Log4J, which is configured with a
file called log4j.properties.
The Mule server has a log4j.properties in its conf directory, which you can customize when running
the server in standalone mode. Additionally, all the examples included with Mule have log4j.properties
files in their conf directories.
Troubleshooting Logging
I don't see any logging output
A log4j.properties file must be at the root of your classpath. If you don't have a log4j.properties
file, you can get a simple one here. For more information about configuring Log4J, see their website.
I reconfigured Log4J, but nothing happened
This happens because there is another log4j.properties file on your classpath that is getting picked up
before your modified one. To find out which configuration file Log4J is using, you must add the following
JVM parameter to the Mule startup script (or container startup script if you are embedding Mule):
-Dlog4j.debug=true
This parameter will write the Log4J startup information, including the location of the configuration file
being used, to stdout. You must remove that configuration file before your modified configuration will
work.
I don't want to use Log4J
You can remove Log4J by deleting log4j-xx.jar from your Mule classpath. You will then need to check
that the logging system you are using is supported by slf4j and put the necessary JAR (unless using
JDK1.4 Logger) and configuration files on the Mule classpath.
Controlling Logging from JMX

You can expose a manager's logging configuration over JMX by configuring a Log4J Jmx agent in your
Mule configuration file. See JMX Management for more information.

Configuring Queues
Configuring Queues
[ SEDA Service Queues ] [ Transport Queues ] [ Queue Configuration ] [ Queue Profile ]
Mule uses queues to enable asynchronous message processing. This page describes the places where
Mule uses queues and how to configure them. Note that you can use Mule HQ to monitor your queues
and see historically how many messages they have contained. For more information, see Using Mule HQ.
SEDA Service Queues

When requests come in to a SEDA service (the default model type), they are stored on a queue until
threads from the component thread pool can pick them up and process them. The queue profile specifies
how this queue behaves. Typically, you do not need to configure the queue profile for performance, as the
endpoints or the component, and not the queue, are the usual bottleneck. However, you might want to
specify the maximum queue size, or specify that you want to enable persistence on the queue (disabled
by default) to store a copy of all messages processed by the component.
When a SEDA service is stopped either by calling stop() on the service or by shutting down Mule,
all messages still in the queue are processed before the service completes the stop phase if a non-
persistent queue is being used. If a persistent queue is being used, Mule will complete the processing of
any messages that are currently being processed but will not take any new messages from the queue
once the service has been requested to stop. Once the service or Mule is restarted, any messages in the
persistent queue will be processed.
Note: If a SEDA service is paused when stop() is called, and a non-persistent queue is being used, all
messages pending processing in the queue will be lost.
By using persistent SEDA queues and using transports that support persistence for any message channels
that Mule uses internally, you can easily achieve graceful shutdown. Although message loss shouldn't
occur if you design your system using these guidelines, if messages are absolutely critical, you should be
using synchronous endpoints with transactions.
Transport Queues
Transports may also uses queues internally to enable asynchronous message delivery. Often this is
inherent in the transport implementation, such as with JMS, whereas the Mule VM Transport allows you to
enable or disable queuing and to configure the queue.
Queue Configuration
You configure the queue profile using the <queue-profile> element on the model and/or services,
where services inherit the queue configuration from the model but override it if a <queue-profile> is
configured explicitly on a service.
Queue Profile
Attributes of <queue-profile...>

maxOutstandingMessages
integer no Defines the
maximum number
of messages that
can be queued.

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.
Default is false.
Persistence Strategies
By default, Mule use two persistence strategies:
• MemoryPersistenceStrategy : a volatile in-memory persistence strategy

• FilePersistenceStrategy : uses a file store to persist messages to disk and maintains messages even
if Mule is restarted.
You specify the persistence strategy to use by setting the persistent attribute of the queue-profile.
If set to true, the FilePersistenceStrategy is used, and if false, the MemoryPersistenceStrategy is
used.
Currently, you cannot configure alternative persistence strategies as part of the typed Mule XML
configuration. However, if you need to change them, such as to persist to a database instead of disk, you
can override the defaults in mule-default-config.xml by redefining the _muleQueueManager bean in
your own configuration file. Custom persistence strategies must implement QueuePersistenceStrategy .

Configuring Security
Configuring Security
Mule allows you to authenticate requests via endpoints using transport-specific or generic authentication
methods. It also allows you to control method-level authorization on your service components. The
Security Manager is responsible for authenticating requests based on one or more security providers. All
security is pluggable via the Mule security API , so you can easily plug in custom implementations.
Acegi
Acegi provides a number of authentication and authorization providers such as JAAS, LDAP, CAS (Yale
Central Authenication service), and DAO. The following topics will help you get started securing your
services using Acegi:
• Configuring the Acegi Security Manager

• Component Authorization Using Acegi
• Setting up LDAP Provider for Acegi
Spring Security 2.0 (As of Mule 2.2+)

Spring Security is the next version of Acegi and provides a number of authentication and authorization
providers such as JAAS, LDAP, CAS (Yale Central Authenication service), and DAO. The following topics
will help you get started securing your services using Acegi:
• Configuring the Spring Security Manager

• Component Authorization Using Spring Security
• Setting up LDAP Provider for Spring Security
Other Security Integration

Mule also supports the following security technologies:
• Encryption Strategies - Secure your messages by encrypting them.

• PGP Security - Secure your messages by encrypting them with PGP.
• Jaas Security

Component Authorization Using Acegi
Component Authorization Using Acegi

[ Securing Services Components ] [ Setting Security Properties on the Security Provider ]
This page describes how you can configure method-level authorization on your components so that users
with different roles can only invoke certain service methods.
Securing Services Components

To secure MethodInvocations, developers must add a properly configured MethodSecurityInterceptor
into the application context. The beans requiring security are chained into the interceptor. This chaining
is accomplished using Spring's ProxyFactoryBean or BeanNameAutoProxyCreator. Alternatively,
Acegi security provides a MethodDefinitionSourceAdvisor, which you can use with Spring's
DefaultAdvisorAutoProxyCreator to automatically chain the security interceptor in front of any beans
defined against the MethodSecurityInterceptor.
In addition to the daoAuthenticationProvider and inMemoryDaoImpl beans (see Configuring Security},

the following beans must be configured:
• MethodSecurityInterceptor
• AuthenticationManager
• AccessDecisionManager
• AutoProxyCreator
• RoleVoter
The MethodSecurityInterceptor
The MethodSecurityInterceptor is configured with a reference to an:
Following is a security interceptor for intercepting calls made to the methods of a component that has an
interface myComponentIfc, which defines two methods: delete and writeSomething. Roles are set on
these methods as seen below in the property objectDefinitionSource.
xmlns:acegi="http://www.mulesource.org/schema/mule/acegi/2.2"
...cut...
<bean id="myComponentSecurity"
class="org.acegisecurity.intercept.method.aopalliance.MethodSecurityInterceptor">
<property name="authenticationManager" ref="authenticationManager"/>
<property name="accessDecisionManager" ref="accessDecisionManager"/>
<property name="objectDefinitionSource">
<value>
com.foo.myComponentIfc.delete=ROLE_ADMIN
com.foo.myComponentIfc.writeSomething=ROLE_ANONYMOUS
</value>
</property>
</bean>

The AuthenticationManager
An AuthenticationManager is responsible for passing requests through a chain of

AuthenticationProvider objects.
<bean id="authenticationManager" class='org.acegisecurity.providers.ProviderManager'>

<property name= "providers">
<list>
<ref local="daoAuthenticationProvider"/>
</list>
</property>
</bean>
The AccessDecisionManager
This bean specifies that a user can access the protected methods if they have any one of the roles
specified in the objectDefinitionSource.
<bean id="accessDecisionManager" class='org.acegisecurity.vote.AffirmativeBased'>

<property name="decisionVoters">
<list>
<ref bean="roleVoter"/>
</list>
</property>
</bean>
The AutoProxyCreator
This bean defines a proxy for the protected bean. When an application asks Spring for a myComponent
bean, it will get this proxy instead.
<bean id="autoProxyCreator"
class="org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator">
<property name="interceptorNames">
<list>
<value>myComponentSecurity</value>
</list>
</property>
<property name="beanNames">
<list>
<value>myComponent</value>
</list>
</property>
<property name='proxyTargetClass' value="true"/>
</bean>
When using BeanNameAutoProxyCreator to create the required proxy for security, the configuration
must contain the property proxyTargetClass set to true. Otherwise, the method passed to
MethodSecurityInterceptor.invoke is the proxy's caller, not the proxy's target.
The RoleVoter
The RoleVoter class will vote if any ConfigAttribute begins with ROLE_. The RoleVoter is case
sensitive on comparisons as well as the ROLE_ prefix.

• It will vote to grant access if there is a GrantedAuthority, which returns a String representation
(via the getAuthority() method) exactly equal to one or more ConfigAttributes starting with
ROLE.
• If there is no exact match of any ConfigAttribute starting with ROLE_, the RoleVoter will vote to
deny access.
• If no ConfigAttribute begins with ROLE_, the voter will abstain.
<bean id="roleVoter" class="org.acegisecurity.vote.RoleVoter"/>
Setting Security Properties on the Security Provider

You can add any additional properties to the security provider in the securityProperties map. For
example, this map can be used to change Acegi's default security strategy into one of the following:
• MODE_THREADLOCAL, which allows the authentication to be set on the current thread (this is the
default strategy used by Acegi)
• MODE_INHERITABLETHREADLOCAL, which allows authentication to be inherited from the parent thread
• MODE_GLOBAL, which allows the authentication to be set on all threads
Securing Components in Asynchronous Systems
The use of Acegi's security strategies is particularly useful when using an asynchronous system, since we
have to add a property on the security provider for the authentication to be set on more than one thread.
In this case, we would use MODE_GLOBAL as seen in the example below.
<acegi:security-manager>
<acegi:delegate-security-provider name="memory-dao" delegate-ref="daoAuthenticationProvider">
<acegi:security-property name="securityMode" value="MODE_GLOBAL"/>
</acegi:delegate-security-provider>
</acegi:security-manager>

Component Authorization Using Spring Security
Component Authorization Using Spring

Security
[ Securing Service Components ] [ Setting Security Properties on the Security Provider ]
This feature requires Mule 2.2, which is currently available as a snapshot only
This page describes how you can configure method-level authorization using Spring Security on your
components so that users with different roles can only invoke certain service methods.
Securing Service Components

To secure MethodInvocations, you must add a properly configured MethodSecurityInterceptor into
the application context. The beans requiring security are chained into the interceptor. This chaining
is accomplished using Spring's ProxyFactoryBean or BeanNameAutoProxyCreator. Alternatively,
Acegi Security provides a MethodDefinitionSourceAdvisor, which you can use with Spring's
DefaultAdvisorAutoProxyCreator to automatically chain the security interceptor in front of any beans
defined against the MethodSecurityInterceptor.
In addition to the daoAuthenticationProvider and inMemoryDaoImpl beans (see Configuring Security},

the following beans must be configured:
• MethodSecurityInterceptor
• AutoProxyCreator
• RoleVoter
The MethodSecurityInterceptor
The MethodSecurityInterceptor is configured with a reference to the following:
Following is a security interceptor for intercepting calls made to the methods of a component that has an
interface myComponentIfc, which defines two methods: delete and writeSomething. Roles are set on
these methods as seen below in the property objectDefinitionSource.
xmlns:mule-ss="http://www.mulesource.org/schema/mule/spring-security/2.2"
...cut...
<bean id="myComponentSecurity"
class="org.springframework.security.intercept.method.aopalliance.MethodSecurityInterceptor">
<property name="authenticationManager" ref="authenticationManager"/>
<property name="accessDecisionManager" ref="accessDecisionManager"/>
<property name="objectDefinitionSource">
<value>
com.foo.myComponentIfc.delete=ROLE_ADMIN
com.foo.myComponentIfc.writeSomething=ROLE_ANONYMOUS
</value>
</property>

</bean>
The AuthenticationManager
This bean is responsible for passing requests through a chain of AuthenticationProvider objects.
<bean id="authenticationManager" class="org.springframework.security.providers.ProviderManager">

<property name= "providers">
<list>
<ref local="daoAuthenticationProvider"/>
</list>
</property>
</bean>
The AccessDecisionManager
This bean specifies that a user can access the protected methods if they have any one of the roles
specified in the objectDefinitionSource.
<bean id="accessDecisionManager" class='org.springframework.security.vote.AffirmativeBased'>

<property name="decisionVoters">
<list>
<ref bean="roleVoter"/>
</list>
</property>
</bean>
The AutoProxyCreator
This bean defines a proxy for the protected bean. When an application asks Spring for a myComponent
bean, it will get this proxy instead.
<bean id="autoProxyCreator"
class="org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator">
<property name="interceptorNames">
<list>
<value>myComponentSecurity</value>
</list>
</property>
<property name="beanNames">
<list>
<value>myComponent</value>
</list>
</property>
<property name='proxyTargetClass' value="true"/>
</bean>
When using BeanNameAutoProxyCreator to create the required proxy for security, the configuration
must contain the property proxyTargetClass set to true. Otherwise, the method passed to
MethodSecurityInterceptor.invoke is the proxy's caller, not the proxy's target.

The RoleVoter
The RoleVoter class will vote if any ConfigAttribute begins with ROLE_. The RoleVoter is case
sensitive on comparisons as well as the ROLE_ prefix.
• It will vote to grant access if there is a GrantedAuthority, which returns a String representation
(via the getAuthority() method) exactly equal to one or more ConfigAttribute objects starting
with ROLE.
• If there is no exact match of any ConfigAttribute starting with ROLE_, the RoleVoter will vote to
deny access.
• If no ConfigAttribute begins with ROLE_, the voter will abstain.
<bean id="roleVoter" class="org.springframework.security.vote.RoleVoter"/>
Setting Security Properties on the Security Provider

You can add any additional properties to the security provider in the securityProperties map. For
example, this map can be used to change Acegi's default security strategy into one of the following:
• MODE_THREADLOCAL: allows the authentication to be set on the current thread (this is the default
strategy used by Acegi)
• MODE_INHERITABLETHREADLOCAL: allows authentication to be inherited from the parent thread
• MODE_GLOBAL: allows the authentication to be set on all threads
Securing Components in Asynchronous Systems
The use of Acegi's security strategies is particularly useful for asynchronous systems, since we have to
add a property on the security provider for the authentication to be set on more than one thread. In this
case, we would use MODE_GLOBAL as shown in the following example:
<mule-ss:security-manager>
<mule-ss:delegate-security-provider name="memory-dao" delegate-ref="authenticationManager">
<mule-ss::security-property name="securityMode" value="MODE_GLOBAL"/>
</mule-ss::delegate-security-provider>
</mule-ss:security-manager>

Configuring the Acegi Security Manager
Configuring the Acegi Security Manager

The Mule Acegi security manager implementation delegates to Acegi to provide authorization and
authentication functions. You can use any of the Acegi security providers such as JAAS, LDAP, CAS (Yale
Central Authenication service), and DAO.
Example Configuration
The following example illustrates how to configure a single security provider on Mule, in this case an
in-memory DAO. Here we have a static DAO security provider that allows user credentials to be set in
memory with two users: ross and anon.
...cut...
<spring:bean id="inMemoryDaoImpl" class="org.acegisecurity.userdetails.memory.InMemoryDaoImpl">

<spring:property name="userMap">
<spring:value>
ross=ross,ROLE_ADMIN
anon=anon,ROLE_ANONYMOUS
</spring:value>
</spring:property>
</spring:bean>
<spring:bean id="daoAuthenticationProvider"
class="org.acegisecurity.providers.dao.DaoAuthenticationProvider">
<spring:property name="userDetailsService" ref="inMemoryDaoImpl"/>
</spring:bean>
<acegi:delegate-security-provider name="memory-dao" delegate-ref="daoAuthenticationProvider"/>
...cut...
</mule>
Security Filters
Security filters can be configured on an object to either authenticate inbound requests or attach
credentials to outbound requests. For example, to configure an HTTP basic authorization filter on an HTTP
endpoint, you would use the following endpoint security filter:
<acegi:http-security-filter realm="mule-realm"/>
</inbound-endpoint>
When a request is received, the authentication header will be read from the request and authenticated
against all security providers on the Security Manager. If you only want to validate on certain ones, you
can supply a comma-separated list of security provider names.

<acegi:http-security-filter realm="mule-realm" securityProviders="default,another"/>
</inbound-endpoint>

Configuring the Spring Security Manager
Configuring the Spring Security Manager

[ Example ] [ Security Filters ]
Mule supports using Spring Security 2.0 as a Security Manager inside of Mule. You can use any of the
library's security providers such as JAAS, LDAP, CAS (Yale Central Authenication service), and DAO.
Example
The following example illustrates how to configure a single security provider on Mule, in this case an
in-memory database of users. To configure the provider, we set up a <user-service> element and the
<authentication-manager> to which Mule delegates.

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:spring="http://
www.springframework.org/schema/beans"
xmlns:http="http://www.mulesource.org/schema/mule/http/2.2"
xmlns:ss="http://www.springframework.org/schema/security"
beans-2.5.xsd
mule.xsd
http://www.mulesource.org/schema/mule/http/2.2 http://www.mulesource.org/schema/mule/http/2.2/
mule-http.xsd
http://www.mulesource.org/schema/mule/spring-security/2.2
http://www.mulesource.org/schema/mule/spring-security/2.2/mule-spring-security.xsd
http://www.springframework.org/schema/security http://www.springframework.org/schema/security/
spring-security-2.0.xsd">
<mule-ss:delegate-security-provider name="memory-provider" delegate-ref="authenticationManager" />
<spring:beans>
<ss:authentication-manager alias="authenticationManager" />
<ss:authentication-provider>
<ss:user-service id="userService">
<ss:user name="ross" password="ross" authorities="ROLE_ADMIN" />
<ss:user name="anon" password="anon" authorities="ROLE_ANON" />
</ss:user-service>
</ss:authentication-provider>
</spring:beans>
...cut...
</mule>

Security Filters
Security filters can be configured on an object to either authenticate inbound requests or attach
credentials to outbound requests. For example, to configure an HTTP basic authorization filter on an HTTP
endpoint, you would use the following endpoint security filter:
<mule-ss:http-security-filter realm="mule-realm"/>
</inbound-endpoint>
When a request is received, the authentication header will be read from the request and authenticated
against all security providers on the Security Manager. If you only want to validate on certain ones, you
can supply a comma-separated list of security provider names.
<mule-ss:http-security-filter realm="mule-realm" securityProviders="default,another"/>
</inbound-endpoint>

Encryption Strategies
Encryption Strategies
The Security Manager can be configured with one or more encryption strategies that can then be
used by encryption transformers, security filters, or secure transports such as SSL or HTTPS. These
encryption strategies can greatly simplify configuration for secure messaging as they can be shared
across components.
Following is an example of a password-based encryption strategy (PBE) that provides password-based

encryption using JCE. Users must specify a password and optionally a salt and iteration count as well. The
default algorithm is PBEWithMD5AndDES, but users can specify any valid algorithm supported by JCE.
<security-manager>
<password-encryption-strategy name="PBE" password="mule"/>
</security-manager>
This strategy can then be referenced by other components in the system such as filters or transformers.
<decrypt-transformer name="EncryptedToByteArray" strategy-ref="PBE"/>
<service name="Svc1">
<inbound>
<inbound-endpoint address="vm://test">
<encryption-security-filter strategy-ref="PBE"/>
</inbound-endpoint>
</inbound>
...cut...
<service name="Svc2">
...cut...
<outbound>
<outbound-endpoint address="vm://output" transformer-refs="EncryptedToByteArray"/>
</outbound>

Setting up LDAP Provider for Acegi
Setting Up an LDAP Provider for Acegi

[ Declaring the Beans ] [ Configuring the Mule Security Provider ] [ Configuring the
MethodSecurityInterceptor ]
This page describes how you can configure an Acegi LDAP provider, which can be:
• Used by Mule as its security provider via AcegiProviderAdapter

• Used by Acegi/Spring to perform Component Authorization
For information on configuring an in-memory DAO provider, see Configuring Security.
Declaring the Beans

You must set up two beans in Spring, an InitialDirContextFactory and an LdapAuthenticationProvider.
The InitialDirContextFactory is the access point for obtaining an LDAP context where the
LdapAuthenticationProvider provides integration with the LDAP server. For example:
...cut...
<bean id="initialDirContextFactory" class="org.acegisecurity.ldap.DefaultInitialDirContextFactory">

<constructor-arg value="ldap://localhost:389/dc=com,dc=foobar" />
<property name="managerDn">
<value>cn=root,dc=com,dc=foobar</value>
</property>
<property name="managerPassword">
<value>secret</value>
</property>
</bean>
<bean id="authenticationProvider" class="org.acegisecurity.providers.ldap.LdapAuthenticationProvider">

<constructor-arg>
<bean class="org.acegisecurity.providers.ldap.authenticator.BindAuthenticator">
<constructor-arg>
<ref local="initialDirContextFactory" />
</constructor-arg>
<property name="userDnPatterns">
<list>
<value>uid={0},ou=people</value>
</list>
</property>
</bean>
</constructor-arg>
<constructor-arg>
<bean class="org.acegisecurity.providers.ldap.populator.DefaultLdapAuthoritiesPopulator">
<constructor-arg>
<ref local="initialDirContextFactory" />
</constructor-arg>
<constructor-arg>
<value>ou=groups</value>
</constructor-arg>
<property name="groupRoleAttribute">
<value>cn</value>
</property>

<property name="searchSubtree">
<value>true</value>
</property>
<property name="rolePrefix">
<value>ROLE_</value>
</property>
<property name="convertToUpperCase">
<value>true</value>
</property>
</bean>
</constructor-arg>
</bean>
Configuring the Mule Security Provider

The AcegiProviderAdapter delegates to an AuthenticationProvider such as the
LdapAuthenticationProvider.
<acegi:delegate-security-provider name="acegi-ldap" delegate-ref="authenticationProvider"/>
With the above configuration, you can achieve endpoint-level security and other security features in Mule
that require one or more security providers.
Configuring the MethodSecurityInterceptor

The configuration for component authorization is similar to the one described in Component Authorization
Using Acegi. A key point of configuration is ObjectDefinitionSource:
<property name="objectDefinitionSource" value="org.mule.api.lifecycle.Callable.onCall=ROLE_MANAGERS"/>
The roles are looked up by the DefaultLdapAuthoritiesPopulator, which you configured in the
previous section. By default, a role is prefixed with ROLE_ and its value is extracted (and converted to
uppercase) from the LDAP attribute defined by the groupRoleAttribute.

Setting up LDAP Provider for Spring Security
Setting Up an LDAP Provider for Spring

Security
[ Declaring the Beans ] [ Configuring the Mule Security Provider ] [ Configuring the
MethodSecurityInterceptor ]
This page describes how you can configure a Spring Security LDAP provider, which can be used by Mule
as follows:
• As its security provider via SpringProviderAdapter

• To perform component authorization
For information on configuring an in-memory provider, see Configuring Security.
Declaring the Beans

You must set up two beans in Spring, an InitialDirContextFactory and an LdapAuthenticationProvider.
The InitialDirContextFactory is the access point for obtaining an LDAP context where the
LdapAuthenticationProvider provides integration with the LDAP server. For example:
...cut...
<bean id="initialDirContextFactory"
class="org.springframework.security.ldap.DefaultInitialDirContextFactory">
<constructor-arg value="ldap://localhost:389/dc=com,dc=foobar" />
<property name="managerDn">
<value>cn=root,dc=com,dc=foobar</value>
</property>
<property name="managerPassword">
<value>secret</value>
</property>
</bean>
<bean id="authenticationProvider"
class="org.springframework.security.providers.ldap.LdapAuthenticationProvider">
<constructor-arg>
<bean class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator">
<constructor-arg ref="initialDirContextFactory" />
<property name="userDnPatterns">
<list>
<value>uid={0},ou=people</value>
</list>
</property>
</bean>
</constructor-arg>
<constructor-arg>
<bean
class="org.springframework.security.providers.ldap.populator.DefaultLdapAuthoritiesPopulator">
<constructor-arg ref="initialDirContextFactory"/>

<constructor-arg value="ou=groups"/>
<property name="groupRoleAttribute" value="ou"/>
</bean>
</constructor-arg>
</bean>
Configuring the Mule Security Provider

The AcegiProviderAdapter delegates to an AuthenticationProvider such as the
LdapAuthenticationProvider.
<mule-ss:delegate-security-provider name="acegi-ldap" delegate-ref="authenticationManager"/>
With the above configuration, you can achieve endpoint-level security and other security features in Mule
that require one or more security providers.
Configuring the MethodSecurityInterceptor

The configuration for component authorization is similar to the one described in Component Authorization
Using Acegi. A key point of configuration is ObjectDefinitionSource:
<property name="objectDefinitionSource" value="org.mule.api.lifecycle.Callable.onCall=ROLE_MANAGERS"/>
The roles are looked up by the DefaultLdapAuthoritiesPopulator, which you configured in the
previous section. By default, a role is prefixed with ROLE_, and its value is extracted and converted to
uppercase from the LDAP attribute defined by the groupRoleAttribute.

Upgrading from Acegi to Spring Security
Upgrading from Acegi to Spring Security

[ Adding the Namespaces ] [ Updating the Acegi Package Names ] [ Using an AuthenticationManager ] [
Simplifying the Configuration ]
Spring Security is version 2.0 of the Acegi Security framework. Upgrading your Mule application to use
Spring Security instead of Acegi involves the following steps:
1. Adding the necessary namespaces to your Mule configuration

2. Updating the Acegi package names
3. Updating your Mule configuration to use an AuthenticationManager
4. Simplification using new Spring Security elements
Adding the Namespaces

Your Mule configuration file should have the following namespaces declared.
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:spring="http://
www.springframework.org/schema/beans"
xmlns:ss="http://www.springframework.org/schema/security"
beans-2.5.xsd
mule.xsd
http://www.mulesource.org/schema/mule/spring-security/2.2
http://www.mulesource.org/schema/mule/spring-security/2.2/mule-spring-security.xsd
http://www.springframework.org/schema/security
http://www.springframework.org/schema/security/spring-security-2.0.xsd">
...
</mule>
The mule-ss namespace is for the Mule Spring Security extensions. The ss namespace is for the Spring
Security schema elements that are not Mule specific and allows you to use the less verbose XML that is
part of Spring Security 2.0.
Updating the Acegi Package Names

Except for the changed package names, the Spring Security API has remained compatible with Acegi. For
example, assume you configured a DaoAuthenticationProvider like this one:
<bean class="org.acegisecurity.providers.dao.DaoAuthenticationProvider">
<property name="userDetailsService" ref="userService"/>
</bean>
To use Spring Security, you simply change the acegisecurity package to springframework.security:
<bean class="org.springframework.security.providers.dao.DaoAuthenticationProvider">

<property name="userDetailsService" ref="userService"/>
</bean>
Repeat this step for all your Acegi bean definitions.
Using an AuthenticationManager
The only major difference between Mule integration with Acegi and Spring Security is that the latter
uses the AuthenticationManager to provider authentication functions, while the former tied in at the
Acegi AuthenticationProvider level. With the Acegi provider, the authentication flow followed this
progression:
AcegiProviderAdapter (Mule) -> AuthenticationProvider (Acegi)
With the new Spring Security adapter, it follows this progression:
SpringProviderAdapter (Mule) -> AuthenticationManager (Spring Security) -> AuthenticationProvider (Spring

Security)
This allows the authentication manager to try multiple authentication providers to authenticate your
messages.
Configuration of this approach requires a little more XML. For example, consider this original
configuration:
<mule ...>
<acegi:delegate-security-provider name="memory-dao" delegate-ref="daoAuthenticationProvider"/>
<spring:bean id="inMemoryDaoImpl" class="org.acegisecurity.userdetails.memory.InMemoryDaoImpl">

<spring:value>
</spring:value>
</spring:property>
</spring:bean>
class="org.acegisecurity.providers.dao.DaoAuthenticationProvider">
</spring:bean>
</mule>
To upgrade this configuration, you add an AuthenticationManager. This would result in the following:
<mule ...>
<mule-ss:delegate-security-provider name="memory-dao" delegate-ref="authenticationManager"/>

<spring:bean id="inMemoryDaoImpl"
class="org.springframework.security.userdetails.memory.InMemoryDaoImpl">
<spring:value>
</spring:value>
</spring:property>
</spring:bean>
class="org.springframework.security.providers.dao.DaoAuthenticationProvider">
</spring:bean>
<spring:bean id="authenticationManager"
class="org.springframework.security.providers.ProviderManager">
<spring:property name="providers">
<spring:list>
<spring:ref bean="daoAuthenticationProvider"/>
</spring:list>
</spring:property>
</spring:bean>
</mule>
Simplifying the Configuration

Spring Security 2.0 includes new XML syntax that can simplify configurations, especially in simple cases.
For example, the previous example has an in-memory user database, a DAO authentication provider, and
an authentication manager. This can be simplified to:
<mule ...>
<mule-ss:delegate-security-provider name="memory-dao" delegate-ref="authenticationManager" />
<spring:beans>
<ss:authentication-manager alias="authenticationManager" />
<ss:authentication-provider>
<ss:user-service id="userService">
<ss:user name="ross" password="ross" authorities="ROLE_ADMIN" />
<ss:user name="anon" password="anon" authorities="ROLE_ANON" />
</ss:user-service>
</ss:authentication-provider>
</spring:beans>
</mule>
The <authentication-manager> element defines the name of our AuthenticationManager bean.

We then create a single AuthenticationProvider with the <authentication-provider and <user-
service> elements. This <user-service> is the same as our InMemoryDaoImpl above.
For more information on how to configure Acegi, see the following Spring documentation:
• Spring Security Documentation

• Spring Security Javadoc
• Spring Security XML Schema reference

Controlling the Infrastructure with Mule Galaxy
Controlling the Infrastructure with Mule Galaxy

Mule Galaxy helps you get control over your infrastructure by providing the following features:
• Governance: provides a centralized control point for policy management and compliance, ensuring
that your SOA adheres to your firm's policies.
• Registry: automatically detects and displays dependencies among services and manages service
lifecycles.
• Repository: stores and manages artifacts (including Mule configuration files, web services
frameworks, and any other artifact), providing version management and collaborative comments,
and allows you to publish the artifacts in a web browser using the Atom Publishing Protocol.
Mule Galaxy can be deployed either alongside Mule or as a standalone component in an enterprise's SOA
infrastructure. Mule Galaxy is available with Mule Enterprise Edition.
For complete information on Mule Galaxy, see the Mule Galaxy site.

Creating a Custom XML Namespace
This page last changed on Dec 10, 2008 by ross.
Creating a Custom XML Namespace

XML schema definitions are used for each module to define the objects and properties that the module
makes available to Mule. These configuration elements are introduced using a namespace for each
module and associating the namespace with the schema. This page describes how configuration is
handled in Mule and what steps are required when writing a new module or transport in Mule.
Advantages of Using Namespaces

The use of namespaces provides the following advantages:
• Class names are removed from XML so that implementation details are hidden.
• All objects introduced by the module are self-contained by a namespace.
• The schema provides a domain-specific language (DSL) for the module where all objects and
properties are described in the schema with type validation.
• The schema can provide additional validation for types, value ranges, and required properties.
Using Module Schemas

Schemas are located in each package's main/resources/META-INF directory. The core schema is in the
mule-core package, the TCP schema is in the tcp package, and so on.
The Mule schema can be used directly or embedded inside Spring. In addition, Spring beans can be
created directly inside the Mule schema (just use <spring:bean .../>) and elements from other
namespaces can be placed in <other>...</other>.
Mule Namespace
The default namespace for Mule xml configuration files is mule:

beans-2.5.xsd
http://www.mulesource.org/schema/mule/core/2.1 META-INF/mule.xsd">

<spring:bean ...you can also embed Spring bean definitions directly.../>
<spring:beans>

</spring:beans>
</mule>
Note here we have a spring namespace declared so we can embed spring beans directly inside your Mule
configuration file.

More on Mixing Mule and Spring
The Mule schema includes the ability to use Spring elements at certain points by including
<spring:bean> inside <mule>. These elements are handled explicitly by Mule code, which delegates their
processing to Spring.
Be careful when using Spring elements in your own schema, and check that they behave as expected.
The <bean> and <beans> elements are all forwarded to Spring for processing. In addition, the predefined
mule:mapType can be used and, when associated with the ChildMapDefinitionParser, will automatically
construct a map using Spring's <entry> elements (this is the only way that <entry> can be used
directly inside Mule elements). For examples, see the use of mapType in the Mule schema. Similar
behavior with ChildPropertiesDefinitionParser should also be possible (but ChildMapEntry and
ChildListEntryDefinitionParsers are unrelated to Spring).
Other namespaces can be introduced via <spring:beans> or by adding a dedicated element in a module
(see the Scripting module's <lang> element).
Documentation
You add documentation to the schema using the <xsd:annotation> and <xsd:documentation> tags:
<xsd:element name="my-element" type="myType">

<xsd:annotation>
<xsd:documentation>This element does this</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:complexType name="myType">
<xsd:annotation>
<xsd:documentation>This type does that</xsd:documentation>
</xsd:annotation>
</xsd:complexType>
While documentation can be added in various places within the schema, tools that use this information
follow certain conventions (see below). As a consequence, embedded documentation should:
• Be placed in the element, attribute, or associated type

• Avoid duplicating information in element and type
• Avoid reference elements (<xsd:element ref="..."/>)
• Make documentation at each level correct and distinct (do not rely on inheritance, but try to avoid
duplication)
IntelliJ Idea
Idea will show documentation defined for an element or attribute, or for the associated type if those are
missing. The information is displayed when the user presses Ctrl-J. For more information see this post
about how to work with Mule schemas in IntelliJ.
Eclipse
The Web Tools Platform (WTP) XML editor shows documentation defined for an element or attribute, or
for the associated type if those are missing. The information is displayed when you press F2 when an
element or attribute is selected or has the cursor on it. The same information is also shown when using
the context-sensitive auto-completion functionality by pressing the "CTRL-." key combination.
The WTP XML editor will display "inherited" documentation but does not show documentation associated
with referenced global elements.

Writing Configuration Handlers
When writing a new Mule transport of module, you will need to write a schema definition and the code
necessary to parse the XML, but most of the work is done for you. The following section will walk through
the process of:
• Defining the XML Schema: Describes all the objects that your module exposes, such as
transformers, components, filters, routers, agents, etc.
• Writing the Namespace Handler: Responsible for configuring the XML parsers for each of the
elements that your schema defines.
• Writing a Definition Parser for each of the elements (objects) defined in the schema
• Testing your Namespace Handler
Defining the Schema
If you are not familiar with XML schema, you may want to take an introductory course here. However,
Mule defines most of what you need out of the box, so it's fairly straightforward to jump in and write your
own. Following are a few key concepts:
• Complex Types are defined for each object in the module. Complex types define the elements and
attributes that make up the type. For example, a connectorType would define shared attributes for
all connectors and define any nested elements such as <service-overrides>.
<xsd:complexType name="connectorType" mixed="true">

<xsd:choice minOccurs="0" maxOccurs="unbounded">
<xsd:element name="receiver-threading-profile" type="threadingProfileType" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="dispatcher-threading-profile" type="threadingProfileType" minOccurs="0"
maxOccurs="1"/>
<xsd:group ref="exceptionStrategies" minOccurs="0" maxOccurs="1"/>
<xsd:element name="service-overrides" type="serviceOverridesType" minOccurs="0"
maxOccurs="1"/>
</xsd:choice>
<xsd:attribute name="name" type="xsd:string" use="required"/>

<xsd:attribute name="createDispatcherPerRequest" type="xsd:boolean"/>
<xsd:attribute name="createMultipleTransactedReceivers" type="xsd:boolean"/>
</xsd:complexType>
Note that complex types can be extended (much like inheritance), so new complex types can
be built upon existing ones. Mule provides a number of base complex types out of the box for
connectors, agents, transformers, and routers. If you write one of these, your schema should
extend the corresponding complex type. Using TCP as an example, here is an excerpt from where
we define the noProtocolTcpConnectorType:
<xsd:import namespace="http://www.mulesource.org/schema/mule/core/2.1"/>
<xsd:complexType name="noProtocolTcpConnectorType">
<xsd:complexContent>
<xsd:extension base="mule:connectorType">
<xsd:attribute name="sendBufferSize" type="mule:substitutableInt">
<xsd:annotation>
<xsd:documentation>
The size of the buffer (in bytes) used when sending data, set on the socket itself.
</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute name="receiveBufferSize" type="mule:substitutableInt">
<xsd:annotation>
<xsd:documentation>

The size of the buffer (in bytes) used when receiving data, set on the socket itself.
</xsd:annotation>
</xsd:attribute>
...
<xsd:attribute name="validateConnections" type="mule:substitutableBoolean">
<xsd:annotation>
<xsd:documentation>
This "blips" the socket, opening and closing it to validate the connection when first accessed.
</xsd:annotation>
</xsd:attribute>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
This complex type extends the mule:connectorType type. Notice that we need to import the Mule
core schema since that is where the connectorType is defined.
Schema Types
Note that the types we use for int, boolean, and all numeric types are custom types
called substitutableInt or substitutableBoolean. These types allow for int values
and boolean values but also allow developers to use property placeholders, such
as ${tcp.keepAlive} as a valid value for the property. These placeholders will be
replaced at run-time by real values defined in property files.
Element definitions describe what elements are available in the schema. An element has a type, which
should be declared as a Complex Type. For example:
<xsd:element name="connector" type="tcpConnectorType"/>
This makes the connector element available within the tcp namespace.
The schema should be called mule-<short module name>.xsd and stored in the META-INF of the module
or transport.
Versioning
In Mule, the version of the schema is maintained in the schema URI. This means that the namespace and
the targetNamespace implicitly contain the schema version. Schema URIs use the following convention:
The first part of the URI http://www.mulesource.org/schema/mule/ is the same for each schema. It is
then followed by the module's short name, followed by the version of the schema.
Schema Mapping
To stop the XML parser from loading Mule schemas from the Internet, you add a mapping file that maps
the remote schema location to a local classpath location. This mapping is done in a simple properties file
called spring.schemas located in the META-INF directory for the module/transport.
http\://www.mulesource.org/schema/mule/tcp/2.1/mule-tcp.xsd=META-INF/mule-tcp.xsd

Namespace Handler
The namespace handler is responsible for registering definition parsers, so that when an element in the
configuration is found, it knows which parser to use to create the corresponding object.
A namespace handler is a single class that is directly associated with a namespace URI. To make this
association, there needs to be a file called spring.handlers in the root of the META-INF directory of the
module or transport. The file contains the following:
http\://www.mulesource.org/schema/mule/tcp/2.1=org.mule.transport.tcp.config.TcpNamespaceHandler
The TcpNamespaceHandler code is very simple because there is a base support class provided:
public class TcpNamespaceHandler extends NamespaceHandlerSupport

{
public void init()
{
registerBeanDefinitionParser("connector", new OrphanDefinitionParser(TcpConnector.class, true));
}
}
Here, there should be one or more registrations binding an element name with a definition parser.
Definition Parsers
The definition parser is where the actual object reference is created. It includes some Spring-specific
classes and terminology, so it's worth reading this introduction.
Mule already includes a number of useful definition parsers that can be used for most
situations or extended to suit your needs. You can also create a custom definition
parser. The following table describes the existing parsers. To see how they are used, see
org.mule.config.spring.handlers.MuleNamespaceHandler .
Parser Description
org.mule.config.spring.parsers.generic.OrphanDefinitionParser
Contructs a single, standalone bean from an
element. It is not injected into any other object.
This parser can be configured to automatically
set the class of the object, the init and destroy
methods, and whether this object is a singleton.
org.mule.config.spring.parsers.generic.ChildDefinitionParser
Creates a definition parser that will construct
a single child element and inject it into the
parent object (the enclosing XML element). The
parser will set all attributes defined in the XML
as bean properties and will process any nested
elements as bean properties too, except the
correct definition parser for the element will be
looked up automatically. If the class is read from
an attribute (when class is null), it is checked
against the constraint. It must be a subclass of
the constraint.
org.mule.config.spring.parsers.generic.ParentDefinitionParser
Processes child property elements in XML but
sets the properties on the parent object. This is
useful when an object has lots of properties and

it's more readable to break those properties into
groups that can be represented as a sub-element
in XML.
org.mule.config.spring.parsers.collection.ChildMapEntryDefinitionParser
Allows a series of key value pair elements to be
set on an object as a Map. There is no need to
define a surrounding 'map' element to contain
the map entries. This is useful for key value pair
mappings.
org.mule.config.spring.parsers.AbstractChildBeanDefinitionParser
This definition parser introduces the notion
of hierarchical processing to nested XML
elements. Definition parsers that extend
this class are always child beans that get
set on the parent definition parser. A single
method getPropertyName must be overriden
to specify the name of the property to set
on the parent bean with this bean. Note
that the property name can be dynamically
resolved depending on the parent element. This
implementation also supports collections and
Maps. If the bean class for this element is set to
MapEntryDefinitionParser.KeyValuePair, it is
assumed that a Map is being processed and any
child elements will be added to the parent Map.
org.mule.config.spring.parsers.AbstractMuleSingleBeanDefinitionParser
This parser extends the Spring provided
AbstractBeanDefinitionParser to provide
additional features for consistently customizing
bean representations for Mule bean definition
parsers. Most custom bean definition parsers
in Mule will use this base class. The following
enhancements are made:
• Attribute mappings can be registered to

control how an attribute name in Mule XML
maps to the bean name in the object being
created.
• Value mappings can be used to map key
value pairs from selection lists in the XML
schema to property values on the bean being
created. These are a comma-separated list
of key=value pairs.
• Provides an automatic way of setting the
init-method and destroy-method for this
object. This will then automatically wire the
bean into the lifecycle of the application
context.
• The singleton property provides a fixed
way to make sure the bean is always a
singleton or not.
Naming Conventions
The number and variety of definition parsers is growing rapidly. To make them more manageable, please
use the following conventions.
• Group by function. Abstract bases live in org.mule.config.spring.parsers. Under that we have

generic, specific, and collection, which should be self-explanatory. Inside those you may want
to add further grouping (e.g., specific.security).
• Use consistent names for the relationship of the object being created with the surrounding context:
° Child objects are injected into parents (the enclosing DOM element)
° Grandchild are like child, but recurse up the DOM tree more than one generation
° Orphan objects stand alone

° Named objects are injected into a target identified by name rather than DOM location.
° Parent definition parsers are something like facades, providing an alternative interface to the
parent.
Testing
Testing the namespace handler is pretty simple. You configure the object in Mule XML, start the server,
and check that the values have been set correctly. For example:
public class TcpNamespaceHandlerTestCase extends FunctionalTestCase

{
protected String getConfigResources()
{
return "tcp-namespace-config.xml";
}
public void testConfig() throws Exception

{
TcpConnector c = (TcpConnector)managementContext.getRegistry().lookupConnector("tcpConnector");
assertNotNull(c);
assertEquals(1024, c.getReceiveBufferSize());
assertEquals(2048, c.getSendBufferSize());
assertEquals(50, c.getReceiveBacklog());
assertEquals(3000, c.getReceiveTimeout());
assertTrue(c.isKeepAlive());
assertTrue(c.isConnected());
assertTrue(c.isStarted());
}
}
Extending Existing Handlers

Instead of creating a new handler, you can extend an existing transport and add new properties and
elements. For example, the SSL transport extends the TCP transport.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<xsd:schema xmlns="http://www.mulesource.org/schema/mule/ssl/2.1"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:tcp="http://www.mulesource.org/schema/mule/tcp/2.1"
targetNamespace="http://www.mulesource.org/schema/mule/ssl/2.1"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xsd:import namespace="http://www.w3.org/XML/1998/namespace"/>
<xsd:import namespace="http://www.mulesource.org/schema/mule/core/2.1"
schemaLocation="http://www.mulesource.org/schema/mule/core/2.1/mule.xsd" />
<xsd:import namespace="http://www.mulesource.org/schema/mule/tcp/2.1"
schemaLocation="http://www.mulesource.org/schema/mule/tcp/2.1/mule-tcp.xsd"/>
<xsd:element name="connector" substitutionGroup="mule:abstract-connector">

<xsd:annotation>
<xsd:documentation>
Connect Mule to an SSL socket, to send or receive data via the network.
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="tcp:tcpConnectorType">

<xsd:sequence>
<xsd:element minOccurs="0" maxOccurs="1" name="client"
type="mule:tlsClientKeyStoreType"/>
<xsd:element minOccurs="0" maxOccurs="1" name="key-store"
type="mule:tlsKeyStoreType"/>
<xsd:element minOccurs="0" maxOccurs="1" name="server"
type="mule:tlsServerTrustStoreType"/>
<xsd:element minOccurs="0" maxOccurs="1" name="protocol-handler"
type="mule:tlsProtocolHandler"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
Simple Recipe
The following recipe is sufficient for a simple transport (like UDP). The ordering helps guarantee complete
coverage.
1. Write a test case for the connector.

a. Use IDE's auto completion to test each public getter (as a first approximation to the public API
- tidy by hand).
b. Set the test value to something other than the default.
2. Write the XML configuration for the connector (test/resources/foo-connector-test.xml) using
the properties from the test (make sure the import section is correct).
3. Write the schema definition (tweaking until the XML connector config shows no errors) (META-INF/
mule-foo.xsd).
4. Write the namespace handler (and any needed definition parsers) (src/main/java/org/mule/
providers/foo/config/FooNamespaceHandler)
5. Set the Spring handler mapping (META-INF/spring.handlers).
6. Set the local schema mapping (META-INF/spring.schemas).
7. Make sure the test runs.
8. Check properties against the documentation and make consistent (but note that things like
connection strategy parameters are handled by an embedded element that is itself inherited from
the connectorType) and then re-run the test.
Resources
• A useful set of PDF slides that give an overview of the new approach in Spring and (slides
29 on) given an introductory example. The Mule code is more complex, but follows the same
structure: org.mule.config.spring.handlers.MuleNamespaceHandler is the namespace handler;
org.mule.config.spring.parsers.AbstractMuleBeanDefinitionParser and subclasses are the
bean definition parsers.
• A couple of blog posts (1, 2) that give a developer's-eye overview.
• Useful papers on mutable/extensible containers 1, 2

Creating Custom Routers
Creating Custom Routers

Typically, you implement custom routing with filters, but occasionally you may need to implement a
customer router.
Custom Outbound Routers

Outbound routers control how a message gets routed to a list of endpoints. For example, sometimes a
message gets routed based on simple rules or business logic, whereas in other cases you may multicast a
message to every router.
The easiest way to write an outbound router is to extend the

org.mule.routing.outbound.AbstractOutboundRouter class:
import org.mule.routing.outbound.AbstractOutboundRouter;
public class CustomOutboundRouter extends AbstractOutboundRouter {

....
}
There are two methods you must implement that control how messages will be routed through the
system. First, you must implement the isMatch method. This determines if a message should be
processed by the router.
For example, to route only messages that have a payload containing the string "hello":
public boolean isMatch(MuleMessage message) throws RoutingException

{
return "hello".equals(message.getPayloadAsString());
}
The second method you must implement is the route method. Each outbound router has a list of
endpoints that are associated with it. The route method contains the logic to control how the event is
propagated to the endpoints.
For example, if there were two endpoints you want to route to based on a condition, you would use this
method to select the endpoint:
MuleMessage route(MuleMessage message, MuleSession session, boolean synchronous) throws

MessagingException {
OutboundEndpoint ep = null;
if (isConditionMet(message)) {
ep = getEndpoints().get(0);
} else {
ep = getEndpoints().get(1);
}
....
Once you've selected an endpoint, you must then dispatch or send the message to it based on whether or
not the message is synchronous:

try
{
if (synchronous)
{
return send(session, message, ep);
}
else
{
dispatch(session, message, ep);
return null;
}
}
catch (MuleException e)
{
throw new CouldNotRouteOutboundMessageException(message, ep, e);
}
return result;
}
If the request is synchronous, you must use the send method to send the inbound messages
synchronously to the endpoint. The result from this is then returned. If the request is asynchronous, it is
sent using the dispatch method, and no response message is returned.
Custom Inbound Routers

Inbound routers control whether a message is consumed by an inbound endpoint. Typically, you do not
have to create custom routers, as the existing ones provide a high degree of customization using existing
or custom filters.
If a new inbound router class is needed, it will typically extend the

org.mule.routing.inbound.SelectiveConsumer
router. This class uses the Mule filter APIs to determine if a message should be consumed and can be
configured using the existing filters.
The other responsibility of inbound routers is to control how a message is processed by a service. It can
choose to:
• Consume the message and start a new message.

• Aggregate several messages.
• Forward an incoming message to an outbound transport and skip the service invocation.
• Pass on the original message.
For more information, examine the source code for the available inbound routers.

Creating Transports
This page last changed on Jan 05, 2009 by ken.yagen.
Creating Transports
[ Overview ] [ Transport Interfaces ] [ Implementation ] [ Connectors ] [ Message Receivers ] [ Message
Dispatchers ] [ Message Requesters ] [ Service Descriptors ] [ Coding Standards ] [ Package Structure ]
Transports are used to implement message channels and provide connectivity to an underlying data
source or message channel in a consistent way. Mule provides transports for many different protocols,
including File, FTP, HTTP, JMS, JDBC, Quartz, and many more. For a complete list, see Available
Transports. There are also community-created transports on MuleForge. If you need to send messages on
a protocol other than those provided, you can create a new transport.
Overview
When creating a new transport, you must implement a set of Mule interfaces in the org.mule.transport
package, and then extend the provided abstract classes. For a quick start, you can use the Maven
transport archetype as a code template for your transports. If you want to update an existing transport,
use the Module Archetype instead.
Mule transports can be one of the following types:
1. inbound-only: Components can only subscribe to events. They cannot dispatch events.
2. outbound-only: Components can only dispatch events. They cannot subscribe to events.
3. inbound-outbound: Components can subscribe and dispatch events
Transport Interfaces
A transport consists of a set of interface implementations that expose the features for the underlying
transport. Cannot resolve external resource into attachment.
Interface Role
Connector Used to manage Receivers, Dispatchers and

Requesters and to store any configuration
information.
Message Receiver Implements the server part of the transport.

For example, a TcpMessageReceiver creates a
server socket to receive incoming requests. A
MessageReceiver instance is created when this
transport is used for inbound communication.
Message Dispatcher Implements the client part of the transport. For

example, a TcpMessageDispatcher opens a socket
to send requests. A MessageDispatcher instance
is created when this transport for outbound
communication.
Message Requester Is also used to receive incoming messages like the

MessageReceiver but rather than subscribing to
inbound events or polling a resource or message
channel messages are only received on "request".
Inbound endpoints on services always use a
MessageReceiver rather than a MessageRequester
but they can be used elsewhere programatically to

request a single message from a message channel
or resource.
Message Adapter Is contained within the message and acts as a

bridge between the underlying message type used
by this transport and a MuleMessage. For
example, the JMS message adapter exposes
Mule methods such as getPayload() to provide
access to the payload of the JMS message, and
all headers and user properties are accessible as
message properties.
Transformers Transformers are used to convert data between

the transport-specific data format and another
format, such as from an HTTP response to a
string.
Endpoints The means of configuring the use of message

channels or resource as part of service
configuration. The endpoint defines which
transport to use and includes settings like the host
or queue name, the filter to use, and transaction
info. Defining an endpoint on a service will cause
Mule to create the necessary transport connector
for the protocol being used.
When writing a transport, you must implement the following interfaces that define the contract between
Mule and the underlying technology.
org.mule.api.transport.Connector
The connector is used by Mule to register listeners and create message dispatchers for the transport.
Configuration parameters that should be shared by all Message Receivers, Dispatchers and Requesters
are stored on the connector. Usually, only one connector instance is needed for multiple inbound and
outbound endpoints as multiple Message Receivers, Dispatchers and Requesters can be associated with
a connector. However, where the underlying transport API has the notion of a connection such as the
JMS or JDBC API, there should be a one-to-one mapping between the Mule connector and the underlying
connection.
org.mule.api.transport.MessageReceiver
The Message Receiver is used to receive incoming data from the underlying transport and package it
as an event. The Message Receiver is essentially the server implementation of the transport (where the
Message Dispatcher is a client implementation). For example, the HTTP Message Receiver is an HTTP
server implementation that accepts HTTP requests. An implementation of this class is needed if the
transport supports inbound communication.
org.mule.api.transport.MessageDispatcher
The Message Dispatcher is used to send messages, which is akin to making client calls with the
underlying technology. For example, the CXF Message Dispatcher will make a web service call. An
implementation of this class is needed if the transport supports outbound communication.
org.mule.api.transport.MessageRequester
The Message Requester is used to request messages from a message channel or resource rather than
subscribing to inbound events or polling a resource for messages. This is often used programatically but
is not used for inbound endpoints configured on services. An implementation of this class is needed if the
transport supports the requesting of messages from a message channel.

org.mule.api.transport.MessageDispatcherFactory
This is a factory class used to create MessageDispatcher instances. An implementation of this class is
needed if the transport supports outbound communication.
org.mule.api.transport.MessageAdapter
The message adapter is used to provide a consistent way of reading messages in Mule. The message
adapter provides methods for reading the payload of the message and reading message properties. These
properties may be message headers, custom properties, or other meta information about the message.
Implementation
Mule provides abstract implementations for all of the above interfaces. These implementations handle all
the Mule specifics, leaving a few abstract methods where custom transport code should be implemented.
Therefore, writing a custom transport is as easy as writing/embedding client and or server code specific
to the underlying technology. The following sections describes the implementations available to you.
For a quick start, use the Maven Transport Archetype.
Connectors
The org.mule.transport.AbstractConnector implements all the default functionality required for Mule
connectors, such as threading configuration and receiver/dispatcher management. For details about the
standard connector properties, see Configuring a Transport.
You can set further properties on the connector that act as defaults. For example, you can set endpoint
properties that are used by default unless you override them when configuring a specific endpoint.
Sometimes the connector is responsible for managing a connection resource of the transport where the
underlying technology has the notion of a connection, such as in JMS or JDBC. These types of connectors
will have a one-to-one mapping between a Mule connector and the underlying connection. Therefore, if
you want to have two or more physical JMS connections in a single Mule instance, a new connector should
be created for each connection.
For other transports, there will be only one connector of a particular protocol in a Mule instance that
manages all endpoint connections. One such example would be socket-based transports such as TCP
where each receiver manages its own ServerSocket and the connector manages multiple receivers.
Methods to Implement
Method Name Description Required
doInitialise() Is called once all bean properties No

have been set on the connector
and can be used to validate and
initialize the connector's state.
doStart() If there is a single server No

instance or connection
associated with the connector
(such as AxisServer or a JMS or
JDBC Connection), this method
should put the resource in a
started state.
doConnect() Makes a connection to the No

underlying resource if this is
not handled at the receiver/
dispatcher level.

doDisconnect() Close any connection made in No
doConnect().
doStop() Should put any associated No

resources into a stopped state.
Mule automatically calls the
stop() method.
doDispose() Should clean up any open No

resources associated with the
connector.
Message Receivers
Message Receivers will behave a bit differently for each transport, but Mule provides some standard
implementations that can be used for polling resources and managing transactions for the resource.
Usually there are two types of Message Receivers: Polling and Listener-based.
• A Polling Receiver polls a resource such as the file system, database, and streams.
• A Listener-based receiver registers itself as a listener to a transport. Examples would be JMS
(javax.message.MessageListener) and Pop3 (javax.mail.MessageCountListener). These base types
may be transacted.
The abstract implementations provided by Mule are described below.
Abstract Message Receiver
The AbstractMessageReceiver provides methods for routing events. When extending this class, you should
set up the necessary code to register the object as a listener to the transport. This will usually be a case
of implementing a listener interface and registering itself.
Method name Description Required
doConnect() Should make a connection to Yes

the underlying transport, such
as to connect to a socket or
register a SOAP service. When
there is no connection to be
made, this method should be
used to check that resources
are available. For example, the
FileMessageReceiver checks that
the directories it will be using
are available and readable.
The MessageReceiver should
remain in a 'stopped' state
even after the doConnect()
method is called. This means
that a connection has been
made but no events will be
received until the start() method
is called. Calling start() on
the MessageReceiver will call
doConnect() if the receiver
hasn't connected.
doDisconnect() Disconnects and tidies up Yes

any resources allocated using

the doConnect() method.
This method should return
the MessageReceiver in a
disconnected state so that it can
be connected again using the
doConnect() method.
doStart() Should perform any actions No

necessary to enable the receiver
to start receiving events. This is
different from the doConnect()
method, which actually makes a
connection to the transport but
leaves the MessageReceiver in a
stopped state. For polling-based
MessageReceivers, the doStart()
method simply starts the polling
thread. For the Axis message
receiver, the start method on
the SOAPService is called.
The action performed depends
on the transport being used.
Typically, a custom transport
doesn't need to override this
method.
doStop() Should perform any actions No

necessary to stop the receiver
from receiving events.
doDispose() Is called when the connector is No

being disposed and should clean
up any resources. The doStop()
and doDisconnect() methods
will be called implicitly when this
method is called.
Polling Message Receiver
Some transports poll a resource periodically waiting for new data to arrive. The polling message receiver,
which is based on AbstractPollingMessageReceiver , implements the code necessary to set up and destroy
a listening thread and provides a single method poll() that is invoked repeatedly at a given frequency.
Setting up and destroying the listening thread should occur in the doStart() and doStop() methods
respectively.
poll() Is executed repeatedly at a Yes

configured frequency. This
method should execute the logic
necessary to read the data and
return it. The data returned
will be the payload of the new
message. Returning null will
cause no event to be fired.

Transacted Polling Message Receiver
The TransactedPollingMessageReceiver can be used by transaction-enabled transports to manage polling

and transactions for incoming requests. This receiver uses a transaction template to execute requests in
transactions, and the transactions themselves are created according to the endpoint configuration for the
receiver. Derived implementations of this class must be thread safe, as several threads can be started at
once for an improved throughput.
You implement the following methods for the transacted polling message receiver in addition to those in
the standard Message Receiver:
getMessages() Returns a list of objects that Yes

represent individual message
payloads. The payload can be
any type of object and will by
sent to Mule services wrapped in
a MuleEvent object.
processMessage(Object) is called for each object Yes

in the list returned from
getMessages(). Each object
processed is managed in its own
transaction.
Thread Management
It's common for receivers to spawn a thread per request. All receiver threads are allocated using the
WorkManager on the receiver. The WorkManager is responsible for executing units of work in a thread. It
has a thread pool that allows threads to be reused and ensures that only a prescribed number of threads
will be spawned.
The WorkManager is an implementation of org.mule.api.context.WorkManager , which is really just a

wrapper of javax.resource.spi.work.WorkManager with some extra lifecycle methods. There is a
getWorkManager() method on the AbstractMessageReceiver that you can use to get a reference to the
WorkManager for the receiver. Work items (such as the code to execute in a separate thread) must
implement javax.resource.spi.work.Work. This interface extends java.lang.Runnable and thus has a
run() method that will be invoked by the WorkManager.
When scheduling work with the WorkManager, you should call scheduleWork(...) on the WorkManager
rather than startWork(...).
Message Dispatchers
Whereas a message receiver is equivalent to a server for the transport in that it serves client requests,
a message dispatcher is the client implementation of the transport. Message dispatchers are responsible
for making client requests over the transport, such as writing to a socket or invoking a web service. The
AbstractMessageDispatcher provides a good base implementation, leaving three methods for the custom
MessageDispatcher to implement.

doSend(MuleEvent) Sends the message payload Yes
over the transport. If there is
a response from the transport,
it should be returned from this
method. The sendEvent method
is called when the endpoint is
running synchronously, and any
response returned will ultimately
be passed back to the caller.
This method is executed in the
same thread as the request
thread.
doDispatch(MuleEvent) Invoked when the endpoint Yes

is asynchronous and should
invoke the transport but not
return any result. If a result
is returned, it should be
ignored, and if they underlying
transport does have a notion of
asynchronous processing, that
should be invoked. This method
is executed in a different thread
from the request thread.
doConnect() Makes a connection to the Yes

underlying transport, such
as connecting to a socket or
registering a SOAP service.
When there is no connection to
be made, this method should
be used to check that resources
are available. For example,
the FileMessageDispatcher
checks that the directories
it will be using are
available and readable. The
MessageDispatcher should
remain in a 'stopped' state even
after the doConnect() method is
called.
doDisconnect() Disconnects and tidies up any Yes

resources that were allocated
by the doConnect() method.
This method should return the
MessageDispatcher into a
doConnect() method
doDispose() Called when the Dispatcher is No

up any open resources.
Message Requesters
As with message receivers and dispatchers the implementation of a message requester for a transport,
if it even applies, will vary greatly. The abstract AbstractMessageRequester provides a base from which
to extend and implement your own Message Requester and implemented methods for routing events.
Although requesters can implement doConnect} and {{doDisconnect methods given the nature of a
requester this can also be done as part of the doRequest implementation, it really depending on the

underlying transport and if you need to maintain a connection open all the time or not to be able to make
arbitrary requests.
doRequest(long) Used to make arbitrary requests

to a transport resource. If the
timeout is 0, the method should
block until a message on the
endpoint is received.
doConnect() Should make a connection to the No

underlying transport if required,
such as to connect to a socket..
doDisconnect() Disconnects and tidies up No

any resources allocated using
the doConnect() method.
This method should return
the MessageReceiver in a
doConnect() method.
doInitialise() Called when the Requester No

is being initialized after all
properties have been set. Any
required initialization can be
done here.
doStart() Called when the Requester is No

started. Any transport specific
implementation that is required
when the requestor is started
should be implemented here.
doStop() Called when the Requester is No

stopped. Any transport specific
implementation that is required
when the requestor is stopped
should be implemented here.
doDispose() Called when the Requester is No

up any open resources.
Threads and Dispatcher Caching
Custom transports do not need to worry about dispatcher threading. Unless threading is turned off,
the Dispatcher methods listed above will be executed in their own thread. This is managed by the
AbstractMessageDispatcher.
When a request is made for a dispatcher, it is looked up from a dispatcher cache on the
AbstractConnector. The cache is keyed by the endpoint being dispatched to. If a Dispatcher is not
found, one is created using the MessageDispatcherFactory and then stored in the cache for later.
Message Adapters
Message adapters are usually simple objects that provide a uniform way of accessing a message payload
and associated metadata from a format used by the underlying transport. Almost all messaging protocols
have the notion of message payload and header properties, which means that a message adapter just
needs to allow access to the header properties using standard Map notation. For example:

//JMS message ID
String id = (String)message.getProperty("JMSMssageID");
//HTTP content length

int contentLength = message.getIntProperty("Content-Length");
Note that the property names use the same name that is used by the underlying transport; Content-
Length is a standard HTTP header name, and JMSMessageID is the equivalent bean property name on the
javax.jms.Message interface.
A message adapter should extend org.mule.transport.AbstractMessageAdapter , which implements much

of the mundane methods needed by the org.mule.api.transport.MessageAdapter interface.
getPayload() Returns the message payload 'as Yes

is'.
getUniqueId() This ID is used by various No

routers when correlating
messages. The superclass
supplies a unique value by
default, but this method can
be overridden to provide an ID
recognized by the underlying
transport.
Service Descriptors
Each transport has a service descriptor that describes what classes are used to construct the transport.
For complete information, see Transport Service Descriptors.
Coding Standards
Following are coding standards to use when creating transports.
Package Structure
All Mule transports have a similar package structure. They follow the convention of:
org.mule.transport.<protocol>
Where protocol is the protocol identifier of the transport such as 'tcp' or 'soap'. Any transformers and
filters for the transport are stored in either a 'transformers' or 'filters' package under the main package.
Note that if a transport has more than one implementation for a given protocol, such as the Axis and CXF
implementations of the SOAP protocol, the package name should be the protocol, such as soap instead of
axis or cxf.

Internationalization
Any exceptions messages used in your transport implementation should be stored in a resource bundle
so that they can be internationalized . The message bundle is a standard Java properties file and must be
located at:
META-INF/services/org/mule/i18n/<protocol>-messages.properties

Transport Archetype
Transport Archetype
The Mule transport archetype will help you generate a tailored boilerplate transport project in seconds.
For more information on Maven, see Using Maven.
If you want to update an existing transport instead of creating a new one, such as adding new schema
namespaces and registry bootstrapping to the transport, use the Module Archetype instead.
Follow the instructions below to create template files for a new transport, including all the necessary Java
boilerplate and detailed implementation instructions in comments.
Configuring Maven
<settings>
<pluginGroups>
</pluginGroups>
...
</settings>
Using the Archetype

First, open a command shell and change to the directory where you want to create your project.
> cd yourDir
Next, you execute the archetype and generate the code. If this is your first time running this command,
Maven will download the archetype for you.
> mvn mule-transport-archetype:create -DtransportId=xxx -DmuleVersion=2.1.2
As of Mule 2.2, the parameter -DtransportId can be replaced with -DartifactId, which is
in line with the other Mule archetypes.
• artifactId: The short name for the project (such as 'tcp'). This must be a single word in lower
case with no spaces, periods, hyphens, etc. For transports this is usually the short protocol name of
the underlying transport being connected.

After you have answered all the questions, the archetype creates a directory using the transport name
you specified. The directory includes a POM file for building with Maven, a Mule configuration file (src
\main\resources\mule-config.xml) that includes the namespaces for the transports and modules you
specified and has placeholder elements for creating your first service, and a package.html file under src
\main\java using the package path you specified. Lastly, it creates some template files under src\test
to help you get started creating a unit test for the transport. A new MULE-README.txt file will be created
in the root of your project explaining what files were created.

The plug-in prompts you to answer several questions about the transport you are writing. These may
vary according to the options you select. An example of the output is shown below.
Provide a description of what the transport does:
You should provide an accurate description of the transport with any high-level details of what you can or
cannot do with it. This text will be used where a description of the transport is required.
Which version of Mule is this transport targeted at?
The version of Mule you want to use for your transport. By default this will default to the version passed
in on the command line.
If the transport is going to be hosted on MuleForge, additional information will be added to your project
for linking to its issue tracker, web site, build server and deployment information.
Will this transport have a custom schema for configuring the transport in Xml?
All new transports targeted for Mule 2.x should define an XML schema that defines how the transport
is configured. If you do not use this option, users will have to use generic configuration to use your
transport.
Can the transport receive inbound requests?
Can this transport receive inbound events? For example, the File transport allows you to listen for files
written to a directory. JMS allows you to listen for events being written to a topic or queue.
Does the Message Receiver need to poll the underlying resource?
To receive a message, some transports must do polling. For example, the File transport must
poll a directory to know something has been written there, whereas JMS provides a callback
(MessageListener) to deliver the message. This question is asked only if the transport can receive
inbound requests.
If this transport will have a default inbound transformer, enter the name of the transformer?
If the protocol of the application being connected to has its own message type, you can define a
default inbound transformer that will be invoked by default when defining endpoints that use this
transport. You enter the name of the transformer class (without package name) to generate, such as
JmsMessageToObject.
Can the transport dispatch outbound requests?
Asks whether messages can be written to this transport. With the File transport, you can write file data to
a directory, and with JMS you can write to a queue or topic.

If this transport will have a default outbound transformer, enter the name of the
transformer?
If the protocol of the application being connected to has its own message type, you can define a default
outbound transformer that will be invoked by default when defining outbound endpoints that use this
transport. You enter the name of the transformer class (without package name) to generate, such as
ObjectToJmsMessage.
Does the transport need a custom MessageAdapter?
This is usually only required if the underlying transport has an API that has a
message object i.e. JMSMessage or HttpServletRequest.
Can the transport request individual messages from the underlying resource?
If the transport can request messages from a message channel or resource rather than subscribing to
inbound events or polling a resource, answer yes to this question. This will generate a MessageRequester
class.
Does this transport support transactions?
If the underlying resource for this transport is transactional, you can have Mule generate a transaction
wrapper that will allow users to enable transactions on endpoints defined using this transport.
Does this transport use a non-JTA transaction manager?
Not all technologies (such as JavaSpaces) support the standard JTA transaction manager. Mule can still
work with different non-JTA transaction managers, and this archetype can generate the necessary stubs
for you.
What type of endpoints does this transport use?
Mule supports a number of well-defined endpoints
• Resource endpoints (e.g., jms://my.queue)

• URL endpoints (e.g., http://localhost:1234/context/foo?param=1)
• Socket endpoints (e.g., tcp://localhost:1234)
• Custom
The Custom option allows you to deviate from the existing endpoint styles and parse your own.
If you are extending one or more existing transports, specify them here in a comma-separated list.
By default, the Mule client module is included to enable easier testing. If you want to include other
modules, specify them here in a comma-separated list.

********************************************************************************
Provide a description of what the transport does:

[default: ]
********************************************************************************
[INFO] muleVersion:
********************************************************************************

Which version of Mule is this transport targeted at?
[default: 2.1.2]
********************************************************************************
********************************************************************************
Will this project be hosted on MuleForge? [y] or [n]

[default: y]
********************************************************************************
[INFO] hasCustomSchema:
********************************************************************************
[y] or [n]
[default: y]
********************************************************************************
[INFO] hasReceiver:
********************************************************************************
Can the transport receive inbound requests? [y] or [n]

[default: y]
********************************************************************************
[INFO] isPollingReceiver:
********************************************************************************
Does the Message Receiver need to poll the underlying resource? [y] or [n]
[default: n]
********************************************************************************
[INFO] inboundTransformer:
********************************************************************************
If this transport will have a default inbound transformer, enter the name of the
transformer? (i.e. JmsMessageToObject)
[default: n]
********************************************************************************
[INFO] hasDispatcher:
********************************************************************************
Can the transport dispatch outbound requests? [y] or [n]

[default: y]
********************************************************************************
[INFO] outboundTransformer:
********************************************************************************
If this transport will have a default outbound transformer, enter the name of the
transformer? (i.e. ObjectToJmsMessage)
[default: n]
********************************************************************************
[INFO] hasCustomMessageAdapter:
********************************************************************************
Does the transport need a custom MessageAdapter? [y] or [n]

(This is usually only required if the underlying transport has an API that has a
message object i.e. JMSMessage or HttpServletRequest)
[default: n]
********************************************************************************
[INFO] hasRequester:
********************************************************************************
Can the transport request incoming messages programmatically? [y] or [n]

[default: y]
********************************************************************************
[INFO] hasTransactions:
********************************************************************************
Does this transport support transactions? [y] or [n]

[default: n]
********************************************************************************
[INFO] hasCustomTransactions:
********************************************************************************
Does this transport use a non-JTA Transaction manager? [y] or [n]

(i.e. needs to wrap proprietary transaction management)
[default: n]
********************************************************************************
[INFO] endpointBuilder:
********************************************************************************
What type of endpoints does this transport use?

- [r]esource endpoints (i.e. jms://my.queue)
- [u]rl endpoints (i.e. http://localhost:1234/context/foo?param=1)
- [s]ocket endpoints (i.e. tcp://localhost:1234)
- [c]ustom - parse your own
[default: r]
********************************************************************************
[INFO] transports:
********************************************************************************
Which Mule transports do you want to include in this project? If you intend extending a
transport you should add it here:
[default: vm]
********************************************************************************
[INFO] modules:
********************************************************************************
Which Mule modules do you want to include in this project? The client is added f
or testing:
[default: client]
********************************************************************************

By default, this plug-in runs in interactive mode, but it's possible to run it in silent mode by using the
following option:
-Dinteractive=false
transportId -DtransportId=tcp none
muleVersion -DmuleVersion=2.1.2 none

hasCustomSchema -DhasCustomSchema=true true
forgeProject -DforgeProject=true true
hasDispatcher -DhasDispatcher=true true
hasRequester -DhasRequester=true true
hasCustomMessageAdapter - false
(Since Mule 2.2) DhasCustomMessageAdapter=true
hasTransactions -DhasTransactions=false false
inboundTransformer -DinboundTransformer=false false
groupId - org.mule.transport.<transportId>
DgroupId=org.mule.transport.tcp
hasReceiver -DhasReceiver=true true
isPollingReceiver -DisPollingReceiver=false false
outboundTransformer -DoutboundTransformer=false false
endpointBuilder -DendpointBuilder=s r
hasCustomTransactions -DhasCustomTransactions=false false
artifactId -DartifactId=mule-transport-tcp mule-transport-<transportId>
transports -Dtransports=vm,jms vm
modules -Dmodules=client,xml client

Transport Service Descriptors
Transport Service Descriptors

A service descriptor is a file containing properties that describes how the internals of a transport is
configured, such as which dispatcher factory to use or which endpoint builder to use. The service
descriptor file must have the same name as the protocol of the transport and must be stored in the
META-INF directory.
META-INF/services/org/mule/providers/<protocol>.properties
Following are the properties that can be set in a transport service descriptor.
Property Description Required
connector The name of the default Yes

connector class to use. This
must be an implementation of
org.mule.api.transport.Connector
.
dispatcher.factory The name of the dispatcher No (if inbound only)

factory class to use. This
org.mule.api.transport.MessageDispatcherFactory
.
requester.factory The name of the requester No

factory class to use.
org.mule.api.transport.MessageRequesterFactory
.
message.receiver The name of the message No (if inbound only)

receiver class to use. This
.
transacted.message.receiver The name of the message No

receiver class to use for
transacted messages. Some
transports implement a
transacted message receiver
separately, in which case the
MessageReceiver class can
be specified here so Mule
knows which receiver to use
when creating endpoints that
are transacted. This must
be an implementation of
xa.transacted.message.receiver If the transport supports XA No

transactions, the name of
the XA transacted message
receiver implementation to use.

Some transports implement
an XA transacted message
receiver separately, in which
case the MessageReceiver
class can be specified here so
Mule knows which receiver to
use when creating endpoints
that are XA transacted. This
.
message.adapter The name of the message No (if outbound only)

adapter class to use for this
connector when receiving
messages. This must be
an implementation of
org.mule.api.transport.MessageAdapter
.
inbound.transformer The default transformer to No

use on inbound endpoints
using this transport if no
transform has been explicitly
set on the endpoint. The
property is the class name of
a transformer that implements
org.mule.api.transformer.Transformer
.
response.transformer The default transformer to use No

on inbound endpoints using
this transport if no transformer
has been explicitly set for
the response message flow
in Request/Response style
messaging. The property
is the class name of a
transformer that implements
.
outbound.transformer The default transformer to No

use on outbound endpoints
using this transport if no
transform has been explicitly
set on the endpoint. The
property is the class name of
a transformer that implements
.
endpoint.builder The class name of the endpoint Yes

builder used to parse the
endpoint and create the URI.
Mule provides a standard set
of endpoint builders such as
ResourceNameEndpointURIBuilder
used by JMS and VM,
SocketEndpointURIBuilder used
by TCP, HTTP, and UDP, and
UrlEndpointURIBuilder used
by SOAP. Custom endpoint
builders should extend

org.mule.endpoint.AbstractEndpointBuilder
.
session.handler The name of the session No

handler class to use for
reading and writing session
information to and from the
current message. This must
be an implementation of
org.mule.api.transport.SessionHandler
.

Deployment Scenarios
Deployment Scenarios
[ Embedding Mule in a Java Application or Webapp ] [ Embedding Mule in an Application Server ] [ Using
Spring ] [ Using Mule NetBoot ]
There are several ways in which you can deploy Mule. The simplest way is from the command prompt,
or from a script or IDE. For more information, see Running Mule. Following are additional deployment
scenarios:
Embedding Mule in a Java Application or Webapp

You can start and stop Mule from a Java application or embed it in a Webapp (such as a JSP or servlet).
For details, see Embedding Mule in a Java Application or Webapp.
Embedding Mule in an Application Server

You can deploy the Mule JCA Resource Adapter to several J2EE application servers, allowing EJBs to send
and receive Mule events. Following are details on specific application servers:
• Geronimo: The Geronimo application server uses ActiveMQ as its default JMS provider. For details,
see ActiveMQ Integration.
• JBoss
• WebLogic
Using Spring
Mule fully integrates with Spring, allowing you to take advantage of Spring's many features, including
support for JNDI and EJB session beans. You can also use Spring remoting to access Mule from an
external applications. For details, see Using Mule with Spring.
Using Mule NetBoot

Mule NetBoot allows you to start and configure multiple instances of Mule simultaneously using Galaxy.
For complete information, see Using Mule NetBoot.

Deploying Mule to WebLogic
Deploying Mule to WebLogic

[ Creating a WebLogic Domain for Mule ] [ Configuring Logging ] [ Setting Up Web.xml ] [ Deploying Mule
] [ Replacing the Mule Configuration File ]
This page describes how to deploy the Mule JCA Resource Adapter to the WebLogic Application Server,
allowing EJBs to send and receive Mule events. For details on configuring WebLogic JMS in Mule, see
WebLogic JMS Integration.
These instructions assume you have downloaded and installed WebLogic Application Server version 10.3
and that you have downloaded the Mule JCA Resource Adapter. Note that WebLogic 8.x and 9.x are also
supported, but these instructions are specific to version 10.3, both on BEA Weblogic and Oracle WebLogic.
Note: You can also deploy the Mule JCA Resource Adapter within an EAR, in which case you follow the
same steps but deploy your EAR rather than the RAR. Alternatively, you can deploy Mule embedded
in a web application, in which case you will need to configure logging as described below, but you will
not need to switch configuration files in the RAR, and you won't use the JCA Resource Adapter, as your
web.xml file will define the configuration file to use instead.
Creating a WebLogic Domain for Mule

The first step is to create a WebLogic domain for Mule using the BEA WebLogic Configuration Wizard.
1. Launch the Configuration Wizard. For example, on Windows choose Start > All Programs > BEA
Products > Tools > Configuration Wizard.
2. In the Welcome screen, select the option to create a new domain and click Next.
3. In the Select Domain Source screen, select the option to generate a domain for WebLogic Server
and click Next.
4. In the Configure Administrator Username and Password screen, enter the user name and password
you want to use, and then click Next.
5. In the Configure Server Start Mode and JDK screen, select Development Mode, select the Sun SDK
1.5 instead of JRockit, and then click Next.
6. In the Customize Environment and Services Settings screen, leave No selected and click Next.
7. In the Create WebLogic Domain screen, enter Mule2.1 for the domain name, leave the location
set to the default user projects domains directory, and then click Create. Note that you can use
whatever domain name you like, but the rest of this page assumes the name Mule2.1.
8. When the domain has been created, click Done.
Configuring Logging
Mule uses Commons logging and Commons lang. Because WebLogic does not include the Commons
logging JAR, and because Mule requires a newer version of Commons lang, you must copy these files
and modify your classpath so they are used correctly by Mule and WebLogic. For more information
on using Commons logging and WebLogic, see http://e-docs.bea.com/wls/docs103/logging/
config_logs.html#wp1015132.
1. Download the Commons logging JAR as a TAR or ZIP file here.

2. Unzip the file and copy commons-logging-api.jar to any location on the WebLogic server
classpath, such as APP-INF/LIB or WEB-INF/LIB, or in Mule2.1/lib under the <WLHome>/
user_projects/domains directory.
3. Copy wlcommons-logging.jar from <WLHome>/server/lib to the same location where you copied
commons-logging.jar.
4. Copy commons-lang.osgi-2.4.jar from inside the Mule JCA Resource Adapter RAR file to the
Mule2.1/lib directory under the <WLHome/user_projects/domains directory. You can use any
decompression program that supports RAR files to extract the JAR from it, or unpackage the RAR
using the jar xvf command, such as: jar xvf muleesb-enterprise-jca-2.1.1.rar
5. In the Mule2.1EE/bin directory, modify the startWebLogic file so that the

commons-lang.osgi-2.4.jar in your Mule2.1/lib directory is loaded first. For example, on
Windows you would modify startWebLogic.cmd and change this line:
set CLASSPATH=%CLASSPATH%;%MEDREC_WEBLOGIC_CLASSPATH%...
to this (type it all on one line):
set CLASSPATH=%WL_HOME%/user_projects/domains/Mule2.1/lib/commons-lang.osgi-2.4.jar;
%CLASSPATH%;%MEDREC_WEBLOGIC_CLASSPATH%...
6. Configure a system property in WebLogic's startup script by adding the following line after the
classpath modification line:
set JAVA_OPTIONS=%JAVA_OPTIONS% -
Dorg.apache.commons.logging.LogFactory=weblogic.logging.commons.LogFactoryImpl
Setting Up Web.xml
You must set up your WebLogic web.xml file to enable WebLogic to work with Mule. Open your web.xml
file and modify it with the following information:
• The class prefix and name of your Mule configuration file

• The listener class
• The Mule servlet configuration, including the order in which the servlet should be loaded. Typically,
set this to a high number so that it is loaded last.
For example, the beginning of the file should look similar to this:
<web-app id="WebApp_ID">

<context-param>
<param-name>org.mule.config</param-name>
<param-value>mule-config.xml</param-value>
</context-param>
<listener>
<listener-class>
org.mule.config.builders.MuleXmlBuilderContextListener
</listener-class>
</listener>
<servlet>
<servlet-name>muleServlet</servlet-name>
<servlet-class>org.mule.transport.servlet.MuleReceiverServlet</servlet-class>
<load-on-startup>100</load-on-startup>
</servlet>

...
</web-app>
Note: Make sure that the ports you specify in your Mule configuration file are open. You can use netstat
-a to verify this.
Deploying Mule
There are many ways to deploy applications to the WebLogic server. These instructions demonstrate the
two most common approaches: through auto-deployment, which provides a fast method for deploying
for testing and evaluation, and through the Administration console, which provides more control over the
configuration. Note that this section also applies when deploying an EAR or WAR that embeds Mule to
WebLogic, in which case you deploy the EAR or WAR instead of the RAR file.

To Auto-deploy Mule:
1. Copy muleesb-enterprise-jca-2.1.1.rar (for Mule Enterprise users) or mule-jca-2.1.1.rar

(for Mule Community users) into the <WLHome>/user_projects/domains/Mule2.1/autodeploy
directory.
2. Restart your domain server instance in development mode. During the starting process, the new
RAR file will be auto-discovered and deployed by the domain server.
To Deploy Mule Using the Administration Console:
1. Start the WebLogic server. For example, on Windows choose Start > BEA Products > WebLogic
Server.
2. Start the Admin Server for the Mule2.1 domain. For example, on Windows you would choose Start
> BEA Products > User Projects > Mule2.1 > Start Admin Server for WebLogic Server
Domain.
3. When prompted, log in to the console using the user name and password you specified when
creating the domain. If you close the console and need to restart it later, you can go to the URL
http://localhost:7001/console/console.portal.
4. In the Domain Structure on the left, click Deployments, and then click Lock & Edit.
5. Click Install, and then navigate to the location where you downloaded the Mule RAR file.
6. Select the RAR file and click Next.
7. Specify that you want to go to the deployment's configuration screen, and then click Finish.
8. In the Change Center on the left, click Activate Change.
Mule is now deployed to WebLogic via the Mule JCA Resource Adapter. You must now replace the default
configuration file in the RAR file with the configuration file for your Mule application.
Replacing the Mule Configuration File

Mule includes a placeholder configuration file called mule-config.xml in the RAR file under mule-module-
jca-core-2.1.1.jar. If you simply want to modify this file, you can do the following:
1. Unpackage the RAR and the JAR file.

2. Modify the configuration file.
3. Repackage the JAR and RAR with the updated file and copy the RAR into the <WLHome>/
user_projects/domains/Mule2.1/autodeploy directory.
4. Run the startWebLogic command.
If you want to replace this file, do the following:
1. Unpackage the RAR file and copy your configuration file to the top level where all the JAR files are
located.
2. Open the META-INF folder, and then open weblogic-ra.xml for editing.
3. Immediately after the <enable-global-access-to-classes>true</enable-global-access-to-
classes> entry and right before outbound-resource-adapter, add the following lines, where echo-
axis-config.xml is the name of your configuration file:
<properties>
<property>
<name>Configurations</name>
<value>echo-axis-config.xml</value>
</property>
</properties>
4. Repackage the RAR file and deploy it by copying it to the autodeploy directory and running
startWebLogic.

Deploying Mule to WebSphere
Deploying Mule to WebSphere

This page is under construction. If you have experience deploying Mule to WebSphere and
would like to share your knowledge with the Mule community, please contact us to become
a site editor.
You can deploy the Mule JCA Resource Adapter to the WebSphere application server, allowing EJBs to
send and receive Mule events. For details on configuring WebSphere MQ in Mule, see WebSphere MQ
Integration.


This page describes how to start and stop Mule from a Java application or to embed it in a Webapp (such
as a JSP or servlet), and how to interact with Mule from your code in both scenarios.
Starting Mule from a Java Application
To start Mule from any Java application, you can call one of its configuration builders. To use Mule XML
configuration:
DefaultMuleContextFactory muleContextFactory = new DefaultMuleContextFactory();

SpringXmlConfigurationBuilder configBuilder = new SpringXmlConfigurationBuilder("mule-config.xml");
muleContext = muleContextFactory.createMuleContext(configBuilder);
Make sure you store a reference to the MuleContext, as you will need it to stop Mule.
If you have multiple configuration files, you can provide a comma-separated list or an array of
configuration files:
SpringXmlConfigurationBuilder configBuilder =
new SpringXmlConfigurationBuilder(new String[] { "mule-config.xml", "another-config.xml" });
You then call the start method to start the server:
Stopping Mule from a Java Application
To stop Mule, you stop its context like this:
muleContext.stop();
muleContext.dispose();
Embedding Mule in a Webapp
To embed Mule inside a webapp, you provide one or more configuration file locations as context params
and include a context listener to initialize the Mule Server. If you are using Mule XML configuration, use
the following -
<context-param>
<param-name>org.mule.config</param-name>
<param-value>mule-config-main.xml,mule-components.xml</param-value>
</context-param>
<listener>
<listener-class>org.mule.config.builders.MuleXmlBuilderContextListener</listener-class>

</listener>
The configuration parameter can be a classpath location or file location. You can also specify multiple
configuration files on the classpath or on the file system.
Interacting with Mule from Your Code
To interact with the Mule server from your application, JSP, or servlet, you can use the Mule Client.
//create a client
MuleClient client = new MuleClient();
//send a jms message asynchronously

client.dispatch("jms://my.queue", "some data", null);
//or to receive a pop3 message via a configured mailbox

MuleMessage message = client.receive("pop3://myInboxProvider", 3000);
//or synchonous send a inter-vm message

MuleMessage message2 = client.send("vm://my.object", "Some more data", null);

JBoss Integration
Deploying Mule to JBoss

The recommended approach for integrating with enterprise application deployed in JBoss is to deploy
Mule as a standalone application and use the Mule EJB Transport or components configured using
spring EJB proxies (http://static.springframework.org/spring/docs/2.5.x/reference/ejb.html using to
integrate with your EJB's in JBoss. If you need to deploy Mule in the JBoss application server for other
reasons (e.g., to use JBoss clustering), use the instructions on this page. Note that if you are using JBoss
clustering, you cannot use stateful routers.
There are three main approaches you can take to deploying Mule to JBoss:
1. Simple WAR deployment: in this approach, you simply embed Mule in your application and build the
WAR. Your custom implementation classes are part of the WAR.
2. EAR application: you can embed the WAR inside the EAR file and include additional files such as
EJBs.
3. JCA deployment: you can use the Mule JCA Resource Adapter. The Mule JCA adaptor allows you to
use "JCA Message Inflow" to Message Driven Beans (MDB's) and use the Mule "ManagedConnection"
for tighter integration when sending message from your Jee application via Mule.
Classloader Isolation
When JBoss comes to classloading, unless classloader isolation is specified, JBoss will first try to use
its own classes for deployment and only when these are not found will it look for them in the libraries
of the deployment file. Since the versions of the libraries used to load Mule are not the same as the
ones used by JBoss, various errors such as ClassCastExceptions can appear, so classloading isolation is
important. Therefore, for best results, you should use classloader isolation in your JBoss configuration.
For more information, see http://wiki.jboss.org/wiki/ClassLoadingConfiguration. If you're using the JCA
adapter, and you have other applications running on JBoss, you should use classloader isolation. However,
classloader isolation is not supported for JCA deployment on JBoss. Therefore, you must wrap your JCA
adapter in an EAR and configure classloader isolation for the EAR.
Building an EAR File for the Deployment of the Mule JCA

Resource Adapter on JBoss 4.2.x
Although you can deploy the Mule JCA Resource Adapter directly, the best way to deploy Mule on JBoss is
to place the resource adapter inside an EAR file. The advantages of this approach over using the Mule JCA
Resource Adapter directly are the following:
• JBoss allows EAR, WAR, and SAR files to have classloader isolation. This feature is not yet available
for the RAR file.
• The Mule JCA Resource Adapter contained in the EAR file is specific for JBoss deployment.
• In order to avoid deployment issues with JBoss the mule-jboss-ds.xml file has to be moved from
the mule-module-jca-jboss-<muleVersion>.jar file up to the EAR level.
Adaptation of the RAR File for Use with the EAR File
In mule-jca-jboss-x.rar (where x is the Mule version number), you must remove mule-jboss-ds.xml
from mule-module-jca-jboss-2.x.jar. Note that if you are going to repackage mule-jca-jboss-x.rar,
repackage it in a simple zip file format instead of other compression formats.
Mule EAR File Structure
The file structure of the EAR file should have the following format:

META-INF
| - application.xml
| - jboss-app.xml
| - MANIFEST.MF
mule-jca-jboss-x.rar
mule-jboss-ds.xml
Mule EAR Configuration Files
Following are the configuration files for the XML files in the above file structure:
mule-jboss-ds.xml
<connection-factories>
<tx-connection-factory>
<jndi-name>mule/ConnectionFactory</jndi-name>
<local-transaction />
<track-connection-by-tx />
<rar-name>my-ear.ear#mule-jca-jboss-2.x.rar</rar-name>
<connection-definition>org.mule.module.jca.MuleConnectionFactory</connection-definition>
</tx-connection-factory>
</connection-factories>
The mule-jboss-ds.xml file is an adaptation of the one you removed from mule-module-jca-
jboss-2.x.jar. Note that because the RAR file is found inside the EAR, the name inside the <rar-name>
tag should be the EAR file name and the RAR file name separated by the # symbol. This will be your data
source.
application.xml

<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN" "http://
java.sun.com/dtd/application_1_3.dtd">
<application>
<display-name>mule-ear</display-name>
<description>EAR packaging for Mule Resource Adapter</description>
<module>
<connector>mule-jca-jboss-2.x.rar</connector>
</module>
</application>
This file is required for telling the EAR file to use mule-jca-jboss-2.x.rar as a connector, allowing it to
be deployed as a resource adapter.
jboss-app.xml
The following configuration file creates a loader-repository that loads the classes during the classloading
operation. The java2ParentDelegation property must be set to false to enable classloader isolation.
The configuration specifies mule-jboss-ds.xml as a service to be loaded.

<!DOCTYPE jboss-app PUBLIC "-//JBoss//DTD J2EE Application 1.4//EN" "http://www.jboss.org/j2ee/dtd/jboss-
app_4_0.dtd">

<jboss-app>
<loader-repository>org.mule:loader=mule-ear-2.1.0.ear
<loader-repository-config>
java2ParentDelegaton=false
</loader-repository-config>
</loader-repository>
<module>
<service>mule-jboss-ds.xml</service>
</module>
</jboss-app>
Deploying Your Application

The resource adapter comes configured with a dummy mule-config.xml file, which you will replace with
your own configuration file. You can physically replace the mule-config.xml file in the Mule JCA Resource
Adapter (mule-module-jca-core-2.x.jar) with your own, but if your POJOs are bundled in a JAR, you
can take the following more elegant approach:
1. Put the resource files (xslt, properties, etc.) in your JAR file (these should be picked up
automatically when Mule starts)
2. Create a folder in the root of the mule-jca-jboss-2.x.rar file and put your Mule configuration in
there. For the time being, let's call this folder "conf".
3. Edit the ra.xml file found in the mule-jca-jboss-2.x.rar META-INF folder and reference your
configuration file name as seen below.
Alternatively you can put your jar files with classes/resources that will be used by mule in your EAR, but
in order to do this you will need to add a "Class-Path" entry in the rar's MANIFEST.MF referencing the
required libraries.
<config-property-name>Configurations</config-property-name>
<config-property-type>java.lang.String</config-property-type>
<config-property-value>conf/my-config1.xml</config-property-value>
The <config-property-value> should contain a list of configuration files separated by a comma. The
"conf/" is the path name telling the loader to look at the conf folder found in the root of the RAR file. If
only the name of the configuration file is given, the loader will only look for the configuration file inside
the mule-module-jca-core-2.x.jar.
JBoss MQ Configuration
For information on configuring a JBoss JMS connector, see JBoss Jms Integration.
Scenarios your User Application with Mule in JBoss

For this scenario, the deployment is very simple: you simply add your own JAR and WAR archives to you
EAR file. Because everything will be deployed in the same EAR, all the classes required by both the user
application and Mule share the same classloader. However sometimes other classes may be required that
are not deployed within your EAR..
Resolving Cross-dependencies
The situation becomes more complex when you want to deploy Mule-dependent code in a separate EAR
file (for example, you have a custom transformer that extends Mule's AbstractTransformer class). The
user EAR depends on the Mule libraries to be loaded to be able to load the custom transformer library,
while Mule expects the user EAR to be loaded to be able to use the transformer class that is found in
the user EAR. To solve these cross-dependencies, you can create a shared library (in another EAR file,
perhaps) and specify the library in the <loader-repository> element of the jboss-app.xml file in

both the Mule EAR and the user EAR. Mule Enterprise Edition users can see an example of this in the
Knowledge Base article titled "Embedding in JBoss: How to Share Classes Between Your Mule EE EAR and
Another Application".

Mule as MBean
Mule as MBean
[ Creating a Simple MBean ] [ Creating JBoss Service Descriptor ] [ Deploying MBean to JBoss ] [ Copy
the Dependencies ] [ References ]
An MBean is a named managed object representing a resource in an JMX environment. You can easily
deploy an MBean with Mule by taking the following steps:
1. Create an MBean
2. Create service descriptor
3. Deploy MBean (as .sar) to application server
4. Copy dependencies to the service's classpath
This page describes these steps using the JBoss application server.
Creating a Simple MBean

To create an MBean, you need an interface and an implementation:
package foo.mbean;
public interface FooServiceMBean {

public String getBar();
public void start();
public void stop();
}
package foo.mbean;
import org.jboss.system.ServiceMBeanSupport;
import org.mule.config.spring.SpringXmlConfigurationBuilder;
import org.mule.api.MuleContext;
import org.mule.api.context.notification.ServerNotification;
public class FooService extends ServiceMBeanSupport implements FooServiceMBean{
public String getBar() {

return "bar";
}
public void start() {

this.getLog().info("MBean being started");
try{
MuleContext context = new DefaultMuleContextFactory().createMuleContext
(new SpringXmlConfigurationBuilder("foo-config.xml"));
context.registerListener(this);
context.start();
}
catch(Exception e){
e.printStackTrace();
}
this.getLog().info("MBean started");
}

public void stop() {
this.getLog().info("MBean being stopped");
try {
if (context != null) {
context.stop();
context.dispose(); //
}
this.getLog().info("Done stopping Mule MBean Service!");
}
catch (Exception ex) {
this.getLog().error("Stopping Mule caused and exception!", ex);
}
}
}
The extension of ServiceMBeanSupport is simply to provide you more control over the API provided by
JBoss.
Creating JBoss Service Descriptor

You must create a service descriptor and add it to to META-INF/. Following is a simple example:

<server>
<mbean code="foo.FooService" name="foo:service=Foo">
</mbean>
</server>
Deploying MBean to JBoss

Based on the examples above, your distribution looks like this:
.
./foo
./foo/FooService
./foo/FooServiceMBean
./META-INF
./META-INF/jboss-service.xml
Package the distribution either as a JAR, which you can then rename to a *.sar that you will eventually
extract, or as a directory called <dirName>.sar.
Copy the Dependencies

Follow the steps below to copy the dependencies and complete the deployment:
1. Copy your <dirName>.sar/ directory to JBOSS_HOME/server/default/deploy/.

2. Copy all dependencies of Mule, such as MULE_HOME/lib/*/*.jar to the <dirName>.sar/ directory
3. Start JBoss. You will see the MBean appears in its MBean console.

References
• Wikipedia - MBean
• The Java Tutorials - Standard MBeans

Developing Service Components
Developing Service Components

[ Entry Point ] [ Default Message Flow Behavior ] [ Customizing the Message Flow Behavior ] [
Component Lifecycle ]
When developing service components, you focus on developing code to handle the business logic, not
to integrate the service component with Mule. For example, if you are developing a service component
that adds customer data to an invoice, you focus on writing code that queries the customer database
and updates the invoice as needed. You do not have to write any special code to handle the message
that's passed to the service component or to integrate with Mule, as all integration is handled through
configuration. You can develop the service component as a POJO, or as a web service using popular
containers such as Spring, EJB, or Plexus.
Mule does allow you to enable service components to obtain information about or even control the current
message instead of just working with the message payload. To enable the service component to work
directly with the message, you must implement the Callable() interface in the service component (see
Entry Points below).
To get started with developing Mule service components, you can use the Mule IDE. The Mule IDE is an
Eclipse plug-in that provides an integrated development environment for developing Mule applications.
You can also use the standard components provided with Mule, or use them as a starting point for
building your own.
Entry Point
The entry point is the method in your component that is invoked by Mule when a message is received. To
specify the method explicitly on your endpoint, you can use the method argument on the endpoint, such
as:
<outbound-endpoint address="ejb://localhost:1099/SomeService?method=remoteMethod"/>
or
<ejb:endpoint host="localhost" port="1099" object="SomeService" method="remoteMethod"/>
If you do not specify this argument, Mule uses an entry point resolver to dynamically choose the method
to invoke based on the payload type of the message. When the match is found, the method is cached
with the parameter types so that introspection is only done once per method for the life of the service. If
multiple methods in the component match the payload type, or no method matches, an error is thrown.
You can also call a method on the component that has no arguments.
Alternatively, your component can implement the org.mule.api.lifecycle.Callable interface. If your

component implements this interface, it will override any dynamic resolution and call the interface
method implementation instead.
For details on configuring entry point resolvers, see Entry Point Resolver Configuration Reference.
Legacy Entry Point Resolver Set
The LegacyEntryPointResolverSet that is used if no other resolver is configured. The

LegacyEntryPointResolverSet provides generic entry point resolution as follows:
1. Use the "method" attribute as described above, if one is specified (see

MethodHeaderPropertyEntryPointResolver ).
2. If the component implements the org.mule.api.lifecycle.Callable lifecycle interface, use the
onCall(MuleEventContext) method to receive the message.
3. If the component has a transformer configured for it, the return type for the transformer will
be matched against methods on the component to see if there is a method that accepts the

transformer return type. If so, this method will be used. Note if there is more than one match, an
exception will be thrown.
4. The message type (without transformer) will be matched against methods on the component to see
if there is a method that accepts the transformer return type. If so, this method will be used. Note if
there is more than one match, an exception will be thrown.
5. If none of the above finds a match, an exception will be thrown and the component registration will
fail.
There are many scenarios where the LegacyEntryPointResolverSet is unsuitable. More control is available
by extending its set of implementations, or by configuring a completely new set. There are several
EntryPointResolver implementations, such as org.mule.model.resolvers.CallableEntryPointResolver
, org.mule.model.resolvers.MethodHeaderPropertyEntryPointResolver , and
org.mule.model.resolvers.ReflectionEntryPointResolver . While these are used in the
LegacyEntryPointResolverSet, they can be more comprehensively configured when specified separately.
Calling No-arguments Methods
If you want to call a method with no arguments, you can use the
org.mule.model.resolvers.NoArgumentsEntryPointResolver . Regardless of the payload of the
current message, this resolver looks only for no-argument methods in the component. Additionally,
ReflectionEntryPointResolver supports the resolution of no-argument service methods if the payload
received is of type NullPayload.
Custom Entry Point Resolver
If you want to create your own entry point resolver, you create a class that implements the
EntryPointResolver interface and specify it with the <custom-entry-point-resolver> element in your
Mule configuration.
Default Message Flow Behavior

Mule has some default behavior rules about managing message flow to and from your component.
1. When a message is received, the entry point method is invoked as described above.
2. The response or outbound message is obtained as follows:
• If the method invoked is not void, (that is, Callable.onEvent() returns an Object), the method
return value is used. If null is returned, no further processing is done for the current request.
• If the method is void, the parameters used to invoke the method are used. This assumes that
the parameters themselves were altered or there was no change to the message.
3. If the inbound endpoint used in synchronous then the result of the component invocation is returned
to caller.
4. The outbound message is then routed according the services <outbound> configuration:
See Mule Messaging Styles for more detail about the different configuration options that affect message
flow.
Customizing the Message Flow Behavior

To customize the message flow behavior, you must get a reference to org.mule.api.MuleEventContext .
You can get the reference by implementing the Callable interface, which passes the event context as a
parameter on this interface:
public interface Callable

{
public Object onCall(MuleEventContext eventContext) throws Exception;
}

From the MuleEventContext, you can send and receive events synchronously and asynchronously,
manage transactions, and override the default event flow behavior. For example:
MuleEventContext context = RequestContext.getEventContext();

OutboundEndpoint endpoint = ...
//to send asynchronously

context.dispatchEvent(new MuleMessage("IBM:0.01", null), endpoint);
//or to request
InboundEndpoint endpoint = ...
MuleMessage quote = context.request(endpoint, 5000);
Even when you use the event context to manually control event flow, when your method returns, Mule
will route the outbound event as normal. You can stop Mule processing events further as follows:
• If your service method is not void, you can return null. This approach tells Mule there is no further
event information to process.
• If your service method is void, Mule will use the inbound message payload as the outbound message
payload. You can override this behavior using the setStopFurtherProcessing method as described
below.
Halting Message Flow
To halt the message flow, you can either call setStopFurtherProcessing() from the MuleEventContext
or else throw an exception. This will cause the ExceptionStrategy on the component to be invoked.
Note:
The use of additional services or the use of component bindings is much preferred to the above
techniques to control message flow from within your component implementation. This is because it allows
for a much more decoupled implementation that can be modified via your configuration file and avoids
the need to use Mule API in your component implementations. To take this approach, do one of the
following:
• Ensure your service components are implemented in such a way that they do a single unit of work
that do not need to do any message sending/receiving. This additional sending/receiving/routing is
then done using Mule services.
• Design your component in such a way that interface methods can be mapped to outbound endpoints
and then use bindings to map these in configuration. For information on how to configure bindings,
see Configuring Java Components.
Component Lifecycle
Your component can implement several lifecycle interfaces. The lifecycle flow typically looks like this, with
onCall() often being replaced by an entry point resolver as described above:

Following are the most commonly used interfaces:
• org.mule.api.lifecycle.Initialisable is called only once for the lifecycle of the component. It is called
when the component is created when the component pool initializes.
• org.mule.api.lifecycle.Startable is called when the component is started. This happens once when
the server starts and whenever the component is stopped and started either through the API or
JMX.
• org.mule.api.lifecycle.Stoppable is called when the component is stopped. This happens when the
server stops or whenever the component is stopped either through the API or JMX.
• org.mule.api.lifecycle.Disposable is called when the component is disposed. This is called once when
the server shuts down.
For more information, see the org.mule.api.lifecycle Javadocs .
If your custom component already has its own lifecycle methods, possibly implementing your own API, or
you just prefer not to depend on Mule's, you can implement and configure a LifecycleAdaptorFactory
to map Mule's lifecyle to your component's lifecycle. To do this, you implement your own
org.mule.api.component.LifecycleAdaptorFactory and org.mule.api.component.LifecycleAdaptor . See
Configuring Java Components for information on how to configure a custom life-cycle adaptor factory.

Entry Point Resolver Configuration Reference
Entry Point Resolver Configuration Reference

This page provides details on the elements you configure for entry point resolvers and entry point
resolver sets. This information is pulled directly from mule.xsd and is cached. If the information appears
to be out of date, refresh the page.
Entry Point Resolver Sets
<entry-point-resolver-set ...>
An extensible set of entry point resolvers. These determine how a message is passed to a component
in Java. Each entry point resolver is tried in turn until one succeeds in delivering the message to the
component. This element can be set on the model or component; the model value provides a default that
individual component values can override.
Attributes
Child Elements
abstract-entry- 0..* A placeholder for

point-resolver an entry point
resolver element.
Entry point
resolvers define
how payloads are
delivered to Java
code by choosing
the method to
call.
<legacy-entry-point-resolver-set ...>
An extensible set of entry point resolvers (which determine how a message is passed to a component in
Java) that already contains resolvers to implement the standard logic. This is already provided by default
and is only needed explicitly if it will be extended with other entry point resolvers. This element can be
set on the model or component; the model value provides a default that individual component values can
override.

Attributes
Child Elements
abstract-entry- 0..* A placeholder for

point-resolver an entry point
resolver element.
Entry point
resolvers define
how payloads are
delivered to Java
code by choosing
the method to
call.
<custom-entry-point-resolver-set ...>
A custom entry point resolver set. This allows user-supplied code to determine how a message is passed
to a component in Java. This element can be set on the model or component; the model value provides a
default that individual component values can override.
Attributes

implementation
of the
EntryPointResolverSet
interface.
Child Elements
<callable-entry-point-resolver ...>
An entry point resolver for components that implement the Callable interface. This passes a
MuleEventContext to the component. This element can be set on the model or component; the model
value provides a default that individual component values can override. This element can also be used
directly or as part of a set of resolvers; the resolvers in a set are used in turn until one is successful.

Attributes
Child Elements
<custom-entry-point-resolver ...>
A custom entry point resolver. This allows user-supplied code to determine how a message is passed to
a component in Java. This element can be set on the model or component; the model value provides a
default that individual component values can override. This element can also be used directly or as part
of a set of resolvers; the resolvers in a set are used in turn until one is successful.
Attributes

implementation
of the
EntryPointResolver
interface.
Child Elements
<property-entry-point-resolver ...>
Uses a message property to select the component method to be called. This element can be set on the
model or component; the model value provides a default that individual component values can override.
This element can also be used directly or as part of a set of resolvers; the resolvers in a set are used in
turn until one is successful.
Attributes
transformFirst boolean no Whether the

message should
be transformed
before being
delivered to the
component. By
default, messages
are transformed.

acceptVoidMethods boolean no Whether the
resolver should
call void methods.
By default, void
methods are
not considered
as possible
candidates for
message delivery.
property name (no spaces) no The name of the

message property
used to select a
method on the
component.
Child Elements
<method-entry-point-resolver ...>
Delivers the message to a named method. This element can be set on the model or component; the
model value provides a default that individual component values can override. This element can also be
used directly or as part of a set of resolvers; the resolvers in a set are used in turn until one is successful.
Attributes

message should
be transformed
before being
delivered to the
component. By
default, messages
are transformed.

resolver should
call void methods.
By default, void
methods are
not considered
as possible
candidates for
message delivery.
Child Elements
include-entry-point 1..* A possible method for delivery.

<reflection-entry-point-resolver ...>
Generates a list of candidate methods from the component via reflections. This element can be set on the
Attributes

message should
be transformed
before being
delivered to the
component. By
default, messages
are transformed.

resolver should
call void methods.
By default, void
methods are
not considered
as possible
candidates for
message delivery.
Child Elements
exclude-object-methods 0..1 If specified, methods in the Java

Object interface are not included
in the list of possible methods
that can receive the message.
exclude-entry-point 0..* Explicitly excludes a named

method from receiving the
message.
<array-entry-point-resolver ...>
Delivers the message to a method that takes a single array as argument. This element can be set on the

Attributes

message should
be transformed
before being
delivered to the
component. By
default, messages
are transformed.

resolver should
call void methods.
By default, void
methods are
not considered
as possible
candidates for
message delivery.
enableDiscovery boolean no true If no method

names are
configured,
attempts to
discover the
method to invoke
based on the
inbound message
type.
Child Elements


message.
<no-arguments-entry-point-resolver ...>
Calls a method without arguments (the message is not passed to the component).

Attributes

message should
be transformed
before being
delivered to the
component. By
default, messages
are transformed.

resolver should
call void methods.
By default, void
methods are
not considered
as possible
candidates for
message delivery.
enableDiscovery boolean no true If no method

names are
configured,
attempts to
discover the
method to invoke
based on the
inbound message
type.
Child Elements


message.
<include-entry-point ...>
A possible method for delivery.

Attributes
method name no The name of the

method.
Child Elements

Error Handling
Error Handling
Error handling includes setting exceptions on models, components, and connectors. Additionally, you
can use exception routers to specify where the message goes when an error occurs. This page describes
these strategies and routers. For details on configuring exception strategies, see Exception Strategy
Configuration Reference. For information on setting retry policies, see Configuring Retry Policies.
Exception Strategies
Exception strategies are used to handle exception conditions when an error occurs processing a message.
Exception strategies are used by components and connectors. You can set a common exception strategy
for all components in a model by configuring the exception strategy on that model.
Cannot resolve external resource into attachment.
Exception strategies associated with components or the model are used to handle component exceptions.
These are typically business logic exceptions.
The user will often want to customize the exception handler to control how these exceptions are logged
and routed.
Exceptions strategies associated with the connector handle exceptions thrown when events are received
or sent using a connector. It is less common that these strategies will be customized by the developer,
but they may be configured to route exceptions to a common error queue.
Model and Component Exception Strategies
The default exception strategy used by the model (and thus all components managed by the model)
is org.mule.service.DefaultServiceExceptionStrategy , which you configure with the <default-service-
exception-strategy> element. To configure it at the model level, add the element before the services:
<model name="CreditCheck">
<vm:outbound-endpoint path="systemErrorHandler"/>
<service> ... </service>
<service> ... </service>
</model>
To configure it on a service, add it at the end of the service:
<model name="CreditCheck">
<service>
...
<vm:outbound-endpoint path="systemErrorHandler"/>
</service>
</model>
You set an endpoint on an exception strategy to forward the message that failed to a destination such as
an error queue.

To implement your own strategy, your class can extend org.mule.AbstractExceptionListener , but a
recommended approach is to extend org.mule.service.DefaultServiceExceptionStrategy and just overload
the defaultHandler() method. Bean properties can be set on your custom exception strategy in the
same way as other Mule configured objects using a <properties> element.
It is up to the defaultHandler() method to do all necessary processing to contain the exception, so an

exception should never be thrown from an exception strategy. The exception strategy must manage fatal
errors. For example, if an error queue is being used but the dispatch fails, you might want to stop the
current component and fire a server notification to alert a system monitor and write the event to file.
If you want to change the way exceptions are logged, override the logException() method from the
org.mule.AbstractExceptionListener .
Connector Exception Strategies
The default exception strategy used by a connector is org.mule.DefaultExceptionStrategy , which you

configure with the <default-exception-strategy> element. This strategy simply logs exceptions and
continues. The exceptions this strategy must handle are typically connection-related exceptions that may
or may not be recoverable.
Using an Exception Router

When an exception occurs, the exception router org.mule.routing.outbound.ExceptionBasedRouter
determines where the message goes. You can have multiple endpoints specified on the exception router,
so that if the first endpoint fails with a FatalConnectionException, the next endpoint is tried, and then
the next. If all endpoints fail, an org.mule.api.routing.RoutingException is thrown. Note that the exception
router will override the endpoint mode to synchronous while looking for a successful send, and it will
resort to using the endpoint's mode for the last item in the list.
Following is an example of configuring an exception router:
<outbound-router>
<router className="org.mule.routing.outbound.ExceptionBasedRouter">
<endpoint address="tcp://10.192.111.10:10001" />
<endpoint address="tcp://10.192.111.11:10001" />
<endpoint address="tcp://10.192.111.12:10001"/>
</router>
</outbound-router>

Functional Testing
Functional Testing
[ FunctionalTestCase ] [ FunctionalTestComponent ] [ Additional Features ] [ Additional Example: Event
Callback With a Spring Component ]
Because Mule is light-weight and embeddable, it is easy to run a Mule Server inside a test case. Mule
provides an abstract JUnit test case called org.mule.tck.FunctionalTestCase that runs Mule inside a test
case and manages the lifecycle of the server. The org.mule.tck.functional package contains a number of
supporting classes for functionally testing Mule code, including FunctionalTestComponent . These classes
are described in more detail in the following sections.
FunctionalTestCase
FunctionalTestCase is a base test case for Mule functional tests. Your test cases can extend
FunctionalTestCase to use its functionality.
FunctionalTestCase fires up a Mule server using a configuration you specify by overriding the
getConfigResources():

{
return "mule-conf.xml";
}
You can use the method getConfigResources to specify a configuration file or comma-
separated list of configuration files to use. All configuration files must exist in your
classpath.
You then create tests that interact with the Mule server. FunctionalTestCase extends
junit.framework.TestCase, so JUnit the framework for creating and running your test cases. For
example, this simple test would send a message to a vm endpoint .
public void testSend() throws Exception

{
String payload = "foo";
MuleMessage result = client.send("vm://test", new DefaultMuleMessage(payload));
assertEquals("foo Received", result.getPayloadAsString());
}
Notice the use of MuleClient to interact with the running Mule server. MuleClient is used to send
messages to and receive messages from endpoints you specify in your Mule configuration file (mule-
conf.xml in this case). The example mule-conf.xml file used in this example is shown below:


beans-2.5.xsd
mule.xsd
mule-vm.xsd
mule-test.xsd">
<model name="TestComponentModel">
<service name="TestComponentService">
<inbound>
<inbound-endpoint address="vm://test"/>
</inbound>
<test:component appendString=" Received"/>
</service>
</model>
</mule>
FunctionalTestComponent
The previous example of FunctionalTestCase covers many common (synchronous) test scenarios, where
the service responds directly to the caller. FunctionalTestComponent can help support richer tests, such
as:
1. Simulating asynchronous communication

2. Returning mock data to the caller
3. Common scenarios such as forced exceptions, storing message history, appending text to responses,
and delayed responses.
The component includes two methods: the onCall method and the onReceive method that basically do
the same thing.
• onCall: receives a MuleEventContext as input and returns an Object.

• onReceive: receives an Object as input and returns an Object.
In both methods, FunctionalTestComponent takes the message that is passed to it (either from the
MuleEventContext or from the Object) and transform it into a String. It then creates a message and
sends it back to the caller. It also checks whether any of its properties are set and acts accordingly.
Asynchronous Tests with FunctionalTestComponent
The FunctionalTestComponent supports two event mechanisms for responding to a caller

asynchronously: event callbacks and notifications. Both event callbacks and notifications fire events
that get handled by registered listeners. During functional testing, the listener will typically be a class
accessible in the FunctionalTestCase.
Event Callbacks
User-defined event callbacks get called when the test component is invoked. Following is an example of a
test case and Mule configuration that uses callbacks:
public void testEventCallback() throws Exception

{
EventCallback callback = new EventCallback()
{
public void eventReceived(MuleEventContext context, Object component)
throws Exception
{
System.out.println("Thanks for calling me back");
}

};
DefaultJavaComponent defaultComponent = (DefaultJavaComponent)

muleContext.getRegistry().lookupService("TestComponentService").getComponent();
FunctionalTestComponent testComponent = (FunctionalTestComponent)
defaultComponent.getObjectFactory().getInstance();
testComponent.setEventCallback(callback);
client.send("vm://test", new DefaultMuleMessage("foo"));
In this example, the eventReceived callback method is invoked as soon as the

FunctionalTestComponent receives the message, and a message is printed to the console. Test
assertions could be made in this method.
The corresponding Mule configuration used in this example is as follows:

beans-2.5.xsd
mule.xsd
mule-vm.xsd
mule-test.xsd">
<inbound>
<inbound-endpoint address="vm://test"/>
</inbound>
<component>
<singleton-object class="org.mule.tck.functional.FunctionalTestComponent"/>
</component>
</service>
</model>
</mule>
Notice that in this configuration, we did not use the "<test:component>" element, since we need
FunctionalTestComponent to be singleton for the callback to work properly.
For an example of an event callback on a Spring component, see the additional example below.
Notifications
Notifications are an alternative to event callbacks. When an event is received, the

FunctionalTestComponent fires a notification informing us that the event has been received. It is up
to us to set up a listener (the FunctionalTestNotificationListener) on our test to capture this
notification.

To do this, we must first make our test case implement the FunctionalTestNotificationListener
interface. Then, we must implement the method exposed by this listener, which is onNotification.
In the example below, we check notification.getAction to see whether it is the
FunctionalTestNotification fired by the FunctionalTestComponent. If it is, we print it out to the
console.
public void onNotification(ServerNotification notification)

{
if (notification.getAction() == FunctionalTestNotification.EVENT_RECEIVED)
{
System.out.println("Event Received");
}
}
Now, in order for our listener to start listening for notifications, we must register it:
muleContext.registerListener(this,"myComponent");
Returning Mock Data from FunctionalTestComponent
FunctionalTestComponent can return mock data specified either in a file or embedded in the Mule
configuration. For example, to have the FunctionalTestComponent return the message "donkey", you
would configure the component as follows:
<test:component>
<test:return-data>donkey</test:return-data>
</test:component>
To return contents from a file, you could use:
<test:component>
<test:return-data file="abc.txt"/>
</test:component>
The file referenced should exist on the Mule classpath.
Other Useful Features of FunctionalTestComponent
Forcing Exceptions
You can use throwException to always return the exception specified by exceptionToThrow, as follows:
<test:component throwException="true" exceptionToThrow="your.service.exception"/>
Storing Message History
By default, every message that is received by the FunctionalTestComponent is stored and can be
retrieved. If you do not want this information stored, you can set enableMessageHistory to false. For

example, if you are running millions of messages through the component, an out-of-memory error would
probably occur eventually if this feature were enabled.
To enable:
<test:component enableMessageHistory="true" />
Messages are stored in an ArrayList. To retrieve a stored message, you use the getReceivedMessage
method to retrieve it by number (e.g., getReceivedMessage(1) to retrieve the first message stored),
or use getLastReceivedMessage to retrieve the last message that was received. You can use
getReceivedMessages to return the total number of messages stored.
Appending Text to Responses
You can use appendString to append text to the response message, as follows:
Delayed Responses
You can set waitTime to delay responses from this FunctionalTestComponent. In this example,
responses are delayed five seconds:
<test:component waitTime="5000" />
Disable Inbound Transformer
You can set doInboundTransform to false to disable the inbound transformer. For example:
<test:component doInboundTransform="false" />
Additional Features
The functional package includes several additional classes, such as CounterCallback, a test callback
that counts the number of messages received. For complete information, see the org.mule.tck.functional
Javadoc.
Additional Example: Event Callback With a Spring Component

This example is identical to the "Event Callbacks" example above, except the component used here is a
Spring component. In this case, we can look up the component using the Spring registry (although using
the Mule registry as in the original example also works).
public void testEventCallback() throws Exception

{
EventCallback callback = new EventCallback()
{
public void eventReceived(MuleEventContext context, Object component)

throws Exception
{
System.out.println("Thanks for calling me back");
}
};
ApplicationContext ac =
(ApplicationContext)muleContext.getRegistry().lookupObject(SpringRegistry.SPRING_APPLICATION_CONTEXT);
FunctionalTestComponent testComponent = (FunctionalTestComponent) ac.getBean("FTC");
testComponent.setEventCallback(callback);
client.send("vm://test", new DefaultMuleMessage("foo"));
The corresponding Mule configuration would be as follows:

beans-2.5.xsd
mule.xsd
mule-vm.xsd
mule-test.xsd">
<spring:bean id="FTC" class="org.mule.tck.functional.FunctionalTestComponent" />
<inbound>
<inbound-endpoint address="vm://test" />
</inbound>
<component>
<spring-object bean="FTC" />
</component>
</service>
</model>
</mule>

Internationalizing Strings
Internationalizing Strings
[ Internationalized Messages ] [ Exceptions ] [ Using Custom Message Bundles ] [ Creating Message
Instances from your Code ]
Mule supports internationalization of exception messages and any other type of string message. Mule has
support for the following Languages:
• English
• Japanese
Internationalized Messages
Mule uses the Java ResourceBundle class to load messages from properties files on the classpath based
on the current system's locale. Mule provides a full set of messages in English and Japanese only, but
there may be additional languages provided in the future.
Mule's internationalized messages are represented by the org.mule.config.i18n.Message class. Instances

are constructed with a message ID and zero or more message parameters. You can see a list of core
messages that Mule provides in META-INF/service/org/mule/i18n/core-messages.properties.
You never create instances of Message directly. Instead, you use subclasses of MessageFactory . The
messages for Mule's core project are accessible through the org.mule.config.i18n.CoreMessages class.
Each of Mule's modules and transports has such a messages class. Its name is equal to the module with
Messages appended. For example, for the JMS transport you will use JmsMessages to retrieve messages.
The dedicated messages class per module/transport has the following advantages:
• Encapsulation of the message code

• Client code is not cluttered with Message constructors
• Client code has typesafe access to its messages
• Client code is not cluttered with formatting of message parameters. Instead, you handle tihs in the
module-specific messages class
Exceptions
MuleException is the base class of all Mule checked exceptions and can only be constructed using
internationalized messages. To create a message for an exception, you use MuleExtension as follows:
MuleException e = new MuleException(CoreMessages.failedToGetPooledObject());

throw e;
Using Custom Message Bundles

When writing Mule extensions or applications that will use the Mule internationalization class, you can
supply custom message bundles containing messages specific to your extension or application. You create
a resource bundle as follows:
1=Error message one

2=Error message with 2 parameters; param {0} and param {1}

...
where the number is the message ID and the actual message comes after. Note that message parameters
are specified using '{0}' notation, which is standard when using the Java MessageFormat class.
The file should be named x-messages.properties where x is the identifying name for this bundle.
You must place this file either in your JAR file under META-INF/services/org/mule/i18n/x-
messages.properties or any other location on the classpath.
To access the messages of your own resource bundle, you create a subclass of MessageFactory as
follows:
public class MyMessages extends MessageFactory

{
// getBundlePath puts together the correct path (META-INF/services/org/mule/i18n/my-
messages.properties)
private static final String BUNDLE_PATH = getBundlePath("my");
public static Message errorMessageOne()

{
return createMessage(BUNDLE_PATH, 1);
}
public static Message anotherErrorMessage(Object param1, Object param2)

{
createMessage(BUNDLE_PATH, 2, param1, param2);
}
}
To load a message from this bundle, pass in the resource bundle name as follows:
Message m = MyMessages.anotherErrorMessage("one", "two");

System.out.pritln(m.toString());
This loads the message with ID 2 from x-messages.properties, formats the message with the
parameters "one" and "two", and prints out the message to System.out as follows:
Error message with 2 parameters; param one and param two
Creating Message Instances from your Code

If you need Message instances from your custom code (e.g., from a custom transformer), you create
them as follows:
Message myMessage = MessageFactory.createStaticMessage("Oops");

Introduction to Extending Mule
Introduction to Extending Mule

[ Creating Extensions ] [ Developing Your Extension ] [ Promoting Your Extension on MuleForge ] [
Internationalizing Mule ]
Mule provides a great deal of default functionality that you can use in your implementation. If you need
different functionality, you can extend Mule as described on this page.
Creating Extensions
There are four types of extensions you can create: projects, modules, transports, and examples.
• A project is a stand-alone Mule application, such as the Mule IDE.
• A module is a package of related functionality in Mule, such as the XML module, which provides
XML-based utilities such as filters and routers. For a list of the available modules you can use, see
Using Mule Modules.
• A transport is a type of module that carries messages between Mule services via a specific
protocol. For a list of the available transports you can use, see Available Transports.
• An example is a sample application that you create to help users get up and running more quickly.
There are several examples provided with Mule.
Mule provides Maven archetypes that create the templates for each of these types of functionality in
seconds, including the configuration files, unit tests, and packages:
• Project Archetype
• Module Archetype
• Transport Archetype
• Example Archetype
An archetype acts as a wizard, prompting you to provide input, and then creates template configuration,
source, and unit test files. Furthermore, if you run an archetype on an existing project or module you
created, it will update it for you. For more information on Maven, see Using Maven.
When working with transports, note that you can configure an existing transport, or you can create a new
one. The recommended approach is to try to use and configure an existing transport first.
Developing Your Extension

After using the Maven archetype to get started, the recommended practice is to use an integrated
development environment (IDE) such as Eclipse or IntelliJ to develop your Mule project, transport,
module, or example. The Mule IDE allows you to quickly get up and running developing with Mule in
Eclipse. For more information, see Using IDEs.
Promoting Your Extension on MuleForge

After you have created a new extension, you can submit it as a project on MuleForge. This allows you
to share it with the Mule community so you can get feedback on the quality and design of the module
before putting it into production. By submitting to MuleForge, you get the benefit of others trying out
your module, and others get the benefit of your work. For more information, see About MuleForge.

Internationalizing Mule
If you will use Mule in countries where English is not spoken, you can extend Mule by internationalizing
the strings in the messages and exceptions. Additionally, there are guidelines you should take
into consideration to make sure your code handles different locales. For more information, see
Internationalizing Strings and Internationalization Guidelines.

Introduction to Testing Mule
Introduction to Testing Mule

This page describes the types of testing you can perform on Mule.
Functional and Unit Tests

When you configure and customize Mule, you perform the following types of tests:
• Functional testing of your Mule configuration and setup

• Unit testing of your simple extensions and customizations
• Functional and unit testing of your custom modules and transports
Mule provides functional test classes in the org.mule.tck and org.mule.tck.functional packages
that allow you to test your configuration as well as your custom modules and transports. For more
information, see Functional Testing. Additionally, the Mule test JAR file contains abstract test cases
that you can use for unit testing your simple extensions (e.g., AbstractTransformerTestCase
and AbstractOutboundRouterTestCase) as well as your custom modules and transports (e.g.,
AbstractConnectorTestCase, AbstractReceiverTestCase, AbstractDispatcherTestCase, and
AbstractEndpointTestCase). For more information, see Unit Testing.
Performance Tests
After you have ensured that your setup and configuration are correct and that your customizations are
working, you should ensure that your system is performing correctly. You can run Japex benchmark tests
to test individual packages. Additionally, the Mule Profiler Pack helps you identify memory leaks in your
customizations.
Using MuleForge for Continuous Integration Testing

If you host your Mule project on MuleForge, you can take advantage of continuous integration testing.
MuleForge projects are configured to be automatically built using Bamboo, a Continuous Integration Build
Server from Atlassian. The source code build frequency is set to 30 minutes, while the snapshot build
frequency is set to 1 day. You can request that these frequencies be changed for your project.
For more information on hosting your project on MuleForge, see the Despot's Guide.

Jmx Management
JMX Management
[ Using the Default JMX Support Agent ] [ Jmx Default Config ] [ Configuring the JMX Agent ] [ Jmx
Server ] [ Remote Management ] [ JMX Notifications Agent ] [ Endpoint Notifications Publisher Agent ] [
Log4J Agent ] [ Log4J Notifications Agent ] [ Chainsaw Notifications Agent ] [ MX4J Adapter ] [ Jmx Mx4j
Adaptor ] [ YourKit Profiler ]
Java Management Extensions (JMX) is a simple and standard way to manage applications, devices,
services, and other resources. JMX is dynamic, so you can use it to monitor and manage resources as
they are created, installed, and implemented. You can also use JMX to monitor and manage the Java
Virtual Machine (JVM).
Each resource is instrumented by one or more Managed Beans, or MBeans. All MBeans are registered in
an MBean Server. The JMX server agent consists of an Mbean Server and a set of services for handling
Mbeans.
There are several agents provided with Mule for JMX support. The easiest way to configure JMX is to use
the default JMX support agent.
Using the Default JMX Support Agent

You can configure several JMX agents simultaneously using the <jmx-default-config> element. When
set, this element registers the following agents:
• JMX agent
• RMI registry agent (if necessary) on rmi://localhost:1099
• Remote JMX access on service:jmx:rmi:///jndi/rmi://localhost:1099/server
• Log4J JMX agent, which exposes the configuration of the Log4J instance used by Mule for JMX
management
• JMX notification agent used to receive server notifications using JMX notifications
• (Optional) MX4J adapter, which provides web-based JMX management, statistics, and configuration
viewing of a Mule instance
This element includes the following properties:
Jmx Default Config
Attributes of <jmx-default-config...>
registerMx4jAdapter boolean no Whether to enable

the MX4J adaptor.
host string no The host to bind

to. Normally,
override this only
for multi-NIC
servers (default is
localhost).
port port number no The port on

which the RMI
registry will run.
This is also used

for remote JMX
management.
Default is 1099.
Child Elements of <jmx-default-config...>
credentials 0..1 A map of username/password

properties for remote JMX
access. The configuration option
delegates to the JmxAgent.
For example:

xmlns:management="http://www.mulesource.org/schema/mule/management/2.1"
http://www.mulesource.org/schema/mule/management/2.1
http://www.mulesource.org/schema/mule/management/2.1/mule-management.xsd">
<management:jmx-default-config port="1098" registerMx4jAdapter="true">
<management:credentials>
<spring:entry key="jsmith" value="foo"/>
<spring:entry key="dthomas" value="bar"/>
<spring:entry key="clee" value="pwd"/>
</management:credentials>
</management:jmx-default-config>
</mule>
Note: you only specify the port if you don't want to use the default of 1099.
The default agent does a lot of useful plumbing for JMX but at the expense of defaulting many
parameters. If you need to customize some subsystems, you could either:
• Subclass DefaultJmxSupportAgent and override the corresponding createXXX() factory methods.

• Disassemble the services provided by this support agent into separate agents and configure them
individually.
Configuring the JMX Agent

The JMX agent enables the configuration of a local or remote JMX connection to Mule and registers
Mule services with the MBean server. You can then use JMX to view the configuration state of the
Mule Manager, stop and start the Mule instance, stop and start services, stop/start/resume service
components, and query event processing and endpoint routing statistics on individual services or the
whole server instance.
You configure the JMX agent using the <jmx-server> element. You can set the following properties on the
agent.

Jmx Server
Attributes of <jmx-server...>
server-ref name (no spaces) no The mBean server

to use.
locateServer boolean no true Whether the agent

should try locating
an MBeanServer
instance before
creating one.
createServer boolean no true Whether the

agent should
create an MBean
server if one
couldn't be found
or locateServer
was set to false.
enableStatistics boolean no true Whether statistics

reporting is
enabled for the
Mule instance.
Child Elements of <jmx-server...>
connector-server 0..1 Configures the remote JMX

connector server by specifying
the URL and whether to rebind.
credentials 0..1 A map of username/password

entries used to authenticate
remote JMX access. If not
specified, remote access is not
restricted.
For example:
<management:jmx-server >
<management:connector-server url="http://myjmxserver.com:1099" rebind="false" />
<spring:entry key="jsmith" value="foo" />
<spring:entry key="dthomas" value="bar" />
</management:jmx-server>
Note that the JMX domain for the Mule server is taken from the Mule server ID. To set the server ID, you
the -M-Dmule.serverId=YOUR_MULE_SERVER_ID system property or set it programatically by calling
org.mule.config.DefaultMuleConfiguration.setId().

Remote Management
You can configure the Mule JMX subsystem for remote management with third-party tools like MC4J. Mule
provides an RMI registry agent, which binds to an existing RMI registry or creates a new one on a defined
URI.
You configure the RMI registry agent using the <rmi-server> element. This element has two attributes:
serverUri, which you set to the URI of the RMI server (the
default is rmi://localhost:1099), and createRegistry, which you set to true if you want to create a new
registry instead of binding to an existing one.
For example:
<management:rmi-server serverUri="rmi://myServer.com:1099" createRegistry="true" />
JMX Notifications Agent

The <jmx-notifications> element configures the JMX notifications agent, which sends JMX server
notifications. This element takes the following attributes:
ignoreManagerNotifications Whether to ignore notifications for state changes

on the Mule manager such as initializing, starting,
and stopping.
ignoreModelNotifications Whether to ignore notifications for state changes

on models such as models initializing, starting,
and stopping or components being registered or
unregistered.
ignoreComponentNotifications Whether to ignore notifications for state changes

on components such as when a component is
started, stopped, paused, or resumed.
ignoreConnectionNotifications Whether to ignore notifications when a connector

attempts to connect to its underlying resource.
Notifications are fired when a connection is made,
released, or the connection attempt fails.
ignoreSecurityNotifications Whether to ignore notifications about security.
ignoreManagementNotifications Whether to ignore notifications for when a request

is denied security access.
ignoreCustomNotifications Whether to ignore notifications fired by objects to

custom notification listeners.
ignoreAdminNotifications Whether to ignore administrative notifications

about requests being received by the Mule Admin
agent. These are usually trigged by MuleClient
calls using the RemoteDispatcher, which proxies
calls to a remote server.
ignoreMessageNotifications Whether to ignore message notifications. These

notifications are fired when an event is sent or
received in the system. They are very good for

tracing, but they create a performance impact, so
they should only be used during testing.
For example:
<management:jmx-notifications ignoreAdminNotifications="true" ignoreMessageNotifications="true" />
Endpoint Notifications Publisher Agent

This agent routes server notifications to a specified endpoint URI. You configure it using the <publish-
notifications> element and specify the endpoint using the endpointAddress attribute. For example:
<management:publish-notifications endpointAddress="vm://myService" />
Log4J Agent
The log4j agent exposes the configuration of the Log4J instance used by Mule for JMX management. You
enable the Log4J agent using the <jmx-log4j> element. It does not take any additional properties.
For example:
<management:jmx-log4j/>
Log4J Notifications Agent

The Log4J notifications agent logs server notifications to a file or console using Log4J. You configure this
agent using the <log4j-notifications> element. It takes the same attributes as the JMX notifications
agent plus two additional attributes: logName, a name used to identify this log, and logConfigFile, the
name of the file where you want to output the log messages.
The Log4J notifications agent also takes the <level-mapping> child element, which takes one or more
pairs of severity/eventId attributes. The severity attribute specifies the severity level of the notifications
you want to log for the corresponding event ID. The severity level can be DEBUG, INFO, WARN, ERROR,
or FATAL. The eventId attribute specifies the type of event to log. The event ID is the notification type
plus the action, such as ModelNotification.stop.
For example:
<management:log4j-notifications logName="myMuleLog" logConfigFile="mule-log.txt">

<management:level-mapping eventId="ModelNotification.stop" severity="WARN"/>
</management:log4j-notifications>
Chainsaw Notifications Agent

The Chainsaw notifications agent logs server notifications to a Chainsaw console. You configure this agent
using the <chainsaw-notifications> element. It takes the same attributes as the JMX notifications
agent plus two additional attributes: chainsawHost and {chainsawPort}}, which specify the host name
and port of the Chainsaw console.

The Chainsaw notifications agent also takes the <level-mapping> child element, which takes one or
more pairs of severity/eventId attributes. The severity attribute specifies the severity level of the
notifications you want to send to the Chainsaw console for the corresponding event ID. The severity
level can be DEBUG, INFO, WARN, ERROR, or FATAL. The eventId attribute specifies the type of
event to send to the Chainsaw console. The event ID is the notification type plus the action, such as
ModelNotification.stop.
For example:
<management:chainsaw-notifications chainsawHost="localhost" chainsawPort="20202">

<management:level-mapping eventId="ModelNotification.stop" severity="WARN"/>
</management:chainsaw-notifications>
MX4J Adapter
MX4J is an open source implementation of the JMX technology. The MX4J agent for Mule configures an
MX4J HTTP adapter to provide JMX management, statistics, and configuration viewing of a Mule instance.
You configure the MX4J agent using the <jmx-mx4j-adaptor> element.
Jmx Mx4j Adaptor
Attributes of <jmx-mx4j-adaptor...>
jmxAdaptorUrl string no The URL of

the JMX web
console. The
default is http://
localhost:9999.
login string no The login name

for accessing the
JMX web console.

accessing the JMX
web console.
authenticationMethodnone/basic/digest no basic The type of

authentication
to perform when
the login and
password are
set: basic (the
default), digest, or
none.
cacheXsl string no true Indicates whether

to cache the
transformation
objects, which
speeds-up the
process. It is
usually set to
true, but you can

set it to false for
easier testing.
xslFilePath string no Specifies the path

of the XSL files
used to customize
the adaptor's
stylesheet. If
you specify a
directory, it
assumes that XSL
files are located
in the directory.
If you specify
a .jar or .zip file, it
assumes that the
files are located
inside. Specifying
a file system is
especially useful
for testing.
pathInJar string no If the xslFilePath

is a JAR file,
specifies the
directory in the
JAR where the
XSL files are
located.
Child Elements of <jmx-mx4j-adaptor...>
socketFactoryProperties 0..1 A map containing properties

for SSL server socket factory
configuration. If this element
contains at least one property,
the agent will switch to HTTPS
connections. These properties
will be delegated as is to the
agent's HTTP/S adaptor. For a
list of available properties, see
the MX4J API documentation.
For example:
<management:jmx-mx4j-adaptor jmxAdaptorUrl="https://myjmxserver.com:9999">
<management:socketFactoryProperties>
<spring:entry key="keystore" value="/path/to/keystore" />
<spring:entry key="storepass" value="storepwd" />
</management:socketFactoryProperties>
</management:jmx-mx4j-adaptor>
For security's sake, the management console is accessible from the localhost only. To loosen this
restriction, change "localhost" to "0.0.0.0", which allows access from any computer on the LAN. For more
information, see the MX4J documentation.

MX4J Security
You can protect the JMX web console with a user name and password. If the login property has been
specified, the authentication scheme is applied.
In addition to protecting the console, you can protect the in-transit data using SSL. If the
socketFactoryProperties element contains at least one property, the agent switches to HTTPS
connections. If this element is omitted from the configuration, the agent will always use HTTP, even if you
specify https:// in the jmxAdaptorUrl property.
Viewing Statistics
Mule traps many different statistics about the running state of a server and number of events processed.
You can view the Mule statistics report in the JMX Management Console by pointing your browser to
http://localhost:9999/ and then clicking on any JMX domain name (except for JMImplementation), or go
to the Statistics tab and query the JMX domain for statistics from there.
YourKit Profiler
This agent exposes the YourKit profiler to JMX to provide CPU and memory profiling. To use this agent,
you must configure the <yourkit-profiler> element as shown below, and you must install and run the
Profiler as described in Profiling Mule.

<management:yourkit-profiler />

Models
About Models
[ Configuring a Model ] [ Model Interface ]
A model is a grouping of services. A model manages the runtime behavior of the service components
that a Mule instance hosts. The manner in which these components are invoked and treated is all
encapsulated inside the current Mule model.
Configuring a Model
To configure a model, you add the <model> element to your Mule configuration file. You then add services
within the model. For configuration details, see the Model Configuration Reference.
Model Interface
Every Mule model implements the Model interface. This interface represents the behavior of a Mule server
and works with the following objects. For a complete list of fields and methods, see in the Model interface
org.mule.api.model.Model . Also, see org.mule.model.AbstractModel , which is an abstract class that
implements this interface and is the parent for all models.
Object Description
Name A string that refers to the name of the model and

is set as an attribute in the <model> element. If
no name is given, a unique value is generated
automatically.
ExceptionListener The exception strategy to use for the entire

model. The exception strategy is used to handle
any exceptions that occur when a component is
processing a message. For more information on
exception strategies, see Error Handling.
EntryPointResolverSet A set of classes that implement the

EntryPointResolver interface. These will be
used to determine the entry point for any hosted
component when a message is received. You
can configure an entry point resolver using the
<abstract-entry-point-resolver> element
or configure an entry point resolver set using
the <abstract-entry-point-resolver-set>
element. For more information on entry point
resolvers, see Developing Service Components.
LifecycleAdapterFactory Used by the model to create lifecycle adapters

that are needed to translate Mule lifecycle events
into messages that components registered with
the model understand. You configure the lifecyle
adapter on the <component> elements, not on
the model itself. For more information on lifecycle
adapters, see Developing Service Components.

Mule Agents
Using Mule Agents

[ Configuring an Agent ] [ Creating Custom Agents ]
An agent is a service that is associated with or used by Mule but is not a Mule-managed component.
Agents have the same lifecycle as the Mule instance they are registered with, so you can initialize and
destroy resources when the Mule instance starts or is disposed.
Mule provides several agents for JMX support, including notifications and remote management. You
can also create custom agents to plug any functionality into Mule, such as running functionality as a
background process or embedding a server in Mule.
Configuring an Agent
Agents are defined in the Management module. To use an agent, specify the management namespace and
schema, and then specify the properties for the agents you want to use. For example:
...
beans-2.5.xsd
mule.xsd
http://www.mulesource.org/schema/mule/management/2.1 http://www.mulesource.org/schema/mule/
management/2.1/mule-management.xsd"
...>
<management:jmx-default-config port="1098" registerMx4jAdapter="true" />
<management:log4j-notifications logName="myMuleLog" logConfigFile="mule-log.txt"/>
<management:chainsaw-notifications chainsawPort="8080" chainsawHost="127.0.0.1" />
<management:publish-notifications endpointAddress="vm://myService" />

...
For a list of agents provided with Mule and how to configure them, see Jmx Management. You can also
create a custom agent as described below.
Creating Custom Agents

To create your own agent, your agent class must implement org.mule.api.agent.Agent . You then
configure your agent using the <custom-agent> element, which takes two attributes: name specifies a
unique name for this agent, and class specifies the class where it's defined. If your agent requires that
you pass in properties, you can specify them as name/value pairs.
For example:
<management:custom-agent name="test-custom-agent" class="org.mule.tck.testmodels.mule.TestAgent">

<spring:property name="frobbit" value="woggle"/>

</management:custom-agent>

Mule Server Notifications
Mule Server Notifications

[ Configuring Notifications ] [ Firing Custom Notifications ] [ Notification Interfaces ] [ Registering
Listeners Programmatically ] [ Notification Payloads ]
Mule provides an internal notification mechanism that you can use to access changes that occur on the
Mule Server, such as a service component being added, a Mule Model being initialized, or Mule being
started. You can set up your agents or service components to react to these notifications.
Configuring Notifications
Message notifications provide a snapshot of all information sent into and out of the Mule Server. These
notifications are fired whenever a message is received or sent. These additional notifications have some
impact on performance, so they are disabled by default. To enable message notifications, you set the type
of messages you want to enable using the <notifications> element in your Mule configuration file. You
also register the notification listeners and associate interfaces with specific notifications.
For example, first you create beans for the notification listeners, specifying the class of the type of
notification you want to receive:
<spring:bean name="componentNotificationLogger" class="org.myfirm.ComponentMessageNotificationLogger"/

>
<spring:bean name="endpointNotificationLogger"
class="org.myfirm.EndpointMessageNotificationLogger"/>
Next, you specify the notifications you want to receive using the <notification> element, and then
register the listeners using the <notification-listener> element:
<notifications>
<notification event="COMPONENT-MESSAGE"/>
<notification event="ENDPOINT-MESSAGE"/>
<notification-listener ref="componentNotificationLogger"/>
<notification-listener ref="endpointNotificationLogger"/>
</notifications>
When you specify the COMPONENT-MESSAGE notification, a notification is sent before and after a
component is invoked. When you set ENDPOINT-MESSAGE, a notification is sent whenever a message
is sent, dispatched, or received on an endpoint. Because the listeners implement the interface for the
type of notification they want to receive (for example, the ComponentMessageNotificationLogger class
would implement org.mule.api.context.notification.ComponentMessageNotificationListener),
the listeners receive the correct notifications.
For a list of notification types, see Notifications Configuration Reference. For a list of notification listener
interfaces, see Notification Interfaces below.
Specifying a Different Interface
If you want to change the interface that is associated with a notification, you specify the new interface
with the interface-class and interface attributes:
<notifications>

<notification event="COMPONENT-MESSAGE" interface-class="org.myfirm.MyMessageNotifications"
interface="myComponentListener"/>
Configuring a Custom Notification
If you create a custom notification, you also specify the event-class attribute:
<notifications>
<notification event="CUSTOM-MESSAGE" event-class="org.myfirm.MyMessageNotificationsCustomMessage"
interface-class="org.myfirm.MyMessageNotifications" interface="myCustomListener"/>
...
Disabling Notifications
If you want to block a specific interface from receiving a notification, you specify it with the <disable-
notification> element. You can specify the notification type (event), event class, interface, and/or
interface class to block.
<notifications>
<disable-notification interface="ComponentMessageNotificationListener"/>
...
Using Subscriptions
When registering a listener, you can specify that it only receive notifications from a specific component
using the subscription attribute. For example, to specify that the listener only receive notifications from
a service component called "MyService1", you would configure the listener as follows:
<notification-listener ref="endpointNotificationLogger" subscription="MyService1"/>
You can also register listeners and filter the subscriptions from your Java code:
MuleServer.getMuleContext().registerListener(listener, "MyService1");
To register interest in notifications from all service components with "Service" in the name, you would use
a wildcard string as follows:
MuleServer.getMuleContext().registerListener(listener, "*Service*");
For more information, see Registering Listeners Programmatically below.
Firing Custom Notifications

Custom notifications can be fired by objects in Mule to notify custom listeners. For example, a discovery
agent might fire a Client Found notification when a client connects.

You fire a custom notification as follows:
CustomNotification n = new CustomNotification("Hello");

MuleServer.getMuleContext().fireNotification(n);
Any objects implementing CustomNotificationListener will receive this notification. It's a good idea to
extend CustomNotification and define actions for your custom notification type. For example:
DiscoveryNotification n = new DiscoveryNotification(client, DiscoveryNotification.CLIENT_ADDED);

MuleServer.getMuleContext().fireNotification(n);
Note that non-system objects in Mule can only fire custom notifications through the manager. Attempting
to fire other notifications such as ModelNotification will cause an UnsupportedOperationException.
Notification Interfaces
The following table describes the Mule server notifications and the interfaces in the
org.mule.api.context.notification class an object can implement to become a listener for that notification.
All listeners extend the ServerNotificationListener interface.
Notification Description Interface
Component Message Notification A message was processed by a ComponentMessageNotificationListener

service component.
Connection Notification A connector connected to ConnectionNotificationListener

its underlying resource or
released the connection, or the
connection attempt failed.
Custom Notification Can be fired by objects CustomNotificationListener

themselves to custom
notification listeners and can be
used to customize notifications
on agents, service components,
connectors, and more.
Endpoint Message Notification A message was sent or received EndpointMessageNotificationListener

from an endpoint.
Exception Notification An exception was thrown. ExceptionNotificationListener
Management Notification The state of the Mule instance or ManagementNotificationListener

its resources have changed.
Message Notification An event was sent or received in MessageNotificationListener

the system. These notifications
are very good for tracing, but
they are not enabled by default
because they have an impact on
performance.
Model Notification The state is changing on a ModelNotificationListener

model, such as initializing,
starting and stopping, or

service components within the
model are being registered or
unregistered.
Mule Context Notification An event occurred on the Mule MuleContextNotificationListener

Manager.
Registry Notification An event occurred on the RegistryNotificationListener

registry.
Routing Notification A routing event such as an RoutingNotificationListener

async-reply miss occurred.
Security Notification A request was denied security SecurityNotificationListener

access.
Server Notification Fired when the server, models, ServerNotificationListener

and components stop, start, or
initialize.
Service Notification An event occurred on a service. ServiceNotificationListener
Transaction Notification During transaction life cycle TransactionNotificationListener

after a transaction has begun,
was committed, or was rolled
back.
The listener interfaces all have a single method:
public void onNotification(ServerNotification notification);
Depending on the listener implemented, only certain notifications will be received. For example, if the
object implements ManagerNotificationListener, only notifications of type ManagerNotification will
be received. Objects can implement more than one listener to receive more types of notifications.
Registering Listeners Programmatically

You can register listeners on the Mule Context as follows:
MuleServer.getMuleContext().registerListener(listener);
If you have local access to the Mule context already (for example, if you created it right before
registering the listener), you would simply call registerListener() on the existing context instead of on
MuleServer.getMuleContext(). For example:

context.registerListener(listener, "*Service*");
Registering Listeners Dynamically
By default, you cannot register listeners in the Mule context after Mule has started. Therefore, you would
register your listeners in your code before starting Mule. For example:

context.registerListener(listener, "*Service*");
context.start();
To change this behavior so that you can add listeners dynamically at run time, you can set the dynamic
attribute on the <notifications> element. If you just want to enable dynamic notifications for a specific
connector, you can set the dynamicNotification attribute on the connector.
Notification Action Codes
Each notification has an action code that determines the notification type. The action code can be queried
in the onEvent method to determine its type. For example, to have an object do something when the
model initializes:
public class MyObject implements ModelNotificationListener

{
public MyObject()
{
MuleServer.getMuleContext().registerListener(this);
}

{
if (notification.getAction() == ModelNotification.MODEL_INITIALISED)
{
system.out.println("The model is initialized!");
}
}
}
For a list of the action codes available with each notification type, see the Javadocs for the
org.mule.context.notification package and click on the class of the notification type you want.
Notification Payloads
All notifications extend java.util.EventObject, and the payload of the object can be accessed using the
getSource() method. The following table describes the payloads for each type of notification.
Notification Payload Type Resource ID Description
Component Message Component Component name The service component

Notification that triggered this
notification
Connection Notification Connectable <connector- The message receiver

or message dispatcher
name>.receiver(<endpoint-
uri>) that was connected
Custom Notification Any object Any String The object type is

custom to the object
firing the notification

Endpoint Message ImmutableEndpoint Endpoint URI The endpoint that
Notification triggered this
notification
Exception Notification Throwable Component Name The service component

that triggered this
notification
Management Object The object ID The monitored object

Notification that triggered this
notification
Message Notification MuleMessage Message ID The message sent or

received
Model Notification Model Model Name The Model instance

on the Mule Context.
Equivalent to calling
MuleContext.getRegistry().lookupMod
Mule Context MuleContext Mule context ID The Mule context

Notification instance. Equivalent
to calling
getMuleContext().
Registry Notification Registry Mule registry ID The Mule registry.

Equivalent to calling
MuleContext.getRegistry().
Routing Notification MuleMessage Message ID The message sent or

received
Security Notification SecurityException The exception message The security exception

that occurred
Service Notification Service Service ID The service that

triggered this
notification
Transaction Notification Transaction Component name The component

that triggered this
notification

Profiling Mule
Profiling Mule
[ Installing the Profiler Pack ] [ Enabling the Profiler Agent ] [ Running the Profiler ] [ Embedded Mule ]
The Mule Profiler Pack uses YourKit to provide CPU and memory profiling, helping you identify memory
leaks in your custom Mule extensions. The Profiler is useful during development and testing. In your
production environment, you should turn off the Profiler because of the high performance overhead. You
can also use any other Profiler, such as JProfiler, by adding it as an agent in your configuration.
Installing the Profiler Pack

If you are installing Mule Enterprise Edition, simply select the Profiler check box when installing the
product.
If you are installing Mule Community Edition, go to the downloads page, and under the latest stable
community release, expand the Downloads section. You can then click the link to the .zip, .tar, or .gz
version of the Profiler pack. After downloading, unpack it on top of the Mule installation.
Enabling the Profiler Agent

The Profiler agent exposes the YourKit Profiler to JMX to provide CPU and memory profiling. You configure
the Profiler agent with the <management:yourkit-profiler> element. For more information, see Jmx
Management.
Running the Profiler

To run the profiler, you run Mule with the -profile switch plus any extra YourKit startup options with
multiple parameters separated by commas, e.g. -profile onlylocal,onexit=memory. This integration
pack will automatically take care of configuration differences for Java 1.4.x and 5.x/6.x.
Embedded Mule
If you are running Mule embedded in a webapp, the Profiler configuration is completely delegated to
the owning container. Launch YourKit Profiler, Tools -> Integrate with J2EE server... and follow the
instructions. Typically, a server's launch script is modified to support profiling, and you then use this
modified start script instead of the original.

Resource Adapter
Mule JCA Resource Adapter

The Mule JCA resource adapter enables a Mule instance to be deployed to a J2EE application server. It can
be deployed to any JCA 1.5 compliant container. See Deployment Scenarios for links to information about
specific application server configurations.
You can download the resource adapter here.
EJB Configuration
The resource adapter supports inbound and outbound communication.
Outbound Bean Configuration
<session>
<description>A stateless session bean that sends a message over a Mule transport
</description>
<display-name>SenderEJB</display-name>
<ejb-name>SenderEJB</ejb-name>
<home>org.mule.samples.ejb.SenderHome</home>
<remote>org.mule.samples.ejb.Sender</remote>
<ejb-class>org.mule.samples.ejb.SenderBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
<resource-ref>
<res-ref-name>mule/connectionFactory</res-ref-name>
<res-type>org.mule.module.jca.MuleConnectionFactory</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Unshareable</res-sharing-scope>
</resource-ref>
</session>
Inbound Configuration
The endpoint property must be a valid endpoint URI to receive Mule events.
<message-driven>
<description>An MDB listening on a Tcp socket</description>
<display-name>TcpReceiverMDB</display-name>
<ejb-name>TcpReceiverMDB</ejb-name>
<ejb-class>org.mule.samples.ejb.SimpleReceiverMessageBean</ejb-class>
<messaging-type>org.mule.api.lifecycle.Callable</messaging-type>
<transaction-type>Container</transaction-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>endpoint</activation-config-property-name>
<activation-config-property-value>tcp://localhost:12345
</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>

Suggested Reading
Suggested Reading
ESB
ESB Introduction Part 1
This first article in this series described the basic concepts and role of the Enterprise Service Bus (ESB). It
focuses on describing scenarios and issues for ESB deployment to support a Service-Oriented Architecture
(SOA). One or more of these scenarios might apply to the SOA and ESB needs of your organization. - by
Rick Robinson

In Part 2 of this series on the Enterprise Service Bus (EBS), the author describes and analyzes some
commonly observed scenarios in which ESBs and other Service-Oriented Architecture (SOA) solutions are
implemented. - by Rick Robinson

In the third installment of this series, the author examines possible solutions for the various scenarios
outlined in Part 2. The ideas on the role of the Bus as explained in Part 1 provide the foundation for the
scenarios. - by Rick Robinson
The ESB Learning Guide - everything you want to know about ESB is here.
Enterprise Integration
Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions - by Gregor
Hohpe, Bobby Woolf
Provides a consistent vocabulary and visual notation framework to describe large-scale integration
solutions across many technologies. It also explores in detail the advantages and limitations of
asynchronous messaging architectures.
SEDA
SEDA
SEDA is an acronym for staged event-driven architecture, and decomposes a complex, event-driven
application into a set of stages connected by queues. This design avoids the high overhead associated
with thread-based concurrency models, and decouples event and thread scheduling from application
logic. Mule uses ideas from SEDA to provide a highly scalable server.
An Architecture for Highly Concurrent,Well-Conditioned Internet Services - (PDF) Dissertation by Matt

Welsh that introduces SEDA
JBI
The Sun JBI Site
Concurrency
Java Concurrency in Practice by Brian Goetz
Concurrent Programming in Java: Design Principles and Patterns by Doug Lea
Open Source Development Process

Producing Open Source Software: How to Run a Successful Free Software Project by Karl Fogel

The Cathedral and the Bazaar by Eric Raymond
Quality Improvement in Volunteer Free and Open Source Software Projects: Exploring the Impact of
Release Management by Martin Michlmayr
Open Source Java

The Server Side

Third-party Software in Mule
Third-party Software
Mule products include the following third-party software as part of the source code, examples, or as
dependencies. The license type for each third-party software product is indicated in parentheses.
Software License Software License
Acegi Apache 2.0 Graphviz CPL 1.0
Antlr BSD Style GreenMail LGPL 2.1
Apache Axis Apache 2.0 Groovy Apache 2.0
Apache Axis Jaxrpc Apache2.0 Hibernate 3.2.2 LGPL 2.1
Apache Catalina Apache 2.0 Hivemind-1.1.1 Apache 2.0
Apache Cocoon Apache 2.0 Howl-logger-0.1.11 BSD

Project
Http-Client Apache 2.0
Apache Commons Apache 2.0
Attributes iHarder Base64 Public Domain/
Permissive
Beanutils IzPack Apache 2.0
Apache Commons Apache 2.0 Jakarta Oro Apache 1.1

Codec
Java Scripting API Sun BCLA
Collections Java Service Wrapper Tanuki Software/Silver
Egg Technology
DBUtils Java UUID Generator Apache 2.0
Apache Commons Apache 2.0 Javaassist MPL 1.1

Digester
JavaDoc for BSD Style
Apache Commons Apache 2.0 JNDI Container
Discovery Implementation
Apache Commons- Apache 2.0 Jaxen-1.1.1 BSD style

lang
JBoss Business LGPL 2.1
Apache Commons- Apache 2.0 Process Management
logging – JBPM
Apache Commons IO Apache 2.0 JBoss Transactions LGPL 2.1
Apache Commons Net Apache 2.0 JDOM BSD style license
Apache Derby Apache 2.0 Jetty 5.1.12 Apache 1.1

Apache FtpServer Apache 2.0 JPEG Library (bundled IJG/JPEG Permissive
with GraphViz) license
Apache Geronimo Apache 2.0
JUnit CPL 1.0
Apache Jakarta Apache 2.0
Commons Transaction Libpng (bundled with Libpng OSI license
Source GraphViz)
Apache Maven Apache 2.0 Linguine Maps LGPL 2.1
Apache Tomcat Utility Apache 2.0 Log4j Apache 2.0
Apache Xalan Apache 2.0 Mockobjects Apache 2.0
Apache XML Security Apache 2.0 Mx4j 1.2 MX4J License 1.0
Apache Velocity Apache 2.0 Mx4j-tools MX4J License 1.0
Apache WebServices Apache 2.0 Nanocontainer BSD Style

Commons
OGNL Attribution
Apache Web Services Apache 2.0
Axis OpenSAML Apache 1.1
Apache Web Services Apache 2.0 Picocontainer BSD

Project (Wss4j)
Quartz 1.6 Apache 2.0
Apache Xerces Apache 2.
Retrotranslator BSD style
Apache XML Apache 2.0
Commons XML APIs Simple Logging MIT Style
Facade for Java
Apache Xpath Apache 2.0 (SLF4J)
ASM – Bundled with BSD Smack Apache 2.0

CGLIB
Spring Framework / Apache 2.0
Axis-Saaj Project Apache 2.0 Modules JBPM
Axis/Web Services Apache 2.0 StaX Apache 2.0
Backport-util- Creative Commons Sun JNDI Sun BCLA

concurrent Public Domain
TrueType Font GPL/LGPL
Bouncy Castle Java Bouncy Castle License Library (bundled with
Cryptography APIs GraphViz)
c3p0: JDBC LGPL 2.1 Truststore files Unknown

DataSources/Resource
Pools Web Services CPL 1.0
Description Language
CAROL: Common LGPL 2.1 for Java (wsdl4j)
Architecture for
ObjectWeb Woodstox Apache 2.0
Commons-cli-1.0 Apache 1.1 xapool LGPL 2.1
Cryptix OpenPGP Cryptix General XMLUnit BSD style

License
XPP3
Commons-pool Apache 2.0

CGLIB Apache 2.0 Indiana University
Extreme! Lab
Cryptix Cryptix General Software License
License
XStream BSD
Dom4j-1.4 BSD
YourKit Java Profiler Commercial
DTDParser referenced Apache Style
by Linguine Maps ZLIB (bundled with Zlib license
GraphViz)
Expat Parser MIT
FreeType Project, FreeType License

bundled with GraphViz

Transaction Management
Transaction Management
[ Single-resource Transactions ] [ Multi-resource Transactions ] [ XA Transactions ] [ Transaction

Manager Lookup ] [ Transaction Coordination ]
Mule's transaction framework is agnostic to the underlying transaction manager. The transaction could
be a JDBC transaction, XA transaction, or a JMS transaction or message acknowledgment. All transaction
types can be handled the same way. Mule transactions are configured on synchronous inbound endpoints,
where an endpoint can be configured to start a new transaction or join an existing one. The outbound
endpoints will automatically enlist in the current transaction, provided that the managed resource is
compatible with the transaction. Transactions are configured on an endpoint using <transaction>, which
maps to the org.mule.transaction.MuleTransactionConfig class. This element defines what action an
endpoint should take when it receives an event and the transaction factory to use to create transactions.
If you have multiple inbound or outbound endpoints in a service and you specify a
transaction for one of them, you must specify transactions for all of them. For example, if
you have two outbound endpoints and you specify a transaction for the first one, you must
also specify a transaction for the second one.
For an excellent article on distributed transactions using both XA and non-XA approaches, see http://
www.javaworld.com/javaworld/jw-01-2009/jw-01-spring-transactions.html. The multi-resource
transaction support described below maps to the Best Efforts 1PC pattern described in the article.
Single-resource Transactions
Single-resource transactions (also called "local transactions") are transactions that are provided by the
underlying resource, such as JDBC transactions and JMS transactions. These kind of transactions can be
used to receive and/or send messages using a single resource only.
An example configuration for a single-resource transaction might look like this:
<jms:endpoint name="In" queue="test.In" connector-ref="jmsConnector1" />

<jms:endpoint name="Out" queue="test.Out" connector-ref="jmsConnector1" />
...
<inbound>
<inbound-endpoint ref="In">
<jms:transaction action="ALWAYS_BEGIN" />
</inbound>
...
<outbound>
<outbound-endpoint ref="Out">
<jms:transaction action="ALWAYS_BEGIN" />
</outbound>
This configuration defines a global JMS endpoint that receives on a "test.In" queue and another global
JMS endpoint that sends on a "test.Out" queue. The action attribute tells Mule what to do for each
message. In this case, a new transaction will be created for every message received. The outbound
endpoint will use the resource enlisted in the current transaction, if one is running. In this case, it will use
the same JMS session that has been used to receive the event. When the message has been routed from
the inbound endpoint to the outbound endpoint, the transaction will be committed or rolled back.

You can send multiple messages using the recipient list router, which will send all messages in the same
transaction.
You can set action values on the <transaction> element as follows:
• NONE - Never participate in a transaction.

• ALWAYS_BEGIN - Always start a new transaction when receiving a message. If a previous
transaction exists, it commits that transaction.
• BEGIN_OR_JOIN - If a transaction is already in progress when an event is received, join the
transaction, otherwise start a new transaction.
• ALWAYS_JOIN - Always expects a transaction to be in progress when an event is received. If there is
no transaction, an exception is thrown.
• JOIN_IF_POSSIBLE - Will join the current transaction if one is available. Otherwise, no transaction is
created.
Multi-resource Transactions
Multi-resource transactions will be available in Mule Enterprise Edition version 2.2
If you are using Mule Enterprise Edition, you can use the <multi-transaction> element to enable a
series of operations from multiple JMS resources to be grouped into a single transaction. Multi-resource
transactions work without the overhead of XA. The trade-off is that XA reliability guarantees aren't
provided, and your services must be ready to handle duplicates. This is very similar to a 1.5 phase
commit concept.
Multi-resource transactions are useful for creating transactional non-XA bridges. For example, if you
want to bridge two different JMS connectors (such as WebSphere MQ and Active MQ), each of which is
running local transactions instead of XA transactions, you could configure the multi-resource transaction
as follows:

xmlns:ee="http://www.mulesource.org/schema/mule/ee/core/2.2"
beans-2.5.xsd
mule.xsd
http://www.mulesource.org/schema/mule/ee/core/2.2 http://www.mulesource.org/schema/mule/ee/
core/2.2/mule-ee.xsd
http://www.mulesource.org/schema/mule/jms/2.2 http://www.mulesource.org/schema/mule/jms/2.2/
mule-jms.xsd
>
<spring:bean id="mqQueueConnectionFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">

<spring:property name="queueManager" value="QM_myServer"/>
<spring:property name="port" value="1417"/>
<spring:property name="hostName" value="172.16.10.0"/>
<spring:property name="transportType" value="1"/>
</spring:bean>
<jms:websphere-connector name="jmsWSConnector"
connectionFactory-ref="mqQueueConnectionFactory"
specification="1.1"
username="" password=""
numberOfConsumers="16"/>
<jms:activemq-connector name="jmsAMQConnector"
specification="1.1"/>

<model name="Multi-TX Test Model">
<service name="JMSService1">
<inbound>
<jms:inbound-endpoint queue="in" connector-ref="jmsWSConnector">
<ee:multi-transaction action="ALWAYS_BEGIN"/>
</inbound>
<test:component/>
<outbound>
<jms:outbound-endpoint queue="out" connector-ref="jmsAMQConnector"
disableTemporaryReplyToDestinations="true">
<ee:multi-transaction action="ALWAYS_JOIN"/>
</jms:outbound-endpoint>
</outbound>
</service>
</model>
</mule>
Because the inbound JMS endpoint has a multi-resource transaction configured on it, any outbound
endpoints must also be configured with multi-resource transaction support to become part of the
transaction.
XA Transactions
You can use XA transactions if you want to enlist multiple managed resources within the same transaction
and require 100% reliability. The inbound endpoints are configured in the same manner as for single-
resource transactions, but the connectors need to be configured to use XA-enabled resources.
If you run Mule outside an application server, you can use JBoss Transaction Manager to configure an
embedded transaction manager.
Currently, only three transports support XA transactions:
• VM Transport
• JDBC Transport
• JMS Transport
The following example of an XA transaction configuration uses a single transaction to read from a JMS
queue and write to a database.
<service name="JmsToJdbc">
<inbound>
<inbound-router>
<jms:inbound-endpoint queue="my.queue" reuseSession="false"/>
<xa-transaction action="ALWAYS_BEGIN" timeout="60000"/>
</inbound-router>
</inbound>
<outbound>
<jdbc:outbound-endpoint address="writeTest" type="2">
<xa-transaction action="ALWAYS_JOIN"/>
</jdbc:outbound-endpoint>
</outbound>

</service>
Because the inbound JMS endpoint has an XA transaction configured on it, any outbound endpoints must
also be configured with XA transaction support to become part of the XA transaction. This requires that
the transport type supports XA transactions. For this configuration to work, you will need to configure a
JMS connector that uses a JMS XA Connection Factory and a JDBC connector that is configured to use an
XA data source.
Transaction Manager Lookup

Mule uses javax.transaction.TransactionManager for managing transaction spanning multiple
resources (XA). If you need the SUSPEND semantics for your transactions (which is what EJB's
RequiresNew transaction attribute value does), you must use the transaction manager. Conversely,
the more typical javax.transaction.UserTransaction is just a thin handle to a transaction manager
with limited (though in most cases sufficient) functionality that does not let you suspend the current
transaction.
Note: Depending on your application server vendor, the transaction manager might be available via JNDI
or only through proprietary APIs.
The following table summarizes some common Java EE servers:
Application Remote Embedded Common Lookup class

Server Location
JBoss java:/ org.mule.transaction.lookup.JBo

TransactionManager
Weblogic javax.transaction.TransactionManager
org.mule.transaction.lookup.We
WebSphere Proprietary API org.mule.transaction.lookup.We

call
Resin java:comp/ org.mule.transaction.lookup.Res

TransactionManager
JRun java:/ org.mule.transaction.lookup.JRu

TransactionManager
Other Specified via a org.mule.transaction.lookup.Ge

jndiName property
For example, to use Weblogic's transaction manager, you would configure Mule as follows:
<transaction-manager factory="org.mule.transaction.lookup.WeblogicTransactionManagerLookupFactory" />
Transaction Coordination
Transaction demarcation is set on endpoints. The actual management of transactions is handled by the
Mule Transaction Coordinator . Note that any transacted event flows will be synchronous. The Transaction
Coordinator is a singleton manager that looks after all the transactions for a Mule instance and provides
methods for binding and unbinding transaction and retrieving the current transaction state.

Tuning Performance
Tuning Performance
[ About Thread Pools ] [ About Threading Profiles ] [ About Pooling Profiles ] [ Calculating Threads ] [
Additional Performance Tuning Tips ] [ Threading Profile Configuration Reference ] [ Receiver Threading
Profile ] [ Dispatcher Threading Profile ] [ Pooling Profile Configuration Reference ] [ Pooling Profile ]
A Mule application is a collaboration of a set of services. Messages are processed by services in three
stages:
1. Connector receiving stage

2. Service component processing stage
3. Connector dispatching stage
Tuning performance in Mule involves analyzing and improving these three stages for each service. You
can start by applying the same tuning approach to all services and then further customize the tuning for
each service as needed.
About Thread Pools

Each request that comes into Mule is processed on its own thread. A connector's receiver has a thread
pool with a certain number of threads available to process requests on the inbound endpoints that use
that connector.
Keep in mind that Mule can send messages asynchronously or synchronously. By default, messages are
asynchronous, which is the "fire-and-forget" style where a message is sent with no response. If you need
a response back, you must configure the Mule service as synchronous. When a service is configured as
asynchronous, a connector receiver and dispatcher are used, whereas a synchronous service uses only
the connector receiver.
If you are using synchronous processing, the same thread will be used to carry the message all the way
through Mule, whereas if you are doing asynchronous processing, the receiver thread is used only to
carry the message to the component, at which point the message is transferred to a component thread,
and the receiver thread is released back into the receiver thread pool so it can carry another message.
The following diagram illustrates these threads.

After the component has finished processing an asynchronous message, it is transferred to a dispatcher
thread and is sent on its way. Therefore, the receiver, component, and dispatcher all have separate
thread pools that are in use during asynchronous processing, whereas only the receiver thread pool is in
use for synchronous processing.
About Threading Profiles

The threading profile specifies how the thread pools behave in Mule. You specify a separate threading
profile for each receiver thread pool, component thread pool, and dispatcher thread pool. The most
important setting of each is maxThreadsActive, which specifies how many threads are in the thread pool.
About Pooling Profiles

Unlike singleton components, pooled components (see PooledJavaComponent ) each have a component
pool, which contains multiple instances of the component to handle simultaneous incoming requests.
A service's pooling profile configures its component pool. The most important setting is maxActive,
which specifies the maximum number of instances of the component that Mule will create to handle
simultaneous requests. Note that this number should be the same as the maxThreadsActive setting on
the receiver thread pool, so that you have enough component instances available to handle the threads.
You can use Mule HQ to monitor your component pools and see the maximum number of components
you've used from the pool to help you tune the number of components and threads.
Calculating Threads
To calculate the number of threads to set, you must take the following factors into consideration.
• Concurrent User Requests: In general, the number of concurrent user requests is the total
number of requests to be processed simultaneously at any given time by the Mule server. For a
service, concurrent user requests is the number of requests a service inbound endpoint can process
simultaneously. Concurrent user requests at the connector level is the total concurrent requests of
all services that share the same connector. Typically, you get the total concurrent user requests from
the business requirements.
• Processing Time: Processing time is the average time Mule takes to process a user request from
the time a connector receiver starts the execution until it finishes and then sends the response to
the outbound endpoint by connector dispatcher or back to the caller by the connector receiver after
a round trip. Typically, you determine the processing time from the unit tests.
• Response Time: If a service runs in synchronous mode, the response time is the actual amount
of time the end user is required to wait for the response to come back. If the service runs in
asynchronous mode, it is the total time from when a request arrives in Mule until it is dispatched
out of the service by the outbound dispatcher. In a thread pooling environment, when a request
arrives, there is no guarantee that a thread will be immediately available. In this case, the request
is put into an internal thread pool work queue to wait for the next available thread. Therefore, the
response time is a function of the following:
Response time = average of thread pool waiting time in work queue + average of processing time
Your business requirements will dictate the actual response time required from the application.
• Timeout Time: If your business requirements dictate a maximum time to wait for a response
before timing out, it will be an important factor in your calculations below.
After you have determined these requirements, you can calculate the adjustments you need to make
to maxThreadsActive and maxBufferSize for the service and the receiver thread pool. In general, the
formula is:
Concurrent user requests = maxThreadsActive + maxBufferSize
Where maxThreadsActive is the number of threads that run concurrently and maxBufferSize is the
number of requests that can wait in the queue for threads to be released.

Calculating the Service Threads
Your business requirements dictate how many threads each service must be able to process concurrently.
For example, one service might need to be able to process 50 requests at a time, while another might
need to process 40 at a time. Typically, you use this requirement to set the maxThreadsActive attribute
on the service (maxThreadsActive="40").
If you have requirements for timeout settings for synchronous processing, you must do some additional
calculations for each service.
1. Run synchronous test cases to determine the response time.

2. Subtract the response time from the timeout time dictated by your business requirements. This is
your maximum wait time (maximum wait time = timeout time - response time).
3. Divide the maximum wait time by the response time to get the number of batches that will be
run sequentially to complete all concurrent requests within the maximum wait time (batches =
maximum wait time / response time). Requests wait in the queue until the first batch is finished,
and then the first batch's threads are released and used by the next batch.
4. Divide the concurrent user requests by the number of batches to get the thread size for the service's
maxThreadsActive setting (where maxThreadsActive = concurrent user requests / processing
batches). This is the total number of threads that can be run simultaneously for this service.
5. Set maxBufferSize to the concurrent user requests minus the maxThreadsActive setting (where
maxBufferSize = concurrent user requests - maxThreadsActive). This is the number of requests
that can wait in the queue for threads to become available.
For example, assume a service must have the ability to process 200 concurrent user requests, your
timeout setting is 10 seconds, and the response time is 2 seconds, making your maximum wait time
8 seconds (10 seconds timeout minus 2 seconds response time). Divide the maximum wait time
(8 seconds) by the response time (2 seconds) to get the number of batches (4). Finally, divide the
concurrent user requests requirement (200 requests) by the batches (4) to get the maxThreadsActive
setting (50) for the service. Subtract this number (50) from the concurrent user requests (200) to get
your maxBufferSize (150).
In summary, the formulas for synchronous processing with timeout restrictions are:
• Maximum wait time = timeout time - response time

• Batches = maximum wait time / response time
• maxThreadsActive = concurrent user requests / batches
• maxBufferSize = concurrent user requests - maxThreadsActive
Calculating the Receiver Threads
A connector's receiver is shared by all services that specify the same connector on their inbound
endpoint. The previous section described how to calculate the maxThreadsActive attribute for each
service. To calculate the maxThreadsActive setting for the receiver, that is, how many threads you should
assign to a connector's receiver thread pool, sum the maxThreadsActive setting for each service that
uses that connector on their inbound endpoints:
maxThreadsActive = # (service 1 maxThreadsActive, service 2 maxThreadsActive...service n

maxThreadsActive)
For example, if you have three components whose inbound endpoints use the VM connector, and your
business requirements dictate that two of the services should handle 50 50 requests at a time and the
third service should handle 40 requests at a time, set maxThreadsActive to 140 in the receiver threading
profile for the VM connector.
Calculating the Component Threads and Instances
In the component stage, the transformed message from the inbound endpoint is passed to the
component thread. As you can see from the previous illustration, there are two pools involved here:
a component thread is taken from component's thread pool, and a POJO instance is taken from the
component object pool (if the component is configured as a pooled component instead of a singleton).
Therefore, the number of component threads must match the number of component instances in the
component pool. Otherwise, a bottle neck on either side will develop.

If most of your components use asychronous processing, typically use the same number of component
threads as you set for the receiver threads. If most of your components do synchronous processing,
however, component threads won't be used as often, so this number can be much lower.
Like the receiver thread pool, the component thread pool can be shared if multiple services use the same
component. In this case, use the following formula:
Component threads = # (service 1 + service 2 + ...+ service n)
Calculating the Dispatcher Threads
Like component threads, dispatcher threads are used only for asynchronous processing. Typically, set the
dispatcher threads to the same number as the component threads.
Other Considerations
You can trade off queue sizes and maximum pool sizes. Using large queues and small pools minimizes
CPU usage, OS resources, and context-switching overhead, but it can lead to artificially low throughput.
If tasks frequently block (for example, if they are I/O bound), a system may be able to schedule time
for more threads than you otherwise allow. Use of small queues generally requires larger pool sizes,
which keeps CPUs busier but may encounter unacceptable scheduling overhead, which also decreases
throughput.
Additional Performance Tuning Tips

• In the log4j.properties file in your conf directory, set up logging to a file instead of the console,
which will bypass the wrapper logging and speed up performance. To do this, create a new file
appender (org.apache.log4j.FileAppender), specify the file and optionally the layout and other
settings, and then change "console" to the file appender. For example:
log4j.rootCategory=INFO, mulelogfile
log4j.appender.mulelogfile=org.apache.log4j.FileAppender
log4j.appender.mulelogfile.layout=org.apache.log4j.PatternLayout
log4j.appender.mulelogfile.layout.ConversionPattern=%-22d{dd/MMM/yyyy HH:mm:ss} - %m%n
log4j.appender.mulelogfile.file=custommule.log
• If polling is enabled for a connector, one thread will be in use by polling, so you should increment
your maxThreadsActive setting by one. Polling is available on connectors such as File, FTP, and
STDIO that extend AbstractPollingMessageReceiver .
• If you are using VM to pass a message between components, you can typically reduce the total
number of threads because VM is so fast.
• If you are processing very heavy loads, or if your endpoints have different simultaneous request
requirements (for example, one endpoint requires the ability to process 20 simultaneous requests
but another endpoint using the same connector requires 50), you might want to split up the
connector so that you have one connector per endpoint.
Thread pools in Mule use the JDK 1.4-compatible util.concurrent backport library, so all
the variables defined on org.mule.config.ThreadingProfile are synonymous with
ThreadPoolExecutor.
Threading Profile Configuration Reference

Following are the elements you configure for threading profiles. You can create a threading profile at the
<configuration>, <connector>, or <service> level and reference it.

Receiver Threading Profile
The threading profile to use when a connector receives messages.
Attributes of <receiver-threading-profile...>

number of threads
that will be used.

number of idle or
inactive threads
that can be in the
pool before they
are destroyed.

long an inactive
thread is kept in
the pool before
being discarded.

is bounded, this
value determines
how to handle
incoming tasks.
Possible values
are: WAIT
(wait until a
thread becomes
available; don't
use this value
if the minimum
number of threads
is zero, in which
case a thread
may never
become available),
DISCARD
(throw away the
current request
and return),
DISCARD_OLDEST
(throw away the
oldest request
and return),
ABORT (throw a
RuntimeException),
and RUN (the
default; the
thread making the
execute request
runs the task
itself, which helps

guard against
lockup).

in milliseconds
when the pool
exhausted
action is WAIT.
If the value is
negative, it will
wait indefinitely.

should be used
(default is true).

many requests
are queued when
the pool is at
maximum usage
capacity and the
pool exhausted
action is WAIT.
The buffer is used
as an overflow.
Dispatcher Threading Profile

The threading profile to use when a connector dispatches messages.
Attributes of <dispatcher-threading-profile...>

number of threads
that will be used.

number of idle or
inactive threads
that can be in the
pool before they
are destroyed.

long an inactive
thread is kept in
the pool before
being discarded.

is bounded, this
value determines
how to handle
incoming tasks.
Possible values
are: WAIT

(wait until a
thread becomes
available; don't
use this value
if the minimum
number of threads
is zero, in which
case a thread
may never
become available),
DISCARD
(throw away the
current request
and return),
DISCARD_OLDEST
(throw away the
oldest request
and return),
ABORT (throw a
RuntimeException),
and RUN (the
default; the
thread making the
execute request
runs the task
itself, which helps
guard against
lockup).

in milliseconds
when the pool
exhausted
action is WAIT.
If the value is
negative, it will
wait indefinitely.

should be used
(default is true).

many requests
are queued when
the pool is at
maximum usage
capacity and the
pool exhausted
action is WAIT.
The buffer is used
as an overflow.
Pooling Profile Configuration Reference

Each service has its own pooling profile. You configure the pooling profile using the <pooling-profile>
element on the <pooled-component> element.

Pooling Profile
Attributes of <pooling-profile...>
maxActive string no Controls the

maximum
number of Mule
components that
can be borrowed
from a session
at one time.
When set to a
negative value,
there is no limit
to the number of
components that
may be active at
one time. When
maxActive is
exceeded, the
pool is said to be
exhausted.
maxIdle string no Controls the

maximum
number of Mule
components that
can sit idle in the
pool at any time.
When set to a
negative value,
there is no limit
to the number of
Mule components
that may be idle
at one time.
initialisationPolicy INITIALISE_NONE/ no INITIALISE_ONE Determines how

INITIALISE_ONE/ components in
INITIALISE_ALL a pool should
be initialized.
The possible
values are:
INITIALISE_NONE
(will not load
any components
into the pool
on startup),
INITIALISE_ONE
(will load one
initial component
into the pool
on startup), or
INITIALISE_ALL
(will load all
components in the
pool on startup)

exhaustedAction WHEN_EXHAUSTED_GROW/
no WHEN_EXHAUSTED_GROW
Specifies the
WHEN_EXHAUSTED_WAIT/ behavior of the
WHEN_EXHAUSTED_FAIL Mule component
pool when the
pool is exhausted.
Possible
values are:
"WHEN_EXHAUSTED_FAIL",
which will throw a
NoSuchElementException,
"WHEN_EXHAUSTED_WAIT",
which will block
by invoking
Object.wait(long)
until a new or
idle object is
available, or
WHEN_EXHAUSTED_GROW,
which will create a
new Mule instance
and return
it, essentially
making maxActive
meaningless. If a
positive maxWait
value is supplied,
it will block for at
most that many
milliseconds,
after which a
NoSuchElementException
will be thrown. If
maxThreadWait
is a negative
value, it will block
indefinitely.
maxWait string no Specifies the

number of
milliseconds to
wait for a pooled
component to
become available
when the pool is
exhausted and the
exhaustedAction
is set to
WHEN_EXHAUSTED_BLOCK.

Unit Testing
This page last changed on Jan 07, 2009 by kevin.depew.
Unit Testing
Mule provides a Test Compatibility Kit (TCK) of unit tests that you can use to test your simple
extensions as well as your custom modules and transports. The unit tests are located in the -
tests.jar file, such as mule-core-2.0.2-tests.jar for Mule version 2.0.2. All unit tests inherit from
org.mule.tck.AbstractMuleTestCase
These unit tests are beneficial for the following reasons:
• Components tested with a TCK test case ensure that the common behavior of the component is
compatible with the Mule framework.
• Using a TCK test case allows the developer to concentrate on writing tests for specific behavior of
their component.
• Where testing of a method in the Service Component API cannot be tested by the TCK test case,
the test cases provides an abstract method for the test, ensuring the developer tests all areas of the
component.
• The TCK provides a default test model that is a simple set of test classes. The developer doesn't
need to worry about writing new test classes for their test cases each time.
• The abstract test cases in the TCK use JUnit's TestCase, so they are compatible with other test
cases.
Following is a description of some of the unit tests in the Mule TCK:
Testing Component Description
AbstractMuleTestCase A helper test case providing methods for creating

test and mock object types. This is the base class
for all other abstract TCK classes.
AbstractConnectorTestCase Used to test the common behavior of a connector.

This tests dispatching and sending events using
mock objects.
AbstractMessageAdapterTestCase Provides tests for all the standard methods

defined in the MessageAdapter interface. It's
usually enough to just extend this test case
without writing any further tests.
AbstractMessageReceiverTestCase Used to test the common behavior of a

MessageReceiver. This tests receiving messages
using mock objects.
AbstractComponentTestCase This is the base class for unit tests that

test custom component implementations.
Concrete subclasses of this base class
include DefaultJavaComponentTestCase,
PooledJavaComponentTestCase, and
SimpleCallableJavaComponentTestCase,
each of which contains methods for testing
that component type. For example, the
DefaultJavaComponentTestCase includes
methods for testing the creation, lifecycle, and
disposal of a basic Java component.
AbstractTransformerTestCase Used to test transformers. This class defines

a number of tests that ensures that the
transformer works in single scenarios as well
as in round trip scenarios. There are many
concrete sub-classes of this abstract class that

test specific types of transformers, such as
StringByteArrayTransformersTestCase.
DefaultMuleContextTestCase Tests the creation and disposal of the Mule

context.
AbstractServiceTestCase An abstract test case that provides methods for

testing the starting, stopping, pausing, resuming,
and disposing of services.

Using IDEs
Using IDEs
You can use an integrated development environment (IDE) such as Eclipse, IntelliJ, and Mule IDE to
rapidly develop Mule applications. For more information on the Mule IDE, see the Mule IDE User Guide.
Usually, you simply attach the src.zip file that comes with the Mule distribution to the Mule JARs in your
project so you can browse the source code while developing your classes. If you want to build Mule from
source, see the following topics in the Mule Developer's Guide:
• Setting Up the Development Environment

• Working with an IDE
• Building from Source

Using Mule HQ
Using Mule HQ
[ Overview ] [ HQ Architecture ] [ Enabling Mule to Use Mule HQ ] [ Installing Mule HQ ] [ Starting
and Stopping Mule HQ ] [ Logging in to Mule HQ ] [ Importing Mule ] [ Configuring Mule in Mule HQ ] [
Setting Up Availability Alerts ] [ Configuring Remote Agents Manually ] [ Monitoring and Controlling Your
Resources ] [ Uninstalling Mule HQ ]
Overview
Mule HQ provides a centralized way to manage all of your stand-alone Mule deployments as well as all of
the disparate systems and services in your SOA infrastructure. For example, a typical stack that Mule HQ
monitors might include Redhat Enterprise Linux, MySQL, JBoss Application Server, OpenMQ, and Mule.
Mule HQ provides integrated log, configuration, and server event tracking. It can detect Mule servers
and associated software and hardware, and report real-time and historical details of events. If you need
to debug a problem with your deployment, you can turn on the Profiler and view the details of memory
consumption at the message level.
Mule HQ is available with Mule Enterprise Edition only. It can monitor both Community Edition and
Enterprise Edition instances of Mule 1.x and 2.1 servers. Mule HQ supports stand-alone Mule deployments
only and cannot monitor embedded Mule instances.
HQ Architecture
Mule HQ is based on Hyperic HQ. This section describes the Hyperic HQ Server and Agent.
Hyperic HQ Server
As HQ's central nervous system, the HQ Server coordinates all system functions, including:
• Processing incoming monitoring data

• Detecting alert conditions and sending out alerts
• Managing inventory, including merging auto-discovery information into current inventory
• Enforcing security
• Maintaining HQ operational schedules (for control actions and auto-discovery scans)
• Processing user-driven actions initiated via the HQ GUI or command line interface
In large environments, the HQ Server can be clustered to enhance fault tolerance and to share the overall
system load across multiple machines.

Hyperic HQ Agent
Acting as the sensory facilities of the HQ system, Agents are deployed throughout the network
infrastructure to provide points-of-presence for discovering inventory, gathering data, controlling
software, and other "in the trenches" tasks.
The HQ Shell's Agent installer makes quick work of installing and managing all your HQ Agents - without
ever having to visit each managed machine.
Enabling Mule to Use Mule HQ

To use Mule with Mule HQ, you must enable the JMX support agent and (if installed) the Mule Profiler in
your Mule configuration.
Your Mule configuration files must be available to Mule HQ on a relative or absolute path.
They cannot be embedded in a JAR file.
Configure the JMX Support Agent
The default JMX support agent configures several JMX agents simultaneously. To add this to your
configuration, you add the management namespace and the <management:jmx-default-config>
element to your configuration file. For example, the following example includes the xmlns:management
entry, the declaration of the XSD location (http://www.mulesource.org/schema/mule/management/2.1
http://www.mulesource.org/schema/mule/management/2.1/mule-management.xsd) and the
<management...> entries:


http://www.mulesource.org/schema/mule/management/2.1
http://www.mulesource.org/schema/mule/management/2.1/mule-management.xsd">
<management:jmx-default-config port="1098">
<spring:entry key="jsmith" value="foo"/>
<spring:entry key="dthomas" value="bar"/>
<spring:entry key="clee" value="pwd"/>
</management:jmx-default-config>
...
</mule>
Note: you only specify the port if you don't want to use the default of 1099.
You can also provide more advanced configuration, such as using the RMI registry agent and specifying
the JMX server explicitly:
<management:rmi-server serverUri="rmi://localhost:9000"/>
<management:jmx-server>
<management:connector-server url="service:jmx:rmi:///jndi/rmi://localhost:9000/server"/>
<spring:entry key="user" value="pass"/>
</management:jmx-server>
For more information, see Jmx Management.
Enable the Profiler Pack
The Mule Profiler pack allows you to profile your application (see Profiling Mule). After downloading and
installing the Profiler pack, you add the following element to your Mule configuration file:
<management:yourkit-profiler />
You must also add the -profile attribute to the bash/cmd script. For example, if you are using Windows,
you would edit stockquote.bat as follows:
IF '%Choice%'=='1' call "%MULE_BASE%\bin\mule.bat" -config

".\conf\stdio-config.xml,.\conf\stockquote-rest-config.xml" -builder spring -profile
If you are using a non-Windows operating system, you would edit it as follows:
if [ 1 = $i ]
then
exec "$MULE_BASE/bin/mule" -config "./conf/stdio-config.xml,./conf/stockquote-rest-config.xml" -builder
spring -profile
The configuration file you specify in the batch file depends on which variation and Mule instance you want
to use. The previous example specified the REST version of the Stock Quote example.

Setting the Server ID
When you run Mule, you must specify the -M-Dmule.serverId=MULE_SERVER_ID switch on the command
line (where MULE_SERVER_ID is the name of your Mule server) or set it programatically by calling
org.mule.config.DefaultMuleConfiguration.setId(). This will create the Mule.MULE_SERVER_ID JMX
domain, which Mule HQ will use to detect the Mule instance. You'll set this same domain ID when you
configure Mule in Mule HQ.
Verify the Configuration
Verify that your configuration changes were applied by starting the Mule instance you just configured (be
sure to specify the server ID as described in the previous section). For example, launch the stock quote
example and select REST when prompted:
You should see an output similar to the one below at the end:

Installing Mule HQ
This section describes how to install the HQ Server and Agent. By default, Mule HQ uses its own
internal database. To install Mule HQ with an external database, see Installing Mule HQ with an External
Database.
Prerequisites
Before you install Mule HQ, you must do the following:
1. If you have not already done so, contact MuleSource Sales to obtain a license (you can get a trial
license for free). Mule HQ will not run without a license.
2. Log in as a non-root user and install Mule. Make sure that this non-root user account has Java in
the environment variable PATH and has write permission to <MULE_BASE>/conf/wrapper files or
<MULE_HOME>/conf/wrapper files, depending on whether MULE_BASE is set. If you already have
Mule installed, ensure that your system is still using the supported platforms (e.g., a supported
version of Java).
3. Configure your Mule instance to support Mule HQ (see Enabling Mule to Use Mule HQ).
4. On UNIX platforms, ensure that libXp.so.6 is installed. HQ Server requires this library to create
charts and other graphics in the user interface.
For more information on prerequisites, see the Installation Overview on the Hyperic site.
Install Mule HQ
1. On the computer where you want to install Mule HQ, log in as the same non-root user you used
when you installed Mule, and then create a directory called MuleHQ, such as C:\Program Files
\MuleHQ.
2. Download the Mule HQ distribution (mule-hq-installer) and decompress it to the Mule HQ
directory.
3. In the Mule HQ directory, run setup.bat (on Windows) or setup.sh (on UNIX) at the command
prompt.
4. Follow the instructions on the screen (see the example below for details) and enter the following
values:
• When prompted to choose which software to install, press 1 and 3 to install both the HQ server
and agent.
• For the HQ server installation path, specify the MuleHQ directory you created in step 1, such as
C:\Program Files\MuleHQ.
Example Installation
This example illustrates what you see during installation. For simplicity, everything will be installed on the
localhost. The values you enter during installation are marked in bold.
Buildfile: C:\Temp\mule-hq-installer\installer-3.1.2-EE\bin\..\data\setup.xml
Initializing Mule HQ 3.1.2-EE Installation...
Loading taskdefs...
Taskdefs loaded
Choose which software to install:
1: Mule HQ Server
2: Mule HQ Shell
3: Mule HQ Agent
You may enter multiple choices, separated by commas.
1,3
HQ server installation path [default 'C:\Program Files']:
C:\Program Files\MuleHQ
HQ agent installation path [default 'd:/server/MuleHQ']:
Loading install configuration...

Install configuration loaded.
Preparing to install...

Validating agent install configuration...
Validating server install configuration...
Checking server webapp port...
Checking server secure webapp port...
Checking server JRMP port...
Checking server JNP port...
Verifying admin user properties
Validating server DB configuration...
Installing the agent...
Looking for previous installation
Unpacking agent to: d:/server/MuleHQ/agent-3.1.2-EE...
Installing the JRE ...
Unpacking JRE x86-win32-jre.exe to: d:/server/MuleHQ/agent-3.1.2-EE...
Setting permissions on agent binaries...
Fixing line endings on text files...
--------------------------------------------------------------------------------
Installation Complete:
Agent successfully installed to: d:/server/MuleHQ/agent-3.1.2-EE
--------------------------------------------------------------------------------
You can now start your HQ agent by running this command:
d:\server\MuleHQ\agent-3.1.2-EE\hq-agent.exe start
Installing the server...

Unpacking server to: d:/server/MuleHQ/server-3.1.2-EE...
Creating server configuration files...
Copying binaries and libraries to server installation...
Copying server configuration file...
Copying server control file...
Copying server binaries...
Copying server libs...
Setting up server database...
Setting up JDBC driver...
Copying database files...
Configuring database...
Starting repopulation of configuration table...
Waiting for built-in database to start (on port 9432)...
Starting built-in database...
Preparing database...
Vacuuming database...
Waiting for server to stop...
Stopping built-in database...
Built-in database stopped.
Installing the JRE ...
Unpacking JRE x86-win32-jre.exe to: d:/server/MuleHQ/server-3.1.2-EE...
Setting permissions on server binaries...
Fixing line endings on text files...
--------------------------------------------------------------------------------
Installation Complete:
Server successfully installed to: d:/server/MuleHQ/server-3.1.2-EE
--------------------------------------------------------------------------------
You should now install the HQ server as a Windows Service using this command:
d:\server\MuleHQ\server-3.1.2-EE\bin\hq-server.exe -i
You can then use the Service Control Manager (Control Panel->Services) to
start the HQ server. Note that the first time the HQ server starts up it may
take several minutes to initialize. Subsequent startups will be much faster.
Once the HQ server reports that it has successfully started, you can log in
to your HQ server at:

http://localhost:7080/
username: hqadmin
password: hqadmin
To change your password, log in to the HQ server, click the "Administration"

link, choose "List Users", then click on the "hqadmin" user.
Setup completed.
A copy of the output shown above has been saved to:
D:\Temp\mule-hq-installer\installer-3.1.2-EE\bin\../hq-install.log
Press the Enter key to exit setup.
Detailed HQ Installation Instructions
For more detailed installation instructions, see the following Hyperic documentation:
• Windows
• Non-Windows
Install the HQ Server as a Windows Service
You can install the HQ Server as a Windows Service so that you can leave the HQ Server running even
after you log out of Windows. To install it as a service, navigate to the Mule HQ Server bin directory
(such as C:\Program Files\MuleHQ\server-3.1.2-EE\bin) and enter the following command at the
command prompt:
hq-server.exe -i
This command creates two services: Hyperic HQ Database and Hyperic HQ Server. You start the database
service first and then the server.
Customize the JVM used by Mule HQ
You can set the environment variable HQ_JAVA_HOME to use a Java VM other than the one that ships
with Mule HQ.
Starting and Stopping Mule HQ

The first time you start the HQ Server, it can take several minutes to initialize. Note that this happens
only the first time you start the server; subsequent starts are much faster.
Starting Mule HQ
To start Mule HQ, you start the database, then the server, and then the agent.
Start the Database and Server
Navigate to the Mule HQ Server bin directory and execute the following commands:
db-start
hq-server
Note that there will be no console output from the first script. The second script should indicate that the
core system was initialized and that it is configuring from URL: resource:log4j.xml. Leave this command
window open while you are running Mule HQ.
If you installed the HQ Server as Windows services, you can start and stop the services from the Services
application in the Control Panel, or you can enter the following commands at the command prompt:
net start "Hyperic HQ Database"

net start "Hyperic HQ Server

Start the Agent
In a new command window, navigate to the agent directory (such as C:\Program Files\MuleHQ
\agent-3.1.2-EE) and enter the following command at the command prompt:
hq-agent
You must now answer several questions at the prompt. If you are testing the setup, you can specify
localhost for the server IP address and accept the defaults for everything else. For more information on
the agent settings, see Mule HQ Agent Settings.
If the connection fails, and you are using an evaluation version of Mule HQ, your license
may have expired. Click here to contact MuleSource about purchasing a license.
Stopping Mule HQ
To stop the server, log out of your Windows session, or enter the following command:
hq-server stop
If you installed the HQ Server as a Windows service, you can stop the service from the Services
application, or by entering net stop "Hyperic HQ Server" at the command prompt.
Logging in to Mule HQ
To log in to Mule HQ, do the following:
1. In a web browser, navigate to port 7080 of the server on which Mule HQ is installed, such as
http://localhost:7080/ or http://hostname.network.com:7080/.
The Mule HQ Login screen appears.
If the login screen does not appear, and you are using an evaluation version of
Mule HQ, your license may have expired. Click here to contact MuleSource about
purchasing a license.
2. Enter the default Administrator Login (hqadmin)and Password (hqadmin).

The Mule HQ Dashboard displays. Mule might be in the Auto-discovery list already. If it is not,
continue to the next section to import Mule into HQ.
Importing Mule
The Dashboard consists of several portlets that provide information about the HQ deployment. The first
portlet is the Auto-Discovery portlet, which discovers platforms, servers, and services on your system
and displays them here. After first starting Mule HQ, the portlet displays several entries (platform and
servers) for the newly registered HQ Agent on the local machine and for any other resource it has found
on the host so far. These resources need to be "imported" (added to the HQ inventory) so that the Agent
can start collecting default metrics for them. You will know that the platform has been successfully
imported when you see its hostname in the Recently Added portlet (at the left).
You can manually import the platform, or use scripts to manage integration with Mule.
Importing the Platform Manually
On the Dashboard, select the radio button next to your host (and next to any other platform and server
entries in this portlet) and click Add to Inventory.
Using the Mule Integration Scripts
Mule HQ provides scripts for managing integration with Mule from the command line or programmatically.
To enable these scripts, copy the file commons-cli-1.1.jar from MULE_HOME\lib\boot to the following
location under your Mule HQ server directory: hq-engine\server\default\deploy\hq.ear\lib

To run these scripts, you enter the following command at the command prompt:
java -jar mule-sdk.jar <subcommand> <hq_host> <hq_port> <hq_username> <hq_password>
The following optional parameters constrain the subcommand to a specific Mule platform (otherwise, all
Mule platforms are affected):
• hq_host is the host where Mule HQ server is installed

• hq_port is the port of Mule HQ server
• hq_username, hq_password are credentials for the Mule HQ user
The subcommand must be one of the following:
Command Description
ai:approve Automatically approves and configures pending

Mule resources in the auto-discovery list.
ai:delete Deletes the pending Mule resources from the

auto-discovery list. In complex scenarios, you
must call this before calling ai:rescan.
ai:rescan Rescans Mule resources so that they will re-

appear in the auto-discovery list.
delete Deletes all approved Mule platforms from Mule

HQ.
ai:revert Reverts all skipped Mule instances from the

ignored state so that they can reappear in the
auto-discovery list.
Viewing Imported Resources
After importing a Mule instance manually or through the scripts, the Mule servers are added to Mule HQ.

All imported Mule servers appear on the Mule Center tab.
After importing the Mule platform, if you want to run auto-discovery manually to discover recently added
Mule instances, do the following:
1. At the top of the Mule HQ window, click Browse Resources.

2. On the Platforms tab, click the Mule platform to display its details.
3. Click Tools Menu in the upper-right corner, and then choose New Auto-Discovery.

4. Select the Mule check box and specify your Mule home directory for the directories to scan.
5. Leave the defaults for everything else and click OK.

Click the Dashboard to see the newly discovered resources that are ready for import.

Configuring Mule in Mule HQ
After you have imported Mule into Mule HQ, you might need to perform some additional configuration.
To configure Mule:
1. On the Dashboard, click the Mule platform, click the Mule instance you want to configure, and click
the Inventory tab.
2. Scroll down until you see the Configuration Properties group, click it to expand its contents, and
then click Edit.
3. Enter the following settings:
• Specify the domain as Mule followed by a period followed by the Mule server ID you specified
when you ran Mule (see Setting the Server ID), such as Mule.MyMuleServer. This step is very
important. If the domain was already imported through auto-discovery, you can leave it as is.
• Specify the JMX URL used by your Mule instance. This URL is displayed on the startup screen
when you start Mule under Agents Running. If you do not see the JMX Agent listed, you have
not properly configured your Mule instance to work with Mule HQ--see Enabling Mule to Use
Mule HQ above.
• Leave the user name and password as empty values.
• Enable the Auto-Discover Components, Connectors, and Other Services option.
Make sure the metrics you want are collected often enough so you see the
results faster. Otherwise, it defaults to 1 minute.
4. Click OK.
For complete instructions on configuring resources in HQ, see Getting Started with HQ.
Setting Up Availability Alerts

Mule HQ can alert you when availability is lost. To enable this feature, take the following steps:

1. Navigate to the conf directory in your Mule HQ Server directory, and then open hq-server.conf for
editing.
2. Configure your mail server and set up email addresses for all Mule HQ users you want to notify, then
save and close the file.
3. In Mule HQ, click Mule, click the Alert tab, click New, and then specify a condition where the
availability metric's value is less than 100%.
4. Save the alert definition and specify the users to be notified for this condition.
For complete information on configuring alerts, click here.
Configuring Remote Agents Manually

JBoss 4.2 does not provide or expose the JMX service URL. You can view Mule within JBoss by enabling a
remote JMX connection. This approach makes JBoss visible through JConsole and enables some remote
actions. However, this approach does not enable Mule HQ access.
To work around this limitation, Mule can start a local RMI registry (the JBoss 4.x registry will not work,
as it is not pure RMI) and connect via this lookup. To enable this approach, set the port attribute on
the <jmx-default-config> element in Mule as shown in Configure the JMX Support Agent above. This
ensures both the registry and JMX connector are coordinated properly and allows you to assign custom
connection ports. You then specify the JMX ServiceURL in MuleHQ as:
service:jmx:rmi:///jndi/rmi://localhost:1099/server
Because Mule HQ will not automatically discover this Mule instance, you must add it manually in the Mule
HQ application. You can specify a dummy server directory but specify the correct JMX URL and port. After
loading Mule HQ Server, the new Mule instance is discovered along with its components, routers, and
more.
For complete information on configuring agents in Mule HQ, click here.
Monitoring and Controlling Your Resources

Now that you have completed the installation and configuration, see the following topics for more
information on using Mule HQ:
• Monitoring Basics
• Controlling Resources
Following is a description of some of the key features for monitoring and controlling your resources in
Mule HQ.
As you monitor your components, note that statistics are not generated for
BridgeComponents, such as the BridgeComponent in the Stock Quote example.
Stopping, Starting, and Restarting Mule from Mule HQ
You can use the Stop, Start, and Restart control actions on the Control tab in Mule HQ to control a Mule
server, component, endpoint, router, or connector.

• The Stop command stops the Mule server and all related processes.
• The Start command launches a new Mule server instance using the HQ Agent. The HQ Agent creates
and executes a new command line using the configuration parameters stored in the inventory.
• The Restart command send a "restart" signal to restart the JVM and re-read the configuration
file. The Wrapper is not stopped, and external parameters like debug, profile, service, and the
configuration file are unchanged. Therefore, Restart is not the same as using the Stop and Start
commands.
Profiling Mule
Mule is integrated with YourKit Java Profiler 7.0, the industry leader among profiling tools. If you installed
Mule and Mule HQ with the profiling option, you can use the Profiling tab in Mule HQ to create a snapshot,
start CPU profiling, and more. Captured snapshots are saved in ~/Snapshots/ on Linux.
If you did not install the Profiling kit with Mule or did not enable it, the Profiling tab indicates that the
profiler is not installed or enabled. If you want to install it now, you can download the ZIP or GZ version
of the mule-profiler-pack file here and follow the instructions here to install it.

Patch Management
The Mule Center tab in Mule HQ provides a list of all your Mule servers. It also allows you to install Mule
patches to remote servers that have been distributed to you by MuleSource.
Viewing Mule Log Files
You can view the Mule log files from remote servers in Mule HQ by clicking the Show Log link on the
Indicators tab when viewing the details of a Mule server.
Uninstalling Mule HQ
To uninstall Mule HQ, you run the hq-server and hq-agent scripts with the -u parameter. For example, on
Windows you would run:
hq-server.exe -u

hq-agent.exe -u
For complete information on uninstalling HQ, see Uninstalling Hyperic HQ on the Hyperic site.

Installing Mule HQ with an External Database
Installing Mule HQ with an External Database

By default, Mule HQ uses its own internal database. This section describes how to install Mule HQ with
a standalone PostgreSQL, Oracle, or MySQL database. To install, navigate to the Mule HQ directory, and
then run one of the following commands to perform a quick install, which prompts you for the database
connection information and uses defaults for all other settings:
PostgreSQL
UNIX: setup.sh -postgresql
Windows: setup.bat -postgresql
Oracle
UNIX: setup.sh -oracle
Windows: setup.bat -oracle
MySQL
UNIX: setup.sh -mysql
Windows: setup.bat -mysql
Notes
PostgreSQL 8.0
During installation, Mule HQ creates a language in the PostgreSQL database, but Mule HQ cannot create
the language automatically in PostgreSQL 8.0. Therefore, to use version 8.0, you must run the following
command on the Mule HQ database before starting the Mule HQ Server.
createlang plpgsql [MULEHQ:DATABASE NAME]
The createlang executable is located in the bin directory of your PostgreSQL installation.
MySQL 5.0
MySQL 5.0 or higher is not yet supported by Hyperic HQ and is currently in Beta. Support is expected for
Hyperic HQ 3.2.
For advanced database preparation, see the Database Preparation Guide

Mule HQ Agent Settings
This page last changed on May 29, 2008 by jackie.wheeler.
Mule HQ Agent Settings

When you run the Mule HQ Agent, it prompts you for connection information to your HQ Server.
[MULEHQ: Running agent setup ]

What is the HQ server IP address: 172.30.46.145
Should Agent communications to HQ always be secure [MULEHQ:default=yes]: yes
What is the HQ server port [MULEHQ:default=7080]: 7080
- Testing secure connection ... Success
What is your HQ login [MULEHQ:default=hqadmin]: hqadmin
What is your HQ password: **Not echoing value**
What IP should HQ use to contact the agent [MULEHQ:default=172.30.46.145]: 172.30.46.145
What port should HQ use to contact the agent [MULEHQ:default=2144]: 2144
- Received temporary auth token from agent
- Registering agent with HQ
- HQ gave us the following agent token
1192444751142-7096515327909319777-6396758454203270452
- Informing agent of new HQ server
- Validating
- Successfully setup agent
To make the Agent deployment process easier, you can specify these settings in the agent.properties
file located in the agent root directory. The file looks like this:
agent.setup.camIP=172.30.46.145
agent.setup.camPort=7080
agent.setup.camSSLPort=7443
agent.setup.camSecure=yes
agent.setup.camLogin=hqadmin
agent.setup.camPword=hqadmin
agent.setup.agentIP=*default*
agent.setup.agentPort=*default*
where values of camIP, camLogin and camPword parameters should be replaced with your HQ Server IP,
user name, and password. By setting these values in the file, you will no longer need to interactively
answer questions when you first start up the Mule HQ Agent.
Additionally, the MuleServerDetector uses an Internet connection to get some DTDs. If you use an
external HTTP proxy for your Internet connection, you must add the following value to the agent.javaOpts
property:
-Dhttp.proxyHost=<PROXY_HOST> -Dhttp.proxyPort=<PROXY_PORT>
For more information on agent properties see the HQ Agent Configuration page on the Hyperic site.

Using Mule Modules
Using Mule Modules

Modules are similar to transports in that they provide pluggable functionality, configured via dedicated
schema, but they differ in that there is no underlying transport to send or receive data. Following is a list
of the default Mule modules.
Acegi Module Security via Acegi.
Client Module MuleClient and the remote dispatcher, giving

simple access to the Mule server.
JAAS Module Security via JAAS.
JBoss Transaction Manager JBoss transaction support.
Management Module Mule agents for server management using JMX.
OGNL Module Provides a filter using OGNL expressions. For

details, see Using OGNL Expressions.
PGP Module Security via PGP.
Scripting Module Interface between Mule and scripting languages

(currently Groovy).
Spring Extras Module Extensions for using the Spring framework with
Mule.
SXC Module A very fast streaming XPath router and filter.
XML Module XML based utilities (mainly filters and routers).

Acegi Module
Acegi Module
This module provides Acegi-based security and delegates authorization to some other provider.
Security Manager
Child Elements of <security-manager...>
delegate-security-provider 0..1 An Acegi-based security provider

that delegates authorization to
some other provider.
Delegate Security Provider

An Acegi-based security provider that delegates authorization to some
other provider.
Attributes of <delegate-security-provider...>
delegate-ref name (no spaces) no
Child Elements of <delegate-security-provider...>
security-property 0..*
Http Security Filter

This appears to authenticate users via information in standard HTTP headers.
Attributes of <http-security-filter...>
realm string no
securityProviders string no The delegate-

security-provider
to use for
authenticating.
Use this element

in case you
have multiple
security managers
defined in your
configuration.

JAAS Module
JAAS Module
This module provides security via JAAS.
Security Manager
This is the security provider type that is used to configure JAAS related functionality.
security-provider 0..1 This is the security provider type

that is used to configure JAAS
related functionality.
password-encryption-strategy 0..*
Security Provider
This is the security provider type that is used to configure JAAS related functionality.
Attributes of <security-provider...>
loginContextName string no
credentials string no
loginConfig string no
loginModule string no
Jaas Security Filter

Authenticates users via JAAS.

JBoss Transaction Manager
JBoss Transaction Manager

This module enables Mule to use the JBoss transaction manager (previously Arjuna) to configure XA
transactions. Developers can configure one Transaction Manger per Mule instance. For more information,
see JBoss Transactions.
Transaction Manager
To configure an instance of the JBoss transaction manager within Mule, add this element to your Mule
XML config file. You can configure arbitrary properties on the transaction manager that will be passed on
to the underlying transaction manager. For example:
<jbossts:transaction-manager>
<property key="test" value="TEST"/>
</jbossts:transaction-manager>
You can then declare XA transactions on endpoints supporting XA transactions, and all those transactions
will be managed by the JBoss transaction manager.

Scripting Module
Table of Contents
• Scripting Module
• ° Script Context Bindings
° Transformers
° Component
° - Attributes of <component...>
- Child Elements of <component...>
° Script
° - Attributes of <script...>
- Child Elements of <script...>
° Groovy Refreshable
° - Attributes of <groovy-refreshable...>
° Lang
° Script Configuration Builder
Scripting Module
The scripting module provides facilities for using scripting languages in Mule. Any scripting languages
that supports JSR-223 can be used inside Mule. Scripts can be used as implementations of service
components or transformers. Also, scripts can be used for expression evaluations, meaning message
routing can be controlled using script evaluations on the current message. You can even configure Mule
instances from scripts.
Script Context Bindings

When run inside Mule, scripts have a number of objects available to them in the script context. These
are:
Name Description
log a logger that can be used to write to Mule's log

file.
muleContext a reference to the MuleContext object.
eventContext A reference to the eventcontext. This allows you

to dispatch events progammatically from your
script
message the current message.
originalPayload the payload of the current message before any

transforms.
payload the transformed payload of the current

message if a transformer is configured on the
service. Otherwise this is the same value as
originalPayload.
src same as payload, kept for backward

compatability.

service a reference to the current service object.
id the current event id.
result a placeholder object where the result of the script

can be written to. Usually it's better to just return
a value from the script unless the script method
doesn't have a return value.
Transformers
registry
transformers.
Name Description
transformer Runs a script to perform transformation on the

current message. To use Groovy as an example,
the following transformer configuration will
converts a comma-separated string of values to a
java.util.List.
Component
Defines a script component backed by a JSR-223 compliant script engine such as Groovy, JavaScript, or
Ruby. Scripting allows you to either directly embed your script inside the XML config or reference a script
using Spring's dynamic language support: http://static.springframework.org/spring/docs/2.5.x/reference/
dynamic-language.html.
Attributes of <component...>
script-ref name (no spaces) no A reference to

a script object
bean, that is, a
<script:script ...>
definition.
Child Elements of <component...>
script 0..1 A script to be executed by

a JSR-223 compliant script
engine such as Groovy,
JavaScript(Rhino), Python, Ruby
or Beanshell (etc).
java-interface-binding 0..* A binding associates a Mule

interface (this is like using

the bean a message is sent to
an endpoint). Script bindings
will only work with Java-based
scripting languages. Right
now there is no validation on
when languages support java
bindinngs since there are so
many scripting languages.
This example demonstrates how to configure a Groovy Script component with an in-line script.
xmlns:script="http://www.mulesource.org/schema/mule/scripting/2.0"
mule.xsd
http://www.mulesource.org/schema/mule/scripting/2.0 http://www.mulesource.org/schema/mule/
scripting/2.0/mule-scripting.xsd
mule-vm.xsd">
<vm:connector name="vmConnector" queueEvents="true"/>
<script:script name="myScript" engine="groovy">

return "$payload Received"
</script:script>
<model>
<service name="inlineScript">
<description>
This example demonstrates how to configure a Groovy Script component with an in-line script.
</description>
<inbound>
<inbound-endpoint address="vm://in1"/>
</inbound>
<script:component>
<script:script engine="groovy">
return "$payload Received"
</script:script>
</script:component>
<outbound>
<outbound-endpoint address="vm://out1"/>
</outbound>
</service>
This example demonstrates how to orchestrate message flows using bindings. The example calls out to
two different services and passes the results on to the outbound router.

<service name="scriptWithBindings">
<description>
This example demonstrates how to orchestrate message flows using bindings. The example calls out to
two
different services and passes the results on to the outbound router.
</description>
<inbound>
<inbound-endpoint ref="client_request"/>
</inbound>
<script:component>
msg = CalloutService.doSomething(payload)
return CalloutService.doSomethingElse(msg)
</script:script>
<script:java-interface-binding interface="org.mule.components.script.CalloutService"
method="doSomething">
<outbound-endpoint ref="callout_1" synchronous="true"/>
</script:java-interface-binding>
<script:java-interface-binding interface="org.mule.components.script.CalloutService"
method="doSomethingElse">
<outbound-endpoint ref="callout_2" synchronous="true"/>
</script:component>
<outbound>
<outbound-endpoint ref="client_response"/>
</outbound>
</service>
<service name="Callout1">
<inbound>
<inbound-endpoint ref="callout_1"/>
</inbound>
<test:component appendString=" Received by ${mule:serviceName}"/>
</service>
<service name="Callout2">
<inbound>
<inbound-endpoint ref="callout_2"/>
</inbound>
<test:component appendString=" Received by ${mule:serviceName}"/>
</service>
Script
Represents a script that can be used as a component for a service or a transformer. The script text can
be pulled in from a script file or be embedded inside this element. A script to be executed by any JSR-223
compliant script engine such as Groovy, JavaScript(Rhino), Python, Ruby or Beanshell (etc).
Attributes of <script...>
name string no The name used

to identify this
script object. This
is used when you

want to reference
this script object
from a component
or transformer.
engine string no The name of the

script engine
being used.
All scripting
languages that
support JSR-223
have a script
engine name such
as groovy, ruby,
python, etc. If this
value is not set,
but a script file is
configured, Mule
will attempt to
load the correct
script engine
according to
the script file's
extension.
file string no The script file

to load for this
object. The file
can be on the
classpath or local
file system.
Child Elements of <script...>
text 0..1 Used for embedding script code

inside the XML. This is useful
for simple scripts where you
are just mocking up a quick
application.
Groovy Refreshable
A wrapper for a component object that allows the underlying object to be reloaded at runtime. This
makes it possible to hot-deploy new component logic without restarting.
Attributes of <groovy-refreshable...>
name string no The name for this

refreshable groovy
bean wrapper.
refreshableBean- name (no spaces) no The referecne to a

ref groovy.lang.Groovy

object to use for
this component.
methodName string no The entrypoint

method to invoke
when a message
is received for the
object.
Lang
This element allows the http://www.springframework.org/schema/lang namespace to be embedded.
Within this element developers can include the spring lang namespace.
Script Configuration Builder

The ScriptConfigurationBuilder allows developers to create a Mule instance from a JSR-223 compliant
script. To load the manager from Groovy:
ConfigurationBuilder builder = new ScriptConfigurationBuilder("groovy", "../conf/mule-

config.groovy");
MuleContext muleContext = new DefaultMuleContextFactory().createMuleContext(builder);
Or to start the server from the command line:
mule -M-Dorg.mule.script.engine=groovy
-builder org.mule.module.scripting.builders.ScriptConfigurationBuilder
-config ../conf/mule-config.groovy
For more information about configuring a Mule instance from code or script see Configuration Overview.

Spring Extras Module
Spring Extras Module

This module provides extensions for using the Spring framework with Mule, such as using the Spring
container to build components managed by Mule.
Package Description
org.mule.module.spring.events A Spring EventMulticaster that allows any Spring

bean to send and receive Mule events through the
ApplicationContext and event listeners.
org.mule.module.spring.i18n Spring messages that can be localized.
org.mule.module.spring.remoting Classes for using Spring remoting. For more

information, see the Spring Remoting example.
org.mule.module.spring.transaction Provides classes for a transaction factory and

transaction manager factory.

SXC Module
SXC Module
The SXC module contains an outbound router and a filter that use the SXC project for streaming XPath
routing.
SXC allows listening for XPath expressions as the document is being parsed. As soon as an expression
is found, an event is fired, and parsing is stopped. This allows for much more efficient XPath evaluation.
XPath evaluators such as Jaxen work with a DOM model, so even when working with lazy-loading DOMs,
such as AXIOM, there is more overhead than in just reading directly off the XML stream.
SXC supports a limited subset of XPath expressions. For details, see the SXC documentation. To request
support for a missing XPath feature, please file a SXC JIRA.
Using the SXC Outbound Router and Filter

SXC requires a special filtering outbound router, inside of which you configure the SXC filter
and any other filters that do not work on the XML payload itself (such as AndFilter, OrFilter, and
MessagePropertyFilter). For example, this configuration routes a message based on an XML attribute:
<sxc:filtering-router>
<outbound-endpoint address="vm://log"/>
<sxc:filter pattern="//purchaseOrder[@country]"/>
<sxc:namespace prefix="test" uri="http://foo"/>
</sxc:filtering-router>
Following is another example of a filter that looks for messages where the billing address is within the
United States:
<sxc:filtering-router>
...
<sxc:filter pattern="/customer/billingaddress/country[text()='US']"/>
...
</sxc:filtering-router>

XML Module
XML Module
[ XML Formats ] [ Transformers ] [ Filters ] [ Splitters ]
The XML module contains several tools to help you read, transform, and write XML.
In addition to the functionality described on this page, you can also use the SXC Module, which enables
efficient XPath XML routing.
XML Formats
Mule understands a wide variety of XML Java representations:
• org.w3c.dom.Document, org.w3c.dom.Element
• org.dom4j.Document
• javax.xml.transform.Source
• InputStream, String, byte[]
• OutputHandler
• XMLStreamReader
• org.mule.module.xml.transformer.DelayedResult
Any transformer that accepts XML as an input will also understand these types.
Transformers
There are several standard transformers that process XML inside Mule.
XmlToObject <-> ObjectToXml Converts XML to a Java object and back again
using XStream.
XSLT Transforms XML payloads using XSL.
DomToXml <-> XmlToDom Converts DOM objects to XML and back again.
XmlToXMLStreamReader Converts XML from a message payload to a StAX

XMLStreamReader.
JXPath Queries and extracts object graphs using XPath

expressions using Jaxen.
XmlPrettyPrinter Allows you to output the XML with controlled

formatting, including trimming white space and
specifying the indent.
Efficient Transformations with DelayedResult
Mule contains a special XML output format called DelayedResult. This format allows very efficient XML
transformations by delaying any XML serialization until an OutputStream is available.
For example, here is an XSLT transformer set up to use DelayedResult:
<mxml:xslt-transformer name="transform-in"

xsl-file="xslt/transform.xslt"
returnClass="org.mule.module.xml.transformer.DelayedResult"/>
If the result of this transformation were being sent to an HTTP client, the HTTP client would ask Mule for
an OutputHandler and pass in the OutputStream to it. Only then would Mule perform the transformation,
writing the output directly to the OutputStream.
If DelayedResult were not used, the XML result would first be written to an in-memory buffer before
being written to the OutputStream. This will cause your XML processing to be slower.
Filters
The XML module contains both a Jaxen and a JXPath filter. For general details on how to use filters, see
Using Filters.
The Jaxen and JXPath filters allow you to route messages based on XPath expressions.
Jaxen Filter
The Jaxen filter is generally faster than the JXPath filter and should be considered the first choice when
using an XPath filter.
The following configuration routes messages to the "vm://echo" endpoint when the value of "/
e:purchaseOrder/e:shipTo/@country" is "US".
<outbound>
<filtering-router>
<outbound-endpoint address="vm://echo" synchronous="true"/>
<mule-xml:jaxen-filter pattern="/e:purchaseOrder/e:shipTo/@country" expectedValue="US">
<mule-xml:namespace prefix="e" uri="http://www.example.com"/>
</mule-xml:jaxen-filter>
</filtering-router>
....
</outbound>
JXPath Filter
The JXPath filter is very similar to the Jaxen filter. It is still used for historical purposes (it existed before
the Jaxen filter).
<outbound>
<filtering-router>
<outbound-endpoint address="vm://echo" synchronous="true"/>
<mule-xml:jxpath-filter pattern="/e:purchaseOrder/e:shipTo/@country"
expectedValue="US">
<mule-xml:namespace prefix="e" uri="http://www.example.com"/>
</mule-xml:jxpath-filter>
</filtering-router>
....
</outbound>
Splitters
The XML module contains two splitters, a filter-based splitter and a round-robin splitter. For more
information on these splitters, see Using Message Routers.

DomToXml Transformer
DOM/XML Transformers
Mule contains several transformers that convert between a W3C DOM object and its serialized
representation. The DomToXml transformer converts DOM objects to XML, the XmlToDom transformer
converts XML strings to DOM objects, and the DomToOutputHandler transformer converts from a DOM to
an OutputHandler serialization.
These transformers support the standard transformer attributes plus the following:
Dom To Xml Transformer

Converts an XML payload (Document, XML stream, Source, etc.) to a serialized String representation.
Attributes of <dom-to-xml-transformer...>
outputEncoding string no The encoding

to use for the
resulting XML/
Text.
Dom To Output Handler Transformer

Converts an XML payload (Document, XML stream, Source, etc.) to an OutputHandler for efficient
serialization.
Attributes of <dom-to-output-handler-transformer...>

to use for the
resulting XML/
Text.
Xml To Dom Transformer

Transforms an XML message payload to an org.w3c.dom.Document.
Attributes of <xml-to-dom-transformer...>

to use for the
resulting XML/
Text.

Example
To use the DOM/XML transformers, you add them to your Mule XML configuration as follows:
<xm:dom-to-xml-transformer name="DomToXml"/>
<xm:xml-to-dom-transformer name="xmlToDom" returnClass="org.w3c.dom.Document" />
<xm:xml-to-output-handler-transformer name="xmlToOutputHandler" />
You can then reference them by name from endpoints:
<vm:inbound-endpoint name="testEndpoint" path="another.queue" connector-ref="vmConnector1"

transformer-refs="DomToXml" />
...
<vm:outbound-endpoint ref="xml-dom-out" transformer-refs="xmlToDom" />
...

JXPath Transformer
JXPath Transformer
The JXPath transformer evaluates an XPath expression against the current message and returns the
result. By default, a single result will be returned. If multiple values are expected, set the singleResult
property to false, which will return a list of values. This property is available for strings only (not XML
nodes).
You configure the JXPath transformer as follows:
<jxpath-extractor-transformer name="invoice" expression="/book/title" singleResult="false"/>

XmlObject Transformers
XML-Object Transformers
[ Object to XML ] [ XML to Object ] [ Testing the Transformers ]
This pair of transformers converts XML code to serialized objects and back again. For serialization of Java
XML objects, see DomToXml Transformer.
Object to XML
The Object to XML transformer converts any object to XML using XStream. You configure this transformer
using the <object-to-xml-transformer> element. It takes the standard transformer attributes plus
one additional attribute, acceptUMOMessage, which specifies whether to serialize the whole message to
XML and not just its payload. This is useful with transports such as TCP where message headers are not
supported and would otherwise be lost.
For example:
<xml:object-to-xml-transformer name="ObjectToXml" acceptUMOMessage="true"/>
You can then reference this transformer from an endpoint:
<vm:inbound-endpoint path="another.queue" transformer-refs="ObjectToXml" />
XML to Object
The XML to Object transformer converts XML created by the Object to XML transformer in to a Java object
graph using XStream. You configure this transformer using the <xml-to-object-transformer> element.
It takes the standard transformer attributes.
For example:
<xm:xml-to-object-transformer name="XmlToObject" />
Testing the Transformers

The transformers can be tested using functional tests. For example, the following functional test uses
FunctionalTestCase, which is part of Mule's Test support, to test the Object to XML transformer.
public class MuleEndpointConfigurationTestCase extends FunctionalTestCase

{

{
return "org/mule/test/integration/test-endpoints-config.xml";
}

...
public void testComponent4Endpoints() throws Exception
{
// test inbound
Service service = muleContext.getRegistry().lookupService("TestComponent4");
assertNotNull(service);
assertNotNull(service.getInboundRouter().getEndpoints());
assertEquals(1, service.getInboundRouter().getEndpoints().size());
ImmutableEndpoint endpoint = (ImmutableEndpoint)service.getInboundRouter().getEndpoints().get(0);
assertNotNull(endpoint);
assertEquals(VMConnector.VM, endpoint.getConnector().getProtocol().toLowerCase());
assertEquals("queue4", endpoint.getEndpointURI().getAddress());
assertFalse(endpoint.getTransformers().isEmpty());
assertTrue(endpoint.getTransformers().get(0) instanceof ObjectToXml);
assertTrue(endpoint instanceof InboundEndpoint);
}
...
}

XmlToXMLStreamReader Transformer
XmlToXMLStreamReader Transformer
The XmlToXMLStreamReader transformer converts XML representations to a StAX XMLStreamReader.
XMLStreamReaders allow XML to be parsed as a series of events that are "pulled" from the stream. It is
very efficient.
This transformer supports the following input formats:
• javax.xml.transform.Source.class
• org.xml.sax.InputSource.class
• org.dom4j.Document.class
• org.w3c.dom.Document.class
• org.w3c.dom.Element.class
• org.mule.module.xml.transformer.DelayedResult.class
• String
• byte[]
• InputStream
Examples
To use the transformer, you must declare a custom transformer element:
<custom-transformer name="XmlToXSR" class="org.mule.module.xml.transformer.XmlToXMLStreamReader"/>
You can also create a "reversible" XMLStreamReader:
<custom-transformer name="XmlToXSR" class="org.mule.module.xml.transformer.XmlToXMLStreamReader">

<property key="reversible" value="true"/>
This allows you to cache XML events and replay them:
MuleMessage message = ...;

ReversibleXMLStreamReader xsr = (ReversibleXMLStreamReader) message.getPayload();
// start caching events

xsr.setTracking(true);
// parse....
while (...) { xsr.next(); }
// Go back to the beginning of the XML document

xsr.reset();
....
// Don't cache events any more

xsr.setTracking(false);

XSLT Transformer
<xslt-transformer ...>
The XSLT transformer uses XSLT to transform the message payload. Transformation objects are pooled
for better performance. You can set transformation context properties on the transformer and can pull
these properties from the message using Expression Evaluators. This works in a very similar way to the
XQuery Transformer on MuleForge.
Attributes

to use for the
resulting XML/
Text.
maxIdleTransformers integer no Transformers

are pooled for
better throughput,
since performing
and XSL
transformation
can be expensive.
This attribute
controls how
many instances
will remain idle in
the transformer
pool.
maxActiveTransformers integer no The total

number of XSLT
transformers that
will get pooled at
any given time.
xsl-file string no The full path to

the XSL template
file to use when
performing the
transformation.
This can be a
path on the local
file system or on
the classpath.
This attribute is
not required if
the <xslt-text>
element has been
set.
uriResolver name (no spaces) no The URI resolver

to use when
validating the XSL
output. If not set,
a default resolver
will be used
that checks for

resources on the
local file system
and classpath.
transformerFactoryClass
name (no spaces) no The fully qualified
class name of the
{{javax.xml.TransformerFactory
instance to use.
If not specified,
the default
JDK factory
{{TransformerFactory.newInsta
will be used.
Child Elements
xslt-text 0..1 The inline XSLT script definition.

This is not required if the {{xslt-
file}} attribute is set.
context-property 0..* A property that wil be made

available to the transform
context. Expression Evaluators
can be used to grab these
properties from the message at
runtime.
Example
The following example demonstrates how to configure an inline XSLT transformer pulling parameters from
the current message.
To use the XSLT transformer, you add it to your Mule XML configuration as follows:
<mulexml:xslt-transformer name="xslt">
<mulexml:xslt-text>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml"/>
<xsl:param name="title"/>
<xsl:param name="rating"/>
<xsl:template match="catalog">
<xsl:element name="cd-listings">
<xsl:attribute name="title">
<xsl:value-of select="$title"/>
</xsl:attribute>
<xsl:attribute name="rating">
<xsl:value-of select="$rating"/>
</xsl:attribute>
<xsl:apply-templates/>
</xsl:element>
</xsl:template>
<xsl:template match="cd">
<xsl:element name="cd-title">
<xsl:value-of select = "title" />
</xsl:element>
</xsl:template>
</xsl:stylesheet>

</mulexml:xslt-text>
<mulexml:context-property key="title" value="${header:ListTitle}"/>

<mulexml:context-property key="rating" value="${header:ListRating}"/>
</mulexml:xslt-transformer>
This example configures a transformer using inline XSLT expressions. It also defines two context
parameters:

These parameters are pulled from the current message and made available in the XSLT context so that
they can be referenced in your XSLT statements. You can use any valid expression. In this example, the
header evaluator is used to pull a header from the current message.
Your configured XSLT transformer can be referenced by an endpoint. In the following example, the result
is written to System.out. The test data looks like this:
<catalog>
<cd>
<title>Empire Burlesque</title>
<artist>Bob Dylan</artist>
<country>USA</country>
<company>Columbia</company>
<price>10.90</price>
<year>1985</year>
</cd>
<cd>
<title>Hide your heart</title>
<artist>Bonnie Tyler</artist>
<country>UK</country>
<company>CBS Records</company>
<price>9.90</price>
<year>1988</year>
</cd>

The result written to System.out looks like this:
<cd-listings title="MyList" rating="6">

<cd-title>Empire Burlesque</cd-title>
<cd-title>Hide your heart</cd-title>

The full configuration for this example is shown below.
xmlns:mulexml="http://www.mulesource.org/schema/mule/xml/2.0"

mule.xsd
mule-vm.xsd
mule-stdio.xsd
http://www.mulesource.org/schema/mule/xml/2.0 http://www.mulesource.org/schema/mule/xml/2.0/
mule-xml.xsd
beans-2.5.xsd">
<mulexml:xslt-transformer name="xslt">
<mulexml:xslt-text>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml"/>
<xsl:template match="catalog">
<xsl:element name="cd-listings">
<xsl:attribute name="title">
<xsl:value-of select="$title"/>
</xsl:attribute>
<xsl:attribute name="rating">
<xsl:value-of select="$rating"/>
</xsl:attribute>
<xsl:apply-templates/>
</xsl:element>
</xsl:template>
<xsl:template match="cd">
<xsl:element name="cd-title">
<xsl:value-of select = "title" />
</xsl:element>
</xsl:template>
</xsl:stylesheet>
</mulexml:xslt-text>

<model name="main">
<service name="Echo">
<inbound>

<vm:inbound-endpoint path="test.in" transformer-refs="xslt" synchronous="true"/>
</inbound>
<echo-component/>
<outbound>
<stdio:outbound-endpoint system="OUT"/>
</outbound>
</service>
</model>
</mule>

Testing the Transformer
This transformer can be tested using the following functional test. Note that it uses FunctionalTestCase,
which is part of Mule's Test support.
public class XSLTWikiDocsTestCase extends FunctionalTestCase

{
{
return "org/mule/test/integration/xml/xslt-functional-test.xml";
}
public void testMessageTransform() throws Exception

{
//We're using Xml Unit to compare results
//Ignore whitespace and comments
XMLUnit.setIgnoreWhitespace(true);
XMLUnit.setIgnoreComments(true);
//Read in src and result data

String srcData = IOUtils.getResourceAsString(
"org/mule/test/integration/xml/cd-catalog.xml", getClass());
String resultData = IOUtils.getResourceAsString(
"org/mule/test/integration/xml/cd-catalog-result-with-params.xml", getClass());
//Create a new Mule Client

//These are the message roperties that will get passed into the XQuery context
Map props = new HashMap();
props.put("ListTitle", "MyList");
props.put("ListRating", new Integer(6));
//Invoke the service

MuleMessage message = client.send("vm://test.in", srcData, props);
assertNotNull(message);
assertNull(message.getExceptionPayload());
//Compare results
assertTrue(XMLUnit.compareXML(message.getPayloadAsString(), resultData).similar());
}
}

Using Mule with Spring
This page last changed on Nov 21, 2008 by tcarlson.
Using Mule with Spring

Mule and Spring can integrate on different levels. You can can choose as much or little Mule in your
Spring application or Spring in your Mule application. The following pages describe in detail how you can
use Mule and Spring together.
• XML Configuration
The default way to configure Mule is via a Spring 2.0 XML file.
• Spring Application Contexts

Describes different options for how Mule creates and manages Spring Application Contexts.
• Using Spring Beans as Service Components

How to configure Spring beans as service components in Mule.
• Sending and Receiving Mule Events in Spring

A really easy way for your beans to send and receive Mule events via the Spring Application Context
without any code changes.
• Spring Remoting
An example of accessing Mule from an external application using Spring remoting.
Additionally, there are two Spring-related projects in the Developer Sandbox.

Sending and Receiving Mule Events in Spring
Sending and Receiving Mule Events in Spring

You can configure Spring beans to publish events to Mule and configure Spring event listeners to receive
Mule events. This page describes how to set up the configuration.
Spring Events Overview

Spring provides a simple mechanism for sending and receiving events between beans. To receive an
event, a bean implements ApplicationListener, which has a single method:
public void onEvent(ApplicationEvent event);
To publish events to listeners, you call the publishEvent() method on the ApplicationContext. This will
publish the same event to every listener in the context. You can also plug in custom event handlers to the
application context.
Mule Events in Spring

To start receiving Mule events, you create a bean based on MuleEventMulticaster in your Mule
configuration file. This class is an Application Event Multicaster that enables Spring beans to send and
receive Mule events. You also add one or more endpoints on which to receive events:
...
<spring:beans>
<spring:bean id="applicationEventMulticaster" class="org.mule.module.spring.events.MuleEventMulticaster">
<spring:property name="subscriptions">
<spring:list>
<spring:value>jms://my.queue</value>
<spring:value>pop3://ross:secret@mail.muleumo.org</value>
</spring:list>
</spring:property>
</spring:bean>
</spring:beans>
With this configuration, any emails received for ross@muleumo.org or any JMS messages sent to
my.queue will be received by all Spring event listeners. Note that the MuleEventMulticaster does
not interfere with normal Spring event behavior. If a non-Mule applicationEvent is sent via the
ApplicationContext, all beans registered to receive events will still get the event.
The inbound endpoints can be any valid Mule Endpoint, so you can receive JMS messages, SOAP
requests, files, HTTP and servlet requests, TCP, multicast, and more.
Adding Bean Subscriptions
You can have beans subscribe only to relevant events. The MuleSubscriptionEventListener includes two
methods for getting and setting an array of endpoints on which the bean will receive events.
package org.mule.module.spring.events;
public class TestSubscriptionEventBean extends TestMuleEventBean implements MuleSubscriptionEventListener

{
private String[] subscriptions;
public void setSubscriptions(String[] subscriptions)
{
this.subscriptions = subscriptions;
}
public String[] getSubscriptions()
{
return subscriptions;
}
}
You configure this bean like any other bean:
...
<spring:beans>
<spring:bean id="subscriptionBean" class="org.mule.module.spring.events.TestSubscriptionEventBean">
<spring:property name="subscriptions">
<spring:list>
<spring:value>vm://event.*</value>
</spring:list>
</spring:property>
</spring:bean>
</spring:beans>
Publishing Events to Mule
Publishing events is just as easy as receiving them. You use the standard publishEvent() method on
the application context. Your bean can get a reference to the application context by implementing
ApplicationContextAware or by querying MuleApplicationEvent .
//Create a new MuleEvent.

Object message = new String("This is a test message");
MuleApplicationEvent muleEvent = new MuleApplicationEvent(
message, "jms://processed.queue");
//Call publishEvent on the application context, and Mule does the rest
applicationContext.publishEvent(muleEvent);
For more information on publishing events, see the Error Handler Example.

Spring Application Contexts
Spring Application Contexts

[ Single Application Context ] [ Multiple Application Contexts ] [ Using an Existing Application Context ] [
Using an Existing Application Context as Parent ]
This page describes the options available for controlling how Mule creates and manages Spring
application contexts for your application.
Single Application Context

By default, Mule will combine all resource files into a single ApplicationContext, whether they are
"pure" Spring files or Mule configuration files. For example, the following code will create a single
application context consisting of the objects in spring-beans.xml plus the objects in mule-config.xml:
MuleContext muleContext = new DefaultMuleContextFactory().createMuleContext();
ConfigurationBuilder builder = new SpringXmlConfigurationBuilder("spring-beans.xml, mule-config.xml");

builder.configure(muleContext);
Or, in a more abbreviated form:
MuleContext muleContext = new DefaultMuleContextFactory().createMuleContext(

new SpringXmlConfigurationBuilder("spring-beans.xml, mule-config.xml"));
Multiple Application Contexts

(Since 2.1.0) You can instruct Mule to create a separate application context for each Mule configuration
file. The following code will create two application contexts, one for each configuration resource:
ConfigurationBuilder builder1 = new SpringXmlConfigurationBuilder("spring-beans.xml");

builder1.configure(muleContext);
ConfigurationBuilder builder2 = new SpringXmlConfigurationBuilder("mule-config.xml");

Using an Existing Application Context

(Since 2.1.2) If you already have an application context, you can instruct Mule to use it as follows:

ApplicationContext myAppContext = getMyAppContextFromSomewhereElse();
ConfigurationBuilder builder1 = new SpringConfigurationBuilder(myAppContext);

ConfigurationBuilder builder2 = new SpringXmlConfigurationBuilder("mule-config.xml");

Using an Existing Application Context as Parent

(Since 2.1.2) You can designate an existing application context as a parent context for Mule, so that the
Mule configuration can refer to and/or override beans in the application context:
ApplicationContext myAppContext = getMyAppContextFromSomewhereElse();
ConfigurationBuilder builder = new SpringXmlConfigurationBuilder("mule-config.xml");

builder.setParentContext(myAppContext);
builder.configure(muleContext);

Using Spring Beans as Service Components
Using Spring Beans as Service Components

[ Defining the Beans ] [ Configuring the Beans ] [ Configuring the Component ] [ Using JNDI and EJB
Session Beans ]
You can construct service components from Spring beans that you define in a separate Spring
context file or right in the Mule configuration file. This pages provides an example using two beans; a
RestaurantWaiter bean that receives and logs orders and then passes them to the KitchenService bean,
which receives the orders.
Defining the Beans

The Java code for the beans look like this:
public class RestaurantWaiter

{
private KitchenService kitchen = null;
public void takeOrder(Order order) {

//log order
//notify kitchen
this.kitchen.submitOrder(order);
}
public void setKitchenService(KitchenService kitchen) {

this.kitchen = kitchen;
}
public KitchenService getKitchenService() {

return kitchen;
}
}
Configuring the Beans

First, you configure the beans in your Spring application context:
<beans>
<bean id="restaurantWaiter" scope="prototype" class="com.foo.RestaurantWaiter">
<property name="kitchenService">
<ref local="kitchenService"/>
</property>
</bean>
<bean id="kitchenService" class="com.foo.KitchenService"/>

</beans>
We now have beans called restaurantWaiter and kitchenService that will be created by Spring. Notice
the resturantWaiter bean scope is set to prototype (by default, all beans in Spring are singletons unless
specified otherwise). This is important because Mule will pool your components, and telling Spring not to
create a singleton ensures that each pooled instance will be a unique instance.

If you want to configure the beans right in your Mule configuration file instead of in a separate Spring
context file, you could specify them like this:
...
<spring:beans>
<spring:bean id="restaurantWaiter" scope="prototype" class="com.foo.RestaurantWaiter">
<spring:property name="kitchenService">
<spring:ref local="kitchenService"/>
</spring:property>
</spring:bean>
<spring:bean id="kitchenService" class="com.foo.KitchenService"/>
</spring:beans>
Configuring the Component

After you have configured the beans, you can create your reference to restaurantWaiter in
the component. For example, the following configuration creates a component that will enable
restaurantWaiter to receive events from VM. This example assumes the beans are in a separate file, so if
you configured them right in the Mule configuration file, you do not need the <spring:import> tag.
...
<spring:import resource="conf/applicationContext.xml"/>
...
<service name="Restaurant Waiter">
<inbound>
<vm:inbound-endpoint path="order.queue"/>
</inbound>
<pooled-component>
<spring-object bean="restaurantWaiter"/>
</pooled-component>
</service>
When the Mule server starts, each of the <service> elements are loaded, and the bean you specified in
the <spring-object> tag is created. When an event is received on vm://orders.queue, an Order object
is passed to the takeOrder() method on the RestaurantWaiter, which then logs the order and passes it
to the KitchenService.
For more information on component configuration, see Configuring Components. For more information on
the elements you use to configure components, see Component Configuration Reference.
Using JNDI and EJB Session Beans

If you define JNDI and EJB session beans in Spring using the generic <bean> element, you configure
them exactly as any other Spring bean in Mule. However, if you use the <jee> elements to define them
in Spring (<jee:jndi-lookup>, <jee:local-slsb>, and <jee:remote-slsb>), you must include the jee
namespace and schema locations in your Mule configuration file as follows:
...
http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-jee-2.5.xsd"
...
<jee:remote-slsb id="creditAgencyEJB" jndi-name="local/CreditAgency"

business-interface="org.mule.example.loanbroker.credit.CreditAgency">
<jee:environment>
java.naming.factory.initial=org.openejb.client.LocalInitialContextFactory
java.naming.provider.url=rmi://localhost:1099 openejb.base=${openejb.base}
openejb.configuration=${openejb.configuration} logging.conf=${logging.conf}
openejb.nobanner=${openejb.nobanner}
</jee:environment>
</jee:remote-slsb>
...
<mule:service name="CreditAgencyService">
<mule:inbound>
<mule:inbound-endpoint ref="CreditAgency" />
</mule:inbound>
<mule:component>
<mule:spring-object bean="creditAgencyEJB" />
</mule:component>
</mule:service>
...
For more information, see Enterprise Java Beans (EJB) integration and the jee schema reference on the
Spring site.

Using the Mule Client
Using the Mule Client

[ Using Send and Dispatch ] [ Configuring the Mule Client ] [ MuleClient as a Web Services Client ] [
Performing an Event Request Call ] [ Associating Properties with the Message ] [ When Not to Use the
Mule Client ] [ Handling Message Collections ] [ Future Results ] [ Using the Remote Dispatcher ] [
Sending Messages to Components Directly ]
In most Mule applications, messages are triggered by an external occurrence such as a message being
received on a queue or a file being copied to a directory. However, if you want to send and receive
messages programmatically, you can create a Mule client.
The Mule client is a simple interface for Java clients to send and receive messages from a Mule server and
other applications. The client serves the following functions:
• Sending and receiving messages to and from a local or remote Mule server
• Communicating with other applications using any Mule transport
• Making requests to a Mule server behind a firewall using the RemoteDispatcher
The Mule client can be used as a web services client to make SOAP requests using popular SOAP
implementations such as Apache CXF. It can also send messages directly to a service component and
bypass the transports layer completely, which is useful for testing your service components or when
triggering an event from a script or JSP page.
The Mule client can be used with any of the Mule transports, making it a universal client for many types
of transports such as JDBC, JMS, FILE, POP3, XMPP, HTTP, etc.
The following sections describe how to use the MuleClient in various scenarios.
Using Send and Dispatch

The Mule client allows the user to send and receive messages programmatically. For example, to send a
JMS message to any application or Mule component listening on my.queue, you can use the dispatch()
method. The dispatch() method provides the ability to "fire and forget" messages over an endpoint.

client.dispatch("jms://my.queue", "Message Payload" null);
To make a regular synchronous call to a service and receive a result, you can use the send() method:

MuleMessage result = client.send("tcp://localhost:3456", "Message Payload", null);
The client send() and dispatch() methods expect the following arguments:
1. The Mule URL endpoint: any valid Mule Endpoint used to determine the transport, endpoint, and
other information about delivery of the message. This can also be an endpoint name stored in
configuration.
2. The message payload: any object carried by the message.
3. Properties: any properties or meta-data to associate with the message being sent
Don't use physical endpoints in your code

For clarity, the examples on this page use a physical endpoint URI, such as jms://myQueue.
However, it is much better practice to define all your endpoints inside a Mule configuration
file using the <endpoint> tag and then reference those endpoint names in your code.
Configuring the Mule Client

If you are using the Mule client in the same classloader (e.g., a Web App or Mule stand-alone), the client
will have access to the server configuration. For example, if you had some endpoints defined in your
server configuration file:
<http:endpoint host="192.168.0.1" port="80" path="/services" name="serviceEndpoint"/>
This endpoint will be accessible by the Mule client:

client.dispatch("serviceEndpoint", dataObject, null);
Essentially, the Mule client will have the same configuration information as the Mule server, since they will
both have access to the same registry.
If you are running the Mule client in stand-alone mode, you can still configure it using its own Mule XML
configuration file(s). You pass in these files when the client is created:
MuleClient client = new MuleClient("http-client-config.xml, shared-client-config.xml");

client.getMuleContext().start();
Note that you must start the local Mule context used by the client. You can also create your own Mule
context and pass it into the client:
//Create a MuleContextFactory
MuleContextFactory muleContextFactory = new DefaultMuleContextFactory();
//create the configuration builder and optionally pass in one or more of these
ConfigurationBuilder builder =
new SpringConfigurationBuilder("http-client-config.xml, shared-client-config.xml"));
//The actual context builder to use
MuleContextBuilder contextBuilder = new DefaultMuleContextBuilder();
//Create the context

MuleContext context = muleContextFactory.createMuleContext(builder, contextBuilder);
//Start the context

context.start();
//Create the client with the context

MuleClient client = new MuleClient(context);
MuleClient as a Web Services Client

The Mule client can be used as a web services client to make SOAP requests using popular SOAP
implementations such as Apache Axis or CXF.

//Arguments for the addPerson WS method

String[] args = new String[]{"Ross", "Mason"};
//Call the web service

client.dispatch("axis:http://localhost:38004/PersonService?method=addPerson", args, null);
//Call another method to look up the newly added person

MuleMessage result = client.send
("axis:http://localhost:38004/PersonService?method=getPerson", "Ross", null);
//A person object is returned, and all type mapping is handled for you
Person person (Person)result.getPayload();
System.out.println(person.toString());
The Mule SOAP Transport supports Apache Axis and CXF. For more information about Mule Axis support,
see Axis Web Services and Mule.
Performing an Event Request Call

Making a request to an endpoint is useful when using a transport that has a store of events that you want
to request rather then have a listener on the resource.
To make a request for a message, use the request() method:

MuleMessage result = client.request("pop3://ross:blah@mail.my.org", 5000);
This code will attempt to receive a message from a mailbox called ross on mail.my.org and will return
after five seconds if no message was received. Calling request() works for all Mule supported transports,
but it is more usual to make event request calls where there is a store to be queried such as a queue, file
directory, or some other repository.
Associating Properties with the Message

The previous examples set the properties argument to null. Properties can be arbitrary, such as to pass
around custom metadata with your messages, or they can be transport-specific. The following example
demonstrates an asynchronous request/response using JMS and the JMS-specific JMSReplyTo property.
When the JMSReplyTo is set, it is stated in the JMS spec that a receiver of the message should send back
any results to the destination defined in the JMSReplyTo header. Mule does this for you.
//create the client instance

//create properties to associate with the message

//Set the JMSReplyTo property, which is where the response message will be sent
props.put("JMSReplyTo", "replyTo.queue");
//dispatch the message asynchronously

client.dispatch("jms://test.queue", "Test Client Dispatch message", props);

//Receive the return message on the replyTo.queue
MuleMessage message = client.request("jms://replyTo.queue", 5000);
//This is the message sent back from the first component to process our message
System.out.println(message.getPayload());
When Not to Use the Mule Client

It's generally not good practice to make calls using the Mule client from your service objects or within
extensions to Mule such as routers or transformers.
When you need to dispatch or request events in Mule, you should use the current
org.mule.api.MuleEventContext and call the send/dispatch/request methods on the context instead.
To gain access to the MuleEventContext inside your services, you can implement the
org.mule.api.lifecycle.Callable interface.
If you need to make an event request from a transformer, filter, or interceptor, you should reconsider your
design strategy for that event flow.
Handling Message Collections

Since Mule 2.1, some outbound routers such as the Message Splitter, Multicaster, and Recipient List may
return more that one result message in the following cases:
• There is more than one endpoint configured on the router

• More than one of the endpoints has the synchronous=true attribute set
To handle situations where multiple results occur, Mule has introduced a new message type
org.mule.api.MuleMessageCollection . This type of message contains all message results in the order they
were received. Note that org.mule.api.MuleMessageCollection extends org.mule.api.MuleMessage , so
the interface is similar. If there are multiple results, the MuleMessage.getPayload() method returns a
java.util.List containing the payloads of each of the returned messages.
When using the Mule client, you can cast the message return type to get access to all MuleMessage
objects.

MuleMessage result = client.send("myEndpoint", "some data", null);
if(result instanceof MuleMessageCollection)

{
MuleMessageCollection resultsCollection = (MuleMessageCollection)result;
System.out.println("Number of messages: " + resultsCollection.size());
MuleMessage[] messages = resultsCollection.getMessagesAsArray();
}
Future Results
The Mule client allows you to make synchronous calls without blocking by using the sendAsync() method,
which returns a FutureMessageResult that can be queried later.

FutureMessageResult result = client.sendAsync("http://localhost:8881",
"Message Payload", null);
//Do some more stuff here

if(result.isready())
{
Object payload = result.getMessage().getPayload();
}
The FutureMessageResult returned is a placeholder for the real result message when the call returns.
By using a future result, you can continue with other tasks while the remote call executes. Calling
getMessage() will block until the call returns. Optionally, you can specify a timeout of how long to wait
(as shown in the example). You can also check if the call has returned using result.isReady().
Using the Remote Dispatcher

The Mule client can connect to, send, and receive messages from a remote Mule server through a
firewall using a remote dispatcher. This should only be used when the remote service being invoked does
not expose an endpoint accessible by the Mule client. Note that there is performance overhead when
using the remote dispatcher, because all requests and responses are serialized, sent to the server, and
deserialized before the real invocation is made from within the firewall.
To use the remote dispatcher, you enable it on the server instance by configuring the remote dispatcher
agent. You can ensure that the server can handle both asynchronous and synchronous calls by setting
the synchronous attribute to true. You can also set the remoteSyncTimeout setting, although often it is
better to control it at the MuleClient call level, as each call might have a different timeout requirement.
<client:remote-dispatcher-agent>
<client:remote-endpoint address="http://localhost:81" synchronous="true" remoteSyncTimeout="10000"/>
</client:remote-dispatcher-agent>
On the client side, you can now communicate with the remote server via the remote dispatcher agent.
For example:

RemoteDispatcher dispatcher = client.getRemoteDispatcher("http://localhost:81");
MuleMessage result = dispatcher.sendToRemoteComponent("StockManager", "give me the price of XXX", null);
StockQuote sq = (StockQuote)result.getPayload();
The Mule client executes the StockManager component on a remote Mule server, returning the result to
the client. Mule handles all the call marshalling. The first null argument is an optional string of comma-
separated transformers to use on the result message. The second null argument contains properties
associated with the request.
If you do not want to wait for the result to be returned from the remote server, you can use the
sendAsyncToRemoteComponent() method, which returns a FutureMessageResult:

RemoteDispatcher dispatcher = client.getRemoteDispatcher("tcp://localhost:60504");
FutureMessageResult result = dispatcher.sendAsyncToRemoteComponent("StockManager", null, "give me the
price of XXX", null);
//do some other stuff
StockQuote sq = (StockQuote)result.getMessage(1000).getPayload();

Specifying the Wire Format
You can specify the wire format to use for dispatching messages by configuring one of the following:
• <xml-wire-format>: uses the XML-Object transformers

• <serialization-wire-format>: uses the ByteArray-Serializable transformers
• <custom-wire-format>: set the class attribute to the class file of the transformer you want to use.
If you do not set the wire format, the serialization format is used. For more information on transformers,
see Using Transformers.
For example:
<client:remote-dispatcher-agent>
<client:remote-endpoint address="http://localhost:81" synchronous="true" remoteSyncTimeout="10000"/>
<client:xml-wire-format/>
</client:remote-dispatcher-agent>
Sending Messages to Components Directly

The Mule client provides a convenient way to send a message directly to a component without needing
to use a transport when the Mule server is running in the same classloader as the client. This approach
can be very useful in testing as well as triggering messages from a JSP page or JavaScript. For example,
to dispatch a message directly to your stock quote component called StockManager, you would do the
following:

MuleMessage result = client.sendDirect("StockManager", null, "give me the price of XXX", null);
StockQuote sq = (StockQuote)result.getPayload();
Note that the call is sendDirect, which tells the Mule client to go directly to the component and not
through a transport. You can specify a comma-separated list of transformers to use in the second
argument of this call.

Using the Mule RESTpack
Using the Mule RESTpack

[ Understanding REST ] [ Architecting RESTful Applications ] [ Mule REST Connectors ]
The Mule RESTpack is geared toward helping you build RESTful applications with Mule. REST is a very
powerful concept that enables scalable, decentralized growth.
Understanding REST
REST can be confusing. For an introduction to its advantages, disadvantages, and notes on using it, see
Making Sense of REST.
Architecting RESTful Applications

Mule is well suited for building RESTful applications, as it can easily bridge between the web and nearly
anything else in your enterprise. For more information on architecture considerations when using REST
with Mule, see Architecting RESTful HTTP applications.
Mule REST Connectors

The Mule RESTpack uses a series of connectors for building RESTful services. This section describes each
connector and links to more information on downloading and using them.
HTTP Connector
The Mule HTTP Transport contains most of the basic HTTP functionality that the connectors in the
RESTpack build on, including:
• Client and Server HTTP transport

• Support for running over a Servlet
• Support for polling resources via the PollingHttpMessageReceiver
The Mule HTTP transport is included with your Mule installation.
Apache Abdera Connector
The Mule Abdera connector makes it possible to integrate easily with Atom feeds and Atom Publishing
Protocol servers via the Apache Abdera project. The connector supports consuming Atom feeds,
publishing of Atom entries and server side AtomPub service.
To download and learn about using the Mule Abdera connector, go to the MuleForge Abdera page.
Jersey JAX-RS Connector
Jersey is the open source JAX-RS (JSR 311) reference implementation for building RESTful web services
via simple annotations. The Mule Jersey connector enables developers to embed these JAX-RS services
inside of Mule.
To download and learn about using the Mule Jersey connector, go to the MuleForge Jersey page.
Restlet Connector
Restlet is an open source REST framework, providing a powerful abstraction for building and consuming
RESTful services. The Mule Restlet connector facilitates the deployment and consumption of RESTful

services using the Restlet APIs inside of Mule. In addition, the transport exploits Restlet's simple URL
routing engine to provide RESTful routing of messages to Mule services.
To download and learn about using the Restlet connector, go to the MuleForge Restlet page.

Architecting RESTful HTTP applications
Architecting RESTful HTTP Applications

[ Modeling services and data ] [ Reliability ] [ Security ]
Modeling services and data

An important step in achieving the benefits REST has to offer is modeling your services and data
correctly. It is very different from the typical RPC (Remote Procedure Call) mindset that most people are
used to. It is however similar to object-oriented programming.
Imagine that each resource is an object. You can then perform the following operations on this object:
Operation Description
Get() Get a representation of the resource. This is a

safe operation. It does not change the state of the
resource.
Post(Representation) Perform an unsafe operation that changes the

state of the server and puts a new resources
somewhere or modifies an existing resource.
Put(Representation) Store a new representation of the resource.
Delete() Delete the resource
Head() Get metadata about the resource. This is a safe

operation. It does not change the state of the
resource
Options() Get information about which operations are

available to be used on the resource. This is a
safe operation. It does not change the state of the
resource.
Modeling your application can be broken down into roughly four steps:
1. Decompose your application into resources whose state you wish to access and modify.
2. Define the applicable operations of each resource
3. Give each resource a URI
4. Decide how to represent each resource
Decompose the application into resources
Anything inside your application can be a resource. So how do you decide what resources to create?
Typically you'll want to make a piece of your application a resource if:
1. You wish to link to that specific piece of data
2. You wish to modify or delete the data the resource represents
The prototypical example is often a CRUD based application. For instance, you may have a database of
orders which need to be fulfilled. If this was to be broken down into resources, you may have a "/orders"
URI for listing the contents of the orders database. You would also have an individual resource for each
order (i.e. "/order/1") which could be accessed, modified or deleted.

Give Each Resource a URI
Define the applicable methods of each resource
After (or while) breaking down your application into resources, you must determine which HTTP methods
you wish to support. It is very important that you respect the semantics of each HTTP method. GET,
HEAD, and OPTIONS are safe. PUT and DELETE are idempotent. POST is unsafe and may have side-
effects.
See the section on reliability for an explanation of how to apply these methods to build a robust service.
Decide how to represent each resource
There are many different data types you can choose to represent your resource. Many times you will not
have to think about what data type to use as it will be obvious. For instance, if you store an image of a
product in the database - the typical way to serve that would be return an image type, i.e. "image/jpeg".
A structured data type such as XML would make no sense.
For structured data, the choices are more complex. There is XML, specific formats of XML such as Atom,
JSON, XHTML, CSV, etc. On top of this, you may wish to multiple different representations of the resource
as well.
The most common formats for structured data are XML, Atom, JSON and XHTML. The table below gives a
quick summary of these formats and when you may wish to consider applying them.
XML
XML is the universal data format. Every system can understand it. It also has advanced tools for
modeling, parsing and querying such as XML schema, XPath, and XQuery. It is typically slower than other
formats as it is verbose, but can perform well for most applications.
Atom
Atom is a standard XML format for syndication. An Atom feed contains a series of entries. Each entry has
a place for a title, last update time, summary, content, authors, and more. It also allows extensions for
proprietary fields. Atom inherits all the benefits of XML, but introduces another very important property
- it is universally understood. If a user or machine understands Atom, it automatically understands your
application to some degree.
JSON
JSON stands for JavaScript Object Notation. One of its great advantages is that it is itself JavaScript. This
means that it becomes trivial to parse and use JSON inside a JavaScript application - especially when
compared to navigating XML. It is also extremely simple. It does not have the concept of namespaces nor
does it have modeling tools XML schema.
XHTML
Over the recent years Microformats have arise as a very powerful alternative to XML based data.
Microformats create a standard XHTML representation for data which allows it to both be parsed reliably
by machines and be used inside a web browser. Consider using a data format whenever possible as it
often allows you to tackle two birds with one stone.
Reliability
An important part of distributed system design is dealing with problems that occur in between the client
and the server it is talking to. Some examples of this include proxies going down or connections being
dropped.
HTTP does not have an inbuilt mechanism for achieving reliable deliveries of messages. Instead, reliability
is typically achieved through idempotent operations. An idempotent operation is one that can be repeated
over and over and still yield the same result. In the case of HTTP, this means that a message can be sent
again and again until confirmation is received. Even if the message is received twice, the ultimate result,
changing the resource state, will be the same.
Let us say that you want to update a resource which represents a customer - maybe they've changed
their address. In this case you would want to PUT the new representation to this resource which contains

the new address. If a connection drops and an error occurs, you can simply try putting the message
again as the operation is idempotent.
The same concept can be applied to the DELETE operation. The DELETE request can simply be repeated it
succeeds.
Creating new resources is trickier to do reliably in a RESTful manner. Typically resources are created
with a POST message. A simple example might go like this: you create a new order by POSTing the
representation to the "/orders" resource. You would then be redirected to the new resource. What
happens if the connection drops here though? You are not sure if the new order resource has been
created. If you simply retry the POST you could end up with two orders, which would be less than idea.
The trick is to use a two step process. First, the client must do a POST to the "/orders" resource with no
data. The server will then respond with a Location header which contains a new URL that the order can be
PUT to.
TODO: put code example in confluence
Now reliability can be achieved by simply repeating each step until it succeeds. If the POST fails and the
client submits the POST again, the worst that can happen is the creation of a URL that is not used. These
URLs can either be ignored or they can be expired. If the PUT fails, it can simply be retried.
There is a limitation of the above approach for reliability though - message ordering is not preserved.
To preserve message ordering, you will have to develop application specific extensions or move to a
technology like HTTPR or WS-ReliableMessaging.
Security
There are many options to provide security to your application depending on your requirements.
Authentication
HTTP has built in support for authentication. The "basic" and "digest" mechanisms are the most
commonly used authentication mechanisms. Basic authentication passes a username and password
in plain text to the server. Because of this, it should only be used over an SSL connection. Digest
authentication sends the username as plain text and an MD5 checksum of the password.
Another option for authentication is to use client side certificates with SSL. If the server has a copy of the
client's public key, it can verify that the messages were in encrypted with that key, and hence from the
client.
Privacy
The most often used mechanism for message privacy is SSL. It is efficient and widely supported. Other
alternatives include the message level security mechanisms mentioned below.
Limitations of SSL
There are two primary limitations of using SSL. First, it does not work well with intermediaries. Imagine
a situation where a gateway handles the SSL processing. In this case, your application will receive none
of the SSL information. This means you cannot use SSL certificates to verify who the client/server is
and that there may be unsecured routes along the network. Second, there is limited ability for other
authentication tokens, such as SAML.
Message level security
If you need message level security XML Signature/Encryption is one of your few options. This does
constrain you to use an XML data format though.
Another option that has been discussed is S/MIME. This has many disadvantages to it though which are
discussed here.

Making Sense of REST
Making Sense of REST

[ Advantages of RESTful Architectures and Implementations ] [ Disadvantages of RESTful Architectures
and Implementations ] [ Notes on Building Your Application with WS-* or RESTful HTTP ]
REST is the formalized architecture of HTTP based on the concepts of resources, links, and a uniform
interface. REST can be a somewhat confusing subject. Even the very acronym itself, which stands for
"Representation State Transfer", is a little obtuse. Luckily, there are some great resources out there.
One of the best resources out there is RESTful Web Services by Leonard Richardson and Sam Ruby.
It explains REST as well as many of the practical issues surrounding the issue of building RESTful web
services in great detail. You can find it at your local bookstore, Amazon, or online at O'Reilly's Safari
website.
For a good online (and free) introduction, Stefan Tilkov has written two excellent articles: A Brief
Introduction to REST and Addressing Doubts about REST.
And of course, there is the authoritative, but dense, thesis by Roy T. Fielding
You should familiarize yourself with the concepts of REST before continuing to read this page.
Advantages of RESTful Architectures and Implementations

Following is a discussion of some key benefits of RESTful architectures and implementations. Note that
while many of these items are benefits of the REST architectural style, many are related to HTTP, which is
a specific implementation of the REST concepts.
REST Is the Architecture of the Web
RESTful applications can be easily integrated in the web to great benefit. Your resources can be linked to
and from web pages. You can take advantage of Microformats to handle both UI and data related issues.
You can also take advantage of the existing web infrastructure and ecosystem: proxies, caches, browsers/
clients, load balancers, web standards, and more.
Increased Scalability
The web is the largest distributed system in the world. This is enabled by the inherent constraints in
RESTful architectures. For example, RESTful interactions are stateless. The server does not have to worry
about managing state between requests, as all state is kept on the client. Also, caching semantics are
built into the protocol. You can enable caching on any RESTful application without any special knowledge
since all interactions are based on the uniform interface.
Evolvability
All resources are identified by URIs. URIs provide a simple way to deal with the evolution of a system
as they can be used to partition servers and manage versioning. All one needs is a proxy to do
redirects based on the URI. Because there is no need to inspect the actual HTTP message payload, the
performance impact of this is negligible.
RESTful systems are based on hypermedia, so they provide links between different resources. Clients are
responsible for navigating the hypertext links. For instance, they browse to an order resource. They may
then browse to different items in the order via a link. If you need to direct a client to a different server or
move a server, simply change the link. Because the client knows the entry point link, it can still navigate
to the various items as your system evolves.

Disadvantages of RESTful Architectures and Implementations
This section describes the disadvantages to the REST approach.
Not Applicable to Many Message-oriented Situations
RESTful systems are fundamentally client-server based and are ill-suited to a number of message-
oriented scenarios. Publish-subscribe scenarios are one example. As there is no mechanism inside HTTP
for asynchronous responses, you often have to set up a second HTTP server if you want to receive
asynchronous replies.
Performance
HTTP is fundamentally a text-based protocol and is not geared toward performance. While it is not slow,
there are other protocols that may be more suitable for situations that are very performance-sensitive.
Transactions
HTTP does not include the concept of transactions. It is possible to model a transaction as an HTTP
resource, but it will not be as efficient as protocols such as JMS. It is also not appropriate to use
transactions with HTTP in many cases, as it can potentially consume many resources across multiple
servers if transactions are long lived.
Notes on Building Your Application with WS-* or RESTful HTTP

WS-* represents common names for the set of standards that encompass SOAP, WSDL, WS-Addressing,
WS-Security, WS-ReliableMessaging, WS-Policy, and many others. One cannot compare WS-* and REST
directly, as WS-* is a set of technology standards and REST is an architectural style. However, you can
compare the actual pieces of software that help you build RESTful systems and traditional web services.
Go Beyond XML
SOAP/WSDL web services are XML based. To create messages that encapsulate binary data, you must
use standards such as MTOM that wrap the XML in a MIME message, which often ends up being extra
work. With HTTP, resources can be any media.
Transport Neutrality
One of the great benefits of SOAP is that it is transport neutral. If this is a requirement for your
application, RESTful services are probably not the way to go.
Reliability
The RESTful and WS-* approaches to reliability differ tremendously.

The WS-* approach is based on WS-ReliableMessaging (WS-RM). WS-RM implements a TCP-like
system of acknowledgments: messages are sent from server A to server B, and server B then sends
acknowledgments back. If server A never receives an acknowledgment for a message, it eventually
resends it. WS-ReliableMessaging implementations (not the protocol) can also ensure messages are
delivered in the correct order.
RESTful systems typically achieve reliability through idempotent operations. See the section on RESTful
reliability for more information.
Security
The RESTful and WS-* approaches to security also differ greatly. WS-* advocates a layered approach. It
creates WS-Security for encryption and authorization, it uses WS-Trust for token exchange, and it uses
WS-SecureConversation to create more efficient security tokens for encrypted communication. These

approaches make sense if you need message-oriented, transport-neutral systems. However, many WS-*
systems make use of the underlying transport security (such as SSL) for its simplicity and performance.
RESTful systems can achieve security through both the transport layer (SSL) and a variety of message-
level mechanisms. Support for different security scenarios is arguably one of the reasons to choose WS-
* instead of REST for some specific (but rare) scenarios. See the section on RESTful security for more
information on how to build secure RESTful services.

Using Transformers
Using Transformers
[ Overview ] [ Configuring Transformers ] [ Types of Transformers ] [ Chaining Transformers ] [ Standard
Transformers Reference ] [ Transformation Best Practices ]
Transformers convert message payloads as they are transported between services.
Overview
Mule provides both standard and custom transformers. Standard transformers are configured with XML
that conforms to a Mule configuration schema. Custom transformers are configured using the fully
qualified class name of the transformer.
Standard Transformers
Standard transformers are easier to use than custom transformers. You don't need to know the Java
name of the transformer, and all properties are explicitly declared in a Mule configuration schema.
Following is an example of declaring the standard Append String transformer, which appends string text
to the original message payload:
<append-string-transformer name="myAppender" message=" ... that's good to know!"/>
If the original message payload was the string "foo", the transformer above would convert the string to
"foo ... that's good to know!".
For a list of the standard transformers, see Standard Transformers Reference below.
Transport-specific Transformers
Many transports and modules have their own transformers, such as the ObjectToJMSMessage for the JMS
transport. For information on transport transformers, see Available Transports and click a transport name
to see its transformers.
Custom Transformers
Custom transformers are typically user-defined transformers. Custom transformers are useful when the
transformer has not or will not be added to a Mule configuration schema, as is often the case with user-
defined transformers. They require more knowledge about the transformer, such as the transformer class
name and properties.
For more information, see Creating Custom Transformers.
Configuring Transformers
You can configure a transformer globally or locally. You configure a local transformer right on the
endpoint. You configure a global transformer before the <model> element in your Mule configuration
properties and then can refer to the transformer in multiple places. For example, the following code
defines two global transformers, which are referenced from two different services:
<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"/>
...
<model name="errorhandler-test">
<service name="Error Manager">
<inbound>
<inbound-endpoint address="file://./test-data/in" transformer-refs="XMLToExceptionBean
ExceptionBeanToErrorMessage">
<file:filename-wildcard-filter pattern="*.xml" />
</inbound-endpoint>
</inbound>
...
</service>
...
<service name="Business Error Manager">
<inbound>
<inbound-endpoint address="jms://exception.queue" transformer-refs="XMLToExceptionBean
ExceptionBeanToErrorMessage" />
</inbound>
...
</service>
</model>
This example uses the transformer-refs attribute on the endpoint to specify the transformers to use.
This is a fast way of specifying global transformers, but if you want to enter a local transformer or a mix
of local and global transformers, you must use the <transformer> element instead. For example, if only
one of the transformers were defined globally, you would refer to the global transformer and configure
the local transformer as follows:
<service name="Error Manager">

<inbound>
<inbound-endpoint address="file://./test-data/in">
<transformer ref="XMLToExceptionBean/>
<custom-transformer name="ExceptionBeanToErrorMessage"
class="org.mule.example.errorhandler.ExceptionBeanToErrorMessage"
returnClass="org.mule.example.errorhandler.ErrorMessage" />
<file:filename-wildcard-filter pattern="*.xml" />
</inbound-endpoint>
</inbound>
...
</service>
Types of Transformers
The above examples illustrate configuring inbound transformers, which are applied to the message after
it is received on the inbound endpoint and before it is passed to the service's component. You specify
inbound transformers under the <inbound-endpoint> element.
You can also specify an outbound transformer in exactly the same way except on the routers in the
<outbound> element, in which case the message is transformed after it has been processed by the
service's component but before it has been sent to the outbound endpoint specified by that router. For
example:
<outbound>
<filtering-router transformer-refs="ErrorMessageToException">
<file:outbound-endpoint path="test-data/exceptions" outputPattern="Exception-[UUID].xml" transformer-
refs=

"ErrorMessageToExceptionBean ExceptionBeanToXML" />
</filtering-router>
...
</outbound>
Lastly, you can specify a response transformer, which converts message payloads on their way from the
service to the caller. To configure a response transformer, you use the responseTransformers-refs
attribute on the router, or you can use the <response-transformer> element. For example:
<inbound>
<vm:inbound-endpoint path="my.inbound.endpoint" responseTransformer-refs="myAppender"/>
</inbound>
<some-component/>
In this example, the response message from "some-component" is transformed using the "myAppender"
transformer before being returned to the caller.
Chaining Transformers
You can chain transformers together so that the output from one transformer becomes the input for the
next. To chain transformers, you create a space-separated list of transformers in the transformer-refs
or responseTransformer-refs attributes or by creating multiple <transformer> elements as shown
above.
For example, this chain ultimately converts from a ByteArray to InputStream:
transformer-refs="ByteArrayToString StringToObject ObjectToInputStream"
You could also configure this as follows:
<transformer ref="ByteArrayToString"/>
<transformer ref="StringToObject"/>
<transformer ref="ObjectToInputStream"/>
Standard Transformers Reference

Following are the standard transformers available with Mule. Individual transports may also have their
own transformer types, which are documented with the transports themselves. For more information, see
Available Transports. For a complete configuration reference to standard transformers, see Transformers
Configuration Reference.
Basic
The basic transformers are in the org.mule.transformer.simple package. They do not require any special
configuration. For details on these transformers, see Transformers Configuration Reference.
ByteArrayToHexString <-> A pair of transformers that convert between byte

HexStringToByteArray arrays and hex strings.

ByteArrayToMuleMessage <-> A pair of transformers that convert between byte
MuleMessageToByteArray arrays and Mule messages.
ByteArrayToObject <-> A pair of transformers that convert between

ObjectToByteArray byte arrays and objects. If the byte array is not
serialized, ByteArrayToObject returns a String
created from the bytes as the returnType on the
transformer.
ByteArrayToSerializable <-> A pair of transformers that serialize and

SerializableToByteArray deserialize objects.
ExpressionTransformer Evaluates one or more expressions on the current

message and return the results as an Array. For
details, see Using Expressions.
MessagePropertiesTransformer A configurable message transformer that allows

users to add, overwrite, and delete properties on
the current message.
ObjectArrayToString <-> A pair of transformers that convert between

StringToObjectArray object arrays and strings. Use the configuration
elements <byte-array-to-string-transformer>
and <string-to-byte-array-transformer>.
ObjectToInputStream Converts serializable objects to an input stream

but treats java.lang.String differently by
converting to bytes using the String.getBytes()
method.
ObjectToOutputHandler Converts a byte array into a String.
ObjectToString Returns human-readable output for various kinds

of objects. Useful for debugging.
StringAppendTransformer Appends a string to an existing string.
StringToObjectArray Converts a string to an object array. Use the

configuration element <string-to-byte-array-
transformer>.
XML
The XML transformers are in the org.mule.module.xml.transformer package. They provide the ability to
transform between different XML formats, use XSLT, and convert to POJOs from XML. For information, see
XML Module.
Scripting
The Scripting transformer transforms objects using scripting, such as JavaScript or Groovy scripts. This
transformer is in the org.mule.module.scripting.transformer package.
Encryption
The encryption transformers are in the org.mule.transformer.encryption package.

Encryption <-> Decryption A pair of transformers that use a configured
EncryptionStrategy implementation to encrypt and
decrypt data.
Compression
The compression transformers are in the org.mule.transformer.compression package. They do not require
any special configuration.
GZipCompressTransformer <-> A pair of transformers that compress and

GZipUncompressTransformer uncompress data.
Encoding
The encoding transformers are in the org.mule.transformer.codec package. They do not require any
special configuration.
Base64Encoder <-> Base64Decoder A pair of transformers that convert to and from

Base 64 encoding.
XMLEntityEncoder <-> XMLEntityDecoder A pair of transformers that convert to and from

XML entity encoding.
Transformation Best Practices

Mule has an efficient transformation mechanism. Transformers are applied to inbound or outbound
endpoints, and the data is transformed just before it is sent from a service or just before it is received by
another service. Transformers can be concatenated, so it is simple to perform multiple transformations on
data in transit.
There is no one standard approach for how and where transformations should occur. Some maintain that
because transformation should always be applied on inbound/outbound data, transformations should be
available as part of the enterprise service bus instead of inside the service components. This approach
matches the concepts of Aspect Oriented Programming (AOP). Others conclude that it is far more efficient
to encode the transformation logic into the service components themselves. In the second case, however,
there is no distinction between code that is related to a business process and code that is generic enough
to be reused, which contradicts the philosophy of an ESB.
While there is no industry best practice, MuleSource recommends that developers examine their
transformation logic to see if it will always be used (AOP) or if it is specific to a business process. In
general, if it will always be used, you should use a transformer, and if it is specific to a single business
process, it should be part of the service component.
References: http://msdn2.microsoft.com/en-us/library/aa480061.aspx http://blogs.ittoolbox.com/eai/

applications/archives/transformation-in-a-soa-12186

Creating Custom Transformers
Creating Custom Transformers

Custom transformers are typically user-defined transformers. Custom transformers are useful when the
transformer has not or will not be added to a Mule configuration schema, as is often the case with user-
defined transformers. They require more knowledge about the transformer, such as the transformer class
name and properties.
For example, if we were to declare the Append String transformer above as a custom transformer and use
Spring for the property, it would look like this:
<custom-transformer name="myAppender" class="org.mule.transformer.simple.StringAppendTransformer">

<spring:property name="message" value=" ... that's good to know!"/>
All Mule transformers implement org.mule.api.transformer.Transformer . There is an abstract transformer

implementation, AbstractTransformer , which defines methods for controlling the object types this
transformer supports and validates the expected return type, leaving you to implement a single
transform() method.
For example, the Hello World example defines a custom transformer called StdinToNameString, which
removes line breaks and newlines from the string:
package org.mule.example.hello;
import org.mule.api.transformer.TransformerException;
import org.mule.transformer.AbstractTransformer;
public class StdinToNameString extends AbstractTransformer

{
public StdinToNameString()
{
super();
this.registerSourceType(String.class);
this.setReturnClass(NameString.class);
}
public Object doTransform(Object src, String encoding) throws TransformerException

{
NameString nameString = new NameString();
String name = (String) src;
nameString.setName(name.replaceAll("\r", "").replaceAll("\n", "").trim());
return nameString;
}
}
The transformer is then configured like this:
<custom-transformer name="StdinToNameString" class="org.mule.example.hello.StdinToNameString" />

...
<service name="GreeterUMO">
<inbound>
<stdio:inbound-endpoint system="IN" transformer-refs="StdinToNameString" />
</inbound>

...
If the transformer needs access to the incoming message to retrieve properties useful for transformation,
you can implement AbstractMessageAwareTransformer instead, a sub-class of AbstractTransformer that
also provides access to the message. In this case, you override the method transform(MuleMessage
message, String outputEncoding) and can use message.getProperty(Object key) to retrieve the
properties or message.setProperty(Object key, Object value) to set properties in the transformed
message.
Mule also provides several standard transformers, including XML transformers (such as XML to
Object, XSLT, and DOM to XML), encryption transformers that encrypt and decrypt data, compression
transformers that compress and decompress data, and more. For a list of the default transformers in
Mule, see Using Transformers.

Transformers Configuration Reference
Transformers Configuration Reference

[ Transformer ] [ Auto Transformer ] [ Custom Transformer ] [ Message Properties Transformer ]
[ No Action Transformer ] [ Base64 Encoder Transformer ] [ Base64 Decoder Transformer ] [ Xml
Entity Encoder Transformer ] [ Xml Entity Decoder Transformer ] [ Gzip Compress Transformer ] [
Gzip Uncompress Transformer ] [ Byte Array To Hex String Transformer ] [ Hex String To Byte Array
Transformer ] [ Byte Array To Object Transformer ] [ Object To Byte Array Transformer ] [ Object To
String Transformer ] [ Byte Array To Serializable Transformer ] [ Serializable To Byte Array Transformer ]
[ Byte Array To String Transformer ] [ String To Byte Array Transformer ] [ Append String Transformer ] [
Encrypt Transformer ] [ Decrypt Transformer ] [ Expression Transformer ]
This page provides details on configuring the standard transformers. Note that many transports and
modules provide their own transformers as well.
Transformer
A reference to a transformer defined elsewhere.
Attributes of <transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.
returnClass class name no The class of

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).
ignoreBadInput boolean no Many transformers

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a

chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.

transformer to
use.
Auto Transformer
A transformer that uses the transform discovery mechanism to convert the message payload. This
transformer works much better when transforming custom object types rather than Java types, because
there is less chance for ambiguity.
Attributes of <auto-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If

a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Custom Transformer
A user-implemented transformer.
Attributes of <custom-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current

message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.

implementation of
the Transformer
interface.
Child Elements of <custom-transformer...>
Message Properties Transformer

A transformer that can add or delete message properties.
Attributes of <message-properties-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.

Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
overwrite boolean no true If false, a property

is not added if
the message
already contains a
property with that
name.
Child Elements of <message-properties-transformer...>
delete-message-property 0..* Delete a message property.
add-message-property 0..* Add a message property.
rename-message-property 0..* Rename a message property.
add-message-properties 0..1 Add a set of message properties.
No Action Transformer
A transformer that has no effect.
Attributes of <no-action-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is

defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Base64 Encoder Transformer

A transformer that base64 encodes a string or byte array message.
Attributes of <base64-encoder-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Base64 Decoder Transformer

A transformer that base64 decodes a message to give an array of bytes.
Attributes of <base64-decoder-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by

the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Xml Entity Encoder Transformer

A transformer that encodes a string using XML entities.
Attributes of <xml-entity-encoder-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers

are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Xml Entity Decoder Transformer

A transformer that decodes a string containing XML entities.
Attributes of <xml-entity-decoder-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat

incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Gzip Compress Transformer

A transformer that compresses a byte array using gzip.
Attributes of <gzip-compress-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Gzip Uncompress Transformer

A transformer that uncompresses a byte array using gzip.
Attributes of <gzip-uncompress-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.

Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Byte Array To Hex String Transformer

A transformer that converts a byte array to a string of hexadecimal digits.
Attributes of <byte-array-to-hex-string-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate

input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Hex String To Byte Array Transformer

A transformer that converts a string of hexadecimal digits to a byte array.
Attributes of <hex-string-to-byte-array-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If

a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Byte Array To Object Transformer

A transformer that converts a byte array to an object (either deserializing or converting to a string).
Attributes of <byte-array-to-object-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot

accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Object To Byte Array Transformer

A transformer that serializes all objects except strings (which are converted using getBytes()).
Attributes of <object-to-byte-array-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls

whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Object To String Transformer

A transformer that gives a human-readable description of various types (useful for debugging).
Attributes of <object-to-string-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is

evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Byte Array To Serializable Transformer

A transformer that converts a byte array to an object (deserializing the object).
Attributes of <byte-array-to-serializable-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is

called. If false
the chain ends,
keeping the result
generated up to
that point.
Serializable To Byte Array Transformer

A transformer that converts an object to a byte array (serializing the object).
Attributes of <serializable-to-byte-array-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result

generated up to
that point.
Byte Array To String Transformer

A transformer that converts a byte array to a string.
Attributes of <byte-array-to-string-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.

String To Byte Array Transformer
A transformer that converts a string to a byte array.
Attributes of <string-to-byte-array-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
Append String Transformer

A transformer that appends a string to a string payload.

Attributes of <append-string-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
message string no The string to

append.
Encrypt Transformer
A transformer that encrypts a message.

Attributes of <encrypt-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.

the encryption
strategy to use.
This should be
configured using
the password-
encryption-
strategy element,
inside a security-

manager element
at the top level.
Decrypt Transformer
A transformer that decrypts a message.
Attributes of <decrypt-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the
remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.

the encryption
strategy to use.
This should be
configured using
the password-
encryption-
strategy element,
inside a security-
manager element
at the top level.
Expression Transformer
A transformer that evaluates one or more expressions on the current message. Each expression equates
to a parameter in the return message. The return message for two or more expressions will be an
Object[].
Attributes of <expression-transformer...>

transformer
so that other
elements can
reference it.
Required if the
transformer is
defined at the
global level.

the message
generated by
the transformer.
This is used if
transformers
are auto-
selected (which
is somewhat
incomplete at the
moment).

only accept
certain classes.
Such transformers
are never called
with inappropriate
input (whatever
the value of this
attribute). If
a transformer
forms part of a
chain and cannot
accept the current
message class,
this flag controls
whether the

remaining part
of the chain is
evaluated. If
true, the next
transformer is
called. If false
the chain ends,
keeping the result
generated up to
that point.
returnSourceIfNull boolean no If all expressions

return null on
this transformer,
this flag will
cause the source
payload to be
returned without
modification.
Child Elements of <expression-transformer...>
return-argument 0..1 A list of expressions, each of

which is evaluated and equates
to an element in the result
message. If just one 'return-
argument' is configured, the
result will be the evaluation of
that expression rather than an
object array.

XmlPrettyPrinter Transformer
Xml Prettyprinter Transformer

Formats an XML string using the Pretty Printer functionality in org.dom4j.io.OutputFormat.
Attributes of <xml-prettyprinter-transformer...>
encoding string no The encoding

format to use,
such as UTF-8.
expandEmptyElements
boolean no Whether to
expand empty
elements from
<tagName> to
<tagName></
tagName>.
indentEnabled boolean no Whether to enable

indenting of the
XML code. If true,
the indent string
and size are used.
indentString string no The string to use

as the indent,
usually an empty
space.
indentSize integer no The number of

indent strings
to use for each
indent, such as
"2" if indentString
is set to an empty
space and you
want to use two
empty spaces for
each indent.
lineSeparator string no The string to use

for new lines,
typically "\n".
newLineAfterNTags integer no If the newlines

attribute is true,
the number of
closing tags
after which a
newline separator
is inserted. For
example, setting
this to "5" will
cause a newline
to be inserted
after the output of

five closing tags
(including single
tags).
newlines boolean no Whether newlines

should be printed.
If false, the XML is
printed all on one
line.
omitEncoding boolean no Whether the

XML declaration
line includes the
encoding of the
document. It
is common to
suppress this in
protocols such as
SOAP.
padText boolean no Whether to

ensure that text
immediately
preceded by or
followed by an
element will be
"padded" with a
single space. This
is useful when
you set trimText
to true and
want to ensure
that "the quick
<b>brown</
b> fox" does
not become "the
quick<b>brown</
b>fox".
suppressDeclaration boolean no Whether to

suppress the XML
declaration line.
It is common to
suppress this in
protocols such as
SOAP.
trimText boolean no Whether to trim

white space in the
XML.
XHTML boolean no Whether to

use the XHTML
standard, which
is like HTML but
passes an XML
parser with real,
closed tags, and
outputs CDATA
sections with
CDATA delimiters.

Web Services
Using Web Services

The following topics describe how to use web services with Mule.
Using Axis with Mule - Links to several topics describing Axis support in Mule.
Building a CXF Web Service - Describes how to build a CXF web service and use it in Mule.
Using the Mule Client - Describes the Mule Client, which can be used as a SOAP client.
Proxying Web Services - Describes how to use Mule as a web service gateway/proxy in various scenarios.
Supported Web Service Standards - Web service standards supported by Mule and CXF.
Web Service Wrapper - Describes how to use the WebServiceWrapperComponent class to send the result
of a web service call to another endpoint.
RESTpack - Provides support for building RESTful services inside Mule. You can also use the REST service
wrapper (a specialized Mule service component) in the HTTP transport to proxy REST-style requests to
external REST/HTTP services. This wrapper component acts as a REST client and is appropriate if you do
not have strict REST requirements.
Echo Example - A simple example of exposing a Mule service as a web service using Axis.
Using .NET Web Services with Mule - Tips for using .NET web services with Mule.

Axis
Using Axis with Mule

The following topics describe how to configure Mule and Apache Axis.
• Axis Web Services and Mule - Introduction to exposing Mule services over Axis and invoking SOAP
services.
• Configuring Axis - Controlling WSDL generation, named parameters, Advanced Service
configuration, and more.
• Axis Transport - Basic configuration of the Axis transport.
• Axis SOAP Transports - Using Axis over JMS, VM, SMTP, and other Mule transports.
• Axis SOAP Styles - Configuring services for Doc/Lit, Message or RPC style invocations.

Axis SOAP Styles
Axis SOAP Styles

By default, Mule Axis support uses RPC/Encoded for SOAP messages. However, because of compatibility
issues on other platforms, it has become increasingly popular to use Document/Literal/Wrapped
style services. This page describes how to use Doc/Lit, Doc/Lit/Wrapped, and Message style services
using Axis in Mule. For an overview of the pros and cons of each style/use combination, see http://
www-128.ibm.com/developerworks/webservices/library/ws-whichwsdl/.
The client examples below show how to invoke an Axis web service hosted in Tomcat using the Mule
client. The example behaves exactly the same way if the service is hosted in Mule unless explicitly noted
otherwise. These tests were run against Tomcat 5.5.12 and Axis 1.3.1. Each test uses the Calculator
service as used in the Axis User Guide.
Document Literal Wrapped

This is the preferred approach to Document Literal style services. "Wrapped" simply means that the
parameters are wrapped in an element whose name is the name of the operation to invoke.
Client Example
This example is very similar to the Doc/Lit example, except that we set the message style to 'wrapped/
literal', and there is no need to add any server configuration, as the method name is stored in the
message.
String URL = "axis:http://localhost:8080/axis/Calculator.jws?method=add";

props.put("style", "wrapped");
props.put("use", "literal");
MuleMessage result = client.send(URL, new Object[]{new Integer(3), new Integer(3)}, props);
assertEquals(result.getPayload(), new Integer(6));
The SOAP request for this call looks like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://
www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<add xmlns="">
<value0 xsi:type="xsd:int">3</value0>
</add>
</soapenv:Body>
</soapenv:Envelope>
In the next example, we can see how to change the namespace of the method as well as naming the
parameters. This is very useful when calling services from other platforms.

Doc/Lit/Wrapped with Named Parameters
If you're invoking external services, the Axis-generated names for parameters and namespaces do not
work. You can easily change these in Mule as follows:
Client Example
String URL = "axis:http://localhost:8080/axis/Calculator.jws";

SoapMethod method = new SoapMethod(new QName("http://muleumo.org/Calc", "add"));

method.addNamedParameter(new QName("Number1"), NamedParameter.XSD_INT, "in");
method.addNamedParameter(new QName("Number2"), NamedParameter.XSD_INT, "in");
method.setReturnType(NamedParameter.XSD_INT);

props.put("style", "wrapped");
props.put("method", method);
Note that we do not pass the method name in the query string of the URL. Instead, we create a
SoapMethod object and add it to the parameters passed to the client call.
The SOAP request now looks like this:

<soapenv:Body>
<add xmlns="http://muleumo.org/Calc">
<Number1 xsi:type="xsd:int" xmlns="">3</Number1>
<Number2 xsi:type="xsd:int" xmlns="">3</Number2>
</add>
</soapenv:Body>
</soapenv:Envelope>
Using the Mule Configuration
Instead of hard-coding the namespaces and parameter names, you can specify them in an endpoint
configuration in the Mule configuration file and reference the endpoint from your Mule client. The
configuration file will look like this:
<axis:endpoint name="calculatorAddEndpoint"
address="http://localhost:62088/axis/Calculator?method=add"
style="WRAPPED" use="LITERAL">
<axis:soap-method method="add">
<axis:soap-parameter parameter="Number1" type="int" mode="IN"/>
<axis:soap-parameter parameter="Number2" type="int" mode="IN"/>
<axis:soap-return type="int"/>
</axis:soap-method>
</axis:endpoint>

This endpoint configuration can be used by the Mule client or on a component outbound router. The client
code is now much simpler:
MuleClient client = new MuleClient("org/mule/test/integration/providers/soap/axis/soap-client-endpoint-

config.xml");
Muleessage result = client.send("calculatorAddEndpoint", new Object[]{new Integer(3), new Integer(3)}, null);

Notice the URL for the MuleClient call contains the name of the service endpoint, not the physical location
of the resource.
Document Literal
Mule hosted Web services using Axis cannot be invoked using Doc/Lit. Use Doc/Lit/Wrapped
instead. Users can still invoke remote web services using Doc/Lit as shown in the example
below.
Client Example
For this example, we must tell the Mule client to use 'document/literal' for the message style, and we
pass this information into the call on the Mule client. This requires some configuration on the Axis server.
The biggest limitation of Doc/Lit is that operation/method name is not passed with the message.

props.put("style", "document");

<soapenv:Body>
</soapenv:Body>
</soapenv:Envelope>
Using Doc/Lit with Axis might appear to work even when you don't add operation info to
the Axis server configuration. This happens when there is a single parameter for the service
and the parameter name is the same as the operation/method name you want to invoke.
For more information, see Axis Operations.
RPC Encoded
Because Axis uses RPC/Encoded by default, there is no need to pass any additional configuration
information. The client call looks like this:

MuleMessage result = client.send(URL, new Object[]{new Integer(4), new Integer(3)}, null);

<soapenv:Body>
<add soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<value0 href="#id0"/>
<value1 href="#id1"/>
</add>
<multiRef id="id0" soapenc:root="0" soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/"
xsi:type="soapenc:int" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">4</
multiRef>
<multiRef id="id1" soapenc:root="0" soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/
encoding/"
xsi:type="soapenc:int" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">3</
multiRef>
</soapenv:Body>
</soapenv:Envelope>

Axis SOAP Transports
Axis SOAP Transports

[ SOAP Over JMS ] [ SOAP Over VM ] [ Binding to a Servlet Container ] [ Using Other Mule Transports ]
Mule transports can deliver SOAP requests between Axis clients and Axis services hosted by Mule. This
means you can easily use JMS, VM, SMTP, or even XMPP (Jabber) to send SOAP requests. This page
describes how to configure these transports.
SOAP Over JMS

First, if you do not want to use the default JMS connector, configure the connector you do want to use in
your Mule XML configuration:
<jms:activemq-connector name="jmsConnector"/>
Next, create the service. In this example, we will create a service that listens to a queue called
echoComponent. The method parameter specifies the operation to invoke. The SOAPAction property
specifies the name of the queue again, which is required if your service name and queue name are not
identical.
<model name="echoSample">
<service name="echoService">
<inbound>
<inbound-endpoint address="axis:jms://echoComponent?method=echo&param=hello"
SOAPAction="jms://echoComponent"/>
</inbound>
<echo-component/>
</service>
</model>
You can also add any other JMS endpoint options, such as transactions. See the JMS Transport
documentation for a full description.
SOAP Over VM
The VM transport also supports SOAP, which can be useful for testing or prototyping. You configure the
endpoints the same as JMS SOAP endpoints. For example:
<model name="test">
<service name="mycomponent">
<inbound>
<inbound-endpoint address="axis:vm://mycomponent"/>
</inbound>
<component>
<singleton-object class="org.mule.tck.testmodels.services.TestServiceComponent"/>
</component>
</service>

<service name="mycomponent2">
<inbound>
<axis:inbound-endpoint address="vm://mycomponent2">
<axis:soap-service interface="org.mule.api.component.simple.EchoService"/>
<axis:soap-service interface="org.mule.tck.testmodels.services.DateService"/>
</axis:inbound-endpoint>
</inbound>
<component>
<singleton-object class="org.mule.tck.testmodels.services.TestServiceComponent"/>
</component>
</service>
</model>
Binding to a Servlet Container

If you embed Mule in a webapp, you might want to bind Axis services to the servlet container port rather
than open another port for Mule SOAP services, but you may not be able to do this because of firewall
restrictions. In this scenario, you can use the Servlet Transport and Axis instead of HTTP. To use this
transport, you must add MuleReceiverServlet to your web.xml file:
<servlet>
<servlet-class>org.mule.transport.servlet.MuleReceiverServlet</servlet-class>
<load-on-startup/>
</servlet>
<servlet-mapping>
<url-pattern>/mule/services/*</url-pattern>
</servlet-mapping>
Next, you add a servlet endpoint to your component:
<servlet:connector name="servlet" servletUrl="http://localhost:62088/services"/>

<model name="test">
<service name="mycomponent">
<inbound>
<axis:inbound-endpoint address="servlet://mycomponent"/>
</inbound>
<component class= "org.mule.tck.testmodels.services.TestServiceComponent"/>
</service>
</model>
Note that you set the host, port, and path on the connector, not the endpoint, using the servletUrl
property.
Using Other Mule Transports

You can send and receive SOAP requests using other transports simply by configuring the endpoint
according to the endpoint scheme and then prepending the axis: scheme. For client endpoints, you also
set the the method parameter.
//Client

axis:xmpp://mule1:mule@jabber.org.au/axis?method=echo&param=hello
//Server
axis:xmpp://mule1:mule@jabber.org.au/axis

Axis Transport
Axis Transport
The Axis transport allows Mule-managed components to be published as Axis services and allows
components to invoke web services using Axis client calls.
The Javadocs for the AxisConnector can be found at org.mule.transport.soap.axis.AxisConnector .
Programmatic Configuration
If you want to programmatically configure your Axis service you can implement the
org.mule.transport.soap.axis.AxisInitialisable interface. This will pass the SOAPService object to your
component where it can be manipulated.
Connector
The Axis connector consumes and provides web services via Axis. It supports all the common connector
attributes and properties as well as the following additional attributes:
axis-ref string no Bean reference to

the Axis server.
clientConfig string no Configuration

file to use when
building the Axis
client.
clientProvider-ref string no Bean reference to

the client provider
to use for creating
the Axis client.
doAutoTypes boolean no Use this property

to configure
whether the Axis
server should
automatically
map types. This
property only
takes effect if you
do not provide
your own Axis
server via the
axis-ref property.
serverConfig string no Configuration

file to use when
building the Axis
server.

serverProvider-ref string no Bean reference
to the server
provider that
should be used
to create the Axis
server.
treatMapAsNamedParams
boolean no The Axis
connector
treats a Map
as a container
for named
parameters and
unpacks them
from the map.
If your exposed
service needs to
take a Map as a
parameter, set this
property to false
to prevent the
connector from
unpacking the
Map.
bean-type 0..*
supported-scheme 0..*
Inbound Endpoint
wsdlFile string no The location of a

WSDL document
to use for this
service if you
do not want the
WSDL document
autogenerated.
clientConfig string no
soapAction string no
SOAPAction string no
serviceNamespace string no
style styleType no Specifies the

SOAP binding

style: RPC
(default),
DOCUMENT,
MESSAGE, or
WRAPPED.
use useType no Specifies the

SOAP binding
use: ENCODED
(default) or
LITERAL.
For example:
<service name="Calculator">
<inbound>
<axis:inbound-endpoint address="http://localhost:62088/axis" style="WRAPPED" use="LITERAL">
<axis:soap-method method="qname{add:http://muleumo.org/Calc}">
<axis:soap-parameter parameter="Number1" type="any" mode="IN" />
<axis:soap-parameter parameter="Number2" type="any" mode="IN" />
<axis:soap-return type="any" />
</axis:soap-method>
</inbound>
<component class="org.mule.transport.soap.axis.Calculator" />
</service>
Outbound Endpoint
clientConfig string no
soapAction string no
SOAPAction string no
serviceNamespace string no

SOAP binding
style: RPC
(default),
DOCUMENT,
MESSAGE, or
WRAPPED.

SOAP binding
use: ENCODED

(default) or
LITERAL.
Wrapper Component
The WebServiceWrapperComponent class allows you to send the result of a web service call to another
endpoint. For example:
<axis:wrapper-component address="http://localhost:65081/services/TestUMO?method=receive"
style="WRAPPED" use="LITERAL" />
Attributes of <wrapper-component...>
address string no Specifies the URL

of the web service
to call.
addressFromMessageboolean no Specifies that the

URL of the web
service will be
obtained from the
message itself.

SOAP binding
style: RPC
(default),
DOCUMENT,
MESSAGE, or
WRAPPED.

SOAP binding
use: ENCODED
(default) or
LITERAL.
Child Elements of <wrapper-component...>
soap-method 0..* Allows you to specify a

SOAP method and optionally
parameters and a return. The
parameter mode can be IN, OUT,
or INOUT.

Axis Web Services and Mule
Axis Web Services and Mule

[ Exposing Web Services ] [ Invoking Web Services ] [ Axis Without a Servlet Container ] [ Configuring
the Axis Server ] [ SOAP Over Other Transports ]
Exposing Web Services

You can expose service components as Axis services and invoke them from Mule. To expose a service
component as an Axis service, you simply import the Axis namespace and then set the component's
inbound endpoint to an Axis URL. Note that web services expect methods to be exposed through
interfaces implemented by their respective components. Otherwise, you will receive configuration errors
when Mule starts.
<service name="echoService">
<inbound>
<axis:inbound-endpoint address="http://localhost:81/services"/>
</inbound>
<echo-component/>
</service>
When Mule starts, the service will be available on http://localhost:81/services/echoService. The Echo
component class (org.mule.components.simple.EchoComponent) implements the EchoService interface,
which has a single method called echo that accepts a single parameter string.
Note: Mule 2.0 supports Axis 1.4.
Invoking Web Services

You can invoke web services from Mule programmatically using the Mule Client or as part of the event
flow of a Mule service. This section describes these approaches in detail.
Invoking Services Using the Mule Client
To invoke the Echo service using the Mule Client, use the following code:
public static void main(String[] args)

{
MuleMessage result = client.send
("axis:http://localhost:81/services/echoService?method=echo",
"Hello!", null);
System.out.println("Message Echoed is: " + result.getPayload());
client.close();
}
Invoking Web Services from a Mule Service
To invoke the Echo service from a service, you add an outbound endpoint to your service configuration.
The following example shows a service that receives an event on vm://test.component, does some work
on the event, and then invokes the Echo service.

<service name="test">
<inbound>
<vm:inbound-endpoint path="test.component" synchronous="true"/>
</inbound>
<component implementation="com.foo.TestComponent"/>
<outbound>
<axis:outbound-endpoint address="http://localhost:81/services/echoService?method=echo"/>
</outbound>
</service>
The org.foo.TestComponent class looks like this:
public class TestComponent implements Callable

{
public Object onCall(MuleEventContext context) throws Exception
{
Object payload = context.getMessage().getPayload();
//Do some work on the payload and return a string that will be
//used by the outbound endpoint to invoke the echo service
//...
return payload.toString();
}
}
If the Web service you are invoking takes more than one parameter, you can return an array of
parameters in your component.
When an event is published to vm://test.component, the onCall method is called with the current event.
After the onCall method executes, Mule invokes the outbound endpoint for TestComponent with what is
returned from onCall.
Note that the vm://test.component endpoint has a parameter synchronous=true. This tells Mule to
invoke requests from that endpoint in a single thread, making it a request/response style request. Thus
the result of invoking the Echo service (by invoking TestComponent) will be returned to the callee who
dispatched the event on vm://test.component.
When the TestEchoService is run, you will see the following output:
Message Echoed is: Hello!
Note the following:
• There is no need for a servlet container, because Mule is the container (see below).
• You don't need to specify a deployment WSDD for your service. You simply specify an endpoint for
the service, and the rest is done for you.
• The MuleClient call will work just as well if the service you are invoking is hosted by an Axis instance
running on Tomcat or any other servlet engine.
• The Axis JAR and associated JARs that ship with the Mule distribution must be on your classpath.
Exposing Services

All service operations are exposed through interfaces implemented by your component.
Therefore, your component must implement at least one service interface, which is
generally good practice anyway.
Axis Without a Servlet Container

When you use Axis with Mule, there is no need for a separate servlet container. When you create an Axis
endpoint, Mule takes the following actions:
• Creates an Axis component in Mule, which is analogous to the AxisServlet. There is only one Axis
component per Mule instance.
• Creates an HTTP connector for the endpoint address and registers it as a receiver for the Axis
component.
Most web services are a lot more complex than the first example, so the following sections will tell you
how to configure the Axis instance and your services in more detail.
Configuring the Axis Server

In the previous example, a default Axis connector is created when the Axis endpoint is processed by
Mule. The Axis connector uses a default server configuration file called mule-axis-server-config.wsdd.
You can override this configuration by setting the serverConfig property on the connector to a different
configuration file, which will allow you to add additional handlers, global configuration, and more.
<axis:connector name="axisConnector" serverConfig="./axis/axis-server-config.wsdd"/>
If you use a custom server configuration, you must add the following handlers in the global configuration:
<requestFlow>
<handler
type="java:org.mule.transport.soap.axis.extensions.MuleSoapHeadersHandler"/>
</requestFlow>
<responseFlow>
<handler
type="java:org.mule.transport.soap.axis.extensions.MuleSoapHeadersHandler"/>
</responseFlow>
If you are configuring Mule from a container such as Spring, you can set the Axis server as a bean
property (axisServer) on the connector and the serverConfig property is ignored.
You can list the Axis services in the same way you list services when Axis is hosted in a servlet container.
To list services, simply point your browser at the host and port of the axis endpoint:
http://localhost:81/
To view Axis version information, go to:
http://localhost:81/Version?method=getVersion
To view the WSDL for the service, go to:
http://localhost:81/Version?wsdl
Note that the Axis JWS feature is not supported by Mule.

SOAP Over Other Transports
You can configure Axis to send/receive soap requests over other transports such as JMS and SMTP. For
more information, see Axis SOAP Transports.
For more information about customizing Axis behavior, naming parameters, message style options, and
more, see Configuring Axis.

Configuring Axis
Configuring Axis
Table of Contents
• Configuring Axis
• ° Controlling Exposed Methods
° Map as Parameter
° Setting SOAP Document Style
° Customizing the SOAP Action Format
° Setting Named Parameters
° Controlling Namespaces
° Controlling WSDL Generation
° Type Mappings
° Service Initialization Callback
Controlling Exposed Methods

To restrict the exposure of a service's methods add additional soap-service elements. These allow you
to specify interfaces that the service implements and that should be exposed.
<axis:inbound-endpoint address="http://localhost:38009/mule/services">
<axis:soap-service interface="org.mule.api.component.simple.EchoService"/>
<axis:soap-service interface="org.mule.tck.testmodels.services.DateService"/>
You can also specify one or more methods to expose in a comma-separated list, using the
allowedMethods attribute.
<service name="myService">
<inbound>
<axis:inbound-endpoint address="http://localhost:38009/mule/services"
allowedMethods="echo,getDate" />
</inbound>
<component class="com.foo.TestComponent" />
</service>
Map as Parameter
The AxisConnector treats a Map as container for named parameters, which eventually will be unpacked.
This becomes a problem if your exposed service needs to take a Map as a parameter, because the actual
Map will never reach the service intact.
To configure the connector not to unpack Maps so that they can be passed as parameters, use the
treatMapAsNamedParams attribute:

<axis:connector name="axisConnector" treatMapAsNamedParams="false"/>
Setting SOAP Document Style

To control the style and use of a service, the style and use properties can be set on Axis endpoints. For
example, to make your inbound endpoint Document/Literal/Wrapped, do the following:
<axis:inbound-endpoint address="http://localhost:38009/mule/services"
style="WRAPPED"
use="LITERAL"/>
The style attribute can be 'RPC' (default), 'DOCUMENT', 'MESSAGE', or 'WRAPPED'. The use attribute can
be either 'ENCODED' (default) or 'LITERAL'.
For more information about service styles and Mule, see Axis SOAP Styles. Also see the Axis web site for
further reference.
Customizing the SOAP Action Format

By default, Mule uses the Axis endpoint as the SOAP Action when making WS calls. This approach works
for Axis clients but might not work with .NET clients. The SOAP Action can be different for different SOAP
implementations, so you must be able to customize how the SOAP Action is formatted. You can set the
soapAction attribute on the outbound endpoint making the SOAP request:
<axis:outbound-endpoint
address="http://localhost:38011/mule/echoService?method=echo"
soapAction="http://localhost:38011/${method}"
The above example sets the SOAP Action on the request to http://localhost:38011/echo. If you are
Using the Mule Client, you can set the SOAP Action as a property when making the call.
The SOAP Action can be a static value, or you can use template variables such as the method variable
used above. The set of variables that can be used are listed below.
Variable Description Example
method The service method name being echo

invoked
methodNamespace The service method name being echo

invoked
address The full SOAP endpoint http://localhost:38011/

mule/echoService?
method=echo
scheme The request scheme being used http
host The hostname from the SOAP localhost

endpoint

port The port from the SOAP 38011
endpoint
path The path info from the SOAP /mule/echoService

endpoint
hostInfo The scheme, host and port http://localhost:38011

combined
serviceName The name of the service being echoService

invoked
Any other properties on the event or the endpoint can be referenced by name in the soapAction
expression.
Setting Named Parameters

Some web service clients require that all method parameters of a call should be named. You can do this
in Mule in two ways.
In the Mule XML configuration, you can set the SOAP method parameters for a service on the endpoint
using the soap-method element.
<axis:outbound-endpoint address="http://localhost:38011/mule/echoService?method=echo"
synchronous="true">
<axis:soap-method method="echo">
<axis:soap-parameter parameter="string1" type="string" mode="IN"/>
<axis:soap-parameter parameter="string2" type="string" mode="IN"/>
<axis:soap-return type="java"/>
</axis:soap-method>
</axis:endpoint>
Within the soap-method element, you can define soap-parameter elements, which control that
parameter's mode, name, and type. The parameter attribute is the name of the parameter. The type
attribute is an XSD string such as int, long, map, etc. The attribute mode can be in, out, or inout. The
return type is also an XSD type string. The soap-return element controls the type of the parameter the
method returns.
Controlling Namespaces
Namespaces for elements can be controlled at the method and parameter level. To declare a namespace
on the method with a prefix of 'foo' and a URI of 'http://mycompany.com/foo', you would use the
following code:
<axis:outbound-endpoint address="http://localhost:38011/mule/echoService?method=echo"
synchronous="true">
<axis:soap-method method="qname{foo:http://mycompany.com/foo}">
<axis:soap-parameter parameter="in0" type="string" mode="IN"/>
<axis:soap-parameter parameter="out" type="ns1:Test" mode="OUT"/>
<axis:soap-return type="org.mule.tck.external.applications.Test"/>
</axis:soap-method>
</axis:endpoint>
The syntax for the qname is:
qname{[MULE:prefix]:[MULE:localname]:[MULE:namespace]}

You can supply just a localname, a localname and namespace, or a prefix, localname, and namespace.
The qname syntax can be used with <soap-parameter> elements as well. For example:
<axis:soap-parameter parameter="qname{foo1:echo1:http://mycompany.com/foo1}" type="string"

mode="OUT"/>
To set the method parameter name using the Mule client, you create a SoapMethod object and set it on
the properties when making the call. The example below shows how to do this.

//create the soap method passing in the method name and return type
SoapMethod soapMethod = new SoapMethod("echo", NamedParameter.XSD_STRING);
//add one or more parameters
soapMethod.addNamedParameter("value", NamedParameter.XSD_STRING, ParameterMode.IN);
//set the soap method as a property and pass the properties
//when making the call
props.put(MuleProperties.MULE_SOAP_METHOD, soapMethod);
MuleMessage result = client.send("axis:http://localhost:38011/mule/echoService?method=echo",

"Hello", props);
Note that you can use the qname notation for setting method and parameter names using the Mule client.
Controlling WSDL Generation

The service namespace (also called the target namespace) for your service can be controlled by setting
the serviceNamespace property on the inbound endpoint:
<axis:inbound-endpoint address="http://localhost/services" serviceNamespace="http://foo.namespace"/>
You can also set the wsdlFile property to the location of a WSDL document to use for this service if you
do not want an auto-generated WSDL document.
<axis:inbound-endpoint address="http://localhost/services" wsdlFile="foo.wsdl"/>
Optionally, you can control the values used in Axis WSDL generation by setting WSDL-specific Axis
options. The options you can set are:
Option Name Description
wsdlPortType Sets the wsdl:portType name attribute. the Axis

default is $Proxy0
wsdlServiceElement Sets the wsdl:service name attribute. the Axis

default is $Proxy0Service

wsdlTargetNamespace Sets the wsdl:definitions targetNamespace
attribute. The Axis default is http:// plus
package name of the service class in reverse.
wsdlServicePort Sets the wsdl:port name attribute of the

wsdl:service element. The default is the name
of the Mule component exposed by this service
endpoint.
wsdlInputSchema
wsdlSoapActionMode
extraClasses
To change the wsdlServiceElement name attribute to MyService in the generated WSDL for a service,
use the following:
<properties>
<spring:entry key="axisOptions">
<spring:map>
<spring:entry key="wsdlServiceElement" value="MyService"/>
</spring:map>
</spring:entry>
</properties>
Type Mappings
Note that as of Axis 1.2-RC3, it is no longer necessary to configure type mappings, as bean serialization
is handled automatically by Axis. If you are using an older version of Axis, you might need to configure
type mappings.
Mule enables default type mappings for object serialization between SOAP calls. This means that
serialization and deserialization of call parameters and return objects is mostly handled automatically by
Axis. This works for most Java types including primitives, Numbers, Strings, Arrays and Collections. It
also works for JavaBeans whose attributes comprise these types. However, it does not work where you
have a bean that has another bean as an attribute; Axis will complain that it doesn't know how to handle
the bean attribute.
Mule handles this by allowing you to specify a list of beanTypes that Axis needs to understand to manage
your service. For example, assume you have a PersonService service that will get a Person object when
passed the person's name. The Person object contains an Address object. The configuration will look like
this:
<property key="beanTypes">
<spring:list>
<spring:value>org.foo.Address</spring:value>
</spring:list>
</property>

It is important to note that only custom types should be listed. If any standard types are
present, like java.util.ArrayList, Axis may produce serialization errors.
For convenience, the beanTypes property can be set on an Axis connector configuration so that all
services that use the connector will have the types registered in the TypeRegistry for the service.
<axis:connector name="axisConnector">
<spring:property name="beanTypes">
<spring:list>
<spring:value>org.foo.Address</spring:value>
</spring:list>
</spring:property>
</axis:connector>
By default, an Axis connector is created if one doesn't exist already when the Axis endpoint is processed.
For more information about configuring Connectors and Providers, see Configuring Endpoints.
Service Initialization Callback

If you need further control over the Axis service created by Mule, it is possible for your component to
implement AxisInitialisable.
public interface AxisInitialisable

{
public void initialise(SOAPService service) throws InitialisationException;
}
This gets called when the service is initialized and allows you to customize the service configuration from
your Mule component.


[ Protocol Bridging ] [ WSProxyService ] [ CXF Proxy Services ] [ Example: Routing Messages Based on
SOAPAction Headers with Transformations ]
Mule can act as a web service gateway/proxy. Gateways can perform several useful functions:
• Routing to the appropriate backend service (whether remote or local)

• Message transformations, such as converting from old versions of the message format
• Protocol bridging, such as HTTP to JMS
• Validation
• Security enforcement
• WS-Policy enforcement
Mule provides several utilities that help you do this:
• Protocol bridging
• WSProxyService - allows you to service WSDLs locally while proxying remote web services
• CXF proxy services - perform WS-Security or WS-Policy actions, route based on information such as
the operation or SOAP Action, and easily work with just the payload by taking advantage of CXF's
web service capabilities
Protocol Bridging
The simplest type of web service proxy just involves forwarding a request from one endpoint to another
via service bridging. Following is a simple example that forwards a request from one HTTP endpoint to
another:
<service name="HttpWebServiceBridge">
<inbound>
<inbound-endpoint address="http://localhost:8080/my/service">
</inbound>
<outbound>
<outbound-endpoint address="http://acme.come/remote/web/service"/>
</outbound>
</service>
This type of bridge can be combined with filters for easy message routing. For fast XPath routing of
messages, you can use the SXC Module.
WSProxyService
The WSProxyService allows you to serve WSDLs locally while proxying remote web services. This is handy
when you have an alternate WSDL you want to service, or if you don't want WSDL requests to be routed
with all the other SOAP message requests. Any request that comes in with a "?wsdl" attached to the HTTP
URL will be redirected, and the specified WSDL will be served instead.
To configure this for your service, you must first define a WSProxyService bean with your WSDL:

xmlns:cxf="http://www.mulesource.org/schema/mule/cxf/2.2"
beans-2.5.xsd
mule.xsd
http://www.mulesource.org/schema/mule/cxf/2.2 http://www.mulesource.org/schema/mule/cxf/2.2/
mule-cxf.xsd">
<spring:bean name="WSProxyService" class="org.mule.transport.soap.WSProxyService">

<spring:property name="wsdlFile" value="localWsdl.wsdl"/>
</spring:bean>
....
</mule>
Next, define your service bridge to use this component:
<service name="HttpWebServiceBridge">
<inbound>
<inbound-endpoint address="http://localhost:8080/my/service">
</inbound>
<component>
<spring-object bean="WSProxyService" />
</component>
<outbound>
<outbound-endpoint address="http://acme.come/remote/web/service"/>
</outbound>
</service>
Now any request to "http://localhost:8080/my/service?wsdl" will cause your WSDL to be served.
CXF Proxy Services

Normally when building CXF web services, you'll databind the XML to POJOs. A CXF component might
receive an OrderRequest object, or you might send an OrderRequest object via a CXF outbound router.
However, it is often useful to work with the XML directly when building web services or consuming other
web services. The CXF transport provides the ability to do this.
While many times you can proxy web services without using CXF (see above), there are several cases
where you might want to use CXF proxies:
• To work directly with the SOAP body

• To take advantage of the CXF web service standards support to use WS-Security or WS-Addressing
• To enforce WS-Policy assertions
• To easily service a WSDL associated with your service
• To transform a SOAP body
Server-side Proxying
To proxy a web service so you can work with the raw XML, you can create a simple inbound endpoint:
<cxf:inbound-endpoint address="http://localhost:63081/services/Echo" proxy="true"/>
This will make the SOAP body available in the Mule message payload as an XMLStreamReader.

Client-side Proxying
Similarly, you can create an outbound endpoint to send raw XML payloads:
<cxf:outbound-endpoint address="http://localhost:63081/services/Echo"
proxy="true"/>
Example: Routing Messages Based on SOAPAction Headers

with Transformations
This example shows how you can use message routing with CXF web service proxying to handle web
service requests that use an old message format. It will listen on the "http://localhost:63081/service"
endpoint and send the SOAP body to the outbound routers. If the message has a SOAPAction header of
"http://acme.com/v2/bid", it will send the message directly to the web service. If the header has a value
of "http://acme.com/v1/bid", it will apply XSLT transformations to convert the message on the way out
and on the way back in.
<service name="routeBasedOnSoapAction">
<inbound>
<cxf:inbound-endpoint address="http://localhost:63081/service" proxy="true"/>
</inbound>
<outbound>
<filtering-router>
proxy="true"
remoteSync="true"/>
<message-property-filter pattern="SOAPAction=http://acme.com/v2/bid"/>
</filtering-router>
<filtering-router>
proxy="true"
remoteSync="true">
<transformers>
<mule-xml:xslt-transformer xsl-file="v1-to-v2.xsl"
</transformers>
<response-transformers>
<mule-xml:xslt-transformer xsl-file="v2-to-v1.xsl"
</response-transformers>
<message-property-filter pattern="SOAPAction=http://acme.com/v1/bid"/>
</filtering-router>
</outbound>
</service>

Using .NET Web Services with Mule
Using .NET Web Services with Mule

Following are tips for using Mule to communicate with .NET web services.
Authentication and Other Security Features

There are three ways to secure a web service:
• Via an HTTP web server

• Via authentication tokens in the SOAP header
• Via WS-Security
Via an HTTP Web Server
If you are running Mule on a Web App, you can configure the web server to use security by setting
security configuration in web.xml and in the server's configuration file.
Alternatively, to secure a web service running on Mule (where Mule is the server), you can set the
HttpBasicAuthenticationFilter on the web service component. Any call made to the web service would
have to pass through the filter that delegates the authentication to Acegi.
Another alternative would be to use HTTPS where certificates are used for authentication.
For more information see Configuring Security and Using HTTPS with CXF.
Using Authentication Tokens in SOAP Headers
You can send authentication tokens through SOAP headers as long as there is an authentication provider
established that is able to understand the headers and perform the authentication.
Using WS-Security
If you are using CXF, you can configure a client and service to use WS-Security. For details, see Enabling
WS-Security.
Passing Authentication Information to a Web Service
There are three methods for passing authentication information to a web service configured on Mule:
• Pass them in the URL, such as http://name:password@localhost:8080/MyService

• Set the authentication items as properties when using the Mule client
• Create headers containing the authentication items and send them as properties when using the
Mule client

Web Service Wrapper
Using the Web Service Wrapper

The WebServiceWrapperComponent class allows you to send the result of a web service call to another
endpoint. The web service call is performed within WebServiceWrapperComponent, providing the following
advantages:
• You can set any type of router on inbound and outbound.

• Unlike the chaining router, it can send more than one HTTP request at a time
• The URL for the web service call can be changed at run-time by sending the URL with the message
Configuring the Web Service Wrapper

To use the web service wrapper, you specify the <wrapper-component> configuration element. The
following table describes the attributes you can set for this element. These attributes are described in
more detail in the examples that follow.
Attribute Description Required?
address Specifies the URL of the web Yes, unless

service to call addressFromMessage is set to
true
addressFromMessage (default is Specifies that the URL of the Not required if address is set
false) web service will be obtained
from the message itself
wrapperProperties The SOAP document style, No

expressed as a map of two
properties: style, which can
be set to RPC (the default),
Document, Message, or Wrapped,
and use, which can be Encoded
or Literal.
<soap-method> A SOAP method to call (see No

Configuring SOAP Methods
below)
The web service wrapper is generic and can be used with any type of web service stack supported by
Mule, including Axis and CXF. The examples below show synchronous use cases, but the web service
wrapper can also support an asynchronous use case like the loan broker example.
Example Configuration Using the CXF Transport
Consider the following example. The web service wrapper is configured as a Mule component, accepting
messages from a VM endpoint. A call must be made to a web service on the URL cxf:http://
localhost:65081/services/TestUMO?method=onReceive and the result must be sent to the outbound
endpoint vm://testout.
The inbound and outbound endpoints are configured in the usual way. The address is set as an attribute
on the component, specifying the web service URL that you want to call.
<cxf:connector name="cxf" defaultFrontend="simple" />

<model name="Sample">

<service name="WebServiceSample">
<inbound>
<vm:inbound-endpoint path="testin" />
</inbound>
<cxf:wrapper-component address="http://localhost:65081/services/TestUMO?method=onReceive"/>
<outbound>
<outbound-endpoint address="vm://testout"/>
</outbound>
</service>
Example Configuration Using the addressFromMessage Property
The "address" property is ideal to use when the web service URL for the web service is known at
configuration time. However, if this URL is either not known or else needs to be changed at run-time,
the "address" property can be omitted and the "adddressFromMessage" property can be set to true. The
following example shows this configuration:
<service name = "WebServiceSample2">

<inbound>
<vm:inbound-endpoint path = "testin2"/>
</inbound>
<cxf:wrapper-component addressFromMessage = "true"/>
</service>
The URL must be set on the message with the property name "ws.service.url".
Configuring SOAP Methods
CXF endpoints are fairly easy to configure, whereas Axis needs some further configuration to set SOAP
methods. You can set a SOAP method using the <soap-method> element as shown below:
<service name = "WebServiceSample3">

<inbound>
<vm:inbound-endpoint path = "queue.in" connector-ref = "VMQueue"/>
</inbound>
<axis:wrapper-component address = "http://localhost:62088/axis/Calculator?method=add" style
= "WRAPPED" use = "LITERAL">
<axis:soap-method method = "qname{add:http://muleumo.org/Calc}">
<axis:soap-parameter parameter = "Number1" type = "int" mode = "IN"/>
<axis:soap-parameter parameter = "Number2" type = "int" mode = "IN"/>
<axis:soap-return type = "int"/>
</axis:soap-method>
</axis:wrapper-component>
<outbound>
<vm:outbound-endpoint path = "queue.out" connector-ref = "VMQueue"/>
</outbound>
</service>

Working with Services
Working with Services

A service component is a class, web service, or other application that contains the business logic you
want to plug in to the Mule framework. For example, one service component could add information to
an invoice from a customer database, and another service component could be the order fulfillment
application that processes that invoice. You can use any existing application for a service component, or
create a new one.
Your service component does not need to contain any Mule-specific code. Instead, you configure
a service, which wraps the service component with the Mule-specific configuration. The service
configuration points to the service component, as well as routers, filters, and transformers to use when
carrying messages to and from the service component. It also specifies the endpoint on which this service
will receive messages and the outbound endpoint where messages will go next. Services are the primary
Mule artifact used to implement integration solutions.
To watch a demo of building a simple service, click here.
Service Components
A service component can be a POJO, servlet, web service, and much more. Typically, you create a custom
service component, but you can also use one of the several standard components included with Mule. For
more information, see Configuring Components.
Service Configuration
Most configuration happens at the service level. Services can be configured using globally defined
endpoints, transformers, and filters, or these can be defined inline. For more information, see Configuring
the Service.
Service Behavior
When a service receives a message on an inbound endpoint, the service model (default is SEDA)
determines the service's threading and queuing behavior, while the messaging pattern defines the
inbound and outbound message exchange patterns that will be used.
Advanced Configuration
You can further configure the service with security (configured on endpoints), transactions, and error
handling.

Configuring Components
Configuring Components
[ Simple Components ] [ Java Components ] [ Other Components ] [ Customizing Behavior with
Interceptors ]
Service components contain the business logic for working with the messages passed through Mule. A
service component can be any type of object, including a Spring bean, POJO, script, web service, or REST
call.
Because they are highly specific to your implementation, you will typically create your own custom
components, or simply use an existing POJO. Mule also ships with some standard components you can
use or extend as needed. This page describes how to configure the different types of components.
For detailed information on the elements you configure for components, see Component Configuration
Reference.
Simple Components
There are several simple components included with Mule that are useful for testing or bypassing
component execution.
Configuration Element Description
<log-component/> Logs component invocations, outputting the

received message as a string. This component
does not return a response.
<echo-component/> Extends the log component to log and echo the

incoming message. The message is transformed
before being returned, so transformations on
inbound endpoints will be applied.
<null-component/> Throws an exception when invoked. This is

useful for testing use cases that use a forwarding
consumer inbound router.
<passthrough-component> Similar to the echo component but does not

log. This component is useful when defining
services that consist of inbound and outbound
endpoints/routers but don't have a component
implementation. Note that explicitly configuring
this component has exactly the same result as
configuring a service with no component.
<bridge-component/> Identical to the pass-through component but

preserves the Mule 1.4 terminology.
<test:component/> Configures the Mule FunctionalTestComponent,

which allows more complex testing scenarios to
be created. For more information, see Functional
Testing.

Java Components
Java components specify a Java class to be used as the service component or configure a reference to an
implementation in a container such as Spring. They also configure the way in which Mule should manage
the Java service component's life-cycle, invoke it, and (if pooled) manage the pool of instances.
Java components can be configured quickly and easily by simply specifying the service component
implementation class name on the <component> or <pooled-component> element. The <pooled-
component> element allows you to establish a pooling profile for the service (see Tuning Performance).
In both cases, the PrototypeObjectFactory will be used by default and a new object instance will be
created for each request or (for pooled components) for each new object in the pool.
<component class="org.my.ServiceComponentImpl"/>
...
<pooled-component class="org.my.ServiceComponentImpl"/>
Alternatively, you can explicitly specify object factories, such as the SingletonObjectFactory that
creates a single instance of the object:
<component>
<singleton-object class="org.my.ServiceComponentImpl"/>
</component>
The explicit syntax is required instead of the shortcut <component class> syntax if you add interceptors
to the component. For further configuration options and information on the default settings that are
applied, see Configuring Java Components.
Other Components
These are several other components available that allow you to use different technologies such as web
services for your service components. These components are often included as part of transports or
modules.
Configuration Description
<http:rest-service-component/> Proxies a remote call to a REST-style web service.
<cxf:wrapper-component/> Proxies a remote call to a web service using CXF.
<axis:wrapper-component/> Proxies a remote call to a web service using Axis.
<script:component/> Configures a JSR-223 script for the service

component.
Customizing Behavior with Interceptors

Mule interceptors are useful for attaching behaviors to multiple service components. The interceptor
pattern is often referred to as practical AOP (Aspect Oriented Programming), as it allows the developer
to intercept processing on an object and potentially alter the processing and outcome. For complete
information, see Using Interceptors.

Configuring Java Components
Configuring Java Components

[ Object Factories ] [ Entry Point Resolvers ] [ Lifecycle Adapter Factory ] [ Bindings ] [ Configuring a
Pooled Java Component ]
Java is the default component type in Mule. Mule provides two JavaComponent implementations:
DefaultJavaComponent , which you configure with the component element, and PooledJavaComponent ,
which adds pooling functionality and which you configure with the pooled-component element. These two
implementations provide the following functionality and configuration options:
• An ObjectFactory is used to obtain the Java service component implementation.

• EntryPointResolvers can be configured to define how Mule services should invoke the component
methods when processing a message.
• A custom LifecycleAdaptor can be configured to customize the way in which the component
implementation is initialized and disposed.
• Bindings can be configured to bind component interface methods to endpoints. These endpoints are
then invoked synchronously when the method is called.
When you specify the class directly on the component or pooled-component element, the
PrototypeObjectFactory is used by default, and a new instance is created for each invocation, or a new
pooled component is created in the case of the PooledJavaComponent.
Example:
<component class="org.my.CustomComponent"/>
..
<pooled-component class="org.my.CustomComponent"/>
Alternatively, you can specify the implementation using an object factory.
Example:
<component>
<prototype-object class="org.my.CustomComponent"/>
</component>
..
<pooled-component>
<singleton-object class="org.my.CustomComponent"/>
</pooled-component>
..
<component>
<spring-object bean="myCustomComponentBean"/>
</component>
All other component configuration elements are configured as children of the component or pooled-
component element.
Note: In Mule 2.0, Java component pooling is used only if the <pooled-component> element is used. In
previous versions of Mule, pooling was the default.

Object Factories
Object factories manage both object creation in the case of a Mule instantiated instance or object look-up
from another container such as Spring via a single API.
The following object factories are included with Mule and can be configured using Mule's core schema.
<prototype-object class=..."/> PrototypeObjectFactory
<singleton-object class=..."/> SingletonObjectFactory
<spring-object bean=..."/> SpringBeanLookup
Object factories also allow you to set properties, which are injected when a new object instance is
created.
Example:
<pooled-component>
<singleton-object class="org.my.SingletonObject">
<property key="myKey" value="theValue"/>
<property key="myKey2" value="theValue2"/>
</singleton-object>
</pooled-component>
For a real-world example of using <spring-object/>, see Using Spring Beans as Service Components.
You can easily implement additional object factories to integrate with other containers or simply to create
object instances in a different way. For more information about creating custom object factories, see
Extending Mule.
Note: Object factories replace ContainerContexts in previous versions of Mule.

You can configure entry point resolvers that determine how your component is invoked when a message
is received by the service. See Developing Service Components for a more detailed description of their
functionality.
To configure entry point resolvers, you can either configure an entry point resolver set or configure a
single entry point resolver independently. When using an entry point resolver set, the order in which the
resolvers are configured is the order of of precedence they are given in run-time.
Example:
<component class="org.my.PrototypeObjectWithMyLifecycle">
<entry-point-resolver-set>
<array-entry-point-resolver/>
<callable-entry-point-resolver/>
</entry-point-resolver-set>
</component>
<reflection-entry-point-resolver/>

</component>
You can also configure entry point resolvers (single or sets) on models to apply them to all services
defined in that model. You use the same configuration syntax as above but on the <model> element
instead of <component>.
Lifecycle Adapter Factory

You can configure your Java component to use a custom lifecycle adaptor. If you do not configure a
custom implementation, the default implementation will be used, which allows the optional propagation of
Mule's lifecycle to your component depending on the Mule lifecycle interfaces that are implemented.
Example:
<custom-lifecycle-adapter-factory class="org.my.MyLifecycleMuleAdapterFactory"/>
</component>
See Developing Service Components for more information about lifecycles.
Bindings
Components can use bindings to call an external service during execution. The bindings used with a Java
component bind a Java interface, or single interface method, to an outbound endpoint. The external
service to be called should implement the same interface, and the component should encapsulate a
reference to that interface, which is initialized during the bootstrap stage by the Mule configuration
builder. The reference will be initialized using a reflective proxy class.
Binding can be used on Java components and script components. For more information see Component
Bindings.
Configuring a Pooled Java Component

A pooled Java component will maintain a pool of object instances that will be reused, with a single
instance being used by one thread at any one time. The configuration of component pooling is
independent of the object factory, allowing you to use whichever object factory you need.
You configure the pool using the nested pooling-profile element as shown below:
<pooled-component class="org.my.PrototypeObject">
<pooling-profile exhaustedAction="WHEN_EXHAUSTED_FAIL" initialisationPolicy="INITIALISE_ALL"
maxActive="1" maxIdle="2" maxWait="3" />
</pooled-component>
For more information about pooling and reference documentation for pooling configuration options, see
Tuning Performance.

Using Interceptors
Using Interceptors
[ Interceptor Types ] [ Interceptor Event Flow ] [ Writing Interceptors ] [ Configuring Interceptors ] [
Interceptor Configuration Reference ]
Mule interceptors are useful for attaching behaviors to multiple service components. The interceptor
pattern is often referred to as practical AOP (Aspect Oriented Programming), as it allows the developer
to intercept processing on an object and potentially alter the processing and outcome. (See also Spring
AOP). Interceptors are very useful for attaching behavior such as profiling and permission and security
checks to your service components.
Interceptor Types
Mule has two types of interceptors:
• EnvelopeInterceptor : Envelope filter that will execute before and after the component is invoked.
Good for logging and profiling.
• Interceptor : Intercepts the message and then forwards it for processing to the next element. An
interceptor can stop further processing by not forwarding control to the next interceptor, as with a
permissions checker interceptor.
Interceptor Event Flow

The following shows an example interceptor stack and the event flow.

Writing Interceptors
If you want to intercept a message flow to a component on the inbound message flow, you should
implement the Interceptor interface. It has a single method:
MuleMessage intercept(Invocation invocation) throws MuleException;
The invocation parameter contains the current message and the Service object of the target
component. Developers can extract the current MuleMessage from the message and manipulate it as
needed. The intercept method must return a MuleMessage that will be passed on to the component (or
to the next interceptor in the chain).
The EnvelopeInterceptor works in the same way, except that it exposes two methods that get invoked
before and after the event processing:
MuleMessage before(Invocation invocation) throws MuleException;
MuleMessage after(Invocation invocation) throws MuleException;
Configuring Interceptors
Interceptors can be configured on your components as follows:
<service name="MyService">
<component>
<custom-interceptor class="org.my.CustomInterceptor"/>
<logging-interceptor/>
<interceptor-stack ref="testInterceptorStack"/>
<timer-interceptor/>
<prototype-object class="org.my.ComponentImpl"/>
</component>
</service>
When you configure interceptors, you must specify the object factory explicitly (in this
example, <prototype-object>) instead of using the <component class> shortcut.
You can also define interceptor stacks, which are one or more interceptors that can be referenced using a
logical name. To use an interceptor stack, you must first configure it in the global section of the Mule XML
configuration file (above the <model> element):
<interceptor-stack name="default">
<custom-interceptor class="org.my.CustomInterceptor"/>
<logging-interceptor/>
</interceptor-stack>
You can configure multiple <interceptor> elements on your components, and you can mix using built-in
interceptors, custom interceptors, and references to interceptor stacks.

Interceptor Configuration Reference
<timer-interceptor ...>
The timer interceptor (ported from 1.x).
Attributes
Child Elements
<logging-interceptor ...>
The logging interceptor (ported from 1.x).
Attributes
Child Elements
<custom-interceptor ...>
A user-implemented interceptor.
Attributes

implementation
of the Interceptor
interface.
Child Elements

<interceptor-stack ...>
Attributes

to identify this
interceptor stack.
Child Elements

element.
<interceptor-stack ...>
A reference to a stack of intereceptors defined globally.
Attributes

interceptor stack
to use.
Child Elements

Configuring the Service
Configuring the Service

[ Inbound ] [ Component ] [ Outbound ] [ Async Reply ] [ Exception Strategy ] [ Service Bridge ] [
Service Model ] [ Service Messaging Style ]
You configure services using a <service> element within a <model> element. Each <service> element
represents and configures a Mule service, providing a unique name that identifies it and optionally
an initial state that determines whether the service and its endpoints are started when Mule starts
(supported values are started, stopped, or paused).
<mule>
<model>
...
</service>
<service name="GreeterUMO2" initialState="stopped" >

...
</service>
</model>
</mule>
Each service can be configured with the following optional elements:
• <description>: Describes the service

• <inbound>: Configures the inbound routers, their endpoints, and inbound transformers
• component: Configures the service component
• <outbound>: Configures the outbound routers, their endpoints, and outbound transformers
• <async-reply>: Configures an async reply router, which is used for asynchronous request-response
messaging
• <exception-strategy>: Configures the exception strategy for the service
If you configure more than one of these elements, note that you must configure them in the order shown
above. For detailed information on the <service> elements and attributes, see Service Configuration
Reference.
Following is a sample service configuration showing these elements:
<description>Adds some text to the string before passing it on</description>
<inbound>
<stdio:inbound-endpoint system="IN">
<transformer ref="StdinToNameString"/>
</stdio:inbound-endpoint>
</inbound>
<component class="org.mule.example.hello.Greeter" />
<outbound>
<filtering-router>
<vm:outbound-endpoint path="chitchatter" />
<payload-type-filter expectedType="org.mule.example.hello.NameString" />
</filtering-router>
</outbound>
<vm:outbound-endpoint path="systemErrorHandler" />

</service>
The following sections describe these elements in more detail.
Inbound
This element is used to configure inbound endpoints and inbound routers. Endpoints are used to receive
incoming messages, and inbound routers determine how these messages are routed. Inbound endpoints
and routers are configured separately within the <inbound> element.
Inbound Endpoints
Inbound endpoints are used to receive incoming messages. An endpoint is simply a set of instructions
indicating which transport and path/address to receive messages from, as well as any transformers,
filters, or security that should be applied when receiving the messages. You can configure multiple
inbound endpoints, each receiving message from different transports. For more information, see
Configuring Endpoints and Available Transports.
Inbound Routers
Inbound routers control and manipulate messages received by a service before passing them to the
service component. Typically, an inbound router is used to filter incoming messages, aggregate a set of
incoming messages, or re-sequence messages when they are received. Inbound routers are also used to
register multiple inbound endpoints for a service. You can chain inbound routers together, so that each
router must be matched before the message can be passed to the component. You can also configure a
catch-all strategy that is invoked if none of the routers accept the current message.
Inbound routers are different from outbound routers in that the endpoint is already known (as the
message has already been received), so the purpose of the router is to control how messages are given
to the component.
If no inbound routers are configured, by default an InboundPassThroughRouter is used to simply pass the
incoming message to the component.
Matching Only the First Router
By default, a message must match and be processed by all inbound routers in a service before it is
passed to the service component. If you want to configure the service so that the message is processed
only by the first router whose conditions it matches, you set the matchAll attribute on the <inbound>
element to false.
This behavior is new in Mule 2.0. Previously, the message was processed only by the first
matching router by default.
For more information about the inbound routers that can be used, see Mule Inbound Routers .
Inbound Example
<inbound>
<stdio:inbound-endpoint system="IN" />
<catch-all-strategy>
<jms:outbound-endpoint queue="failure.queue"/>
</catch-all-strategy>
<selective-consumer-router>
<mulexml:jxpath-filter pattern="(msg/header/resultcode)='success'"/>
</selective-consumer-router>
</inbound>

This example uses a selective consumer router that will accept a message if a 'resultcode' element has a
value of 'success'. If the message matches this filter's criteria, the message is passed to the component.
If the message does not match, the catch-all strategy is invoked, which sends the message via its
configured endpoint, in this case a JMS queue called 'failure.queue'.
Component
The <component> element configures the service component that will be invoked after the inbound
message is processed by the inbound routers. If no component is configured, the service acts as a bridge
and simply passes messages through to the outbound router.
There are several standard components you can use, such as <log-component>, which logs component
invocations, outputting the received message as a string, and <echo-component>, which extends the log
component to log and echo the incoming message. Typically, you will create your own component as a
plain old Java object (POJO) and configure it using the <component> element.
For more information about component types and their configuration, see Configuring Components. You
can also implement new component types in your Mule modules and use them within your configuration.
In Mule 2.0, it is now easier to implement and use new non-Java component types and configure them
with their own custom component element.
Outbound
The <outbound> element configures outbound routers and their endpoints. Because outbound routers
are used to determine which endpoints to use for dispatching messages after the component has finished
processing them, outbound endpoints are configured on the outbound routers, not directly on the
<outbound> element. Outbound routers allow the developer to define multiple routing constraints for any
given message. You can specify a catch-all strategy to invoke if none of the routers accept the current
message. For more information, see Configuring Endpoints and Available Transports.
Matching All Routers
By default, a message is processed only by the first outbound router whose conditions it matches. If
you want the message to be processed by all the outbound routers, you can set the matchAll attribute
to true. For example, assume you always want to send a confirmation of a deposit back to the original
depositor. Also assume that if the deposit was above $100,000, you want to send a notification message
to the 'high net worth client manager' for possible follow-up. In this case, you would set the matchAll
attribute on the <outbound> definition as follows:
<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>
In this example, the message will always match the first router because there is no filter on it.
Additionally, the message will match the second router if the deposit amount is >= $100000, in which
case both routers will have been invoked.
For more information about the outbound routers you can use, see Mule Outbound Routers .
Outbound Example
<outbound>

<catch-all-strategy>
<jms:outbound-endpoint queue="default.queue"/>
</catch-all-strategy>
<filtering-router>
<smtp:outbound-endpoint to="exceptions@muleumo.org" subject="Exception!"
from="mule@mycompany.com!">
<transformer ref="ExceptionToEmail"/>
</smtp:outbound-endpoint>
<payload-type-filter expectedType="java.lang.Exception"/>
</filtering-router>
<filtering-router>
<vm:endpoint path="my.component"/>
<and-filter>
</and-filter>
</filtering-router>
</outbound>
Async Reply
This element is used to configure the endpoints and routers that will be used to receive the response in
asynchronous request-response scenarios where you must consolidate responses from a remote endpoint
before the current service responds via its inbound endpoint. The classic example of this approach is
where a request is made and then multiple tasks are executed in parallel. Each task must finish executing
and the results processed before a response can be sent back to the requester. For an illustration of
asynchronous request-response, click here. For more information about the available Async Reply routers,
see Asynchronous Reply Routers . For information on configuring endpoints, see Configuring Endpoints.
Async Reply routers can be used to join forked tasks in a request-response call. In fact, you would
only use an async reply router with services that use synchronous calls (as there is no response
when dispatching a message asynchronously). Mule provides aggregator routers that can be used in
conjunction with a message splitter or recipient list router to aggregate messages before returning a
response. For more information on these routers, see Using Message Routers.
<async-reply>
<jms:inbound-endpoint queue="bank.quotes"/>
<custom-async-reply-router class="org.mule.samples.loanbroker.routers.BankQuotesResponseAggregator"/
>
</async-reply>
The endpoint specifies the address where responses should be sent to be processed. The router is
responsible for aggregating bank quotes into a single quote for the customer. Consider the inbound
configuration and the async-reply router in the LoanBroker configuration:
<service name="LoanBroker">
<inbound>
<vm:inbound-endpoint path="Loan.Requests"/>
</inbound>
<component class="org.mule.samples.loanbroker.SyncLoanBroker">
<outbound>
<static-recipient-list-router>
<reply-to address="jms://Loan.Quotes"/>
<message-property-filter expression="recipients!=null"/>
</static-recipient-list-router>
</outbound-router>
<async-reply>
<jms:inbound-endpoint queue="Loan.Quotes"/>

<custom-async-reply-router
class="org.mule.samples.loanbroker.routers.BankQuotesResponseAggregator"/>
</async-reply>
</service>
This configuration specifies that the Loan Broker will receive requests from vm://Loan.Requests and will
dispatch multiple requests to different banks via the outbound router. The bank endpoints are defined
in a List called 'recipients', which is a property on the outbound message. The important setting on
the outbound router is the <reply-to> endpoint, which tells Mule to route all responses to the jms://
Loan.Quotes endpoint, which is the endpoint on which the async-reply router is listening. When all
responses are received, the BankQuotesResponseAggregator selects the cheapest quotes and returns it.
Mule then handles returning this to the requester. The <reply-to> endpoint is applied to the next service
invoked. For example, if service1 dispatches to service2, and service1 has an outbound router with a
reply-to endpoint, service2 will send the results of its invocation to the reply-to endpoint.
Response Transformers
If you want to transform a response message without doing any other work on the response, you set the
transformers attribute on the response router without any other routing configuration.
<response-router transformers="OrderConfirmationToXml XmlToWebPage"/>
ReplyTo
All outbound routers can have a reply-to endpoint endpoint that defines where the message should be
routed after the recipient of the message has finished processing it. The <reply-to> endpoint is applied
to the next component invoked. For example, if component1 dispatches to component2, and component1
has an outbound router with a reply-to endpoint, component2 will send the results of its invocation to
the reply-to endpoint. The <reply-to> endpoint can be any valid Mule endpoint URI and is passed along
with the message to the next component if the underlying transport supports reply-to messages. For
information on which transports support reply-to, see Available Transports.
<outbound>
<custom-router class="org.foo.ConcreteMessageSplitter">
<vm:endpoint path="component1"/>
<vm:endpoint path="vm://component2"/>
<vm:endpoint path="vm://component3"/>
<reply-to address="vm://component4"/>
</custom-router>
</outbound>
Time-outs
The Async Reply router timeout determines how long Mule should wait for replies before returning the
result. The default value is determined by the value of the defaultSynchronousEventTimeout attribute
that has been configured for the Mule instance. (For more information, see Global Settings Configuration
Reference.) You can also specify an independent timeout value for asynchronous replies for a given
service using the optional timeout attribute on the async-reply element.
The optional failOnTimeout attribute determines whether to throw an exception if the router times out
before all expected messages have been received. If set to false (the default), the current messages are
returned for processing.

Exception Strategy
Exception strategies are used to handle exception conditions when an error occurs during the processing
of a message. You can configure exception strategies on services. If no exception strategy is configured,
the DefaultServiceExceptionStrategy is used.
For more information on exception strategies, see Error Handling.
Service Bridge
Service component configuration is optional in Mule 2.x. The default and implicit component used is
PassThroughComponent . This component automatically bridges inbound messages to the outbound
phase and simply passes messages to the outbound routers. This approach is useful for bridging
endpoints if you want to pass a message from one transport to another.
As of Mule 2.0, you no longer need to configure an explicit BridgeComponent.
The following example demonstrates reading a file and send its contents onto a JMS topic.
<service name="FileToJmsBridge">
<inbound>
<file:inbound-endpoint path="/data/in">
<file:filename-wildcard-filter pattern="*.txt"/>
</inbound-endpoint>
</inbound>

<outbound>
<outbound-pass-through-router">
<jms:outbound-endpoint topic="receivedFiles"/>
</outbound>
</service>
Service Model
By default, Mule uses the staged event-driven architecture (SEDA) model. SEDA is an architecture
model where applications consist of a network of event-driven stages connected by explicit queues.
This architecture allows services to be well-conditioned to load, preventing resources from being
overcommitted when demand exceeds service capacity. As a result, SEDA provides an efficient event-
based queuing model that maximizes performance and throughput.
See Models for more information about alternative models and information about how you can implement
your own.
Service Messaging Style

The messaging style determines the message exchange pattern that is to to be used on inbound
and outbound endpoints and allows endpoints to be configured as synchronous request/response or
asynchronous in-only as well as other patterns.
The messaging style is configured on endpoints, allowing multiple styles to be used with the same
service. For more information, see Mule Messaging Styles.

MEPs
This document is in progress and forms part of a proposal of how messaging exchanges in
Mule should work. Not unnecessarily how they work now. See Mule Messaging Styles for
information on how Mule message exchanges work as of Mule 2.0.
Table of Contents
• Message Exchange Patterns in Mule

• ° Focus on Services
° WSDL MEPs
° Extended MEPs (WSDL 2.0)
• Mule MEPs
• ° Notation
° In-Only
° - Example Configuration
- Example Code
° In-Out
- Example Code
° In-Out (async)
- Example Code
° In-Optional-Out
- Example Code
° In-Only, Out-Only
- Example Code
° In-Only, Optional-Out
- Example Code
° In-Out, Out-Only
- Example Code
° In-Optional-Out, Out-Optional-In
- Example Code
° In-Out, Out-In
- Example Code
° In-Optional-Out, Out-Only
- Example Code
• Advanced Patterns
• ° In-Optional-Out, Out-Only (Async Reply Router)
- Example Code
° In-Out, Out-Only (Async Reply Router)
- Example Code
° Orchestration using Component Bindings
- Example Code
• What Next?
• ° Possible MuleClient Changes
° Simplifying the client

Message Exchange Patterns in Mule
Message Exchange Patterns (MEPs) as defined as part of the WSDL specifications and provide a set of
well-defined interaction patterns between client and server. When talking about ESBs or EAI there are
typically a number of services that collaborate and the definition of which service is the client and which
is the server becomes blurred. This document describes a way of describing Mule interactions (messaging
styles) using the well-known MEPs.
Focus on Services
Web Services MEPs talk about client and server. Clients make requests to a server and (may) get a result,
whilst the server will receive data from a client (and sometimes may push data to a client). On the other
hand, Mule like other SOA-centric platforms focus on services. This means the world is viewed in terms of
data coming into and sent out of a service. The service could be viewed as a client or a server depending
on whether data flowing inbound or outbound. Thus, it makes a lot of sense to model service interactions
on the inbound and outbound separately.
The way to think about this is that we are defining MEPs between two parties, it doesn't matter if it's a
client or server, a service or legacy application that initiates or is the recipient of a request. And a request
is just an event, something that was triggered by a local or external process. By defining MEPs on the
inbound and outbound we can go on to define a set of combined MEPs (in and out) for Mule.
The diagram above shows a party (Application or Mule) that initiates a request. This gets receive by a
service inbound endpoint. Next the component is invoked and the result is routed via the outbound router
to another party (Application or Mule).
WSDL MEPs
Before we go any further lets introduce the MEPs defined in the WSDL 1.1 and WSDL 2.0 specifications.
Pattern Description
In-only This is equivalent to one-way or asynchronous. A

standard one-way messaging exchange where the
consumer sends a message to the provider that
provides only a status response.
Robust-In-Only This pattern is for guaranteed one-way message

exchanges. The consumer initiates with a
message. The provider can responds with status
or a fault. Note Guaranteed only means that the
consumer knows if the message got delivered.
Don't confuse this with reliable.

In-Out This is equivalent to request-response. A standard
two-way message exchange where the consumer
initiates with a message, the provider responds
with a message or fault.
In-Optional-Out A standard two-way message exchange where the

provider's response is optional.
Extended MEPs (WSDL 2.0)
Pattern Description
Out-Only The provider (server) initiates the message to the

client
Robust-Out-Only The provider initiates the message to the client

and the client must respond with either a status
or a fault.
Out-In The provider initiates a call and the client must

respond.
Out-Optional-In The provider initiates the call and the client can
choose to respond.
Mule MEPs
The following sections will introduce each exchange pattern in Mule based on the convention defined
above. Each pattern will either have an inbound MEP, outbound MEP or both. It is possible to have
multiple inbound and outbound MEPS for a single service, this will be discussed later on.
For the sake of clarity each pattern is described in terms of what interactions will occur for each scenario.
For those familiar with Mule, I will provide examples of the equivalent configuration in Mule. The plan for
this document is to come up with a simpler configuration for these MEPs in Mule.
Notation
Each pattern below is presented with a diagram that depicts the message flow for the pattern using the
diagram notation above. Each pattern also has a description and further information below it. Then there
is an XML configuration for each. Note that all components are written using Groovy just so that the
components are transparent for the user. Finally, there is a code example for each which shows how a
test-case is written to test each pattern.

In-Only
Description Receives a message from another party. No result

is expected and any result returned from the
service will be ignored.
Error Handling If an error occurs it is handled by the

ExceptionStrategy configured on either the
service or the model. An error endpoint can be
used to route errors and the party that initiated
the call can listen on the error endpoint.
Mule Config The Mule service must have an asynchronous

inbound endpoint and no outbound routers
configured.
<description>
Receives a message from another party. No result is expected and any result returned from the service will
be
ignored.
</description>
<vm:endpoint path="test.inbound" name="inboundEndpoint" synchronous="false"/>
<model>
<service name="In-Only-Service">
<inbound>
<vm:inbound-endpoint ref="inboundEndpoint"/>
</inbound>
<script:component>
import org.mule.tck.functional.FunctionalTestNotification
muleContext.fireNotification(new FunctionalTestNotification(
src, FunctionalTestNotification.EVENT_RECEIVED));
</script:script>
</script:component>
</service>

</model>
Example Code
The following example shows how to test the above configuration using a FunctionalTestCase.
public class InOnlyTestCase extends FunctionalTestCase

{
public static final long TIMEOUT = 3000;

{
return "org/mule/test/integration/messaging/meps/pattern_In-Only.xml";
}
public void testExchange() throws Exception

{
final Latch latch = new Latch();

client.getMuleContext().registerListener(new FunctionalTestNotificationListener()
{
{
latch.countDown();
}
});
client.dispatch("inboundEndpoint", "some data", null);

assertTrue(latch.await(TIMEOUT, TimeUnit.MILLISECONDS));
}
}
In-Out
Description Receives a message from another party and

the result of the service invocation is returned.
If the service returns null a message with a
NullPayload payload is returned.

Error Handling A response message is always
sent back. Clients can check the
MuleMessage.getExceptionPayload() property
to get all information about the service error. If
an exception originates from the callee side, the
exception will be thrown and can be caught by the
callee.
Mule Config The Mule service must have an synchronous

configured.
<description>
Receives a message from another party and the result of the service invocation is returned. If the
service returns null a message with a NullPayload payload is returned.
</description>
<http:endpoint name="inboundEndpoint" host="localhost" port="8081" synchronous="true"/>
<model>
<service name="In-Out-Service">
<inbound>
<http:inbound-endpoint ref="inboundEndpoint"/>
</inbound>
<script:component>
if (message.getProperty("foo"))
return "foo header received"
else
return "foo header not received"
</script:script>
</script:component>
</service>
</model>
Example Code
public class InOutTestCase extends FunctionalTestCase

{

{
return "org/mule/test/integration/messaging/meps/pattern_In-Out.xml";
}

{

MuleMessage result = client.send("inboundEndpoint", "some data", null);
assertNotNull(result);
assertEquals("foo header not received", result.getPayloadAsString());

props.put("foo", "bar");
result = client.send("inboundEndpoint", "some data", props);
assertEquals("foo header received", result.getPayloadAsString());
}
}
In-Out (async)
Description Receives a message from another party and the

result of the service invocation is returned via
a back channel. This measn that an inbound
and response communication channel is used.
If the service returns null a message with a
NullPayload payload is returned.

callee.

configured. Additionally the callee must
configure a MULE_REPLY_TO header or a reply
to destination understood by the transport being
used i.e. For JMS JMSReplyTo property on the
javax.jms.Message.
<description>

A request is made from a party but the result of the request is returned on another channel as specified
either
as a MULE_REPLY_TO header or a reply to destination understood by the transport being used i.e.
JMSReplyTo.
</description>
<jms:endpoint queue="test.inbound" name="inboundEndpoint" remoteSync="true" synchronous="true"/>
<model>
<service name="In-Out-Async-Service">
<inbound>
<inbound-endpoint ref="inboundEndpoint"/>
</inbound>
<script:component>
message.setProperty("foo", "bar");
return "got it!"
</script:script>
</script:component>

</service>
</model>
Example Code
public class InOutAsyncTestCase extends FunctionalTestCase

{

{
return "org/mule/test/integration/messaging/meps/pattern_In-Out-Async.xml";
}

{
//Almost any endpoint can be used here
props.put(MuleProperties.MULE_REPLY_TO_PROPERTY, "jms://client-reply");
MuleMessage result = client.send("inboundEndpoint", "some data", props);

assertEquals("got it!", result.getPayloadAsString());
assertNotNull(result.getProperty("foo"));
assertEquals("bar", result.getProperty("foo"));
}
}

In-Optional-Out
Description Receives a message from another party and the

result of the service invocation is returned. If the
service returns null and there was no error while
processing the request, nothing is returned to the
callee.
Error Handling If an error occurs while the service is

processing the request a response message
is always sent back. Clients can check the
callee.

configured.
<description>
service returns null and there was no error while processing the request, nothing is returned to the callee.
</description>
<http:endpoint name="inboundEndpoint" host="localhost" port="8081" synchronous="true"/>
<model>
<service name="In-Optional-Out-Service">
<inbound>
</inbound>
<script:component>
else
return null
</script:script>

</script:component>
</service>
</model>
Example Code
public class InOptionalOutTestCase extends FunctionalTestCase

{

{
return "org/mule/test/integration/messaging/meps/pattern_In-Optional-Out.xml";
}

{

assertEquals(StringUtils.EMPTY, result.getPayloadAsString());

}
}
In-Only, Out-Only
Description Receives a message from another party but will

not return a result. The service component must
always return a result.


inbound endpoint and at least one outbound
routers configured.
<description>
service returns null a message with a NullPayload payload is returned.
MEP TODO: If a message does not originate from the service an exception should be thrown.
</description>

<vm:endpoint path="test.header.received" name="receivedEndpoint" synchronous="false"/>
<vm:endpoint path="test.header.notreceived" name="notReceivedEndpoint" synchronous="false"/>
<model>
<service name="In-Only_Out-Only-Service">
<inbound>
</inbound>
<script:component>
if (message.getProperty("foo")!=null)
else
</script:script>
</script:component>
<outbound>
<filtering-router>
<vm:outbound-endpoint ref="receivedEndpoint"/>
<wildcard-filter pattern="* header received"/>
</filtering-router>
<filtering-router>
<vm:outbound-endpoint ref="notReceivedEndpoint"/>
<wildcard-filter pattern="* header not received"/>
</filtering-router>
</outbound>
</service>
</model>
Example Code

public class InOnlyOutOnlyTestCase extends FunctionalTestCase
{

{
return "org/mule/test/integration/messaging/meps/pattern_In-Only_Out-Only.xml";
}

{

client.dispatch("inboundEndpoint", "some data", props);
MuleMessage result = client.request("receivedEndpoint", TIMEOUT);

result = client.request("notReceivedEndpoint", TIMEOUT);

}
}
In-Only, Optional-Out
Description Receives a message from another party but will

not return a result. If the service component does
return a result then a the result will be sent on
otherwise nothing further happens.


routers configured.
<description>
Receives a message from another party but will not return a result. The service component must always
return a
result.
</description>

<model>
<service name="In-Only_Optional-Out--Service">
<inbound>
</inbound>
<script:component>
else
return null
</script:script>
</script:component>
<outbound>
<filtering-router>
</filtering-router>
<filtering-router>
</filtering-router>
</outbound>
</service>
</model>
Example Code
public class InOnlyOptionalOutTestCase extends FunctionalTestCase

{

{

return "org/mule/test/integration/messaging/meps/pattern_In-Only_Optional-Out.xml";
}

{

client.dispatch("inboundEndpoint", "some data", props);


assertNull(result);
}
}
In-Out, Out-Only

returns a result from the service. Additionally
the same result will be router via the service
outbound routers.

the call can listen on the error endpoint. The
exception and context information will be attached
to the return message, however the message will
not be routed by the outbound endpoint.
Mule Config The Mule service must have a synchronous

routers configured.

<description>
Receives a message from another party and returns a result from the service. Additionally the same result
will
be router via the service outbound routers.
</description>
<vm:endpoint path="test.inbound" name="inboundEndpoint" synchronous="true"/>

<model>
<service name="In-Out_Out-Only-Service">
<inbound>
</inbound>
<script:component>
if (message.getProperty("foo")!=null)
else
</script:script>
</script:component>
<outbound>
<filtering-router>
</filtering-router>
<filtering-router>
</filtering-router>
</outbound>
</service>
</model>
Example Code
public class InOutOutOnlyTestCase extends FunctionalTestCase

{

{
return "org/mule/test/integration/messaging/meps/pattern_In-Out_Out-Only.xml";
}

{


result = client.request("receivedEndpoint", TIMEOUT);


}
}
In-Optional-Out, Out-Optional-In
Description Receives a message from another party. The

service processes the message and then it gets
routed via the outbound router. The outbound
router will wait for a result from the call and will
return the result to the originating party if one
is received. This pattern is analogous to using
Remote Sync on a Mule endpoint. If no result is
returned from the outbound call, null is returned.

to the return message. If there was no result a
NullPayload message will be returned with the
exception information attached.

inbound endpoint and an outbound router
configured with an endpoint with 'remoteSync' set
to true.

<description>
Receives a message from another party. The service processes the message and then it gets routed via the
outbound router. The outbound router will wait for a result from the call and will return the result to the
originating party if one is received. This pattern is analogous to using Remote Sync on a Mule endpoint. If no
result is returned from the outbound call, null is returned.
</description>
<jms:activemq-connector name="amq"/>
<jms:endpoint queue="external.app" name="ExternalEndpoint" remoteSync="true"

remoteSyncTimeout="3000"/>
<model>
<service name="In-Optional-Out_Out-Optional-In-Service">
<inbound>
</inbound>
<script:component>
if (message.getProperty("foo") != null)
{
message.setProperty("bar", "baz")
return message
}
else
return message
</script:script>
</script:component>
<outbound>
<outbound-endpoint ref="ExternalEndpoint"/>


</outbound>
</service>
<service name="Mock-External-App">
<inbound>
<inbound-endpoint ref="ExternalEndpoint"/>
</inbound>
<script:component>
message.setProperty("externalApp", "Received")
if (message.getProperty("bar") != null)
return "bar header received"
else
return null
</script:script>
</script:component>
</service>
</model>

Example Code
public class InOptionalOutOutOptionalInTestCase extends FunctionalTestCase

{

{
return "org/mule/test/integration/messaging/meps/pattern_In-Optional-Out_Out-Optional-In.xml";
}

{

assertEquals(NullPayload.getInstance(), result.getPayload());
//TODO Even though the component returns a null the remoteSync is honoured.
// I don't think this is right for Out-Optional-In, but probably should be the behaviour for Out-In
assertEquals("Received", result.getProperty("externalApp"));

assertEquals("bar header received", result.getPayload());
assertEquals("Received", result.getProperty("externalApp"));
}
}
In-Out, Out-In

routed via the outbound router. The outbound
router will wait for a result from the call and will
return the result to the originating party if one
is received. This pattern is analogous to using

Remote Sync on a Mule endpoint. If a result is not
returned from the outbound call an error will be
thrown.

to the return message if there is a result.

configured with an endpoint with 'remoteSync' set
to true.
<description>
outbound router. The outbound router will wait for a result from the call and will return the result to the
originating party if one is received. This pattern is analogous to using Remote Sync on a Mule endpoint. If a
result is not returned from the outbound call an error will be thrown.
</description>
<jms:activemq-connector name="amq"/>
<jms:endpoint queue="external.app" name="ExternalEndpoint" remoteSync="true"

<model>
<service name="In-Out_Out-In-Service">
<inbound>
</inbound>
<script:component>
message.setProperty("bar", "baz")
return message
</script:script>
</script:component>
<outbound>
<outbound-endpoint ref="ExternalEndpoint"/>


</outbound>
</service>
<service name="Mock-External-App">
<inbound>
<inbound-endpoint ref="ExternalEndpoint"/>
</inbound>
<script:component>

message.setProperty("externalApp", "Received")
if (message.getProperty("bar") != null)
return "bar header received"
</script:script>
</script:component>
</service>
</model>
Example Code
public class InOutOutInTestCase extends FunctionalTestCase

{

{
return "org/mule/test/integration/messaging/meps/pattern_In-Out_Out-In.xml";
}

{

MuleMessage result = client.send("inboundEndpoint", "some data", props);
assertEquals("bar header received", result.getPayload());
}
}
In-Optional-Out, Out-Only

routed via the outbound router. If a result is

returned from the component it is returned back
to the calling party.

to the return message if there is a result.

configured with an endpoint.
<description>
outbound router. If a result is returned from the component it is returned back to the calling party.
</description>

<model>
<service name="In-Optional-Out_Out-Only-Service">
<inbound>
</inbound>
<script:component>
else
return null
</script:script>
</script:component>
<outbound>
<outbound-endpoint ref="receivedEndpoint"/>
</outbound>
</service>
</model>
Example Code
public class InOptionalOutOutOnlyTestCase extends FunctionalTestCase

{


{
return "org/mule/test/integration/messaging/meps/pattern_In-Optional-Out_Out-Only.xml";
}

{


assertEquals("foo header received", result.getPayload());
}
}
Advanced Patterns
In-Optional-Out, Out-Only (Async Reply Router)

processes the message. Then the message is sent
to another service (or application) for processing.
A Reply-To endpoint is attached to the message
and this is used by the second service to return
a result. Note that if the external service is not a
Mule instance the protocol being used will ahve
to ahve the notion of a back channel or reply-to
destination, i.e. JMS, WS-Addressing, Socket-bsed
protocols.

Since the response is optional, the <async-reply>
router timeout should be reduced since, it will
block for the whole time if no reply is given.
This MEP combination should ONLY be used in
low message volume scenarios. In high volume
scenarios the pattern MEPs#In-Out, Out-Only
(Async Reply Router) should be used and a
response always returned, even if it is an empty
or acknowledgment message.
Error Handling A response message is always sent back

if an error occurs. Clients can check the
callee.

inbound endpoint, at least outbound routers
configured with a reply-to endpoint and an
Async Reply router to listen on the reply to
endpoint. Only the inbound endpoint needs to be
synchronous al others can be asynchronous.
<description>
Receives a message from another party and processes the message. Then the message is sent to another
service (or
application) for processing. A Reply-To endpoint is attached to the message and this is used by the second
service to return a result. Note that if the external service is not a Mule instance the protocol being used
will ahve to ahve the notion of a back channel or reply-to destination, i.e. JMS, WS-Addressing, Socket-bsed
protocols.
Since the response is optional, the <async-reply> router timeout should be reduced since, it will block
for the whole time if no reply is given.
This MEP combination should *ONLY* be used in low message volume scenarios. In high volume scenarios
the pattern
In-Out, Out-Only (async) should be used and a response always returned, even if it is an empty or
acknowledgement message.
Note: this fails with ActiveMQ because of an outstanding issue on the part of ActiveMQ for handling
temporary
destinations.
</description>
<vm:endpoint path="test.inbound" name="inboundEndpoint" remoteSync="true" synchronous="true"/>

<vm:endpoint path="test.external.app" name="externalEndpoint" synchronous="false"/>
<vm:endpoint path="test.reply" name="replyEndpoint" synchronous="false"/>
<model>
<service name="In-Out_Out-Only-Async-Service">
<inbound>
</inbound>
<script:component>

return message
else
{
//This shouldn't be needed but null does not stop the async-reply...
eventContext.setStopFurtherProcessing(true)
return null
}
</script:script>
</script:component>
<outbound>
<filtering-router>
<outbound-endpoint ref="externalEndpoint"/>
<reply-to ref="replyEndpoint"/>
</filtering-router>
</outbound>
<async-reply failOnTimeout="false" timeout="2000">

<inbound-endpoint ref="replyEndpoint"/>
<single-async-reply-router/>
</async-reply>
</service>
<service name="ExternalApp">
<inbound>
<inbound-endpoint ref="externalEndpoint"/>
</inbound>
<test:component>
<test:return-data>got it!</test:return-data>
</test:component>
</service>
</model>
Example Code
public class InOptionalOutOutOnlyAsyncRouterTestCase extends FunctionalTestCase

{

{
return "org/mule/test/integration/messaging/meps/pattern_In-Optional-Out_Out-Only-Async-Router.xml";
}

{

assertNull(result.getExceptionPayload());


}
}
In-Out, Out-Only (Async Reply Router)

processes the message. Then the message is sent
to another service (or application) for processing.
A Reply-To endpoint is attached to the message
and this is used by the second service to return
a result. Note that if the external service is not a
Mule instance the protocol being used will need
to have the notion of a back channel or reply-
to destination, i.e. JMS, WS-Addressing, Socket-
based protocols.

callee.

inbound endpoint, at least outbound routers
configured with a reply-to endpoint and an
Async Reply router to listen on the reply to
endpoint. Only the inbound endpoint needs to be
synchronous al others can be asynchronous.

<description>
Receives a message from another party and processes the message. Then the message is sent to another
service (or
application) for processing. A Reply-To endpoint is attached to the message and this is used by the second
service to return a result. Note that if the external service is not a Mule instance the protocol being used
will need to have the notion of a back channel or reply-to destination, i.e. JMS, WS-Addressing, Socket-
based
protocols.
</description>

<jms:endpoint queue="test.external.app" name="externalEndpoint" synchronous="false"/>
<jms:endpoint queue="test.reply" name="replyEndpoint" synchronous="false"/>
<model>
<service name="In-Out_Out-Only-Async-Service">
<inbound>
</inbound>
<script:component>
message.setProperty("foo", "bar")
return message
</script:script>
</script:component>
<outbound>
<filtering-router>
<outbound-endpoint ref="externalEndpoint"/>
<reply-to ref="replyEndpoint"/>
</filtering-router>
</outbound>
<async-reply failOnTimeout="true" timeout="4000">

</async-reply>
</service>
<service name="ExternalApp">
<inbound>
<inbound-endpoint ref="externalEndpoint"/>
</inbound>
<test:component>
<test:return-data>got it!</test:return-data>
</test:component>
</service>
</model>
Example Code
public class InOutOutOnlyAsyncRouterTestCase extends FunctionalTestCase

{


{
return "org/mule/test/integration/messaging/meps/pattern_In-Out_Out-Only-Async-Router.xml";
}

{

}
}
Orchestration using Component Bindings
TODO
<description>
Receives a message from another party but will not return a result. The service component will call out to
another
service before sending the result out on the the outbound router. Bindings provide a way to orchestrate flows
between services.

</description>

<vm:endpoint path="addition.service" name="additionEndpoint" synchronous="true"/>
<vm:endpoint path="test.received" name="receivedEndpoint" synchronous="false"/>
<model>
<service name="In-Only_In-Out_Out-Only-Service">
<inbound>
</inbound>
<script:component>
return "Total: " + AdditionService.add(payload)
</script:script>
<script:java-interface-binding interface="org.mule.tck.services.AdditionService" method="add">
<outbound-endpoint ref="additionEndpoint"/>
</script:component>
<outbound>
<filtering-router>
</filtering-router>
</outbound>
</service>
<service name="Addition-Service">
<inbound>
<vm:inbound-endpoint ref="additionEndpoint"/>
</inbound>
<component class="org.mule.tck.services.SimpleMathsComponent"/>
</service>
</model>
Example Code
public class BindingInOnlyInOutOutOnlyTestCase extends FunctionalTestCase

{

{
return "org/mule/test/integration/messaging/meps/pattern_binding-In-Only_In-Out_Out-Only.xml";
}

{
client.dispatch("inboundEndpoint", new int[]{1,2,3,4,5}, null);

assertEquals("Total: 15", result.getPayloadAsString());
}

}
What Next?
Mule can model every MEP combination that makes sense. What is difficult in Mule right now it to know
how to do this. The logical next step would be to change the way endpoints are configured. Instead,
of having the synchronous and remoteSync attributes on the endpoint, users could set an exchange
attribute that would define one of the options above. There are some obvious benefits:
• This method removes the complexity of the current configuration options

• Using well defined exchange patterns explicitly will have readability of Mule configurations
• Mule can provide much better validation over the correct MEP combinations that can be used with
different transports.
For example, depending on the transport being used developers could define endpoints such as:
<jms:inbound-endpoint queue="my.queue" exchange="In-Only"/>
<http:inbound-endpoint host="localhost" port="8080" path="/mule" exchange="In-Out"/>
Obviously, there would be a similar method for defining outbound endpoints:
<jms:outbound-endpoint queue="my.queue" exchange="Out-Only"/>
<http:inbound-endpoint host="localhost" port="8080" path="/mule" exchange="Out-In"/>
Possible MuleClient Changes

The Mule client is a common way for users to interact with Mule services. The MuleClient provides a
number of interfaces for sending or requesting information from an endpoint. These methods such as
MuleClient.send, MuleClient.dispatch, MuleClient.request determine how the request is made.
For example, using the send() methods causes a synchronous request and returns a result. Whilst
dispatch() causes an asynchronous request and does not return a result. So right now the MuleClient is
partly responsible (from the client-side) for how a MEP works in Mule.
Simplifying the client

If Mule can have a MEP defined on the inbound and outbound, it become redundant to have these
additional methods on the MuleClient. Instead, we could have a single exchange interface that will honour
the request based on the MEPs configured on the endpoints involved.
The Mule client code may look something like this:
MuleClient2 client = new MuleClient2();

MuleExchange exchange = client.invoke("jms://topic:in", "some data", null);
MuleMessage result = exchange.getNextResultMessage();

assertEquals("some data received", result.getPayload());
assertEquals(1, exchange.getresultsSize());
//Get message history

assertEquals("some data", exchange.getSourceMessage().getPayload());
The MuleExchange object here provides an interface for all messages generated from the invocation.
If we wanted to configure the MuleExchange we might do the following:
MuleClient2 client = new MuleClient2();

MuleExchange exchange = client.createExchange();
exchange.setEnableHistory(false);
client.invoke(exchange, "jms://topic:in", "some data", null);
MuleMessage result = exchange.getNextResultMessage();

assertEquals("some data received", result.getPayload());
assertEquals(1, exchange.getresultsSize());
//Message History disabled
assertNull(exchange.getSourceMessage());

Mule Messaging Styles
Mule Messaging Styles

[ Overview ] [ Asynchronous ] [ Request Response ] [ Synchronous ] [ Remote Synchronous ] [ Async
Request Response ]
Overview
Mule can send messages asynchronously (each stage of the message is on a different thread) or
synchronously (after the message is received by the component, it uses a single thread throughout the
rest of its lifecycle and supports request-response). You can set the synchronous property on the model,
on the endpoint, and implicitly within the transport.
By default, Mule uses SEDA, which uses asynchronous staged queues. One thread is used for the inbound
message, another thread is used for processing the message in the service component, and another
thread is used for the outbound message. You can configure the message so that the inbound message
is on one thread and the remaining stages are on a second thread, or so that all stages are on a single
thread.
Mule also supports the request-response messaging style. In this case, there is no outbound router, so
the message is sent back to the same endpoint as the inbound endpoint, providing a reply back to the
sender.
You can use a mix of synchronous and asynchronous messaging styles throughout Mule. You can also
use a mix of styles for a single service component. For example, a service component can have multiple
outbound routers that route to different endpoints depending on filter criteria, and you might want the
message to be sent synchronously in some cases and asynchronously in others.
The rest of this page describes the various messaging styles in more detail and how to configure them. It
includes reference to the message exchange patterns (MEPs) that each message style supports. For more
information on MEPs and Mule, see MEPs.
Asynchronous
Description Receives a message and puts it on a SEDA queue.

The callee thread returns and the message is
processed by the SEDA thread pool. Nothing gets
returned from the result of the call.
Error Handling If an error occurs it is handled by the Mule server.

An error endpoint can be used to route errors and
the client that initiated the call can listen on the
error queue in a separate thread, other have a
specific error handling client.

inbound endpoint.
Equivalent MEPs In-only
Discussion Points • We have no way of supporting Robust In-

only MEP outside of web services (where in
Mule you would use Request/Response) and
define the MEP in the service contract.
mule.xsd
mule-test.xsd
mule-jms.xsd
beans-2.5.xsd">
<model name="Asynchronous_Message_Pattern">
<service name="AsynchronousService">
<inbound>
<jms:inbound-endpoint queue="test.in" synchronous="false"/>
</inbound>
<test:component/>
</service>
</model>
</mule>
Request Response
Description Receives a message and the component returns a

message. If the component call returns null, then
a MuleMessage with a NullPayload is returned.

If the call method is void the request message is
returned.

inbound endpoint and no outbound endpoint
configured.

MuleMessage.getExceptionPayload() to get
all information about the server-side error. If
an exception originates from the client call, the
Equivalent MEPs In-Out, In-Optional-Out
Discussion Points • In-Optional-Out returns the request message

if there is no result from the call. This is
confusing.
mule.xsd
mule-test.xsd
mule-http.xsd
beans-2.5.xsd">
<model name="Request-Response_Message_Pattern">
<service name="SynchronousService">
<inbound>
<http:inbound-endpoint host="localhost" port="8080" path="/mule/services" synchronous="true"/
>
</inbound>
<test:component/>
</service>
</model>
</mule>

Synchronous
Description Receives a message and the component processes

before sending it out on another endpoint. The
synchronous call must be used if transactions
are being used on the inbound endpoint. The
odd behaviour right now is that a Synchronous
call always returns a result, even if there is an
outbound endpoint.

inbound endpoint and an outbound endpoint
configured.

Equivalent MEPs In-Only, In-Optional-Out, In-Out
Discussion Points • Mule will aways return the result the

component returned back to the callee as
well as sending it out via the outbound
endpoint. This causes some confusion.
mule.xsd
mule-test.xsd
mule-jms.xsd
beans-2.5.xsd">

<model name="Synchronous_Message_Pattern">
<service name="SynchronousService">
<inbound>
<jms:inbound-endpoint queue="test.in" synchronous="true"/>
</inbound>
<test:component/>
<outbound>
<jms:outbound-endpoint queue="test.out"/>
</outbound>
</service>
</model>
</mule>
Remote Synchronous
Description Receives a message and the component processes

before sending it out on another endpoint.
The request happens in the same thread. Mule
blocks on at the outbound endpoint to wait for
a response from the remote application. Some
protocols do not support a reply channel and Mule
will ignore the remoteSync if this is the case.

inbound endpoint and an outbound endpoint
configured. The inbound endpoint or the outbound
endpoint should have 'remoteSync' configured to
true.

Discussion Points • Need to clean up configuration semantics of

remoteSync
• RemoteSync validation is silent

mule.xsd
mule-test.xsd
mule-jms.xsd
beans-2.5.xsd">
<model name="Remote_Synchronous_Message_Pattern">
<service name="RemoteSynchronousService">
<inbound>
<jms:inbound-endpoint queue="test.in" synchronous="true"/>
</inbound>
<test:component/>
<outbound>
<jms:outbound-endpoint queue="another.service" remoteSync="true"
</outbound>
</service>
<service name="AnotherService">
<inbound>
<jms:inbound-endpoint queue="another.service" synchronous="true"/>
</inbound>
<test:component/>
</service>
</model>
</mule>
Async Request Response

Description This pattern enables Request Response messaging
and allows the back-end process to be forked to
invoke other services and return a result based
on the results of multiple service invocations. The
Async Reply Router is used to listen on a Reply To
endpoint for results.
Mule Config A <async-reply> element can be used to listen

on a reply endpoint. There must also be at least
one outbound endpoint and the inbound endpoint
must be synchronous.

Discussion Points None
xmlns:scripting="http://www.mulesource.org/schema/mule/scripting/2.0"
mule.xsd
mule-test.xsd
mule-http.xsd
mule-jms.xsd
http://www.mulesource.org/schema/mule/scripting/2.0 http://www.mulesource.org/schema/mule/
scripting/2.0/mule-scripting.xsd
beans-2.5.xsd">
<model name="Async_Request-Response_Message_Pattern">
<service name="AsyncRequestResponseService">
<inbound>
<http:inbound-endpoint host="localhost" port="8080" path="/mule/services" synchronous="true"/
>
</inbound>
<test:component/>
<async-reply timeout="5000">
<collection-async-reply-router/>
<jms:inbound-endpoint queue="reply.queue"/>

</async-reply>
<outbound>
<reply-to address="jms://reply.queue"/>
<jms:outbound-endpoint queue="service1" synchronous="false"/>
<jms:outbound-endpoint queue="service2" synchronous="false"/>
</outbound>
</service>
</model>
</mule>

Using Message Routers
Using Message Routers

[ Quick Reference ] [ Mule Inbound Routers ] [ Mule Outbound Routers ] [ Asynchronous Reply Routers ]
[ Catch-all Strategies ] [ Filters ]
Message routers are used to control how messages are sent and received by components in the system.
Mule defines inbound routers that apply to messages as they are received, and outbound routers that are
invoked when a message is being dispatched.
Mule provides flexible message routing support for your components. Routing features are based on the
enterprise routing requirements described in EIP.
For information on how your Java or Script components can orchestrate messages, see Component
Bindings.
Quick Reference
Inbound Routers Outbound Routers Async-Reply Routers Catch All Strategies
No Router Pass-through Single Forwarding
Selective Consumer Filtering Collection Custom Fowarding
Idempotent Receiver Static Recipient List Custom Logging
Idempotent Secure Multicasting Custom

Hash Receiver
Collection Aggregator Chaining
Message Chunking List Message Splitter

Aggregator
Custom Correlation Filtering XML Message

Aggregator Splitter
Forwarding Message Chunking

Router
WireTap Exception Based Router
Custom Endpoint Template
Round Robin XML

Splitter
Custom
Mule Inbound Routers

When a message is received via an endpoint, the inbound router controls how and if this message gets
routed into the service. The following sections describe the Mule inbound routers and how to configure
them. For more detailed information on inbound router configuration elements and attributes, see the
Inbound Router Configuration Reference.

All inbound routers are configured on a service within the <inbound> element.
No Router
If no router is defined on the inbound, all messages received via the endpoints will be processed by the
service component.
<inbound>
<jms:inbound-endpoint queue="foo.bar"/>
<vm:inbound-endpoint path="foo.bar.local"/>
</inbound>
Selective Consumer
A selective consumer is an inbound router that can apply one or more filters to the incoming message. If
the filters match, the message is forwarded to the component. Otherwise, the message is forwarded to
the catch-all strategy on the router. If no catch-all is configured, the message is ignored and a warning is
logged.
Configuration for this router is as follows:
<inbound>
<mulexml:jxpath-filter expression="msg/header/resultcode = 'success'"/>
<jms:endpoint topic="error.topic"/>
</inbound>
For information on using filters with this router, see Using Filters. Note that by default the filter is applied
to the message after the inbound transformers are applied. If you need to execute filters on the message
without applying any transformation, you can set the transformFirst property on this router to control
whether transformations are applied.
<inbound>
<jms:endpoint topic="error.topic"/>
<selective-consumer-router transformFirst="false">
</inbound>
Idempotent Receiver
An idempotent receiver ensures that only unique messages are received by a service by checking the
unique ID of the incoming message. The ID can be generated from the message using an expression
defined in the idExpression attribute. By default, the expression used is #[message:id], which
means the underlying endpoint must support unique message IDs for this to work. Otherwise, a
UniqueIdNotSupportedException is thrown.

There is a simple idempotent receiver implementation provided at
org.mule.routers.inbound.IdempotentReceiver . The default implementation uses a simple file-based
mechanism for storing message IDs, but you can extend this class to store the IDs in a database instead
by implementing the ObjectStore interface.
<inbound>
<idempotent-receiver-router idExpression="#[message:id]-#[header:foo]">
<simple-text-file-store directory="./idempotent"/>
</idempotent-receiver-router>
</inbound>
The optional idExpression attribute determines what should be used as the unique message ID. If this
attribute is not used, #[message:id] is used by default.
The nested element shown above configures the location where the received message IDs are stored.
In this example, they are stored to disk so that the router can remember state between restarts. If the
directory attribute is not specified, the default value used is ${mule.working.dir}/objectstore where
mule.working.dir is the working directory configured for the Mule instance.
If no store is configured, the InMemoryObjectStore is used by default.
Idempotent Secure Hash Receiver
This router ensures that only unique messages are received by a service by calculating the hash of the
message itself using a message digest algorithm. This approach provides a value with an infinitesimally
small chance of a collision and can be used to filter message duplicates. Note that the hash is calculated
over the entire byte array representing the message, so any leading or trailing spaces or extraneous
bytes (like padding) can produce different hash values for the same semantic message content.
Therefore, you should ensure that messages do not contain extraneous bytes. This router is useful when
the message does not support unique identifiers.
<inbound>
<secure-hash-idempotent-receiver-router messageDigestAlgorithm="SHA26">
<simple-text-file-store directory="./idempotent"/>
</secure-hash-idempotent-receiver-router>
</inbound>
Idempotent Secure Hash Receiver also uses object stores, which are configured the same way as the
Idempotent Receiver. The optional messageDigestAlgorithm attribute determines the hashing algorithm
that will be used. If this attribute is not specified, the default algorithm SHA-256 is used.
Collection Aggregator
Some outbound routers assign a correlation ID to messages when they are dispatched. The Collection
Aggregator groups incoming messages with matching correlation IDs into a MuleMessageCollection.
MuleMessageCollection extends MuleMessage and provides additional methods for working with a
collection of messages. You can specify the timeout attribute to determine how long the router waits in
milliseconds for messages to complete the group.
The aggregator is based on the Selective Consumer, so you can also apply filters to the messages.

<inbound>
<collection-aggregator-router timeout="6000">
<payload-type-filter expectedType="org.foo.some.Object"/>
</collection-aggregator-router>
</inbound>
Message Chunking Aggregator
This aggregator combines messages that have the same correlation ID into a single message. Correlation
IDs are set on messages when they are dispatched by certain outbound routers such as the Recipient
List and List Message Splitter routers. These messages can be aggregated back together again using this
router.
This aggregator is based on the Selective Consumer, so filters can also be applied to messages.
<inbound>
<message-chunking-aggregator-router>
<message-info-mapping correlationId="##" />
</message-chunking-aggregator-router>
</inbound>
The optional message-info-mapping element allows you to identify the correlation ID in the message
using an expression. If this element is not specified, MuleMessage.getCorrelationId() is used.
Custom Correlation Aggregator
This router is used to configure a custom message aggregator. Mule provides an abstract implementation
that has a template method that performs the message aggregation. A common use of the aggregator
router is to combine the results of multiple requests such as "ask this set of vendors for the best price of
X".
The aggregator is based on the Selective Consumer, so you can also apply filters to messages.
<inbound>
<custom-correlation-aggregator-router class="org.mule.CustomAgregator">
</custom-correlation-aggregator-router>
</inbound>
There is an AbstractEventAggregator that provides a thread-safe implementation for custom aggregators,

which you can can use to write a custom aggregator router. For example, the Loan Broker examples
included in the Mule distribution use a custom BankQuotesInboundAggregator router to aggregate bank
quotes.

Correlation Resequencer
The Correlation Resequencer Router will hold back a group of messages and resequence them using
the messages correlation sequence property. A java.util.Comparator is used to sort the messages.
This router is based on the Selective Consumer, which means that filters can be applied to the incoming
messages.
<inbound>
<correlation-resequencer-router>
</correlation-resequencer-router>
</inbound>
Forwarding Router
This router allows messages to be forwarded to an outbound router without first being processed by a
component. It essentially acts as a bridge between an inbound and an outbound endpoint. This is useful
in situations where the developer does not need to execute any logic on the inbound message but does
need to forward it on to a component residing on another destination (such as a remote Mule node or
application) over the network.
<service name="FileReader">
<inbound>
<file:inbound-endpoint path="/temp/myfiles/in"/>
<forwarding-router/>
</inbound>
<echo-component/>
<outbound>
<tcp:outbound-endpoint host="192.168.0.6" port="12345">
<object-to-byte-array-transformer/>
</tcp:outbound-endpoint>
</outbound>
</service>
When a file becomes available on the local file system, an event is triggered that creates the
message, which is then automatically forwarded via TCP to 192.168.0.6. Notice that there is an
outboundTransformer configured. This will be used to transform the message's payload before it is
dispatched over TCP. There is an echo component configured, but when the forwarding consumer is used,
the component invocation is skipped, and the message is forwarded directly the the outbound router(s).
Configuring the service as a bridge is recommended for most forwarding scenarios. However, if you need
to selectively forward only some events while others are processed by the component, you will need to
use this router.
The Forwarding router extends the Selective Consumer, so you can configure filters on this router.
Wiretap Router
See Using the WireTap Inbound Router.

Custom Inbound Router
You can configure custom inbound routers by specifying the custom router class on the <custom-
inbound-router> element and by using Spring properties. Optionally, you can also configure an
outbound endpoint in case this is needed for implementing a custom wiretap router for example.
<inbound>
<custom-inbound-router class="org.my.CustomInboundRouter">
<spring:properties>
<spring:property key="key1" value="value1"/>
</spring:properties>
<vm:outbound-endpoint path="out"/>
</custom-inbound-router>
</inbound>
Mule Outbound Routers

After a message has been processed by a component, you use outbound routers to determine where to
send the message next. The following sections describe each Mule outbound router and how to configure
them. Outbound routers can be more complex to configure, as they allow different routing paths that
can be selected depending on the logic defined in one or more filters. For more detailed information
on outbound router configuration elements and attributes, see the Outbound Router Configuration
Reference.
Pass-through Router
This router always matches and simply sends or dispatches message via the one endpoint it has
configured.
2.0:
<outbound>
<smtp:outbound-endpoint to="ross@muleumo.org"/>
</outbound>
2.1:
<outbound>
</outbound>

Filtering Router
This router uses filters to route only those messages that meet specific criteria to the endpoint configured
on the router. All Mule outbound routers, except the pass-through router described above, extend
FilteringOutboundRouter, so you can always apply a filter to an outbound router.
<outbound>
<filtering-router>
</filtering-router>
<filtering-router>
<jms:outbound-endpoint queue="string.queue"/>
<and-filter>
</and-filter>
</filtering-router>
</outbound>
The filter is applied to the message first, and then the transformers are applied. If you need to transform
the message before the filter is applied, you can set a transformer on this router that will be applied to
the message before the filter is applied.
<outbound>
<filtering-router>
<transformer ref="aTransformer"/>
</filtering-router>
</outbound>
Recipient List Router
The recipient list 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. Mule provides an abstract recipient list implementation
org.mule.routing.outbound.AbstractRecipientList , which provides a thread-safe base for specialized
implementations.
Mule also provides a static recipient list router that takes a configured list of endpoints from the current
message or from a statically declared list on the endpoint.
<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>
Multicasting Router
The Multicasting router can be used to send the same message over multiple endpoints. When using
this router, be sure to configure the correct transformers on the endpoints to handle the message source
type.
<outbound>
<jms:endpoint queue="test.queue" transformer-refs="StringToJmsMessage"/>
<http:endpoint host="10.192.111.11" transformer-refs="StringToHttpClientRequest"/>
<tcp:endpoint host="10.192.111.12" transformer-refs="StringToByteArray"/>
</outbound>
Chaining Router
The Chaining router can be used to send the message through multiple endpoints using the result of the
first invocation as the input for the next. For example, this can be useful where you want to send the
results of a synchronous request-response invocation such as a Web service call to a JMS queue. Endpoint
transformers can be used to transform the message to the format the next endpoint requires.
<outbound>
<chaining-router>
<axis:outbound-endpoint address="http://localhost:8081/services/xyz?method=getSomething"/>
<jms:outbound-endpoint queue="something.queue">
<transformer ref="SomethingToJmsMessage"/>
</chaining-router>
</outbound>
List Message Splitter
A message splitter can be used to break down an outgoing message into parts and dispatch those parts
over different endpoints configured on the router. The List Message Splitter accepts a list of objects that
will be routed to different endpoints. The actual endpoint used for each object in the list is determined by
a filter configured on the endpoint itself. If the endpoint's filter accepts the object, the endpoint will be
used to route the object.
By default the AbstractMessageSplitter sets a correlation ID and correlation sequence on the outbound
messages so that inbound routers such as the Collection Aggregator or Correlation Resequencer are able
to resequence or combine the split messages.
The router configuration below expects the message payload to be a java.util.List and will route
objects in the list that are of type com.foo.Order, com.foo.Item, and com.foo.Customer. The router will
allow any number and combination of these objects.

<outbound>
<list-message-splitter-router">
<jms:outbound-endpoint queue="order.queue">
<payload-type-filter expectedType="com.foo.Order"/>
<jms:outbound-endpoint queue="item.queue">
<payload-type-filter expectedType="com.foo.Item"/>
<jms:outbound-endpoint queue="customer.queue">
<payload-type-filter expectedType="com.foo.Customer"/>
<payload-type-filter expectedType="java.util.List"/>
</list-message-splitter-router>
</outbound>
Note that there is also a filter on the router itself that ensures that the message payload received is
of type java.util.List. If there are objects in the list that do not match any of the endpoint filters,
a warning is written to the log and processing continues. To route any non-matching object types to
another endpoint, add the endpoint at the end of the list without a filter.
Filtering XML Message Splitter
This router is similar to the List Message Splitter but operates on XML documents. Supported payload
types are:
• org.dom4j.Document objects
• byte[]
• java.lang.String
If no match is found, it is ignored and logged at the WARN level.
The router splits the payload into nodes based on the splitExpression property. The actual endpoint
used for each object in the list is determined by a filter configured on the endpoint itself. If the endpoint's
filter accepts the object, the endpoint will be used to route the object. Each part returned is actually
returned as a new DOM4J document.
The router can optionally perform a validation against an external XML schema document. To perform the
validation, set externalSchemaLocation to the XSD file in your classpath. Setting this property overrides
whatever schema document you declare in the XML header.
<outbound>
<mulexml:message-splitter splitExpression="root/nodes" validateSchema="true" externalSchemaLocation="/
com/example/TheSchema.xsd">
<vm:outbound-endpoint path="order">
<payload-type-filter expectedType="com.foo.Order"/>
</vm:outbound-endpoint>
<vm:outbound-endpoint path="item">
<payload-type-filter expectedType="com.foo.Item"/>
<vm:outbound-endpoint path="customer">
<payload-type-filter expectedType="com.foo.Customer"/>
<payload-type-filter expectedType="org.dom4j.Document"/>
</mulexml:message-splitter>

</outbound>
Round Robin Message Splitter
The round robin message splitter will split a DOM4J document into nodes based on the "splitExpression"
property. It will then send these document fragments to the list of endpoints specified in a round
robbin fashion. Optionally, you can specify a namespaces property map that contain prefix/namespace
mappings.
For instance, the following fragment will route the "/a:orders/a:order" nodes inside the document to the
robin1 and robin2 endpoints.
<outbound>
<mxml:round-robin-splitter splitExpression="/a:orders/a:order" deterministic="false">
<outbound-endpoint ref="robin1"/>
<mxml:namespace prefix="a" uri="http://acme.com"/>
</mxml:round-robin-splitter>
</outbound>
The router can optionally perform a validation against an external XML schema document. To perform the
validation, set externalSchemaLocation to the XSD file in your classpath. Setting this property overrides
whatever schema document you declare in the XML header.
<outbound>
<mxml:round-robin-splitter splitExpression="/a:orders/a:order" deterministic="false"
externalSchemaLocation="mySchema.xsd" validateSchema="true">
<mxml:namespace prefix="a" uri="http://acme.com"/>
</mxml:round-robin-splitter>
</outbound>
Message Chunking Outbound Router
This routing pattern allows you to split a single message into a number of fixed-length messages that
will all be routed to the same endpoint. It will split the message up into a number of smaller chunks
according to the messageSize attribute that you configure for the router. If you do not configure a
messageSize, or if it has a value of zero, the message will not be split up and the entire message will be
routed to the destination endpoint as is. The router splits up the message by first converting it to a byte
array and then splitting this array into chunks. If the message cannot be converted into a byte array, a
RoutingException is raised.
A message chunking router is useful if you have bandwidth problems (or size limitations) when using
a particular transport. If you want to be able to route different segments of the original message to
different endpoints, consider using the List Message Splitter or Filtering Xml Message Splitter router
instead.
To put the chunked items back together again, you can use the Message Chunking Aggregator as the
inbound router on the next service.

Sample Configuration
<service name="chunkingService">
<inbound>
<vm:inbound-endpoint path="fromClient"/>
</inbound>
<outbound>
<message-chunking-router messageSize="4">
<vm:outbound-endpoint path="toClient"/>
</message-chunking-router>
</outbound>
</service>
In the example above, any data received on the vm fromClient endpoint is chunked into messages four
bytes long before being sent along the vm toClient endpoint. If we sent "The quick brown fox jumped
over the lazy dog" to this service, anything listening on the vm toClient endpoint would receive the
following messages (the spaces have been replaced with underscores for better legibility):
Message # Contents
1 The_
2 quic
3 k_br
4 own_
5 fox_
6 jump
7 ed_o
8 ver_
9 the_
10 lazy
11 _dog
Exception Based Router
The Exception Based router can be used to send a message over an endpoint by selecting the first
endpoint that can connect to the transport. This can be useful for setting up retries. When the first
endpoint fails, the second will be invoked, and if that fails, it will try the next endpoint. Note that this
router overrides the endpoint mode to synchronous while looking for a successful send and will resort to
using the endpoint's mode for the last item in the list.
<outbound>
<exception-based-router>
<tcp:endpoint host="10.192.111.10" port="10001" />

</exception-based-router>
</outbound>
Endpoint Template Router
The endpoint template router allows endpoints to be altered at runtime based on properties set on the
current message or fallback values set on the endpoint properties. Templated values are expressed using
square braces around a property name, such as:
axis:http://localhost:8082/MyService?method=[SOAP_METHOD]
<outbound>
<endpoint-template-router address="foobar://server:1234/path/path/path?
param1=[header1]&param2=[header2]"/>
</outbound>
The header1 and header2 parameters are substituted with the actual values from the current message.
The parameters can be used only in the query string, as the square brackets are not valid characters for
the authority and path URI components.
Custom Outbound Router
You can configure custom outbound routers by specifying the custom router class on the <custom-
outbound-router> element and by using Spring properties.
<outbound>
<custom-outbound-router class="org.my.CustomOutboundRouter" transformers-ref="Transformer1">
<spring:properties>
</spring:properties>
</custom-outbound-router>
</outbound>
Asynchronous Reply Routers

Asynchronous reply routers are used in request/response scenarios where message traffic is triggered
by a request and the traffic needs to be consolidated before a response is given. The classic example of
this is where a request is made and tasks are executed in parallel. Each task must finish executing and
the results processed before a response can be sent back. For detailed information on the elements you
configure for asynchronous reply routers, see Asynchronous Reply Router Configuration Reference.
Asynchronous reply routers are configured as follows:

<async-reply failOnTimeout="false" timeout="2000">
</async-reply>
The timeout attribute determines how long to wait for replies to be received. The failOnTimeout
attribute determines if an exception should be thrown or if, in the case of the collection reply router, the
messages received so far should be returned to the service.
Single Asynchronous Reply
The Single Asynchronous Reply router configures a single response router. This router returns the first
message it receives on a reply endpoint and discards the rest.
Collection Asynchronous Reply
The Collection Asynchronous Reply router configures a collection response router. This router returns a
MuleMessageCollection message type that contains all messages received for the current correlation.
Custom Asynchronous Reply
The Custom Asynchronous Reply router allows you to configure a custom asynchronous reply router. To
configure the custom router, set the class attribute to the custom router class.
<custom-async-reply-router class="org.mule.CustomAsyncReplyRouter"/>
Catch-all Strategies
You can configure a catch-all strategy that will be invoked if no routing path can be found for the current
message. An inbound or outbound endpoint can be associated with a catch-all strategy so that any
orphaned messages can be caught and routed to a common location. For detailed information on the
elements you configure for catch-all strategies, see Catch All Strategy Configuration Reference.
For example:
<inbound>
<inbound-endpoint address="vm://in2" connector-ref="vmQueue">
<string-to-byte-array-transformer/>
</inbound-endpoint>

<payload-type-filter expectedType="java.lang.Integer"/>
<custom-forwarding-catch-all-strategy
class="org.mule.test.usecases.routing.InboundTransformingForwardingCatchAllStrategy">
<outbound-endpoint address="vm://catchall" connector-ref="vmQueue">
<string-to-byte-array-transformer/>
</custom-forwarding-catch-all-strategy>
</inbound>
...
<outbound>
<filtering-router transformer-refs="TestCompressionTransformer">
<outbound-endpoint address="test://appleQ2" name="TestApple-Out" />
<payload-type-filter expectedType="java.lang.String" />
</filtering-router>
<custom-catch-all-strategy class="org.mule.tck.testmodels.mule.TestCatchAllStrategy" />
</outbound>
...
</service>
Following are descriptions of the different catch-all strategies you can use.
Forwarding
This catch-all strategy is used to forward the message to an endpoint that is configured if no outbound
routers match.
Custom Forwarding
This catch-all strategy is the same as the default forwarding catch-all strategy, but it allows you to specify
a custom implementation to use by configuring the class attribute. You can also configure additional
optional properties.
<custom-forwarding-catch-all-strategy class="org.my.CustomForwardingCatchAllStrategy">
<spring:property key="myProperty" value="myValue"/>
Logging
This catch-all strategy does nothing with the message and simply logs a warning indicating that the
message was not dispatched because there was no routing path defined.
<logging-catch-all-strategy/>

Custom
This catch-all strategy allows you to use a custom class to perform whatever behavior you require. To
implement a custom catch-all strategy that forwards the message to an endpoint, you should used the
custom forwarding catch-all strategy instead.
<custom-catch-all-strategy/>
Filters
Filters provide the logic used to invoke a particular router. Filters can be combined using the logic filters
AndFilter, OrFilter, and NotFilter. Not all routers need to use filters, but all routers support them. See
Using Filters for complete information.

Component Bindings
Component Bindings
[ Java Component Binding Configuration ] [ Script Component Bindings ]
Components can use bindings to call an external service during execution. The bindings used with a Java
component bind a Java interface, or single interface method, to an outbound endpoint. The external
service to be called should implement the same interface, and the component should encapsulate a
reference to that interface, which is initialized during the bootstrap stage by the Mule configuration
builder. The reference will be initialized using a reflective proxy class.
With component bindings, you can configure multiple interfaces or a single interface with an endpoint
bound to one or more Mule endpoints.
Note that Mule currently supports component bindings for Java components (the default components in
Mule) and script components, such as Groovy or JRuby. This page describes how to configure each.
Java Component Binding Configuration

Bindings can be used by components to call out to an external service. The bound interface is added to
the component as a field with the usual bean getter and setter methods. In the binding configuration for
the component, you can bind this interface along with a method in the interface to a Mule endpoint. When
that method is called, the call parameters are sent over the Mule endpoint to another service, which
may be local or remote. A result may be returned from the service and passed back to the component
using the return argument of the method. This model is very similar to traditional RPC calls. Here is an
example:
public class InvokerComponent

{
private HelloInterface hello;
public String invoke(String s)

{
return "Received: " + hello.sayHello(s, "English");
}
public void setHello(HelloInterface hello)
{
this.hello = hello;
}
public HelloInterface getHello()
{
return hello;
}
}
In this example, the component InvokerComponent has a field hello, which is of type HelloInterface,
with getter and setter methods for the field. The invoke method will be called on the service and calls the
hello.sayHello() method. This call will result in another service call.
The HelloInterface is very simple with a single method sayHello.
public interface HelloInterface

{
public String sayHello(String to, String language);

}
Now, you simply configure your component to bind the sayHello method to the endpoint that will invoke
another service.
<service name="InvokerComponent">
<inbound>
<jms:inbound-endpoint queue="Invoker.in"/>
</inbound>
<component class="org.mule.examples.bindings.InvokerComponent">
<binding interface="org.mule.examples.bindings.HelloInterface" method="sayHello">
<axis:outbound-endpoint use="LITERAL" style="WRAPPED"
address="http://myhost.com:81/services/HelloWeb?method=helloMethod" synchronous="true"/>
</binding>
</component>
<outbound>
<jms:outbound-endpoint queue="Invoker.out"/>
</outbound>
</service>
Note that the call to the external web service is synchronous, because you want a result returned and
need to block until the call is finished.
Handling Data Types
One powerful feature is that you can handle data conversion when making a call and receiving a result
using the normal transformer configuration on the endpoint. In the above example, assume the web
service was expecting an org.mule.examples.bindings.WebHelloRequest object and returned an
org.mule.examples.bindings.WebHelloResponse object. You don't want your component to know about
these external data types, so you can configure transformers to do the conversion when the call is made:
<component class="org.mule.examples.bindings.InvokerComponent">
<binding interface="org.mule.examples.bindings.HelloInterface" method="sayHello">
<axis:outbound-endpoint use="LITERAL" style="WRAPPED"
address="http://myhost.com:81/services/HelloWeb?method=helloMethod" synchronous="true">
<transformers>
<custom-transformer class="org.mule.examples.bindings.StringsToWebRequest"/>
</transformers>
<response-transformers>
<custom-transformer class="org.mule.examples.bindings.WebResponseToString"/>
</response-transformers>
</axis:outbound-endpoint>
</binding>
</component>
Exceptions
If the remote service call triggers an exception of fault, this exception will get serialized back to the local
service call and thrown. If your service wants to handle this exception, you must add the exception (or
java.lang.Exception) to the bound method signature and use a try catch block as usual.

Script Component Bindings
Similar to the Java component bindings, script bindings enable the same behavior for your scripting
components. When using a scripting component, the binding is bound to the scripting context and is
accessible by using the binding interface class name.
<service name="ScriptService">
<inbound>
</inbound>
<script:component>
return "Total: " + AdditionService.add(1,2)
</script:script>
<script:java-interface-binding interface="org.mule.tck.services.AdditionService" method="add">
<vm:outbound-endpoint path="addition.service" synchronous="true"/>
</script:component>
<outbound>
</outbound>
</service>
The implementation for the component is contained within the <script:script> element:
return "Total: " + AdditionService.add(1,2)
We refer to the binding interface using the short class name AdditionService and invoke the add
method, which will call a local addition service.

Using the WireTap Inbound Router
Using the WireTap Inbound Router

The WireTap inbound router allows you to route certain messages to a different endpoint as well as to the
component.
To copy all messages to a specific component, you configure an outbound endpoint on the WireTap
router:
<inbound>
<vm:inbound endpoint path="FromUser"/>
<wire-tap-router>
</wire-tap-router>
</inbound>
In the following scenario, no component is specified, so all data from the inbound VM channel is copied
to the outbound endpoint using implicit bridging. However, let's assume you want to forward some of
the data to another component called WireTapReceiver based on a filter. For the sake of illustration, this
component simply prepends the message with "INTERCEPTED:" before sending it to the FromTapper VM
channel. The code for the WireTapReceiver component is as follows:
public class WireTapReceiver {
public String handleInterceptedData (String aMessage) {

//Just Prepend the message with a label
return "\nINTERCEPTED: "+aMessage;
}
}
Following is the configuration of the Mule services:
<model name="default">
<service name="StdComp">
<inbound>
<vm:inbound-endpoint path="In"/>
<wire-tap-router>
<vm:outbound-endpoint path="ToTapper"/>
</wire-tap-router>
</inbound>
<outbound>
<vm:outbound-endpoint path="ToClient"/>

</outbound>
</service>
<service name="wiretapper">
<inbound>
<vm:inbound-endpoint path="ToTapper"/>
</inbound>
<component class="org.myclass.WireTapReceiver"/>
<outbound>
<vm:outbound-endpoint path="FromTapper"/>
</outbound>
</service>
</model>
Note: Mule uses a separate dispatcher thread for the wiretap endpoint.
Using Filters
The WireTap router is useful both with and without filtering. If filtered, it can be used to record or
take note of particular messages or to copy messages that require additional processing to a different
component. If filters aren't used, you can make a backup copy of all messages received by a component.
The behavior here is similar to that of an interceptor, but interceptors can alter the message flow by
preventing the message from reaching the component. WireTap routers cannot alter message flow but
just copy on demand.
In the previous example, the StdComp service receives messages from the In endpoint, and the router
passes the message to the component and copies it to the vm://ToTapper endpoint. The WireTapper
component listens on this channel and forwards the message, after processing, to the FromTapper
endpoint.
The WireTap router is based on the SelectiveConsumer router, so it can take any filters supported by
SelectiveConsumer. In this example, only messages that match the filter expression are copied to the
vm://ToTapper endpoint.
<wire-tap-router>
<wildcard-filter pattern="the quick brown*"/>
</wire-tap-router>
Multiple WireTapping
You can have multiple WireTap routers for the same service:
<inbound>
<endpoint address="vm://In"/>
<wire-tap-router>
<wildcard-filter pattern="the quick brown*"/>
<vm:outbound-endpoint path="ToTapper"/>
</wire-tap-router>
<wire-tap-router>
<wildcard-filter pattern="the slow green*"/>
<vm:outbound-endpoint path="ToOtherTapper"/>
</wire-tap-router>
</inbound>

In this example, input is passed to the component and also copied to one of two destinations depending
on the filter.
Method Invocation
You can invoke your service with a specific method. For example, if your inbound endpoint is not vm://
In but axis\:http://localhost\:8080/services, or if your component StdComp is a customized
component with a method foo(), you can invoke the web service and its method foo() via the following
endpoint:
http\://localhost\:8080/services/StdComp?method=foo&param=bar
When this message is wire-tapped to the receiving component, Mule might fail with an exception if the
receiving component does not have the method foo(). To avoid this problem and to ensure that the
desired method is invoked, you overwrite the method of the message by specifying ?method=methodName,
or by specifying ?method= so that the onCall() will be called instead. For example:
<wire-tap-router>
<outbound-endpoint addres="vm://inboundEndpoint3?connector=vm2"/>
</wire-tap-router>
...
<service name="serviceComponent3">
<inbound>
<inbound-endpoint address="vm://inboundEndpoint3?connector=vm2&method="
synchronous="false"/>
</inbound>
<component class="org.mule.components.simple.LogComponent"/>
</service>
Additional Features
The WireTap router supports the following additional features:
• Transactions are supported, so the forwarding of messages can either start or join a transaction
provided that the endpoint supports transactions.
• Reply-To can be used to route replies from this endpoint.

XML Configuration
XML Configuration
[ XML Schema ] [ Namespaces ] [ Spring ] [ Property Placeholders ] [ Global Configuration Settings ]
As explained in the overview, the most common way to configure Mule is via Spring XML files that use
custom Mule namespaces.
XML Schema
The configuration files are based on XML schemas, which are specified in the header:

xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:file="http://www.mulesource.org/schema/mule/file/2.1"
mule.xsd
mule-jms.xsd
http://www.mulesource.org/schema/mule/file/2.1 http://www.mulesource.org/schema/mule/file/2.1/
mule-file.xsd">
Be sure to specify all the necessary schema files. This can be time-consuming when setting up the
configuration file, but importing schemas provides the following time-saving benefits:
• Auto-completion and context-specific help in your favorite IDE

• Design-time configuration validation
• Typed properties
Namespaces
Each Mule module or transport has its own XML schema. When you import a schema, it has its own
namespace. For example, the following lines from the above header:
xsi:schemaLocation="http://www.mulesource.org/schema/mule/jms/2.1 http://www.mulesource.org/schema/
mule/jms/2.1/mule-jms.xsd"
will bind the mule-jms.xsd schema to the jms namespace. Therefore, any XML element starting with
<jms: will assume the element comes from the mule-jms.xsd schema.
Default Namespace
Typically, you set the Mule core schema as the default namespace for your configuration file. This means
that any XML element without a prefix will come from the Mule core schema (mule.xsd). To set the
default namespace schema, specify xmlns immediately followed by the URL of the Mule schema, without
the colon and namespace prefix you set in the previous example (e.g., xmlns instead of xmlns:jms):

xsi:schemaLocation="http://www.mulesource.org/schema/mule/core/2.1 http://www.mulesource.org/
schema/mule/core/2.1/mule.xsd">
...config...
</mule>
Spring
Although your configuration files appear to be Mule-specific, they are really just Spring configuration files
with Mule-specific extensions
This approach allows you to use anything Spring offers within your Mule configuration, such as beans,
factory beans, resource loaders, EJBs, JNDI, AOP, even integration with other software such as Hivemind,
jBPM, Gigaspaces, JBoss Rules, etc.
To use the standard Spring elements, you import the standard Spring namespaces:
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/
schema/beans/spring-beans-2.0.xsd"
...
<spring:bean id="myBean" class="com.acme.CoolBean">
<spring:property name="sessionFactory">
<spring:ref local="mySessionFactory" />
</spring:property>
<spring:property name="configuration">
<spring:value>my-config.xml</spring:value>
</spring:property>
</spring:bean>
For complete information on Spring configuration, see the Spring Framework reference documentation.
Property Placeholders
You can use Ant-style property placeholders in your Mule configuration. For example:
<smtp:outbound-endpoint user="${smtp.username}" password="${smtp.password}"/>
The values for these placeholders can be made available in a variety of ways, as described in this section.
Global Properties
You can use the <global-property> element to set a placeholder value from within your Mule
configuration, such as from within another Mule configuration file:
<global-property name="smtp.username" value="JSmith"/>

<global-property name="smtp.password" value="ChangeMe"/>
Properties Files
To load properties from a file, you can use the standard Spring element

<context:property-placeholder>:
xsi:schemaLocation="http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-2.5.xsd"
<context:property-placeholder location="smtp.properties" placeholderPrefix="${"/>
where the contents of smtp.properties is:
smtp.username=JSmith
smtp.password=ChangeMe
The placeholderPrefix value can be anything other than "#[", which is what Mule uses to parse its
message properties in expressions. We recommend you set the value to "${". Note that you do not
have to change anything in your Spring configuration or properties file to match this value; it simply
differentiates Spring properties from Mule properties.
To load multiple properties files, separate them with commas:
<context:property-placeholder location="email.properties,http.properties,system.properties"
placeholderPrefix="${"/>
Message Properties
You can use placeholders to perform logic on message properties such as the header. For example,
if you wanted to evaluate the content-type portion of the message header, you would specify it as
#[header:Content-Type]. Typically, you message property placeholders with expressions. For more
information, see Using Expressions.
System Properties
The placeholder value can come from a JDK system property. If you start Mule from the command line,
you would specify the properties as follows:
mule -M-Dsmtp.username=JSmith -M-Dsmtp.password=ChangeMe -config my-config.xml
or edit the system properties in conf/wrapper.conf.
If you start Mule programmatically, you would specify the properties as follows:
System.getProperties().put("smtp.username", "JSmith");
System.getProperties().put("smtp.password", "ChangeMe");
MuleContext muleContext = new DefaultMuleContextFactory().createMuleContext(new
SpringXmlConfigurationBuilder("my-config.xml"));

Environment Variables
There is no standard way in Java to access environment variables. However, this link has some options
you might find useful.
Global Configuration Settings

You can configure global configuration settings such as the default transaction timeout and default
threading profile in the <configuration> element. For example:
<mule>
...
<configuration defaultTransactionTimeout="31337">
<default-component-threading-profile poolExhaustedAction="RUN"/>
...
</configuration>
For a list of the available global configuration settings, see Global Settings Configuration Reference.

Fiorano Integration
Configuring the JMS Connector for FioranoMQ

2007
FioranoMQ is a High Performance Enterprise Communication Backbone.
<jms:connector name="FioranoJMSConnector"
connectionFactoryJndiName="PrimaryCF"
jndiInitialFactory="fiorano.jms.runtime.naming.FioranoInitialContextFactory"
specification="1.1"
jndiProviderUrl="http://localhost:1856"
username="anonymous"
password="anonymous">


<spring:property key="connectionFactoryProperties">
<spring:map>
<spring:entry key="clientID" value="sampleClientID"/>
<spring:entry key="ConnectURL" value="http://localhost:1856"/>
<spring:entry key="BackupConnectURLs" value="http://localhost:1956"/>
</spring:map>
</spring:property>
</jms:connector>
You will need the following jars on your classpath:
• FioranoMQ2007/fmq/lib/client/all/fmq-client.jar
• FioranoMQ2007/framework/lib/all/fiorano-framework.jar
Sample Usage
The following steps illustrate modifying the "Echo" sample shipped with Mule. Instead of using
System.out in the outbound router, we will write the output onto a Topic in FioranoMQ using the above
configuration.
Modify the outbound router in the echo-config.xml under examples\echo\conf to use a Topic:
<jms:outbound-endpoint topic="muleTopic"/>
Start the durable connection sample available in FioranoMQ from a command prompt in fmq/samples/
PubSub/DurableSubscribers as shown below:
runClient DurableSubscriber -clientid sampleClientID -topicName muleTopic
Now on starting Mule with the above echo-config.xml file we can push messages onto the topic and
consequently to the subscriber.
The durable connection property can also be tested by killing the subscriber, pumping in more messages
and then again starting the subscriber.

Integrating SwiftMQ with Mule
Integrating SwiftMQ with Mule

This page describes how to use SwiftMQ with Mule.
Configuring a Mule JMS Connector

The best approach for integrating SwiftMQ is via JNDI. You will specify the following attributes:
Attribute Description Recommended Value
jndiInitialFactory InitialContext factory com.swiftmq.jndi.InitialContextFactoryImpl
jndiProviderUrl JNDI Provider URL smqp://localhost:4001/

timeout=10000
jndiDestinations JNDI lookup of queues/topics true
forceJndiDestinations Forces a JNDI exception if a true

destination was not found in
JNDI
specification Version of the JMS specification 1.1
connectionFactoryJndiName Name of the JMS connection ConnectionFactory

factory to use
Example:
<jms:connector name="jmsConnector"
connectionFactoryJndiName="ConnectionFactory"
forceJndiDestinations="true"
jndiInitialFactory="com.swiftmq.jndi.InitialContextFactoryImpl"
jndiProviderUrl="smqp://localhost:4001/timeout=10000"
After you have configured the connector, copy swiftmq.jar into the Mule lib/user directory and start
the SwiftMQ Router. You can now use SwiftMQ from Mule.
Configuring the Loan Broker ESB Example with SwiftMQ

The following example shows you how to modify the Loan Broker ESB example to use SwiftMQ. The only
change necessary is to modify the JMS connector in both example configuration files. With a SwiftMQ
Router running on the local host, the connector would look like this:
connectionFactoryJndiName="ConnectionFactory"
jndiInitialFactory="com.swiftmq.jndi.InitialContextFactoryImpl"
jndiProviderUrl="smqp://localhost:4001/timeout=10000"

The Loan Broker ESB example uses the following JMS queues (Mule syntax):
jms://esb.loan.quotes
jms://esb.credit.agency
jms://esb.lender.service
jms://esb.banks
SwiftMQ does not allow dots '.' in queue names. Instead, use underscores '_' in SwiftMQ's
routerconfig.xml:
<swiftlet name="sys$queuemanager">
<queue-controllers>
<queue-controller name="01" persistence-mode="non_persistent" predicate="tmp$%"/>
<queue-controller name="02" predicate="sys$%"/>
<queue-controller name="03" predicate="swiftmq%"/>
<queue-controller name="04" predicate="rt$%"/>
<queue-controller name="05" predicate="unroutable"/>
<queue-controller name="06" predicate="%$%"/>
<queue-controller name="07" predicate="%"/>
</queue-controllers>
<queues>
<queue name="esb_banks"/>
<queue name="esb_credit_agency"/>
<queue name="esb_lender_service"/>
<queue name="esb_loan_quotes"/>
</queues>
</swiftlet>
To match with the Loan Broker ESB example's JMS queue names, define JNDI aliases in SwiftMQ's
routerconfig.xml:
<swiftlet name="sys$jndi">
<aliases>
<alias name="esb.banks" map-to="esb_banks@router1"/>
<alias name="esb.credit.agency" map-to="esb_credit_agency@router1"/>
<alias name="esb.lender.service" map-to="esb_lender_service@router1"/>
<alias name="esb.loan.quotes" map-to="esb_loan_quotes@router1"/>
</aliases>
<jndi-replications/>
<remote-queues/>
</swiftlet>
You now rebuild the Loan Broker ESB example with Ant or Maven so that the configuration changes can
take effect, then start the SwiftMQ Router and the Loan Broker ESB example.
Note that the @ sign can be escaped with %40 in the Mule URI, so for an alternate configuration you can
use the following:
<endpoint name="LoanBrokerRequestsREST" address="jetty:rest://localhost:8080/loanbroker"/>

<vm:endpoint name="LoanBrokerRequests" path="loan.broker.requests"/>
<jms:endpoint name="LoanQuotes" address="jms://esb_loan_quotes%40router1"/>
<jms:endpoint name="CreditAgencyGateway" address="jms://esb_credit_agency%40router1"/>

<ejb:endpoint name="CreditAgency" host="localhost" port="1099" object="local/CreditAgency"
method="getCreditProfile" />

<endpoint name="LenderGateway" address="jms://esb.lender.service" />
<endpoint name="LenderService" address="vm://lender.service" />
<endpoint name="BankingGateway" address="jms://esb.banks%40router1" />
<endpoint name="Bank1" address="axis:http://localhost:10080/mule/TheBank1?method=getLoanQuote"
Keep in mind that a SwiftMQ JNDI alias also decouples a queue from its physical location. You can move
a queue to another router without affecting clients. So it's always best practice to avoid physical queue
names.

Jaas Security
Jaas Security
[ Using the Jaas Configuration File ] [ Passing the Credentials Directly to the Provider ] [ Passing a Non-
default Login Module ] [ Configuring the Security Filter on an Endpoint ]
The JaasSimpleAuthenticationProvider is a security provider that provides a way to interact with the Jaas
Authentication Service.
The security provider for Jaas can be configured in a couple of different ways. It allows you to configure
Jaas either by passing to the provider a Jaas configuration file or by passing the required attributes
directly to the JaasSimpleAuthenticationProvider. These two configuration methods are described
below.
Using the Jaas Configuration File

Usually, JAAS authentication is performed in a pluggable fashion, so applications can remain independent
from underlying authentication technologies.
jaasTest{
org.mule.module.jaas.loginmodule.DefaultLoginModule required
credentials="anon:anon;Marie.Rizzo:dragon;"
};
The above example was saved in a file called jaas.conf. This file contains just one entry called
com.ss.jaasTest, which is where the application we want to protect can be found. The entry specifies
the login module that will be used to authenticate the user. As a login module, you can either use Mule's
DefaultLoginModule, one of the login modules that come with Sun, or else create your own. In this
case, we have opted for Mule's DefaultLoginModule.
The required flag that follows the login module specifies that the login module must succeed for the
authentication to be considered successful. Additional flags are:
Required - The login module is required to succeed. If it succeeds or fails, authentication still continues
to proceed down the login module list.
Requisite - The login module is required to succeed. If it succeeds, authentication continues down the
login module list. If it fails, control immediately returns to the application.
Sufficient - The login module is not required to succeed. If it does succeed, control immediately returns
to the application (authentication does not proceed down the login module list). If it fails, authentication
continues down the login module list.
Optional - The login module is not required to succeed. If it succeeds or fails, authentication still
continues to proceed down the login module list.
The entry also specifies the credentials, in which we put a string of authorized users together with their
passwords. The credentials are put here only when the DefaultLoginModule is going to be used, as the
method in which the user names and passwords are obtained may vary from one login module to another.
The format of the credentials string must adhere to the following format if the DefaultLoginModule is
going to be used:
<username>:<password>;

Configuring the Provider in the Mule Configuration File
xmlns:jaas="http://www.mulesource.org/schema/mule/jaas/2.2"
...cut...
<jaas:security-manager>
<jaas:security-provider name="jaasSecurityProvider" loginContextName="jaasTest"
loginConfig="jaas.conf"/>
</jaas:security-manager>
Note that in the above, the loginContextName contains the same name of the entry as in the Jaas
configuration file. This name will be used for creating the login context as well as to find the complete
URL of the jaas.conf file.
Passing the Credentials Directly to the Provider

The second option for the configuration of the JaasSimpleAuthenticationProvider is to pass the
configuration details that would otherwise be found in the Jaas configuration file directly to the provider.
credentials="anon:anon;Marie.Rizzo:dragon;"/>
In the above configuration, note that we removed the property loginConfig and don't need to pass any
Jaas configuration file. Instead, we simply pass the credentials to the provider (using the same format as
specified above). Since no login module is specified, the DefaultLoginModule is used.
Passing a Non-default Login Module

The third option is to enter your own login module.
loginModule="com.sun.security.auth.module.NTLoginModule"/>
In the above configuration, we have added the loginModule property, which allows you to specify the
login module you want to use to authenticate the user. Since the NTLoginModule does not require you to
input a list of accepted usernames and passwords, the property for the credentials was removed.
Configuring the Security Filter on an Endpoint

You can use JaasSecurityFilter as a security filter, as follows:
<inbound>
<inbound-endpoint address="vm://test">
<jaas:jaas-security-filter/>
</inbound-endpoint>

</inbound>

JavaRebel Integration
JavaRebel Integration
This page is under construction. JavaRebel Integration is not yet supported for Mule 2.x.
JavaRebel is a JVM plugin that reloads Java class files on the fly so that you can recompile and see your
changes to the application without restarting or redeploying it. This page describes how to integrate
JavaRebel with Mule. It assumes you have installed Mule and have an Internet connection available.
Note that JavaRebel reloads custom class files only, such as those in the examples, and not Mule core
classes.
Setup
These instructions use the Hello Example bundled with Mule to demonstrate the setup.
1. Download JavaRebel from http://www.zeroturnaround.com/download/

2. Unpack and copy javarebel.jar to your MULE_HOME/bin directory.
3. Navigate to your MULE_HOME/examples/hello directory and generate the project files for your IDE:
mvn idea:idea for IntelliJ IDEA or mvn eclipse:eclipse for Eclipse.
4. If you are using IDEA, change the module output path to compile into MULE_HOME/lib/user.
5. Delete mule-example-hello.jar from MULE_HOME/lib/user, as it contains the same classes you
will compile.
6. Make/build the project.
7. Set up your run configuration to start Mule with an extra switch to enable JavaRebel:
-config hello-config.xml -M-javaagent:../../bin/javarebel.jar -M-noverify
Note that we reference the configuration file as a resource. It's been put on the classpath in
MULE_HOME/lib/user when you built the project.
8. Type your name when prompted and watch the standard reply.
9. Modify the org.mule.samples.hello.Greeter#greet() method with a new greeting:
public Object greet(NameString person) {

...
person.setGreeting("Greetings ");
...
}
10. Make/build the project, then type your name again when prompted. Notice that the greeting has
changed.
Running in Debug Mode

To run JavaRebel in debug mode, add the -debug switch to the Mule start command and connect your
debugger on port 5005 (default). Be sure to say No when you see the debugger's prompt to reload
classes, as JavaRebel handles this for you. IDEA users will need to get the JavaRebel debugger plugin,
either from the IntelliJ IDEA plugin repository or from http://plugins.intellij.net/plugin/?id=1699.
Otherwise, you will experience problems with the debugger not stopping at breakpoints.

Specifying the JDK
If you have trouble compiling the code in IDEA, make sure the JDK is properly configured for the project.
If you know the name of the JDK as it is listed in IDEA, you can use it during project generation: mvn
idea:idea -DjdkName=1.6

JBoss Jms Integration
JBoss JMS Integration

You configure a JBoss JMS connector for Mule as follows:

<mule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:util="http://www.springframework.org/schema/util"
xmlns="http://www.mulesource.org/schema/mule/core/2.1"
...
beans-2.5.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-
util-2.1.xsd
http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-
jee-2.1.xsd
mule.xsd
mule-jms.xsd
...>
<spring:beans>
<util:properties id="jndiEnv">
<spring:prop key="java.naming.factory.initial">org.jnp.interfaces.NamingContextFactory</spring:prop>
<spring:prop key="java.naming.provider.url">jnp://localhost:1099/</spring:prop>
</util:properties>
<jee:jndi-lookup id="connectionFactory" jndi-name="java:/ConnectionFactory" environment-ref="jndiEnv"/>
</spring:beans>
<jms:connector name="jmsConnector" connectionFactory-ref="connectionFactory"/>
The JNDI provider and JBoss properties are specified in Spring.
If you use user credentials to connect to JBoss MQ, make sure that the user has the 'guest'
role assigned to it. This will ensure that there are no issues if Temporary Topics or Queues
(e.g., in RemoteSync calls) are used.

Module Archetype
Module Archetype
Updating an Existing Module ] [ Command Line Options ]
Mule provides Maven archetypes that you can use as code templates for your Mule modules that you
want to host on MuleForge or include with the Mule distribution. These templates include a set of
implementation notes and "todo" pointers that help you get started quickly. The Mule module archetype
will help you generate a tailored boilerplate module in seconds. For more information on using Maven, see
Using Maven.
Updating Existing Modules and Transports
The Module archetype allows developers to create new Mule modules or upgrade existing Mule modules
adding support for schemas and registry bootstrapping. See Updating an Existing Module for more
information.
Follow the instructions below to create template files for a new Mule module, including all the necessary
Java boilerplate and detailed implementation instructions in comments.
Configuring Maven
<settings>
<pluginGroups>
</pluginGroups>
...
</settings>
Using the Archetype

First, open a command shell and change to the directory where you want to create your module.
> cd yourDir
> mvn mule-module-archetype:create -DartifactId=xxx -DmuleVersion=2.1.2

-DarchetypeArtifactId=mule-module-archetype
At minimum, you pass in these system parameters:
• artifactId: The short name for the project (such as 'myApp'). This must be a single word in lower
case with no spaces, periods, hyphens, etc.
• archetypeArtifactId: Enter mule-module-archetype when running the module archetype.
artifactId

After you have answered all the questions, the archetype creates a directory using the module name you
specified that includes a POM file for building with Maven, a Mule configuration file (src\main\resources
\mule-config.xml) that includes the namespaces for the transports and modules you specified and has
placeholder elements for creating your first service, and a package.html file under src\main\java using
the package path you specified. Lastly, it creates some template files under src\test to help you get
started creating a unit test for the module. A new MULE-README.txt file will be created in the root of your
project explaining what files were created.

The plug-in prompts you to answer several questions about the project you are writing. These may vary
according to the options you select. An example of the output is shown below.
Are you creating a new module (rather than updating an existing one)?
If you are creating an brand new Mule module, chose yes here. The wizard will then ask you what
resources you want to create. If you are updating an existing module, choose no, and see Updating
an Existing Module for more information. The following questions get asked if you are creating a new
module.
Provide a description of what the project does:
You should provide an accurate description of the module with any high-level details of what you can or
cannot do with it. This text will be used where a description of the module is required.
Which version of Mule is this project targeted at?
The version of Mule you want to use for your module. This will default to the archetype version passed in
If the transport is going to be hosted on MuleForge, additional information will be added to your project
for linking to its issue tracker, web site, build server and deployment information.
A comma-separated list of the transports you plan to use in this module (such as HTTP and VM). This will
add the namespaces for those transports to the configuration file.
Which Mule modules to you want to include in this project?
A comma-separated list of the modules you are extending with this module (such as XML and Scripting).
This will add the namespaces for those modules to the configuration file.
All new transports targeted for Mule 2.x should define an XML schema that defines how the transport
is configured. If you do not use this option, users will have to use generic configuration to use your
transport.

Will this module make objects available in the Registry as soon as it's loaded?
The registry bootstrap is a properties file that specifies class names of simple objects that can be made
available in the Mule Registry as soon as the module is loaded. This is useful for registering custom
transformers or expression evaluators.

********************************************************************************
Are you creating a new module (rather than updating an existing one)? [y] or [n]
[default: y]
********************************************************************************
y
[INFO] description:
********************************************************************************
Provide a description of what the module does:

[default: ]
********************************************************************************
foo Bar
[INFO] muleVersion:
********************************************************************************
Which version of Mule is this module targeted at?

[default: 2.1.2]
********************************************************************************
********************************************************************************
Will this module be hosted on MuleForge? [y] or [n]

[default: y]
********************************************************************************
[INFO] transports:
********************************************************************************
Which Mule transports do you want to include in this module?
(options: axis, cxf, ejb, file, ftp, http, https, imap, imaps, jbpm, jdbc,
jetty, jetty-ssl, jms, jnp, multicast, pop3, pop3s, quartz, rmi, servlet,
smtp, smtps, servlet, ssl, tls, stdio, tcp, udp, vm, xmpp):
[default: vm]
********************************************************************************
[INFO] modules:
********************************************************************************
Which Mule modules do you want to include in this module?
(options: bulders, client, jaas, jbossts, management, ognl, pgp, scripting,

spring-extras, sxc, xml):
[default: client]
********************************************************************************
[INFO] hasCustomSchema:
********************************************************************************
Will this module have a custom schema for configuring the module in Xml? [y] or [n]
[default: y]
********************************************************************************
[INFO] hasBootstrap:

********************************************************************************
Will this module make objects available in the Registry as soon as it's loaded? [y] or [n]
[default: n]
********************************************************************************
Updating an Existing Module

The module archetype can be used for updating existing modules and transports. It allows developers to
add template code for schema configurations and boostrap the registry. It will leave your existing code
untouched.
For example, if your existing Module or transport is located under /projects/foo, you update the project
by running the following commands:
cd /project/foo
mvn mule-module-archetype:create -DartifactId=foo -DmuleVersion=2.1.2 -DarchetypeArtifactId=mule-
module-archetype
Notice that the artifactId must be set to the name of your project. This ensures that any new classes
will be created with the same naming scheme.
When you run this command, you will be prompted with three questions. The first question will ask you
whether this is a new project. Make sure you select 'n' so that the wizard will upgrade your existing
module or transport. It then asks you the last two questions about the custom schema and registry
bootstrap. After you answer the questions, the code will be created and a new MULE-UPDATE-README.txt
file will be created in the root of your project explaining what files were created.

following option:
-Dinteractive=false
groupId - org.mule.application.<artifactId>
DgroupId=org.mule.applicationxxx

application

package -Dpackage=org/mule/ none

application/myPkg
artifactId -DartifactId=myMuleProject mule-application-<artifactId>

OpenJms Integration
OpenJMS Integration
The following example configuration describes how to configure a Mule JMS connector for OpenJMS.
You will probably need to change the connectionFactoryJndiName to one that is configured from your
OpenJMS configuration.
jndiInitialFactory="org.exolab.jms.jndi.InitialContextFactory"
jndiProviderUrl="tcp://localhost:3035"
connectionFactoryJndiName="QueueConnectionFactory"/>

PGP Security
PGP Security
[ Requirements ] [ Configuring the PGP Filter ] [ Configuration Reference ]
This extension adds PGP security on endpoint communication. With PGP you can achieve end-to-end
security communication with signed and encrypted messages between parties.
Requirements
Libraries
You must add these libraries to your Mule classpath:
• Cryptix OpenPGP
• Cryptix JCE
Policy Files
If you are running JDK 1.4+ that comes with the Sun JCE by default, you must install the Unlimited
Strength Jurisdiction Policy files, which can be downloaded from the following URL (note that they are
listed entirely at the bottom of the page, in the Other Downloads section):
JDK 1.4
JDK 5
JDK 6
These files must be installed in $JAVA_HOME$/jre/lib/security
According to Sun, the default distribution of the JCE allows "strong, but limited strength cryptography."
This means that you cannot use RSA keys bigger than 2048 bits and no symmetric ciphers that use more
than 128 bits. ElGamal is not allowed at all, thus DH/DSS cannot be used for encryption.
Useful PGP Links
How PGP works (intro documentation)

GnuPG (freeware implementation)
enigmail (extension for Thunderbird)
Configuring the PGP Filter

Using a Spring context, you define a manager for accessing public and private keys.
xmlns:pgp="http://www.mulesource.org/schema/mule/pgp/2.2"
...cut...
<spring:bean id="pgpKeyManager" class="org.mule.module.pgp.PGPKeyRingImpl" init-method="initialise">

<spring:property name="publicKeyRingFileName" value="serverPublic.gpg"/>
<spring:property name="secretKeyRingFileName" value="serverPrivate.gpg"/>
<spring:property name="secretAliasId" value="0x6168F39C"/>
<spring:property name="secretPassphrase" value="TestingPassphrase"/>
</spring:bean>

<spring:bean id="fakeCredentialAccessor" class="org.mule.module.pgp.FakeCredentialAccessor"/>
You must also specify a class that identifies the sender of a message. For this example, we simply fake
the sender using the FakeCredentialAccessor (available in the test classes of mule-module-pgp), which
returns a fixed user name.
PGP stores keys in files called keyrings

There is a public keyring storing public keys of your trusted parties and a private keyring
storing your secret key. In a keyring, keys are referenced by an alias ID (also named key
Id). Your secret keyring is encrypted on your disk using a passphrase.
In this example, we define a sample echo application that reads signed (and encrypted) files from
a directory (/temp/signedAndEncryptedFiles/in) and write the decrypted content into /temp/
decryptedFiles/out. The configuration looks like this:
<pgp:security-manager>
<pgp:security-provider name="pgpSecurityProvider" keyManager-ref="pgpKeyManager"/>
<pgp:keybased-encryption-strategy name="keyBasedEncryptionStrategy" keyManager-
ref="pgpKeyManager"/>
</pgp:security-manager>
<model name="test">
<service name="echo">
<inbound>
<inbound-endpoint address="file:///temp/signedAndEncryptedFiles/in">
<pgp:security-filter strategyName="keyBasedEncryptionStrategy" signRequired="true"
credentialsAccessor-ref="fakeCredentialAccessor"
keyManager-ref="pgpKeyManager"/>
</inbound-endpoint>
</inbound>
<component class="org.mule.module.pgp.EchoMsg"/>
<outbound>
<outbound-endpoint address="file:///temp/decryptedFiles/out">
<pgp:security-filter strategyName="keyBasedEncryptionStrategy"
credentialsAccessor-ref="fakeCredentialAccessor"
keyManager-ref="pgpKeyManager"/>
</outbound>
</service>
</model>
</mule>
The property signRequired in the inbound security filter controls whether to accept unsigned messages.
Security Manager
security-provider 0..1 Security provider for PGP-

related functionality.

keybased-encryption-strategy 0..1 The key-based PGP encryption
strategy to use.
Security Provider
Security provider for PGP-related functionality.
Attributes of <security-provider...>
keyManager-ref name (no spaces) no Reference to the

key manager to
use.
Keybased Encryption Strategy

The key-based PGP encryption strategy to use.
Attributes of <keybased-encryption-strategy...>

key manager to
use.
credentialsAccessor- name (no spaces) no Reference to

ref the credentials
accessor to use.
Security Filter
Filters messages based on PGP encryption.
Attributes of <security-filter...>
strategyName string no The name of the

PGP encryption
strategy to use.
signRequired string no Whether signing is

required.

key manager to
use.
credentialsAccessor- name (no spaces) no Reference to

ref the credentials
accessor to use.

Project Archetype
Project Archetype
The Mule project archetype will help you generate a tailored boilerplate project in seconds. For more
information on using Maven, see Using Maven.
Follow the instructions below to create template files for a new project, including all the necessary Java
boilerplate and detailed implementation instructions.
Configuring Maven
<settings>
<pluginGroups>
</pluginGroups>
...
</settings>
Using the Archetype

First, open a command shell and change to the directory where you want to create your project.
> cd yourDir
> mvn mule-project-archetype:create -DartifactId=xxx -DmuleVersion=2.1.2
• artifactId: The short name for the project (such as 'myApp'). This must be a single word in lower
case with no spaces, periods, hyphens, etc.
artifactId

After you have answered all the questions, the archetype creates a directory using the project name you
specified that includes a POM file for building with Maven, a Mule configuration file (src\main\resources
\mule-config.xml) that includes the namespaces for the transports and modules you specified and has
placeholder elements for creating your first service, and a package.html file under src\main\java using
the package path you specified. Lastly, it creates some template files under src\test to help you get
started creating a unit test for the project. A new MULE-README.txt file will be created in the root of your
project explaining what files were created.

The plug-in prompts you to answer several questions about the project you are writing. These may vary
according to the options you select. An example of the output is shown below.
You should provide an accurate description of the project with any high-level details of what you can or
cannot do with it. This text will be used where a description of the project is required.
Which version of Mule is this project targeted at?
The version of Mule you want to use for your project. This will default to the archetype version passed in
What is the base Java package path for this project?
This should be a Java package path for you project, such as com/mycompany/project. Note that you must
use slashes for separators, not periods.
A comma-separated list of the transports you plan to use in this project (such as HTTP and VM). This will
add the namespaces for those transports to the configuration file.
Which Mule modules to you want to include in this project?
A comma-separated list of the modules you plan to use in this project (such as XML and Scripting). This
will add the namespaces for those modules to the configuration file.

[INFO] description:
********************************************************************************
[default:]
********************************************************************************
[INFO] muleVersion:
********************************************************************************
Which version of Mule is this module targeted at?
[default: 2.1.2]
********************************************************************************
[INFO] package:
********************************************************************************
What is the base Java package path for this project? (i.e. com/mycompany/project):

[default:]
********************************************************************************
[INFO] transports:
********************************************************************************
[default: cxf,file,http,jdbc,jms,stdio,vm]
********************************************************************************
[INFO] modules:
********************************************************************************
[default: client,management,scripting,sxc,xml]
********************************************************************************

following option:
-Dinteractive=false
groupId - org.mule.application.<artifactId>
DgroupId=org.mule.applicationxxx

application

package -Dpackage=org/mule/ none
application/myPkg
artifactId -DartifactId=myMuleProject <artifactId>

SeeBeyond JMS Server Integration
SeeBeyond JMS Server Integration

The following configuration is for the SeeBeyond ICAN IQManager JMS Server. Note the values in [ ]
(square brackets), which should be replaced by values relevant to your installation. Port 18006 is the
default, which you can change in the SeeBeyond designer.
jndiInitialFactory="com.stc.is.naming.NamingContextFactory"
jndiProviderUrl="[ServerName]:18006"
connectionFactoryJndiName="/jms/connectionfactory/queue/[LogicalHostName]_[JMS iqManager
Name]"/>
</jms:connector>
For a topic, the connectionFactoryJndiName would be /jms/connectionfactory/topic/

[LogicalHostName]_[JMS iqManager Name].
You will need the following files from the Java API Kit on your classpath:
• com.stc.jmsis.jar
• fscontext.jar
• providerutil.jar
• jms.jar
• jta.jar
• log4j.jar
• log4j.properties

SonicMQ Integration
SonicMQ Integration
The following configuration was tested with versions 6.1 and 7.0 of SonicMQ.
<jms:connector name="jmsSonicMQConnector"
jndiInitialFactory="com.sonicsw.jndi.mfcontext.MFContextFactory"
specification="1.1"
connectionFactoryJndiName="sonic-cf"
jndiProviderUrl="tcp://localhost:2506"
username="Administrator"
password="Administrator">
<spring:property key="connectionFactoryProperties">
<spring:map>
<spring:entry key="clientID" value="clientIDString"/>
<spring:entry key="connectID" value="connectIDString"/>
<spring:entry key="connectionURLs" value="somURLStrings here"/>
<spring:entry key="defaultUser" value="userString"/>
<spring:entry key="defaultPassword" value="passwordString"/>
<spring:entry key="prefetchCount" value="10"/>
<spring:entry key="prefetchThreshold" value="10"/>
<spring:entry key="faultTolerant" value="true"/>
<spring:entry key="persistentDelivery" value="true"/>
<spring:entry key="loadBalancing" value="true"/>
<spring:entry key="sequential" value="false"/>
</spring:map>
</spring:property>
<spring:property key="jndiProviderProperties">
<spring:map>
<spring:entry key="com.sonicsw.jndi.mfcontext.domain" value="Domain1"/>
<spring:entry key="java.naming.security.principal" value="Administrator"/>
<spring:entry key="java.naming.security.credentials" value="Administrator"/>

<spring:entry key="com.sonicsw.jndi.mfcontext.idleTimeout" value="5000"/>
</spring:map>
</spring:property>
</jms:connector>

Streaming
Streaming
[ Advantages of Streaming ] [ Streaming Filters and Transformers ] [ Configuring Stream Flows ] [
Writing Streaming Components, Routers, and Filters ]
This page is under construction
Several of Mule's transports support streaming, which enables efficient processing of large data objects
such as files, documents, and records by streaming the data through Mule rather than reading the whole
thing into memory. The following transports support streaming:
• CXF
• File
• HTTP/S
• Jetty/Jetty SSL
• Servlet
• SOAP
• STDIO
• TCP
• UDP
• VM
Advantages of Streaming
Streaming provides the following advantages:
• Allows services to consume very large messages in an efficient way

• Message payloads are not read into memory
• Simple routing rules based on message metadata are still possible
• You can combine streaming and non-streaming endpoints
Streaming Filters and Transformers

The following filters support streaming
TODO: document which filters and transformers support streaming
Configuring Stream Flows

TODO: document how to configure stream flows
Writing Streaming Components, Routers, and Filters

TODO: document how to write streaming components/routers/filters

Sun JMS Grid Integration
Sun JMS Grid Integration

The following configuration demonstrates how to configure Mule to use the Sun JMS Grid server.
<jms:connector name="jmsConnector" specification="1.1"

connectionFactoryJndiName="QueueConnectionFactory"
jndiInitialFactory="com.spirit.directory.SpiritVMDirectoryContextFactory"
<spring:property name="jndiProviderProperties">
<spring:map>
<spring:entry key="driverName" value="WMSEmbedded"/>
</spring:map>
</spring:property>
</jms:connector>

Tibco EMS Integration
TIBCO EMS Integration

This page demonstrates how to configure Mule to use the TIBCO Enterprise Message Server (EMS) with
authentication in place.
jndiProviderUrl="tibjmsnaming://host:port"
connectionFactoryJndiName="QueueConnectionFactory"
username="username"
password="password"
jndiInitialFactory="com.tibco.tibjms.naming.TibjmsInitialContextFactory"
specification="1.1">
<spring:property name="jndiProviderProperties">
<spring:map>
<spring:entry key="java.naming.security.principal" value="jndiUsername"/>
<spring:entry key="java.naming.security.credentials" value="jndiPassword"/>
</spring:map>
</spring:property>
</jms:connector>
Note that when you use tibjmsnaming as the protocol in your jndiProviderUrl, you can also specify
TCP or SSL with the JNDI property com.tibco.tibjms.naming.security_protocol.
For XA transactions, you must create an XA Connection Factory from the TIBCO administration-tool
(tibemsadmin) as follows:
> create factory XAQueueConnectionFactory xaqueue url=tcp://7222

Using Expressions
This page last changed on Jan 23, 2009 by andrew.
Using Expressions
[ Using Expressions with Transformers ] [ Using Expression Filters ] [ Using Expression Routers ]
Expressions allow you to extract information from the current message or determine how to handle the
message. Expressions are very useful with routers and filters for defining routing logic and for filtering
out unwanted messages.
Mule provides several default expression evaluators, allowing you to embed expression logic in a variety
of expression languages, or you can create your own evaluators to support additional languages.
This page describes how to use expressions. For more details on how to configure expressions, see
Expressions Configuration Reference.
Using Expressions with Transformers

This section describes the transformers that support expressions. For more information on transformers,
see Using Transformers.
Expression Transformer
The expression transformer executes one or more expressions on the current message where the result
of the expression(s) will become the payload of the current message.
For example, imagine you have a service component with a message signature that accepts three
arguments:
public class ShippingService

{
public ShippingConfirmation makeShippingRequest(Customer customer, Item[] items, DataHandler
supportingDocumentation)
{
//do stuff
}
}
And the message being passed to you component looks like this:
public interface ShippingRequestMessage

{
public Customer getCustomer();
public Item[] getShippingItems();
//etc
}
The <expression-transformer> can be used to extract the fields from the ShippingRequestMessage
to invoke the ShippingService. Note that we can only get two of the arguments from the
ShippingRequestMessage: Customer and Item[]. The supporting documentation, which could be
something like a Microsoft Word or Excel document, is an attachment to the ShippingRequestMessage.
Attachments can be associated with any message within Mule.
<expression-transformer>

<return-argument evaluator="bean" expression="customer"/>
<return-argument evaluator="bean" expression="shippingItems"/>
<return-argument evaluator="attachment" expression="supportingDocs" required="false"/>
</expression-transformer>
Here we execute three separate expressions to obtain the three arguments required to invoke the
ShippingService.makeShippingRequest() method. The first two expressions use the bean evaluator
to extract objects from the message. The last argument uses the attachment evaluator to obtain a
single attachment. Note that supportDocuments can be null, so we set required="false" on the return
argument.
Message Properties Transformer
The <message-properties-transformer> allows you to add, remove, or rename properties dynamically

or statically on the current message. For example:
<message-properties-transformer>
<add-property name="GUID" value="#[xpath:/msg/header/ID]-#[xpath:/msg/body/@ref]"/>
</message-properties-transformer>
The above expressions extract the <ID> element value and the ref attribute on the <body> element,
setting the result as a message property named GUID.
XSLT Transformer
The XSLT transformer processes the XML payload of the message through XSLT. Using expressions, you
can inject information about the current message into the XSLT as a parameter. For example:
<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]"/>
When executed, the headers ListTitle and ListRating from the current message are added to the
XSLT context as parameters called title and rating, respectively. You can reference these parameters
inside the XSLT using the <xsl:param> element:
Using Expression Filters

Expression filters can be used in content-based routing to assert statements on the current message and
route the message accordingly. Expression filters work in the same way as other types of Mule filters and
have the same expression attributes as listed above. The expression on the filter must evaluate to true or
false. For example:
<expression-filter evaluator="header" expression="my-header!=null"/>
As usual, you can use AND, OR, and NOT filters to combine expressions.

<and-filter>
<expression-filter evaluator="header" expression="origin-country=USA"/>
<expression-filter evaluator="groovy" expression="payload.purchase.amount > 10000"/>
</and-filter>
Note that expression filters support a sub-set of all expression evaluators, because filters should only
evaluate against the current message. For example, there is no point in using a function expression on
a filter. The supported expression evaluators are: bean, custom, exception-type, groovy, header, jxpath,
ognl, payload-type, regex, wildcard, and xpath. For more information on expression evaluators, see
Expressions Configuration Reference.
Using Expression Routers

Expression routers use expressions to determine where to route a message. Usually, outbound routers
will support expressions. This section describes each of the Mule routers that support expressions. For
more information on routers, see Using Message Routers.
Expression Recipient List Router
The <expression-recipient-list> router will evaluate an expression on the current message to obtain
a list of one or more recipients to send the current message. Following is an example of an XML message:
<message>
<header>
<routing-slip>
<recipient>http://mycompany.com/service1</recipient>
<recipient>http://mycompany.com/service2</recipient>
</routing-slip>
</header>
<body>
...
<body>
</message>
The following router configuration extracts recipients from this message. This type of routing is commonly
referred to as content-based routing.
<outbound>
<expression-recipient-list-router evaluator="xpath" expression="/message/header/routing-slip/recipient" />
</outbound>
Best Practice
This example uses physical addresses for endpoints in the message. In a real production
scenario, you would use logical endpoint names that map to physical endpoint addresses.
These can be configured in your Mule configuration file or in the Mule Galaxy centralized
registry.

Expression Message Splitter Router
The <expression-message-splitter> router can be used to route different parts of the current message
to different destinations. Let's say our current message is a FruitBowl that contains different fruit that
should be delivered to different places.
FruitBowl fruitBowl = new FruitBowl();

fruitBowl.addFruit(new Orange());
fruitBowl.addFruit(new Apple());
fruitBowl.addFruit(new Banana());
fruitBowl.addFruit(new Banana());
Now we have a FruitBowl containing an apple, an orange, and two bananas. When Mule receives
this object, we want to route the fruit to different locations: the AppleService, BananaService, and
OrangeService.
<service name="Distributor">
<inbound>
<jms:inbound-endpoint queue="distributor.queue"/>
</inbound>
<outbound>

<expression-splitter-router evaluator="bean" expression="fruit">
<vm:outbound-endpoint path="apple.service.queue">
<payload-type-filter expectedType="org.mule.tck.testmodels.fruit.Apple"/>
<vm:outbound-endpoint path="banana.service.queue">
<payload-type-filter expectedType="org.mule.tck.testmodels.fruit.Banana"/>
<vm:outbound-endpoint path="orange.service.queue">
<payload-type-filter expectedType="org.mule.tck.testmodels.fruit.Orange"/>
</expression-splitter-router>
</outbound>
</service>
Notice that each of our outbound endpoints has a filter defined. This allows the splitter router to validate
that the right object is routed to the right service. In this example, the AppleService and OrangeService
will receive one request (fruit object) each and the BananaService will receive two. If the filters were
not defined, the splitter router would send each object to the next endpoint in the list in a round robin
fashion.

Creating Expression Evaluators
Creating Expression Evaluators

In addition to the standard expression evaluators provided with Mule, you can create your own
evaluators. This page describes how to create a custom evaluator, as well as how to add expression
support to a custom module.
Creating the Custom Evaluator

To create a custom evaluator, the first step is to implement the ExpressionEvaluator interface. This is a
simple strategy interface:
public interface ExpressionEvaluator extends NamedObject

{
Object evaluate(String expression, Object message);
}
Note that this interface implements NamedObject, which allows the evaluator to be named. This name
maps to the evaluator part of an expression.
The arguments on the evaluate method are self-explanatory. The expression argument is the
expression to evaluate on the current message being passed in. The message is of type Object rather
than MuleMessage. This means your expression evaluator will explicitly check the message type.
The API may change in Mule 2.2 to accept a MessageAdapter instead, making things a little
easier. See MULE-3842@JIRA.
Lets take the header expression evaluator as a concrete example. This evaluator will only produce a
result if a MuleMessage object is passed in. It will assume that the expression will contain a name of a
header to return.
public class MessageHeaderExpressionEvaluator implements ExpressionEvaluator

{
public static final String NAME = "header";
public Object evaluate(String expression, Object message)

{
Object result = null;
if (message instanceof MessageAdapter)
{
result = ((MessageAdapter) message).getProperty(expression);
}
return result;
}
public String getName()

{
return NAME;
}
public void setName(String name)

{
throw new UnsupportedOperationException("setName");
}

}
Here, we cast the message received to a MessageAdapter and look up the message header. Note
that the name of the expression evaluator is fixed as "header" so the setName method throws an
UnsupportedOperationException.
Registering the Custom Evaluator

After creating your custom expression evaluator, you must register it with Mule. There are two ways of
doing this, depending on how you are configuring your Mule instance.
Configuring the Evaluator as a Bean
If you are using XML configuration, you can just configure your expression evaluator as a bean, and Mule
will discover it.
<spring:beans>
<spring:bean class="org.mule.expressions.MessageHeaderExpressionEvaluator"/>
</spring:beans>
Bootstrapping the Evaluator
If you want your expression evaluator to be loaded automatically by Mule when your module (JAR) is on
the class path, you need to add a registry-bootstrap.properties file to your JAR under the following
directory:
/META-INF/services/org/mule/config
The contents of the registry-bootstrap.properties should look something like this:
object.1=org.mule.util.expression.MessageHeaderExpressionEvaluator
When Mule starts, it will discover this bootstrap file before loading any configuration and will install any
objects listed in the file into the local registry. For more information, see Bootstrapping the Registry.
Using the Custom Evaluator

To use the custom evaluator, you use the customEvaluator attribute as follows:
<expression-transformer>
<return-argument evaluator="custom" customEvaluator="myEval" expression="foo"/>
</expression-transformer>
When embedding the expression, you can use normal syntax:

#[myEval:foo]
Adding Expression Support to Custom Modules

The ExpressionEvaluatorManager is responsible for maintaining a list of supported Expression
Evaluators and resolving expressions at run-time. If you are adding support for expressions in your
custom Mule extensions, you will need access to this object. This is currently a static class so all methods
can be called statically, for example:
Object result = ExpressionEvaluatorManager.evaluate("#[xpath://foo/bar]", muleMessage);
For more information, see the Javadoc for ExpressionEvaluatorManager .
In Mule 2.2, the ExpressionEvaluatorManager will be available from the MuleContext

using muleContext.getExptessionManager(). For more information follow issue
MULE-3801@JIRA.

Expressions Configuration Reference
Expressions Configuration Reference

[ Expression Attributes ] [ Syntax ] [ Spring Property Placeholders and Expressions ] [ Expression
Evaluator Reference ]
This page provides reference information for configuring expressions.
Expression Attributes
The XML configuration elements in Mule that support expressions have three common attributes that
define the expression to execute, the evaluator to use, and the option of defining a custom evaluator.
expression The expression to evaluate. The syntax of this

attribute will change depending on the evaluator
being used.
evaluator The expression evaluator to use. Expression

evaluators must be registered with the
ExpressionEvaluatorManager before they can be
used. Using the custom evaluator allows you to
define your custom evaluator via the custom-
evaluator attribute. Note that some evaluators
such as Xpath, Groovy, and Bean are loaded
from other Mule modules (XML and Scripting,
respectively). These modules must be on your
classpath before their evaluators can be used.
custom-evaluator The name of a custom evaluator to use. This

evaluator must be registered in the local registry
before it can be used.
Expressions can be used in a number of other scenarios such as filters, routing, and endpoints.
Syntax
There are two ways of specifying expressions depending on where the expression is being used. Typically,
expression-based elements such as the expression transformer, expression filter, and expression-based
routers such as the expression message splitter, will have specific attributes for expression, evaluator,
and custom-evaluator. For example:
<expression-filter evaluator="header" expression="my-header!=null"/>
For these elements, only a single expression can be set for the element.
When defining expressions for things like property values, multiple expressions can be defined using the
following syntax:

#[<evaluator>:<expression>]
The syntax here requires that an expression is preceded with #[, then the evaluator is defined, followed
by a colon (:) and the expression to execute. Finally, the expression is terminated with a ]. Multiple
expressions can be defined as a string. For example:
<message-properties-transformer>
<add-property name="GUID" value="#[xpath:/msg/header/ID]-#[xpath:/msg/body/@ref]"/>
</message-properties-transformer>
Syntax Change between Mule 2.0 and Mule 2.1
In Mule 2.0 the syntax for expressions used a dollar sign and curly braces i.e. ${xpath://
foo/bar}. This has been replaced in Mule 2.1 with the syntax described above, #[xpath://
foo/bar]. This change was made so that Mule expressions would not conflict with Spring
Property placeholders that use the ${...} syntax.
Spring Property Placeholders and Expressions

Spring and Mule have had long-time support for property placeholders that allow developers to inject
static properties into their configuration when their application starts up. The property values are defined
in Java property files that are passed into the framework on start up. The following example shows a
properties file that defines configuration information used by a Mule endpoint:
web.proxy.host=192.168.2.2
web.proxy.port=8081
The Mule configuration file can embed these properties as placeholders.
<mule ...>
<http:connector name="HttpConnector" proxyHostname="${web.proxy.host}"
proxyPort="${web.proxy.port}"/>
</mule>
These property placeholders are resolved during the start-up phase of your application. Mule expressions
are evaluated continuously for every message received or sent.
Expression Evaluator Reference

Following are the default expression evaluators that are loaded at runtime. Not all expression evaluators
are supported by every type of expression-based object. For example, the attachment evaluator is
available to routers but not filters.
Name Example Comments
attachment #[attachment:supporting-docs] Not supported by expression

filters.

attachments #[attachments:attach1,attach2] Returns a java.util.Map of
attachments. Not supported by
expression filters.
attachments-list #[attachments- Returns a java.util.List

list:attach1,attach2] of attachments objects. Not
supported by expression filters.
bean #[bean:fruit.isWashed] The bean property expression.

Use "." or "/" as element
delimiter.
endpoint #[endpoint:myEP.address] Use endpointName.property,

e.g.,
endpoint:endpointName.address.
endpoint:endpointName.foobar.
Not supported by expression
filters.
exception-type #[exception- Matches an exception type. Only

type:java.lang.RuntimeException] supported by expression filters.
function #[function:dateStamp(dd-MM- Performs a function: now, date,

yyyy)] datestamp, systime, uuid,
hostname, ip, or count. Not
groovy #[groovy:payload.fruit.washed] Evaluates the expression using

the Groovy language.
header #[header:Content-Type] Evaluates the specified part of

the message header.
headers #[headers:Content- Returns a jaa.util.Map of

Type,Content-Length] headers. Not supported by
expression filters.
headers-list #[headers-list:Content- Returns a java.util.List of

Type,Content-Length] header values. Not supported by
expression filters.
jxpath #[jxpath:/fruit] JXPath expression that works on

both XML/DOM and Beans.
map-payload #[map-payload:key] Returns a value from within a

java.util.Map payload. Not
message #[message.correlationId] Available expressions

are id, correlationId,
correlationSequence,
correlationGroupSize, replyTo,
payload, encoding, exception.
Not supported by expression
filters.
mule #[mule:serverId] Available expressions are

serviceName, modelName,
inboundEndpoint, serverId,
clusterId, domainId, workingDir,
homeDir. Not supported by
expression filters.

ognl #[ognl:[MULE:0].equals(42)] or Set the evaluator attribute
on the <expression-filter>
element to ognl when specifying
an OGNL filter.
payload #[payload:com.foo.RequiredType] If expression is provided, it will

be a class to be class loaded.
The class will be the desired
return type of the payload.
See getPayload(Class) in
MuleMessage . Not supported by
expression filters.
payload-type #[payload:java.lang.String] Matches the type of the payload.

Only supported by expression
filters.
regex #[regex:the quick brown (.*)] Only supported by expression

filters.
wildcard #[wildcard:*.txt] Only supported by expression

filters.
xpath #[xpath://fruit] The expression is an XPath

expression.
Currently there is no way to configure namespaces for XML expressions. In Mule 2.2 it will
be possible to define global namespaces that will be accessible to all XML expressions. For
more information please follow (and vote) on this issue MULE-3303@JIRA.

WebLogic JMS Integration
WebLogic JMS Integration

Before using Mule with WebLogic, copy the weblogic.jar file to $MULE_HOME/lib/user.
JNDI destinations syntax

If Mule fails to look up topics or queues in WebLogic's JNDI, but the JNDI tree lists them
as available, try replacing JNDI subcontext delimiters with dots, so tracker/topic/
PriceUpdates becomes tracker.topic.PriceUpdates.
WebLogic 8.x and Earlier
jndiProviderUrl="t3://localhost:7001"
connectionFactoryJndiName="javax.jms.QueueConnectionFactory"
jndiInitialFactory="weblogic.jndi.WLInitialContextFactory"
specification="1.0.2b"/>
WebLogic 9.x
For WebLogic 9.x, the configuration is almost the same. The only differences are:
• Supported JMS specification level is 1.1 (1.0.2b should still work, however)
• The unified JMS connection factory can be used as a result of the above. The following example
demonstrates using the default factories available out of the box.
jndiProviderUrl="t3://localhost:7001"
connectionFactoryJndiName="weblogic.jms.ConnectionFactory"
jndiInitialFactory="weblogic.jndi.WLInitialContextFactory"

WebSphere MQ Integration
WebSphere MQ Integration
If you are using WebSphere MQ, there are two transports you can use:
• The Mule WMQ Transport provides support for native MQ. This transport is available only with Mule
Enterprise 1.6 or later.
• The JMS Transport includes a WebSphere connector that does not provide support for native MQ
but provides more functionality than the Mule WMQ connector and is available with the community
edition of Mule. The rest of this page describes the WebSphere connector in the JMS transport.
To configure the WebSphere MQ JMS connector for Mule, you do the following:
1. Set up a connection factory in the WAS admin console

2. Configure the <websphere-connector> in your Mule configuration file to use the connection factory.
Setting Up the Connection Factory

1. In the WAS Admin Console, go to Resources > WebSphere MQ JMS Provider > WebSphere MQ
Queue Connection Factories.
2. Set the following properties:
• Name: Connection Factory

• JNDI Name: jms/ConnectionFactory
• Queue Manager: (Your QMGR Here)
• Host, Port, etc.
Configuring Mule
In your Mule configuration file, add the following connector configuration:
connectionFactoryJndiName="jms/ConnectionFactory"
jndiInitialFactory="com.ibm.websphere.naming.WsnInitialContextFactory"
specification="1.1">
<spring:property name="connectionFactoryProperties">
<spring:map>
<spring:entry key="hostName" value="myMQServer"/>
<spring:entry key="transportType" value="1"/>
<spring:entry key="name" value="myMQConnector"/>
</spring:map>
</spring:property>
</jms:connector>
The hostName property is mandatory and refers to a name that will be used for this connection. This is
different from the host property, which refers to an IP address or network name of the server hosting
WebSphere MQ. In addition to the name attribute for the connector, you must also set a name property for
WebSphere.
If you're using IBM's connection factory, you may additionally need the following configuration - the
connection factory is configured in Spring here:
connectionFactoryJndiName="jms/ConnectionFactory"

jndiInitialFactory="com.ibm.websphere.naming.WsnInitialContextFactory"
specification="1.1"
connectionFactory-ref="MQConnectionFactory"/>
<spring:beans>
<spring:bean name="MQConnectionFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">
<spring:property name="hostName" value="MyHost"/>
<spring:property name="port" value="6969"/>
<spring:property name="channel" value="S_machine"/>
<spring:property name="queueManager" value="QM_machine"/>
<spring:property name="transportType" value="1"/>
<spring:property name="specification" value="1.1"/>
</spring:bean>
</spring:beans>
Note that WebSphere MQ v5.3 requires at least Fix Pack 6 (CSD06) applied for JMS 1.1 support. Earlier
levels must set the specification property to 1.0.2b.
The latest WebSphere MQ Fix Packs can be downloaded here: http://www-1.ibm.com/support/
docview.wss?uid=swg27006037
You will also need the following IBM WebSphere JARs on your classpath:
• com.ibm.mq.jar
• com.ibm.mqjms.jar
• connector.jar
If you are using WAS, refer to this discussion for some known limitations.

Mule 2.1.2 Users Guide

Uploaded by

Copyright:

Available Formats

Mule 2.1.2 Users Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Mule 2.1.2 Users Guide

Uploaded by

Copyright:

Available Formats

Space Details

Creator (Creation Date): ross (Jan 30, 2008)

Document generated by Confluence on Jan 30, 2009 11:37 Page 1

Document generated by Confluence on Jan 30, 2009 11:37 Page 2

Document generated by Confluence on Jan 30, 2009 11:37 Page 3

Document generated by Confluence on Jan 30, 2009 11:37 Page 4

Document generated by Confluence on Jan 30, 2009 11:37 Page 5

This page last changed on Jan 30, 2009 by jackie.wheeler.

<?xml version="1.0" encoding="UTF-8" ?>

<jms:activemq-connector name="jmsConnector" specification="1.1" brokerURL="vm://localhost"

<--! or use the XA connector to support transactions -->

<?xml version="1.0" encoding="UTF-8"?>

<bean id="activeMqConnectionFactory" class="org.activemq.ActiveMQConnectionFactory">

<?xml version="1.0" encoding="UTF-8"?>

Document generated by Confluence on Jan 30, 2009 11:37 Page 6

Document generated by Confluence on Jan 30, 2009 11:37 Page 7

This page last changed on Dec 16, 2008 by jackie.wheeler.

Using the Archetype

> mvn mule-example-archetype:create -DartifactId=xxx -DmuleVersion=2.1.2

At minimum, you pass in two system parameters:

Document generated by Confluence on Jan 30, 2009 11:37 Page 8

The Questions Explained

Provide a description of what the example does:

Which version of Mule is this example targeted at?

Will this project be hosted on MuleForge?

Which Mule transports do you want to include in this project?

Which Mule modules do you want to include in this project?

Example Console Output

Provide a description of what the example does:

Which version of Mule is this example targeted at?

Will This project be hosted on MuleForge? [y] or [n]

Document generated by Confluence on Jan 30, 2009 11:37 Page 9

Which Mule transports do you want to include in this project?

Which Mule modules do you want to include in this project?

Command Line Options

The following options can be passed in:

Name Example Default Value

packagePath -DpackagePath=org/mule/ none

transports -Dtransports=http,vm cxf,file,http,jdbc,jms,stdio,vm

muleVersion -DmuleVersion2.1.2 none

packageName -DpackageName=myPkg none

description -Ddescription="some text" none

modules -Dmodules=xml,scripting client,management,scripting,sxc,xml

basedir -Dbasedir=/projects/mule/tools <current dir>

Document generated by Confluence on Jan 30, 2009 11:37 Page 10

artifactId -DartifactId=myMuleExample mule-application-<artifactId>

version -Dversion=1.0-SNAPSHOT <muleVersion>

Document generated by Confluence on Jan 30, 2009 11:37 Page 11

This page last changed on Jan 27, 2009 by jackie.wheeler.

Getting Started Using Transports

Document generated by Confluence on Jan 30, 2009 11:37 Page 12

Document generated by Confluence on Jan 30, 2009 11:37 Page 13

This page last changed on Nov 19, 2008 by jackie.wheeler.

Document generated by Confluence on Jan 30, 2009 11:37 Page 14

This page last changed on Jan 19, 2009 by jackie.wheeler.

are available only in Mule Enterprise Edition are denoted by .

Connectivity to IBM AS400 Data Queue messaging

Axis Transport Allows Mule managed components to be published

BPM Transport Allows Mule events to initiate and/or advance