1

2009

Mule Framework Guideline

Author: Pawan Modi

2009

Table of Contents

1.1.

Introduction

Installation
1.2.
Prerequisites
1.2.1.
Download
1.2.2.

4
5
5
5

1.3.

Configuring Mule in Your Environment

1.4.

Configuration File

1.5.

Running Mule

Mule Examples
1.6.
Hello World Example
1.6.1.
Loan Broker Example
1.6.2.

10
10
10

MuleIDE Eclipse Plugin

1.7.
Download MuleIDE
1.7.1.
Prerequisites
1.7.2.
Install MuleIDE
1.7.3.
New Mule Project in Eclipse
1.7.4.

12
12
12
12
13

Mule Spring Integration

1.8.
Mule - Spring Config File
1.8.1.
Spring Application in Mule
1.8.2.
Running Spring Application
1.8.3.
Spring Mule Example
1.8.4.

16
16
18
18
19

Mule as ESB
1.9.
Mule JMS EventBus Example
1.9.1.

21
23

Abbreviation
UMO = Universal Message Object
ESB = Enterprise Service Buss

2009

2009

1.1. Introduction
Mule is a light-weight messaging framework. It is a highly distributable object broker that can seamlessly handle
interactions with other applications using disparate technologies, transports and protocols.
The Mule framework provides a highly scalable environment in which you can deploy your business components.
Mule manages all the interactions between components transparently whether they exist in the same VM or over the
internet and regardless of the underlying transport used.
Mule was designed around the Enterprise Service Bus architecture, which stipulates that different components or
applications communicate through a common messaging bus, usually implemented using Jms or some other
messaging server.
Mule architecture is scalable, highly distributable object broker that can seamlessly handle interactions across legacy
systems, in-house application and almost all modern transports and protocols. Mule is feature rich & easy to deploy.
The diagram below shows a common scenario with Mule. Mule applications usually consist of many Mule instances
across the network. Each instance is a light-weight container that hosts one or more UMO component. Each UMO
component will have one or more endpoints that it will send and receive events through.

2009

1.2. Installation
1.2.1. Prerequisites
Following are the prerequisites you must meet before you can install Mule.
Supported Operating Systems
Mule will run on any platform that supports JAVA, including:

Windows XP SP2 and Windows 2000

Linux, Solaris, AIX, and HP-UX

Mac OSX

Software and Environment Setup

Before you can install Mule, you must have the following software installed and environment settings configured:

Java Developer Kit (JDK) 1.4x or greater is required for deploying Mule. JDK 1.5.x is required for building Mule
from the source code. Download.

The JAVA_HOME environment variable must be set to the directory where the JDK is installed, e.g.
C:\java\j2sdk1.4.2_08

Your path environment variable must contain the path to the JDK bin directory, such as
C:\java\j2sdk1.4.2_08\bin.

Ant 1.7.0 is required to build from source code & running some examples.

Maven 1.0.2 is required for building from the source code and running some of the examples. Download.

A compression tool such as WinZip (Windows) or GZip (Linux/Unix) is required for decompressing the Mule
distribution of the community edition, snapshot release, or source code.

For Linux/Unix users working from a shell, a download tool such as wget or _ftp _is required for downloading
the Mule distribution.

1.2.2. Download
Latest editions of mule are available at the following link. Download the full distribution of Mule2.0. Downloading
mule will take good amount of time so start downloading go to grab a cup of tea.
http://mule.mulesource.org/display/MULE/Download
5

2009

After finishing download, unzip mule distribution in a local directory.

Distribution contents
The Mule distribution contains the following directories:

/bin - Shell and batch scripts for controlling Mule from the command line

/conf - Configuration files

/docs - API documentation (Javadoc) for Mule and its sub-projects (not included in the Developer releases)

/examples - Example applications you can run and try building yourself (not included in the source
distribution)

/lib/boot - Libraries used by the Java Service Wrapper to boot the server

/lib/mule - Core Mule libraries

/lib/opt - Third-party libraries

/lib/user - Your custom classes and libraries. This directory comes before
/lib/mule on the classpath and can therefore be used to patch the distributed Mule classes if necessary. If
you add files to this directory when Mule is already running, you must restart Mule after adding the files.

/licenses - License information for all libraries shipped with Mule

/logs - Log file output when running in background mode

