Mule Framework Guideline

1

2009

Mule Framework Guideline

Author: Pawan Modi

1

1

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

7

1.4.

Configuration File

8

1.5.

Running Mule

9

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

2

1

Abbreviation UMO = Universal Message Object ESB = Enterprise Service Buss

3

2009

1

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.

4

1

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

1

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

6

1

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

7

1

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

8

1

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

9

1

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

1

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

1

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

1

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

1

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

14

2009

1

15

2009

1

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

1

•

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

1

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 -builder spring Or follow the steps given in section 1.7.4 to run spring application using mule server via eclipse.

18

1

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

1

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

1

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

1

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

1

•

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

1

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

1

•

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

1

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

26

2009

1

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