1 2009

1

Mule Framework Guideline

Author: Pawan Modi

1 2009

2

Table of Contents

1.1. Introduction 4

1.2. Installation 51.2.1. Prerequisites 51.2.2. Download 5

1.3. Configuring Mule in Your Environment 7

1.4. Configuration File 8

1.5. Running Mule 9

1.6. Mule Examples 101.6.1. Hello World Example 101.6.2. Loan Broker Example 10

1.7. MuleIDE Eclipse Plugin 121.7.1. Download MuleIDE 121.7.2. Prerequisites 121.7.3. Install MuleIDE 121.7.4. New Mule Project in Eclipse 13

1.8. Mule – Spring Integration 161.8.1. Mule - Spring Config File 161.8.2. Spring Application in Mule 181.8.3. Running Spring Application 181.8.4. Spring Mule Example 19

1.9. Mule as ESB 211.9.1. Mule JMS EventBus Example 23

1 2009

3

Abbreviation

UMO = Universal Message Object

ESB = Enterprise Service Buss

1 2009

4

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.

1 2009

5

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

1 2009

6

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

1 2009

7

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

1 2009

8

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

1 2009

9

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

1 2009

10

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

1 2009

11

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

1 2009

12

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

1 2009

13

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.

1 2009

14

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

1 2009

15

1 2009

16

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.

1 2009

17

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

1 2009

18

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.

1 2009

19

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

1 2009

20

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.

1 2009

21

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

1 2009

22

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

1 2009

23

• Weblogic Jms

• IBM WebSphere MQ

• SwiftMQ

• FioranoMQ

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.

1 2009

24

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

1 2009

25

• 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:

1 2009

26

Both components shown above consist of two UMOs i.e PublisherUMO & ConsumerUMO.

UMO configuration of Component1 is as follow

1 2009

27

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.