/sbin - Internal scripts (not to be run by the user)

/src - The source code for all Mule modules. You can import this into your IDE.

/LICENSE.txt - License agreement for Mule.

Download mail-1.4.jar from the following link & put it in <MULE_HOME>/lib/boot directory.
http://repo1.maven.org/maven2/javax/mail/mail/1.4/mail-1.4.jar
Note: Mule includes connectors for a wide variety of technologies. Some connectors use libraries that cannot be
distributed as part of Mule because of licensing restrictions. For these connectors, you must obtain the required
libraries and place them in the MULE_HOME/lib/user directory.
Visit the following link for more information about installation.
http://mule.mulesource.org/display/MULE2INTRO/Home

2009

1.3. Configuring Mule in Your Environment

Before you can use Mule, you must create the MULE_HOME environment variable and set it to the location of your
Mule installation. You must also add the location of your MULE_HOME/bin directory to your path.
Eg.
set MULE_HOME=C:\Mule
set PATH=%PATH%;%MULE_HOME%\bin

2009

1.4. Configuration File

Mule configuration file contains information about UMO services & their endpoints. Basic tree structure of the
configuration file is as follow. But there are many more tags. Root of the tree is always being mule tag.
<mule>
<model name=modelname or componenetname>
<service name=services name or umo name>
<inbound/>
<outbound/>
</service>
</model>
</mule>
Configuration file for mule resides in <Mule_HOME>/conf/ directory. Sample or default config file is available at
<MULE_HOME>/src/mule-config.xml. Mule configuration file is version specific. Configuration file from old version
may not work with new version of Mule. Refer the attached configuration files to know more.

Visit following link for more information on configuration.

http://mule.mulesource.org/display/MULE2INTRO/Installing+Mule#InstallingMule-%23configFiles

2009

1.5. Running Mule

To run Mule, you have to enter the following at the command prompt:
mule -config your-config.xml
Where your-config.xml is the Mule configuration file you want to use (see Configuration Files above 1.4). If you do
not specify the -config parameter then Mule looks for the default file mule-config.xml. If needed, you can specify
more than one configuration file in a comma-separated list. This approach is useful for splitting up your Mule
configuration to make it more manageable. All configuration files must be on the classpath prior to startup. A
convenient way to achieve this is by placing them in the /conf or /lib/user directory. Alternatively, you can specify an
explicit path to their location on the file system.
If you make changes to a configuration file, you must restart Mule for the changes to take effect.
To stop Mule, enter: Ctrl-C
Visit the following link to get more information about running mule.
http://mule.mulesource.org/display/MULE2INTRO/Running+Mule

2009

1.6. Mule Examples

Mule examples are available in <MULE_HOME>/examples directory
1.6.1. Hello World Example
This example shows how to configure multiple service components to interact on a single request and how to
manage event transformations. Detail explanation of this example is available at the following link.
http://mule.mulesource.org/display/MULE2INTRO/Hello+World+Example
Steps to run Hello Example:
1. First build & compile the source of example using Ant.
2. There are two ways to run Hello example.
a. Execute hello.bat
b. Run the following command at the command prompt
mule -config <MULE_HOME>/example/hello/conf/hello-config.xml

1.6.2. Loan Broker Example

This example demonstrates the Loan Broker using a typical ESB architecture with a shared Message Bus. The example
use HTTP/REST, Web Services, EJB and JMS and is configured according to a typical ESB implementation. Detail
explanation of this example is available at the following link.
http://mule.mulesource.org/display/MULE2INTRO/LoanBroker+ESB
http://mule.mulesource.org/display/MULE2INTRO/LoanBroker
Note: To run this example user need few third party libraries. These libraries are downloaded at the time of building /
compiling via Ant. User needs appropriate target for proxy settings in their build.xml file. Proxy settings are missing in
provided build.xml file. Use this attached build.xml to build / compile the source code.

Steps to run LoanBroker Example:

1. First build & compile the source using above attached build.xml file.
2. There are two ways to run LoanBroker example.
a. Execute loadbroker.bat
b. Run the following commands at the command prompt
10

2009

mule -main org.mule.example.loanbroker.bpm.LoanBrokerApp

All other examples can be run in the same way explained above. Visit the following link for more examples
http://mule.mulesource.org/display/MULE2INTRO/Home

11

2009

1.7. MuleIDE Eclipse Plugin

Mule IDE2.0 provides an integrated environment for developing 2.0.x Mule applications in Eclipse. Mule team is
working on creating a version of Mule IDE compatible with Mule 2.0 to support all new features.

1.7.1. Download MuleIDE

User can download Mule IDE from the following links
Download & install dependencies first. Following zip also consists of Eclipse GMF, EMF, and GEF dependencies. These
dependencies are needed to install MuleIDE.
http://dist.muleforge.org/mule-ide/MuleIDE-2.0.0.M2-dependencies.zip
Download plugin
http://dist.muleforge.org/mule-ide/MuleIDE-2.0.0.M2-I200804251604.zip

1.7.2. Prerequisites

Java 5 or higher

Eclipse 3.3 in running & working state.

Mule IDE has been tested with the Europa (3.3) version of Eclipse IDE for Java Developers using a Java 5 JRE.

1.7.3. Install MuleIDE

Follow the steps to install plugin.
1. Unzip downloaded MuleIDE-2.0.0.M2-dependencies.zip & MuleIDE-2.0.0.M2-I200804251604.zip in local
drives.
2. Start Eclipse.
3. Go to the menu Help -> Software Updates -> Find and Install...
4. Select the option "Search for new features and install". Click the Next button.
5. Click the New local Site button.
6. Provide the path for the directory having MuleIDE-2.0.0.M2-dependencies & click finish
12

2009

7. Now restart the eclipse & follow the same steps to install plug-in MuleIDE-2.0.0.M2-I200804251604.
Visit the following link for more information on MuleIDE installation.
http://www.mulesource.org/display/MULEIDE/Mule+IDE+2.0

1.7.4. New Mule Project in Eclipse

Follow the steps to create new project in eclipse.
1. Select new mule project from new project window & provide appropriate name to project.

2. You can see new project is created with Mule libraries.

3. Provide source file in src directory & put all configuration files & property files in bin directory.

13

4. Run application on mule server using configuration file shown in the figure below.

14

2009

15

2009

2009

1.8. Mule Spring Integration

Mule can be configured to use and manage any object from external containers or Naming Directories such as spring,
Jndi, Ejb, spring, Pico, Plexus, or HiveMind. Mule separates the container in which components are created and the
Mule model in which they are managed. This means developers can plug-in a container such as spring or
PicoContainer to construct the components that Mule manages.
Mule and spring can be integrated at different levels. Developer can choose as much or little Mule in your spring
application or spring in your Mule application. Spring & mule are the similar concept.

Visit the following link to know more about mule spring integration.
http://mule.mulesource.org/display/MULE2USER/Spring

1.8.1. Mule - Spring Config File

Following are the necessary components of your application configuration file.

Mule Manager

The Mule Manager is the primary component for each instance of a Mule server and is used to manage all Mule
objects (connectors, endpoints, transformers, etc.) for each Mule server instance. All objects are registered with
the MuleManager. The AutowireUMOManagerFactoryBean is responsible for determining the UMOManager to
implement, creates a default UMOModel and autowires the components to the model and all other global
objects to the MuleManager.

16

2009

Mule Name Processor

Mule name processors are use to set mule object names to their corresponding bean id.

Connector

A connector is the object that sends and receives messages on behalf of an endpoint. Connectors are bundled as
part of specific transports or providers.

Transformer

Transformers are used to convert inbound data to an object type required by the UMO Component or outbound
to an object type required by the transport such as a JmsMessage. Transformers can be configured on Endpoints
that receive data to ensure that the expected object type is always received by an UMO Component.
Transformers configured on an Outbound endpoint ensure that the endpoint receives the the correct object type
before dispatching the event. Multiple transformers can be chained together to allow for finer grained
transformer implementations that are easier to reuse. To configure an Endpoint to use more than one
transformer, just specify a space separated list of transformers in the config file or programmatically chain the
transformers together using the setTransformer() method on the transformer.

Interceptor

An interceptor is a piece of code that can be configured to execute before and/or after an event is received for a
component. User can define a stack of interceptors that will be executed in sequence. User can then configure
the stack on your components. Note the interceptor stack must not be a singleton. Each component needs its
own copy of an interceptor stack.

Spring Components (Mule Descriptor)

A Mule descriptor defines all the necessary information about how your components will interact with the
framework, other components in the system and external sources.
Sample configuration file is attached here.

17

2009

1.8.2. Spring Application in Mule

Adapting spring application to run in mule requires little modification in the code. User has to add transformers in
their application. Writing transformers is a easy job. To write custom transformer, developer has to inherit
org.mule.transformers.AbstractTransformer. Transformer class contains information about source
& destination of message & transformation of message in to destination understandable form. Following figure
shows the sample transformation class.

1.8.3. Running Spring Application

Use the following command to run spring application on command prompt
mule config <config-file> -builder spring
Or follow the steps given in section 1.7.4 to run spring application using mule server via eclipse.

18

2009

1.8.4. Spring Mule Example

This example is about Restaurant Service. This application consists of following package.
com.agilent.mulespring
This package consists of following classes & one application config file.
RestaurantWaiter.java
RestaurantWaiterInput.java

Transformer

RestaurantWaiterPayload.java Payload
KitchenService.java
KitchenServiceInput.java

Transformer

KitchenServiceOutput.java

Transformer

KitchenServicePayload.java

Payload

In this application it is show how to start mule service via spring application context xml file. You can see the config
file attached in section 1.8.1

19

2009

This example demonstrates that two spring components can exchange messages / objects using mule services. This
application is ready & working in my Eclipse environment. If the readers want to have a glance to code the let me
know I will share the project.
Note: Currently this example is implement using mule 1.4.3. Documentation & examples for Mule 2.0 is not available
for now. We need to do little investigation for the same.

20

2009

1.9. Mule as ESB

ESB is a software architecture construct that provides foundational services using an event-driven bus. ESB is a single
shared communications framework for all service interactions to pass through.
Without ESB

With ESB

21

2009

Mule is a light-weight messaging framework. It is a highly distributable object broker that can seamlessly handle
interactions with other applications using disparate technologies, transports and protocols. Mule was designed
around the Enterprise Service Bus architecture Mule's ultimate goal is to be the "Swiss-army knife" of integration.
Mule talks lots of different protocols

HTTP, JMS, TCP, POP3, FTP, RMI, JDBC, Quartz.

LDAP, JCR, Sales force.

Mule can route, transform and filter messages, transactions, security, management etc.
Mule support the following implementations of JMS.

ActiveMQ

JBoss MQ

Joram

OpenJms

Oracle AQ

SeeBeyond

SonicMQ

Sun JMS Grid

Tibco EMS

UberMQ
22

Weblogic Jms

IBM WebSphere MQ

SwiftMQ

FioranoMQ

2009

We have looked in to ActiveMQ implementation of JMS. Following is the JMS ActiveMQ configuration. This
configuration will go in mule-config.xml file.

I am not able to implement JMS using spring application. Investigation is going on for the same. I will update this
document with all my findings.

1.9.1. Mule JMS EventBus Example

Mule1.4.3 is tested with JMS ActiveMQ 4.1.1.
This application is a sample application to demonstrate mule event bus using ActiveMQ JMS.

23

2009

Sample application comprises of two components as show above Component1 & Component2. Both component take
inputs from console & send it to other component that display it on console. User has to type message from console.
Component1 is a publisher of topic my.q1 & Component2 is a consumer of topic my.q1 & viceversa. Both
components exchanges messages using ActiveMQ JMS.
Note: ActiveMQ server is running on machine1. Mule is not JMS server. We need to run ActiveMQ server separately.

Message exchange between these two components is using ActiveMQ JMS. We have to provide following
information in mule-config.xml
Connectors:
Transformers:
Interceptors:
Application Components:
Sample application is using following connectors
24

SystemStreamConnector is to take input from console & display output on console

jmsConnector is to provide activemq JMS bus for communication

Connectors configuration of Component1 is as follow

Connector configuration of Component2 is as follow:

25

2009

Both components shown above consist of two UMOs i.e PublisherUMO & ConsumerUMO.
UMO configuration of Component1 is as follow

26

2009

2009

As show in above configuration setting, publisherUMO is reads input from console & send it to other component.
ConsumerUMO receives JMS message from other component & displays that message on the console.

UMO configuration of Component2 is as follow.

Execution
Following figure shows, sender sends a message using publisherUMO & receives an response using consumerUMO.

27