Professional Documents
Culture Documents
Confidential
The ideas contained in this publication are subject to use and disclosure restrictions as set forth in the license agreement.
Copyright
Copyright 2003-2010, MuleSoft, Inc. All rights reserved. No part of this publication may be copied or distributed,
transmitted, transcribed, stored in a retrieval system, or translated into any human or computer language, in any form or
by any means, electronic, mechanical, magnetic, manual, optical, chemical or otherwise; or disclosed to third parties
without the express written permission of MuleSoft, Inc.
Disclaimer
Information in this document is subject to change without notice and does not represent a commitment on the part of
MuleSoft, Inc. The software described in this document is furnished under a license agreement or nondisclosure
agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to
copy the software on any medium except as specifically allowed in the agreement.
In addition, MuleSoft, Inc makes no representation or warranties either express or implied, with respect to this manual
and accompanying software and specifically disclaim any implied warranties of merchantability or fitness for any
particular purpose. This manual and accompanying software are sold as is and MuleSoft, Inc will in no event be liable
for direct, indirect, incidental or consequential damages resulting from any defect, error or failure to perform except as
expressly set forth in the license agreement.
Trademarks
MuleSoft, Mule and MuleForge are among the trademarks of MuleSoft. All other product names are trademarks of their
respective companies.
Part number: 223en_us2009.11.1
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Who Should Read This Guide? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Whats the Fastest Way Through This Guide? . . . . . . . . . . . . . . . . . . . .
Existing Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Typographic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mule Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
6
7
8
8
8
Chapter 1
Introduction to Mule ESB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
What is Mule ESB? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Understanding the Messaging Framework . . . . . . . . . . . . . . . . . . . . . . 11
Understanding the Mule ESB Architecture. . . . . . . . . . . . . . . . . . . . . . 12
About SOA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Processing the Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Routing Messages Between Service Components. . . . . . . . . . . . . . 14
Separating Business Logic from Messaging . . . . . . . . . . . . . . . . . . 15
Wiring Everything Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Understanding the Logical Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . 18
Integrating Mule ESB into Your Environment . . . . . . . . . . . . . . . . . . . 21
Administering Mule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Managing Your Deployments with the Management Console. . . . 23
Controlling the Infrastructure with the Service Registry . . . . . . . . 23
Monitoring Mule Instances Using JMX . . . . . . . . . . . . . . . . . . . . 24
Compatible Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
JMS Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Developer Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Web Service Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table of Contents
Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deployment Topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Event Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
28
28
29
29
Chapter 2
Installing and Running Mule. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing Mule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Distribution Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compatible Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing Third-Party Software . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Up Your Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing Mule Enterprise. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the Community or Snapshot Release . . . . . . . . . . . . . . .
Installing Multiple Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Up Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Build the Hello Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generate the Eclipse Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configure Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Import the Eclipse Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configure the Eclipse Build Path . . . . . . . . . . . . . . . . . . . . . . . . .
Create a Run Configuration and Run the Application . . . . . . . . .
Installing and Configuring Mule IDE . . . . . . . . . . . . . . . . . . . . . . . . .
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing Mule IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Mule Distribution. . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running Mule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Create a Service Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configure the Mule Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configure the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Extend Mule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Where Do I Go Next? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
30
31
32
32
33
35
36
37
38
39
39
39
39
41
41
42
43
43
44
45
45
46
47
48
48
48
49
49
Chapter 3
Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Lesson 1: Creating an Application Using Mule IDE . . . . . . . . . . . . . . . 51
Table of Contents
54
60
60
60
62
63
67
75
75
75
80
80
81
82
84
85
Chapter 4
Using Mule IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Mule Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Mule Configuration File . . . . . . . . . . . . . . . . . . . . . . .
Testing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Switching Mule Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
86
86
88
89
93
93
Appendix A
Distribution Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Appendix B
Third-party Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Preface
The Mule Getting Started Guide introduces Mule and related products from MuleSoft. It
provides the conceptual information and context that everyone from decision makers to
programmers need to get started with planning and implementing Mule.
Preface
Read...
Appendix B, Third-party
Software
Chapter 1, Introduction to Mule
ESB
Appendix B, Third-party
Software
Chapter 3, Tutorial
Chapter 1, Introduction to Mule
ESB
Chapter 3, Tutorial
Typographic Conventions
Preface
Existing Users
If you are an existing user, go to http://mule.mulesource.org/x/J4H8 to learn about the
new features and how to migrate your configuration files to this release. Mule Enterprise
customers can use the migration tool and follow the instructions in the Migration Guide,
both available from the Downloads page on the MuleSoft customer portal (log in at
http://mulesupport.mulesource.com/portal/login.mule.
Typographic Conventions
The following table describes the typographic conventions used in the Mule documentation:
Typeface
Meaning
Example
AaBbCc123
AaBbCc123
AaBbCc123
AaBbCc123
http://serverName/mule
Chapter 1
The Mule framework is highly scalable, allowing you to start small and connect more
applications over time. Mule ESB manages all the interactions between applications and
components transparently, regardless of whether they exist in the same virtual machine or
over the Internet, and regardless of the underlying transport protocol used.
Mule ESB is based on ideas from Enterprise Service Bus (ESB) architectures. The key
advantage of an ESB is that it allows different applications to communicate with each other
by acting as a transit system for carrying data between applications within your intranet or
across the Internet. There are currently several commercial ESB implementations on the
market. However, many of these provide limited functionality or are built on top of an
existing application server or messaging server, locking you into that specific vendor. Mule
ESB is vendor-neutral, so different vendor implementations can plug in to it. You are never
locked in to a specific vendor when you use Mule ESB.
10
Mule ESB components can be any type you want. You can easily integrate anything from
a plain old Java object (POJO) to a component from another framework.
Mule ESB and the ESB model enable significant component reuse. Unlike other
frameworks, Mule ESB allows you to use your existing components without any changes.
Components do not require any Mule ESB-specific code to run in Mule ESB, and there is
no programmatic API required. The business logic is kept completely separate from the
messaging logic.
Messages can be in any format from SOAP to binary image files. Mule ESB does not force
any design constraints on the architect, such as XML messaging or WSDL service
contracts.
You can deploy Mule ESB in a variety of topologies, not just ESB. Because it is
lightweight and embeddable, Mule ESB can dramatically decrease time to market and
increases productivity for projects to provide secure, scalable applications that are adaptive
to change and can scale up or down as needed.
MuleSoft also provides administration tools that allow you to manage your deployments
(Mule Management Console) and control your infrastructure (Mule Galaxy). These tools are
described in more detail in Administering Mule on page 23.
The next section provides more detail on the messaging framework and how Mule ESB
exchanges data among applications.
Application 2
Data
Channel
11
At the simplest level, when you connect applications to Mule ESB, it reads data from one
application, transforms it as needed so it can be read by the target application, and sends it to
that application. This allows you to integrate all types of applications, even those that were
not built to be integrated.
Mule ESB is a messaging framework based on ideas from Enterprise Service Bus (ESB)
architectures. The key advantage of an ESB is that it allows different applications to
communicate with each other by acting as a transit system for carrying data between
applications within your intranet or across the Internet. The heart of the system is the
message bus, which routes messages between applications.
One difference between Mule ESB and a traditional ESB is that Mule ESB only converts data
as needed. With a typical ESB, you have to create an adapter for every application you
connect to the bus and convert the applications data into a single common messaging
format. The development of these adapters and the time required to process every message
requires a lot of time and effort. Mule ESB eliminates the need for a single message format.
The information is sent on any communication channel, such as HTTP or JMS, and is
translated only as needed along the way. Therefore, Mule ESB increases performance and
reduces development time over a traditional ESB.
The Mule ESB architecture and terminology use the principles described in the book
Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions by
Gregor Hohpe and Bobby Woolf. This book is highly recommended reading for anyone
involved in working with enterprise messaging solutions. For more information, see
http://www.enterpriseintegrationpatterns.com.
Message
Order Entry
Application
Process Invoice
Invoice
12
Updated
Invoice
Order
Fulfillment
Application
About SOA
Mule ESB is based on the concept of a service-oriented architecture (SOA). The SOA
approach to development allows IT organizations to create applications by bringing together
components of application functionality, or services. Services are discrete sets of functionality
that are completely separate from each other but can work together on the same objects. For
example, if you need to process invoices, you might have one service that merges customer
data from a database into the invoice and another service that checks the inventory database
to see if the items on the invoice are in stock.
Because each service stands alone, services can be used as building blocks for multiple
processes and do not have to be recreated for each type of process or message. For example,
the service that merges customer data onto the invoice could also be used to merge customer
data onto statements, letters, or other documents. This modular approach allows you to
create functionality once and re-use it as many times as needed, streamlining development.
Using SOA, businesses can realize dramatic savings on development costs and can rapidly
adapt to changing business conditions by reusing and reconfiguring existing services in
developing new applications. SOA also enables better integration of enterprise IT resources,
including previously isolated application silos and legacy systems. Mule ESB fully supports
the SOA approach and orchestrates communication among the services, allowing you to
easily tie all these applications together.
13
service is the service component. The service component executes business logic on messages,
such as reading the invoice object, adding information to it from the customer database, and
then forwarding it to the order fulfillment application.
Customer Database
Message
Order Entry
Application
Invoice
Customer Data
Service
Component
Configuration
Settings
Message
Updated
Invoice
Order
Fulfillment
Application
Service
An important feature of the service component is that it doesnt have to have any Mule
ESB-specific code; it can simply be a POJO, Spring bean, Java bean, or web service
containing the business logic for processing data in a specific way. Mule ESB manages the
service component, bundles it with configuration settings and exposes it as a service, and
ensures that the right information is passed to and from it based on the settings you specified
for the service in the Mule ESB configuration file.
You can have many different service components that perform different business logic, such
as one that verifies whether the items on the invoice are in stock and one that updates a
separate customer database with the order history. The invoice, which is encapsulated in a
message, can flow from one service component to the next until all the required processing is
complete.
14
Inbound routers specify which messages the service component will process. They can filter
incoming messages, aggregate them, and resequence them before routing them to a service
component. For example, if a service component subscribes to an RSS feed, the inbound
router could filter which messages it receives from that feed.
After a service component has processed a message, the outbound router specifies where to
dispatch the message. For example, it might route invoices for in-state addresses to one
shipping department and route all other invoices to another shipping department. You can
define multiple inbound and outbound routing constraints and even chain routers together
so that a service component receives and routes messages exactly as required.
Customer Data
Service
Component
Message
Updated
Invoice
Message
Outbound Router
Updated
Invoice
Domestic
Order
Fulfillment
Application
Inbound Router
International
Order
Fulfillment
Application
Inbound Router
15
component that needs to process it, and transformers change the invoice along the way (such
as from XML to a Java object) as required by each service component. All the transporting,
transforming, and routing of the message are completely transparent to the service
component.
Service
Customer Data
Service
Component
Message
Message
JMS Transport
HTTP Transport
Transformers are the key to exchanging data, as they allow Mule ESB to convert the data to a
format that another component or application can understand. Most importantly, data is
transformed only as needed. Instead of converting every message to a single common
messaging format, messages and their data are transformed only as needed for the target
component or application where the message is being sent. Lastly, you can use multiple types
of transports to handle different channels, such as sending the message over HTTP and then
forwarding it as a JMS message after it has been processed by the Customer Data service
component.
The separation of the business logic from the sending and transformation of messages allows
for great flexibility in how you set up your architecture and makes it much simpler to
customize the business logic without having to worry about the various formats in which a
message might arrive. Your service component can work with the raw data of the message if
desired, but it is not required.
16
Service
Order
Fulfillment
Service
Component
Customer Data
Service
Component
Endpoint: http://
myfirm.com/mule
Inbound Router
Endpoint:
jms://myqueue
Endpoint:
jms://myqueue
Outbound Router
Inbound Router
HTTP message
HTTP Transport
JMS Transport
JMS message
A service can receive messages using different transports. For each type of transport that a
service will use, you must specify one or more separate endpoints. For example, if you want
one of your services to handle messages coming in on both the HTTP and JMS channels,
you would specify at least one HTTP endpoint and at least one JMS endpoint in the
inbound router for that service. Mule ESB registers these endpoints with the service, and the
transport uses this registry information at runtime to configure itself and determine where to
send and receive messages.
17
The router or endpoint can include filters that further specify which messages to send or
receive. For example, you can specify that the service component only receives RSS messages
by a specific author. Specifying routers and endpoints for your services simply requires
editing an XML file. You do not have to write any Java code. As stated previously, your
service components code remains completely separate from messaging and routing, which
you handle through the Mule ESB configuration.
In summary, Mule ESB provides a simple and lightweight way to write service components
that do something to data without needing to worry about the sender or recipient of the
data, the format of the data, or the technology being used to send/receive the data. Although
many brokering and integration technologies offer the ability to connect to disparate data
sources, they often require extra coding to get messages to behave the way you want and to
deliver the data where you want it to go. Mule ESB allows you to quickly develop service
components and then change the way they behave through simple XML configuration
instead of writing Java code.
inbound router specifies that the message must contain a Java object, so the HTTP
transport prepares to transform the XML invoice and dispatch the message to the service.
3 The XML to Object transformer converts the XML invoice into a Java object. Note that
the next service and the final application also expect Java objects, so no further
transformers are used in this scenario.
4 The transport passes the message with its transformed payload to the Customer Data
service.
5 The Customer Data service component queries the master customer database to pull
additional data about the customer and updates the invoice with the data.
18
6 The HTTP transport uses the outbound router configuration to determine that it must
now dispatch the message to http://myfirm.com/verify.
7 The HTTP transport uses the inbound router configuration of the Inventory Verification
message to the order fulfillment application, which picks up orders on that address.
19
5
Data
http://
myfirm.com/
verify
Outbound Router
4
POJO
XML to
Java Object
Transformer
1
XML
Order Entry
Sends messages to
http://myfirm.com/orders
HTTP Transport
JMS message
HTTP Transport
Outbound Router
jms://myqueue
POJO includes
warehouse ID
Order Fulfillment
Receives messages on
jms://myqueue
20
9
JMS Transport
7
Inbound Router
http://
myfirm.com/
verify
Inventory
Verification
Service
Component
When integrating with Mule ESB, you can start with just a few applications and connect
more applications to Mule ESB over time. For example, one Mule ESB customer started by
integrating six systems. Three years later, they had a total of 71 systems connected using
Mule ESB. Mule ESB allows you to start as small as needed and easily scale over time.
21
You can have multiple instances of Mule ESB distributed across your network, as shown in
the following illustration. This approach is useful for failover (if one Mule ESB instance
becomes unavailable because the server stops, another Mule ESB instance can take over its
messages) as well as for load-balancing (you can send some messages to one instance and
other messages to another instance to balance the load).
You can deploy each instance of Mule ESB as a stand-alone application, in a web container
(such as Apache Tomcat), or in an application server. You can use proprietary J2EE
application servers such as BEA WebLogic, IBM WebSphere, Oracle Application Server, and
SunOne, as well as in open source products like Geronimo or JBoss.
Designing your system is both an art and a science. It must be done correctly to ensure
scalability. MuleSoft Professional Services can help you by reviewing your architecture,
designing components, or doing the full implementation for you. For more information,
contact your MuleSoft Professional Services representative.
22
Administering Mule
Administering Mule
MuleSoft provides additional tools for monitoring and managing your Mule deployment, as
shown in the following illustration. This section describes these tools and how they can help
you administer Mule.
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.
23
Compatible Technologies
The service registry can be deployed either alongside Mule or as a standalone component in
an enterprise's SOA infrastructure. The service registry is available with Mule ESB
Enterprise. It is based on the open-source Mule Galaxy project, which can be used with the
community edition of Mule ESB.
Compatible Technologies
Following are the technologies that are known to work with Mule.
Operating Systems
Linux
Windows
Solaris
AIX
HP-UX
Mac OS X
Application Servers
24
Standalone
Tomcat
WebLogic
WebSphere
Geronimo
JBoss
Jetty
Compatible Technologies
Resin
Containers
EJB 3
jBPM
Spring
JMS Servers
ActiveMQ
FioranoMQ
JBossMQ
OpenJMS
OpenMQ
Oracle AQ
SeeBeyond
SonicMQ
Sun JMS Grid
SwiftMQ
TIBCO EMS
WebLogic JMS
Developer Tools
Ant
Data Mapper (Eclipse IDE, Oakland)
Eclipse
Japex
Maven
Mule IDE
Profiler
25
Compatible Technologies
Transports
26
Abdera
Amazon SQS
Axis
BPM
CICS CTG
CXF
Email
FTP
Hibernate
HTTP/S
IMAP/S
JCR
JDBC
Jersey
Jetty/Jetty SSL
JMS
LDAP
Multicast
POP3/S
Quartz
Restlet
RMI
SalesForce
SAP
Servlet
SMTP/S
SOAP
STDIO
TCP
UDP
VM
XMPP
WSDL
Compatible Technologies
Security
WS-Security
Acegi
Jaas
PGP
Spring Security
Databases
Derby
MySQL
Oracle
Axis
Atom
CXF
.NET Web Servces
REST
SOAP
WS-Addressing
WS-Policy
WS-Security
WS-I BasicProfile
WS-I SecurityProfile
WSDL
Languages
Groovy
Java
JavaScript
Jaxen
JRuby
27
Compatible Technologies
JXPath
Jython (Python)
OGNL
RegEx
SXC
XPath
XQuery
Data Formats
Atom
Base 64 encoded
Byte arrays
CSV
EDI
Encrypted
GZIP
Hex strings
HTML / XHTML
Java objects
JAXB
JSON
Streaming
Strings
XHTML
XML
XML entity encoded
Deployment Topologies
28
ESB
Client/Server
Peer-to-Peer
Enterprise Service Network
Hub and Spoke
Pipeline
Summary
Event Handling
Asynchronous
Routing Patterns
SEDA
Streaming
Synchronous
Transactions
Summary
Mule ESB provides a messaging framework that enables exchange of data among
applications. The application functionality is wrapped as a service, which includes a service
component (the business logic that processes the data), routers (which use endpoints to
specify where to send the message), and other configuration settings. Transports carry the
messages on different channels from service to service, and transformers convert the messages
and data as needed along the way.
Mule ESB is not a replacement for existing application frameworks. Instead, Mule ESB
leverages many open source projects such as Apache CXF, Spring, and ActiveMQ and fills a
void in enterprise Java development where an application requires complex interactions with
a variety of systems on a variety of platforms. Mule ESB makes light work of wiring systems
together in a robust, decoupled environment with little to no code and provides the
necessary support to route, transport, and transform data to and from these systems.
This chapter provided an introduction to the Mule ESB architecture. Now, read Chapter
2, Installing and Running Mule, for more detailed information on how to download,
install, and get started using Mule.
29
Chapter 2
Installing Mule
This section describes how to download and install the three types of Mule distributions.
Install the third-party software and set up your environment first, and then follow the
installation instructions for the distribution type you are downloading.
Note If you need to upgrade from a previous release of Mule, see Existing Users on
page 8.
30
Installing Mule
Distribution Types
There are three types of Mule distributions. The distribution you choose depends on your
business needs and current phase of development.
MuleSoft supported release (Mule Enterprise): the latest, fully tested release of Mule
ESB created by MuleSoft that includes premium features not found in the community
release. Mule Enterprise provides access to technical support, maintenance patches, and
the MuleSoft knowledge base and is suitable for development, pre-production, and
production environments alike.
If you have purchased a license for Mule Enterprise, log in to the customer portal at
http://mulesupport.mulesource.com/portal/login.mule, and then click
Downloads. If you are evaluating Mule, you can download the 30-day trial of Mule
Enterprise at http://www.mulesoft.com/mule-esb-enterprise-trial-download.
Latest stable community release: the latest stable release of the community release of
Mule ESB. This distribution is suitable for people who are evaluating Mule ESB in
development or pre-production environments. (Mule Enterprise is the best choice for
production environments.) To download the community release, go to
http://www.mulesource.org/display/MULE/Download
Snapshot release: the latest Mule distribution built against the very latest code base (the
bleeding edge). Snapshot releases may be unstable, so they are intended for development
environments only, not for production environments. Additionally, snapshot releases do
not include any documentation. To download a snapshot release, go to
http://www.mulesource.org/display/MULE/Download
You can also download the source code and build Mule yourself. For complete information,
see Setting Up the Development Environment
(http://www.mulesoft.org/documentation/display/MULECDEV/Setting+Up+the+
Development+Environment) and Building from Source
(http://www.mulesoft.org/documentation/display/MULECDEV/Building+from+S
ource).
Note If you download one of the compressed distributions, you will need a compression
tool such as WinZip (Windows) or GZip (Linux/UNIX) to decompress the ZIP or TAR file.
31
Installing Mule
Compatible Platforms
Users run Mule on many different operating systems with a variety of messaging platforms
and application servers. The following table lists the platforms that members of the
community have reported are compatible with Mule.
Technology
Platforms
Operating Systems
Application Servers
Messaging
Any JMS vendor; users have reported integration with Active MQ,
Open MQ, TIBCO EMS, TIBCO Rendezvous, Oracle AQ, and IBM
WebSphere MQ
Java
that your environment and Mule installation can support Mule HQ if you decide to install it
later, as Mule HQ requires that you log in as a non-root user before you install it.
Java: Install Java Developer Kit (JDK) 1.5. Note that JDK 1.4.x will work if you are not
using CXF or building Mule from the source code, but JDK 1.5.x is highly
recommended. Run the installer, following the instructions that appear on the screen.
You can download JDK 1.5 from
http://java.sun.com/javase/downloads/index_jdk5.jsp
If you are using the Mule IDE, you must also endorse the JDK with a proper JAXP (Java
API for XML Processing) implementation. To do this, download Apache Xerces and
Xalan and drop the JARs into your JVM's jre/lib/endorsed directory. If that
directory does not yet exist, create it.
32
Installing Mule
Mule IDE: If you are installing the Mule IDE, install it immediately after installing
Mulesee IInstalling Mule on page 30.
Maven: If you do not want to use the Mule IDE, or if you will be using the Maven
archetypes to create a new transport or module, install Maven.
z
<localRepository>c:/.m2/repository</localRepository>
Ant: If you want to use Ant to build the examples instead of Maven, download and install
it if you have not done so already.
You can download Ant from http://ant.apache.org/bindownload.cgi.
JDK is installed.
2 Create an environment variable called MAVEN_HOME and set it to the directory where you
unpacked Maven.
3 Create an environment variable called MAVEN_OPTS and set it to
-Xmx512m -XX:MaxPermSize=256
4 If you will use Ant, create an environment variable called ANT_HOME and set it to your Ant
home directory.
33
Installing Mule
5 Create the MULE_HOME environment variable and set it to the location where you will
install Mule. If you are running Windows, the installation path must not contain any
spaces (for example, you cannot use C:\Program Files). A good workaround is to create
a root directory called Mule (for example, C:\Mule). This step is not required if you will
use the Mule IDE.
6 Update the PATH environment variable so that it includes the path to the JDK, Maven,
Linux/UNIX
export
export
export
export
export
JAVA_HOME=/opt/java/jdk
MAVEN_HOME=/opt/apache/maven-2.0.9
MAVEN_OPTS='-Xmx512m -XX:MaxPermSize=256m'
MULE_HOME=/opt/mule
PATH=$PATH:$JAVA_HOME/bin:$MAVEN_HOME/bin:$MULE_HOME/bin
Windows
set
set
set
set
set
JAVA_HOME=C:\Program Files\Java\jdk
MAVEN_HOME=C:\Apache\maven-2.0.9
MAVEN_OPTS='-Xmx512m -XX:MaxPermSize=256m'
MULE_HOME=C:\Mule
PATH=%PATH%;%JAVA_HOME%/bin;%MAVEN_HOME%/bin;MULE_HOME/bin
You are now ready to install Mule. If you are installing Mule Enterprise, read the next
section. If you are installing the community or snapshot release, skip ahead to Installing
the Community or Snapshot Release on page 36.
34
Installing Mule
1 If you downloaded the TAR.GZ version of Mule Enterprise, simply decompress the files
If you will use the Mule IDE, see Installing and Configuring Mule IDE on
page 43.
If you will use Maven, skip ahead to Setting Up the Maven Repository on
page 36.
1 If you downloaded the JAR version of Mule Enterprise onto Windows, double-click the
file to launch the installer. If you do not have Java associated with JAR files by default,
open a command prompt, navigate to the directory where you downloaded the JAR file,
and then enter the following command:
java -jar mule-enterprise-standalone-installer-version.jar
installing the Profiler pack, which helps you identify memory leaks in your custom Mule
extensions, and the scripting module, which provides facilities for using scripting
languages in Mule.
3 When you are prompted to specify the installation directory, be sure to specify the same
directory as you specified for the MULE_HOME environment variable.
4 Do one of the following:
z
If you will use the Mule IDE, see Installing and Configuring Mule IDE on
page 43.
35
Installing Mule
If you will use Maven, skip ahead to Setting Up the Maven Repository on
page 36.
For example:
cd c:\mule\bin
populate_m2_repo.cmd c:\.m2\repository
This step is required to populate the Maven repository with the local Mule Enterprise JAR
files from the distribution. Note that when you add Mule Enterprise-only features to your
code, you must add the correct dependencies to your POM before building your project with
Maven. For more information, see Dependencies on the Using Maven page at
http://www.mulesoft.org/documentation/display/MULECDEV/Using+Maven#Us
ingMaven-Dependencies.
You have completed the Mule installation and setup. You can now skip the next section and
go to Setting Up Eclipse on page 38.
36
Installing Mule
3 Click the link next to the release you want to download. Use the .zip links for installing
on Windows and the .tar.gz links for installing on Linux/UNIX. The latest releases are
Linux/UNIX, you would switch to your MULE_HOME directory, and then enter a
command like this to extract the files:
tar -xvzf mule-full-2.0.1-SNAPSHOT.tar.gz
libraries will be properly configured and available for secondary instances. If you are
running the enterprise version of Mule, also apply the license to the primary instance
before setting up the secondary instance.
2 Log in as the user who will use a secondary instance.
3 Create a directory for the secondary instance with the following subdirectories:
z
37
Setting Up Eclipse
4 Copy the files from these subdirectories in the primary Mule instance to the
Setting Up Eclipse
When you work with Mule, you can make configuration and development much easier by
using an IDE. This section describes how to set up Eclipse, an open-source IDE, to enable
easy configuration of Mule and development of new functionality. This section describes
using Eclipse 3.4 (Ganymede), which you can download from
http://www.eclipse.org/downloads/packages/ (download the Eclipse IDE for Java
EE Developers). It contains the following sections:
38
Prerequisites on page 39
Build the Hello Application on page 39
Generate the Eclipse Project on page 39
Configure Eclipse on page 39
Import the Eclipse Project on page 41
Configure the Eclipse Build Path on page 41
Create a Run Configuration and Run the Application on page 42
Setting Up Eclipse
Prerequisites
Before you continue, be sure you have installed Mule and the prerequisites as described
earlier in this chapter. You must also have Internet access to build the example application
and generate the Eclipse project, as each of those steps downloads dependencies.
Configure Eclipse
You only need to configure Eclipse once. With subsequent projects, you can skip these steps.
1 Start Eclipse.
2 In the Workspace Launcher, specify the location of the examples directory under your
Mule home directory (such as C:\mule\examples), and click OK.
3 Click the Workbench icon on the right to display the workbench.
4 Choose Window > Preferences.
39
Setting Up Eclipse
5 Expand Java in the navigation tree, click Compiler, and then change the compiler
6 Click Installed JREs. If the JRE is not version 1.5, click Edit, click Directory and
navigate to your JDK1.5 directory, and then change the JRE name to jdk5. Click Finish,
and then click OK.
7 When prompted to rebuild, click No.
40
Setting Up Eclipse
3 In the Import dialog box, click Browse, navigate to the Mule examples directory again,
and click OK. The hello project should be listed and selected.
4 Click Finish.
The hello project is now listed in the Project Explorer on the left. You will notice some errors
at the bottom of the screen, which are caused by your build path needing to be configured.
41
Setting Up Eclipse
1 In the Project Explorer, right-click the hello project and choose Build Path > Configure
Build from the popup menu.
2 In the Properties dialog box, click the Libraries tab, and then click Add Library.
3 Click User Library and click Next.
4 Click User Libraries, and then in the Preferences dialog box, click New.
5 In the New User Library dialog box, enter MULE_LIB and click OK.
6 Click Add JARs, navigate to the \lib\mule directory under your Mule home directory,
select all the JARs, and click Open.
7 Click OK and then Finish.
8 Click Add Variable, click Configure Variables, and then in the Preferences dialog box,
click New.
9 In the New Variable Entry dialog box, create a variable called M2_REPO that points to your
Maven repository (such as C:\.m2\repository), which you created when you installed
Maven. Click OK.
10 In the Preferences dialog box, click OK, and this time when you're prompted to rebuild,
click Yes. Click OK in the open dialog boxes to close them and rebuild the project.
42
3 Click the Arguments tab, and then enter -config conf\hello-config.xml (for
Windows) or -config conf/hello-config.xml (for Linux/UNIX) in the Program
Arguments box.
4 Click Apply and then Run.
The Hello application runs in the Console tab at the bottom of the window, prompting you
to enter your name. You can type your name and press Enter to see the application continue.
Congratulations! You have successfully built and run your first Mule example from within
Eclipse. You can now add services to the configuration, write POJOs as needed, debug your
code, and compile and run your examples all within the IDE.
If you want to import another example into Eclipse, repeat the instructions to generate an
Eclipse project for that example, import the project into the workspace, and then just run the
example by choosing Run > Run. You do not have to repeat the steps for configuring Eclipse.
Prerequisites
Before you install Mule IDE, ensure that you have installed the following software:
43
You must also endorse the JDK with a proper JAXP (Java API for XML Processing)
implementation. To do this, download Apache Xerces
(http://xerces.apache.org/xerces2-j/) and Xalan
(http://xml.apache.org/xalan-j/) and drop the JARs into your JVMs
jre/lib/endorsed directory. If that directory does not yet exist, create it.
1 Start Eclipse, and set up a workspace for your installation of Mule if you haven't already.
(Make sure your workspace does not have a space in the directory path)
2 In the workbench view, choose Help > Install New Software.
3 Click Add next to the Work with text box, enter
http://dist.muleforge.org/mule-ide/updates/3.4/, and click Enter.
4 Click the Mule IDE check box and click Next, and after Eclipse processes for a moment,
click Next again.
5 Review the IDE license, select the option to accept the license, and then click Finish.
6 Click Yes to restart Eclipse.
You are now ready to configure the Mule distribution as described in Configuring the
Mule Distribution on page 45.
1 Start Eclipse, and set up a workspace for your installation of Mule if you haven't already.
(Make sure your workspace does not have a space in the directory path)
2 In the workbench view, choose Help > Software Updates, and then click the Available
Software tab.
3 If you previously installed a preview release of Mule IDE 2.0, click Manage Sites, select
the Mule IDE update site, click Remove, and then click OK.
4 On the Available Software tab, click Add Site.
44
You are now ready to configure the Mule distribution as described in the next section.
default Mule distribution. You can configure multiple Mule directories, but only one can
be the default.
You are now ready to start Eclipse and start using Mule IDE as described in Chapter
3, Tutorial and Chapter 4, Using Mule IDE.
Troubleshooting
If you have difficulty installing or using Mule IDE, verify the following:
You have the correct update site and have uninstalled any developer preview releases.
Does your workspace directory or project name have a space in it? Mule runs from the
workspace folder, and if it has a space in the name (like Documents and Settings), Mule
cannot locate the configuration file to start.
45
Running Mule
If you cannot successfully complete the installation steps, remove and recreate the update
site. To remove a site in Eclipse, choose Help > Software Updates, on the Available
Software tab click Manage Sites, select Mule IDE, and then click Remove. You can
now recreate the Mule IDE site following the steps above.
Have you updated the other libraries in your eclipse installation? Make sure all of your
existing standard Eclipse plug-ins are up to date.
Ensure you followed the documented steps to register the endorsed XML libraries and
have also previously installed Mule. You will need to configure the location of Mule the
first time you create a Mule project.
Running Mule
Now that you have installed and configured Mule, you are ready to get started! This section
describes how to run Mule. If you installed Eclipse, see Create a Run Configuration
and Run the Application on page 42 instead.
Note If you are using the 30-day trial version of Mule Enterprise, you will not be able to run
the trial version after the 30 days has expired unless you purchase a license. (This does not
affect the community release of Mule.) For information on purchasing Mule Enterprise, go
to http://www.mulesource.com/buynow/.
The simplest way to run Mule is to enter the following command at the command prompt:
mule [-config your-config.xml]
where your-config.xml is the Mule configuration file you want to use. For a quick start, use
one of the configuration files in the Examples subdirectories to see how this works. For more
information on examples, see http://mule.mulesource.org/x/wAm7.
To get up and running quickly with developing a Mule application using an example
application, see Chapter 3, Tutorial.
If you are running the community release of Mule, the MuleSoft Public License is displayed
page by page when you first run Mule. To advance a page, press Enter. At the end of the
license display, type y to accept the license file and proceed with startup.
For more information on ways you can run Mule, see
http://mule.mulesource.org/x/gQi7.
46
Basic Usage
Basic Usage
When you look at how a message flows through Mule, you can see that there are three layers
in the architecture: the application layer, the integration layer, and the transport layer.
Service
Customer Data
Service
Component
Inbound Router
Application
Layer
Outbound Router
Integration
Layer
XML to
Java Object
Transformer
Message
Message
HTTP Transport
HTTP Channel
Transport
Layer
JMS Transport
JMS Channel
Likewise, there are three general types of tasks you can perform to configure and customize
your Mule deployment:
Service component development: developing POJOs, services, or beans that contain the
business logic and will be used as service components in a Mule deployment.
Extending Mule: developing new transports, connectors, and other modules used by
Mule.
This section provides a high-level overview of the steps you take to perform these tasks.
47
Basic Usage
Routers
Inbound routers specify how messages are routed to a service, and outbound routers specify
how messages are routed after the service has finished processing them. There are several
default routers that come with Mule that you can use, or you can create your own routers.
For more information, see: http://mule.mulesource.org/x/NAKV
48
Where Do I Go Next?
Filters
Filters specify conditions that must be met for a message to be routed to a service. There are
several default filters that come with Mule that you can use, or you can create your own
filters. For more information, see: http://mule.mulesource.org/x/7AGV
Transformers
Transformers convert incoming payload data to the type required by the service component.
After the service has finished processing the message, they can also convert the message to a
different type as needed by the outbound transport. There are several default transformers
you can use, or create your own. For more information, see:
http://mule.mulesource.org/x/IgKV
Extend Mule
Mule provides transports for many different channels, including File, FTP, HTTP, JMS,
JDBC, Quartz, and many more. There are also community-created transports on MuleForge
(http://muleforge.org/). If you need to send messages on a channel other than those
provided, you can create a new transport. You can also create a custom connector for a
transport. A connector is the Java class in the transport that contains the actual logic for
sending and receiving messages on that channel. For more information, see:
http://mule.mulesource.org/x/zoDR
You can also use Maven to create new Mule projects (transports and other types of modules).
For more information, see: http://mule.mulesource.org/x/YgI
Where Do I Go Next?
This chapter has provided a brief overview of getting started with Mule. Following is
information about where to go next.
For a tutorial on running Mule in an IDE, walking through a configuration, and adding a
service to a Mule application, see Chapter 3, Tutorial.
For complete information on using Mule, go to the Mule User Guide at:
http://www.mulesoft.org/documentation/display/MULE2USER/Home
If you need assistance and are a Mule Enterprise customer, see the support page at:
http://www.mulesource.org/display/MULE/Support
49
Where Do I Go Next?
If you are evaluating Mule and want to find out about subscription options, you can
submit a request for MuleSoft to contact you by going to
http://www.mulesource.com/buynow/, or call us at 877-MULE-OSS.
All Mule users can subscribe to the Mule mailing lists. You can find these lists at:
http://www.mulesource.org/display/MULE/Mailing+Lists
If you experience problems with the Mule software or documentation, please log an issue
in the MuleSoft issue-tracking system, located at:
http://www.mulesource.org/jira/browse/MULE
50
Chapter 3
Tutorial
This chapter provides a tutorial for running an example, walking through its configuration,
and adding a service to an existing Mule application. This chapter contains the following
sections:
1 In Eclipse Workbench, choose File > New > Project, expand the Mule folder and select
Mule Project, and then click Next.
2 Enter the name myHelloApp, ensuring that there is no space in the project name.
51
Chapter 3 Tutorial
3 Click Add sample project content and select the Hello example.
4 Click Next, and then click the Libraries tab and verify that the Java 5 or later library is
You will now see the myHelloApp project in the navigation pane on the left. You can expand
its folders to see the source code, configuration files, and more.
Now, lets create a new configuration file for this application using the System I/O (also
called STDIO) and VM transports.
52
Chapter 3 Tutorial
1 Choose File > New > Other, expand the Mule folder and select Mule Configuration,
and then click Next.
2 Click Browse..., expand the myHelloApp project, select the conf directory, and then
click OK.
3 Change the default name from mule-config.xml to my-hello-config.xml.
You can use any name you like, as long as it is unique within the project and has an .xml
extension. If you use the name of an existing file, it will overwrite that file.
4 Select the System I/O and VM transports, leave Spring Config selected, and then click
Finish.
Mule IDE creates the configuration file in the conf directory of the myHelloApp project. It
adds the namespaces for the STDIO and VM transports.
53
Chapter 3 Tutorial
You can now add global elements below the namespace declarations, add services within a
<model> element, and add local routers, filters, endpoints, and transformers to the services.
Eclipse provides a fast and error-proof method for entering these elements. Simply click
somewhere between the opening and closing tags of an element and click Ctrl+space to see
the available elements. Double-click the element you want, and Eclipse enters the opening
and closing tags for that element. You can also hover over a tag to see a description of the
element and its supported attributes.
Now that you know how to set up a Mule project and configuration file, the next lesson
walks you through the configuration file in detail to help you understand the elements you
add. You can continue on with the next lesson from within the Mule IDE and just skip past
the first two steps, as you have already declared your XML namespaces.
Next, in the <mule> element, declare the namespaces for the core Mule schema, XSI, Spring,
and the transports and modules you want to use. In this example, we'll use the STDIO and
VM transports. You then use the XSI namespace to declare the locations of the schemas. For
example:
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:stdio="http://www.mulesource.org/schema/mule/stdio/2.2"
xmlns:vm="http://www.mulesource.org/schema/mule/vm/2.2"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
54
Chapter 3 Tutorial
http://www.mulesource.org/schema/mule/core/2.2
http://www.mulesource.org/schema/mule/core/2.2/mule.xsd
http://www.mulesource.org/schema/mule/stdio/2.2
http://www.mulesource.org/schema/mule/stdio/2.2/mule-stdio.xsd
http://www.mulesource.org/schema/mule/vm/2.2
http://www.mulesource.org/schema/mule/vm/2.2/mule-vm.xsd">
Optionally, add the <description> element with a description of this configuration file. If
you are creating only one configuration file for your entire application, the description could
be about the entire application.
<description>The Hello World sample application has two components 1. The Greeter component that adds a greeting to the message it receives
2. The ChitChatter component that adds some additional conversation to the
message it receives.
A message is triggered by input through the system console and the
outbound message is also written out through the system console. This
configuration also demonstrates user and system error handling. User error
handling returns an error message to the end user. System error handling
logs errors.
</description>
While there are several ways in Mule to configure a transport, the best practice is to use the
<connector> element to define a global connector configuration, which you can then
reference in multiple places. The <connector> element must be prefixed by the namespace
of its transport. For example, the following connector will be available to endpoints that use
the STDIO transport:
<stdio:connector name="SystemStreamConnector"
promptMessageCode="3"
resourceBundle="messages.hello-example-messages"
messageDelayTime="1000"/>
Because we have only one connector defined for the STDIO transport, this connector will be
used by default whenever we create an STDIO transport. If we defined multiple STDIO
connectors, you would use the connector-ref attribute on the endpoint to specify the one
you want to use.
To see which attributes you can set for a connector, go to the transports reference page by
clicking its name on the Available Transports page at:
http://www.mulesource.org/x/3oHR
55
Chapter 3 Tutorial
Similarly, if you want to configure custom transformers that you can reference from multiple
places, add them to the configuration now. For example, the Hello World example uses
several transformers that format the message payload and convert it to the datatype expected
by each component:
<custom-transformer name="StdinToNameString"
class="org.mule.example.hello.StdinToNameString"/>
<custom-transformer name="NameStringToChatString"
class="org.mule.example.hello.NameStringToChatString"/>
<custom-transformer name="ChatStringToString"
class="org.mule.example.hello.ChatStringToString"/>
<custom-transformer name="ExceptionToString"
class="org.mule.example.hello.ExceptionToString"/>
You are now ready to add your services, which is where you specify your components that do
the actual work. Services are contained within models, so you add the <model> tag first:
<model name="helloSample">
...services will go here
Now, start configuring your services by adding <service> tags with a name attribute that
contains a unique name for the service. The Hello World example has four services, each of
which has an <inbound> section, a <component>, and an <outbound> section in that order.
For details on the elements you can configure in a service, see the Service Configuration
Reference page at http://www.mulesource.org/x/P5HR.
Lets add the inbound section for the GreeterUMO service first:
<service name="GreeterUMO">
<inbound>
<stdio:inbound-endpoint system="IN"
transformer-refs="StdinToNameString"/>
</inbound>
Notice that within the inbound section, weve specified the inbound endpoint. The inbound
endpoint defines which messages this service will handle by specifying the following:
56
Where the message originates. In this case, its system.in because the user is typing the
information at the command prompt.
The transformer to use. Here we reference one of the global transformers we defined
earlier in the configuration.
Chapter 3 Tutorial
If there is more than one connector configured for the transport, you specify the
connector to use. As mentioned earlier, we have only one STDIO connector, so we dont
have to specify it explicitly on the endpoint.
This inbound endpoint specifies that only messages that are received on system.in at the
command line will be received by this service, and they will be transformed by the
StdinToNameString transformer before they are passed to the component. There is no
inbound router specified, so all messages received on this endpoint will be processed by the
service.
The component is the next element to configure. The component can be a Java class, web
service, or anything that can perform logic on the messages. For information on creating a
component, see Developing Service Components at
http://www.mulesource.org/x/2IDR.
In this example, our component is a POJO, so you specify the class in the <component> tag:
<component class="org.mule.example.hello.Greeter"/>
By default, Mule automatically discovers the correct method in the Java class to execute (the
entry point) by matching the return type on the transformer (in this case, NameString) to the
methods in the component. For information on other ways of resolving the entry point, see
Entry Point at http://www.mulesource.org/x/2IDR.
Now we need to specify what the service will do after the component has finished with it. We
specify this in the outbound section. In this case, we want to use an outbound router to send
the message to one service if the message was processed successfully and to a different service
if the message had errors. To do this, we use filtering routers, each of which specifies a) the
outbound endpoint where the message will go next, and b) the criteria the message must
meet to be routed there. If a message does not meet the criteria of the first router, its checked
against the second routers criteria, and so on until theres a match.
<outbound>
<filtering-router>
<vm:outbound-endpoint path="chitchatter"/>
<payload-type-filter
expectedType="org.mule.example.hello.NameString"/>
</filtering-router>
<filtering-router>
<vm:outbound-endpoint path="userErrorHandler"/>
<payload-type-filter expectedType="java.lang.Exception"/>
</filtering-router>
</outbound>
57
Chapter 3 Tutorial
In this case, if the message payload was transformed correctly into a NameString object, the
first router sends it to the chitchatter path using the VM transport. If the message was not
transformed correctly and the payload contains an exception, the message is routed to the
userErrorHandler path using the VM transport. When you configure the services that will
handle the message in each of these cases, you must ensure that they specify chitchatter or
userErrorHandler as the path on their inbound endpoints.
Mule provides support for error handling for unexpected errors. Exception strategies allow you
to handle messages when there is a system error:
<!-- Route unexpected errors to separate error handler -->
<default-service-exception-strategy>
<vm:outbound-endpoint path="systemErrorHandler"/>
</default-service-exception-strategy>
</service>
In the Hello World example, user errors are routed to system.out and system errors are
routed to system.err. These error-handling services are defined below:
<!-- This error handler returns user error messages to caller. Errors could
also be routed elsewhere,
e.g. into an error file, send via email to a list, stored in a database,
etc. -->
<service name="UserErrorHandler">
<inbound>
<vm:inbound-endpoint path="userErrorHandler"
transformer-refs="ExceptionToString"/>
</inbound>
<outbound>
<pass-through-router>
<stdio:outbound-endpoint system="OUT"/>
</pass-through-router>
</outbound>
</service>
<!-- Handle any unexpected errors. Errors could also be routed elsewhere,
e.g. into an error file, send via email to a list, stored in a database,
etc. -->
<service name="SystemErrorHandler">
<inbound>
<vm:inbound-endpoint path="systemErrorHandler"/>
</inbound>
<outbound>
<pass-through-router>
<stdio:outbound-endpoint system="ERR"/>
58
Chapter 3 Tutorial
</pass-through-router>
</outbound>
</service>
Notice that these services do not configure components, because they simply route the
messages using the pass-through router and do not need to perform any extra logic on the
messages.
There is one last service in the example: the ChitChatUMO service. This service transforms
the message, adds text to it, and writes it to system.out:
<service name="ChitChatUMO">
<inbound>
<vm:inbound-endpoint path="chitchatter"
transformer-refs="NameStringToChatString"/>
</inbound>
<component class="org.mule.example.hello.ChitChatter"/>
<outbound>
<pass-through-router>
<stdio:outbound-endpoint system="OUT"
transformer-refs="ChatStringToString" />
</pass-through-router>
</outbound>
</service>
Lastly, end the file with the closing </model> and </mule> tags:
...
</model>
</mule>
To see the entire configuration file for this example, navigate to the examples/hello/conf
directory under your Mule home directory and open the hello-config.xml file. The
custom classes referenced in the configuration file are included with the example under the
examples/hello/src/main/java directory.
To run the application, the custom classes must be compiled and available on the Java
classpath when Mule starts. If you created your project in the Mule IDE, it handles this for
you, and you can execute your application by selecting the Mule configuration file you
created (my-hello-config.xml) and running it as a Mule Server.
59
Chapter 3 Tutorial
How it Works
This section walks through the configuration of the REST version of the Stock Quote
example, but the Web Service configuration is very similar. Because you've already walked
through the Hello example, this section will discuss the configuration without going into
step-by-step detail.
First, because the proxy settings are in an external properties file, we specify the file in the
Mule context:
60
Chapter 3 Tutorial
<context:property-placeholder location="proxy.properties"/>
Next, we configure the HTTP connector with the properties whose values are defined in the
proxy.properties file:
<http:connector name="HttpConnector"
proxyHostname="${proxyHostname}"
proxyPassword="${proxyPassword}"
proxyPort="${proxyPort}"
proxyUsername="${proxyUsername}"/>
The next section is the configuration for the transformers. There are four transformers,
which will be chained together. Note that the XSLT transformer references the XSLT file in
the xsl subdirectory under the stockquote directory. The XSLT file can be anywhere on
your classpath.
<xm:xml-to-object-transformer name="XmlToObject"/>
<xml-entity-decoder-transformer name="XmlDecoder"/>
<xm:xslt-transformer name="Xslt" xsl-file="xsl/rest-stock.xsl"/>
<object-to-string-transformer name="ToString"/>
Next, we set up a model as a container for the one service in this example:
HTTPPostSample. This service receives messages sent to vm://stockquote and transforms
them using all four transformers before passing them to the component.
<model name="Sample-Rest">
<service name="HTTPPostSample">
<inbound>
<vm:inbound-endpoint path="stockquote"
responseTransformer-refs="ToString XmlDecoder Xslt
XmlToObject"/>
</inbound>
<http:rest-service-component
serviceUrl="http://www.webservicex.net/stockquote.asmx/GetQuote"
httpMethod="POST">
<http:payloadParameterName value="symbol"/>
</http:rest-service-component>
</service>
</model>
The component is the REST service component, which uses the REST service wrapper to
proxy a REST service to act like a local Mule component. The REST service wrapper has a
number of properties configured. The serviceUrl is the URL of the REST service to
61
Chapter 3 Tutorial
invoke. The payloadParameterName is the name of the parameter to associate with the
message payload. In this case, we have only one parameter name, symbol. The httpMethod
can either be GET or POST.
62
Chapter 3 Tutorial
Set Up Eclipse
To use the Stock Quote example in Eclipse, you take the following steps as described in
Setting Up Eclipse on page 38:
1 Build the Stock Quote example using the mvn command
2 Generate the Eclipse project using mvn eclipse:eclipse
3 Import the project into Eclipse
4 Create a run configuration for the project (see the following illustration)
5 Ensure that the application runs successfully from the Console tab
These steps are described in detail in Setting Up Eclipse on page 38. Follow the
instructions replacing hello with stockquote, and set the run configuration program
arguments to:
-config "conf\stdio-config.xml,conf\stockquote-wsdl-config.xml"
63
Chapter 3 Tutorial
You can create your own HTML page using the complete sample file getQuote.html on
page 67.
64
Chapter 3 Tutorial
Additionally, we need to set the content type to HTML, so we can define a simple
transformer right in the XML file that does this:
<message-properties-transformer name="SetHtmlContentType">
<add-message-property key="Content-Type" value="text/html"/>
</message-properties-transformer>
65
Chapter 3 Tutorial
project.
3 Copy and paste the HTML file you created (or downloaded) to the root folder of the
stockquote project.
and leave the WSDL version intact. The configuration should now look like this:
-config "conf\stockquote-http-config.xml,conf\stockquote-wsdl-config.xml"
4 Click Apply and then Run.
66
Chapter 3 Tutorial
The results of the Stock Quote web service appear on the page.
Congratulations! You have successfully added a new service and transformers to the Stock
Quote example and configured it to capture and display information on a web page instead
of the console. For more information on using Mule, including basic and advanced
configuration, working with transformers and filters, configuring transports, and more, see
the Mule User Guide at: http://mule.mulesource.org/x/VgKV
You can also use the Mule IDE, an Eclipse plug-in that provides additional functionality for
developing Mule applications in Eclipse. The Mule IDE is in beta and is available for
download on the MuleForge at: http://www.mulesource.org/display/IDE/Home
Example Files
This section contains the files used in this tutorial. You can copy and paste them from this
section, or download them using the links.
getQuote.html
You can download this file from:
http://www.mulesource.org/download/attachments/12257709/getQuote.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Get Quotes</title>
</head>
<script type="text/javascript" src="jquery-1.2.3.js"></script>
<body>
<!-- Layout -->
<div id="wrapper">
<div id="container" class="clear-block">
67
Chapter 3 Tutorial
68
Chapter 3 Tutorial
stockquote-http-config.xml
You can download this file from:
http://www.mulesource.org/download/attachments/12257709/stockquote-http
-config.xml
<mule 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.2
http://www.mulesource.org/schema/mule/core/2.2/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/vm/2.2
http://www.mulesource.org/schema/mule/vm/2.2/mule-vm.xsd
http://www.mulesource.org/schema/mule/stdio/2.2
http://www.mulesource.org/schema/mule/stdio/2.2/mule-stdio.xsd
http://www.mulesource.org/schema/mule/xml/2.2
http://www.mulesource.org/schema/mule/xml/2.2/mule-xml.xsd">
<description>
The StockQuote HTTP example listens for http requests and Uses the VM
transport to call the stockquote proxy service and returns results to the
enduser as a html page.
</description>
<custom-transformer name="HttpRequestToStockSymbol"
class="org.mule.example.stockquote.HttpRequestToStockSymbol"/>
<custom-transformer name="StockQuoteToHTMLString"
class="org.mule.example.stockquote.StockQuoteToHTMLString"/>
<message-properties-transformer name="SetHtmlContentType">
<add-message-property key="Content-Type" value="text/html"/>
</message-properties-transformer>
<model name="Sample-HTTP">
<!-- This component can proxy external web service calls over Jms, tcp, ssl
or any other transport. For this example we use Vm. -->
<service name="httpservice">
<inbound>
<inbound-endpoint address="http://localhost:8888/getQuote"
synchronous="true" transformer-refs="HttpRequestToStockSymbol"
responseTransformer-refs="StockQuoteToHTMLString SetHtmlContentType"/>
</inbound>
69
Chapter 3 Tutorial
<outbound>
<pass-through-router>
<vm:outbound-endpoint path="stockquote" synchronous="true" />
</pass-through-router>
</outbound>
</service>
</model>
</mule>
HttpRequestToStockSymbol.java
You can download this file from:
http://www.mulesource.org/download/attachments/12257709/HttpRequestTo
StockSymbol.java.
package org.mule.example.stockquote;
import org.mule.transformer.AbstractTransformer;
import org.mule.util.IOUtils;
import org.mule.api.transformer.TransformerException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
public class HttpRequestToStockSymbol extends AbstractTransformer {
public HttpRequestToStockSymbol() {
super();
this.registerSourceType(String.class);
this.registerSourceType(byte[].class);
this.registerSourceType(InputStream.class);
this.setReturnClass(String.class);
}
/*
* (non-Javadoc)
*
* @see
* org.mule.transformers.AbstractTransformer#doTransform(java.lang.Object)
*/
public Object doTransform(Object src, String encoding)
throws TransformerException {
String srcAsString;
if (src instanceof byte[]) {
70
Chapter 3 Tutorial
if (encoding != null) {
try {
srcAsString = new String((byte[]) src, encoding);
} catch (UnsupportedEncodingException ex) {
srcAsString = new String((byte[]) src);
}
} else {
srcAsString = new String((byte[]) src);
}
}
else if (src instanceof InputStream)
{
InputStream input = (InputStream) src;
try
{
srcAsString = IOUtils.toString(input);
}
finally
{
IOUtils.closeQuietly(input);
}
}else {
srcAsString = src.toString();
}
System.out.println("http post string:" + srcAsString);
String request = srcAsString;
String symbol = extractValue("symbol", request);
if (symbol == null || symbol.trim().length() == 0) {
throw new TransformerException(this, new Exception(
"Invalid Stock Symbol specified"));
}
return symbol;
}
private String extractValue(String name, String requestQuery)
throws TransformerException {
String nameValue = null;
if (requestQuery != null && requestQuery.length() > 0) {
int nameParameterPos = requestQuery.indexOf(name + "=");
if (nameParameterPos != -1) {
int nextParameterValuePos = requestQuery.indexOf('&',
nameParameterPos);
if (nextParameterValuePos == -1
|| nextParameterValuePos < nameParameterPos) {
71
Chapter 3 Tutorial
nextParameterValuePos = requestQuery.length();
}
nameValue = requestQuery.substring(nameParameterPos
+ name.length() + 1, nextParameterValuePos);
}
if (nameValue != null && nameValue.length() > 0) {
try {
nameValue = URLDecoder.decode(nameValue, "UTF-8");
} catch (UnsupportedEncodingException uee) {
System.err.println("USER ERROR: " + uee.getMessage());
}
}
}
if (nameValue == null) {
nameValue = "";
}
return nameValue;
}
}
StockQuoteToHTMLString.java
You can download this file from:
http://www.mulesource.org/download/attachments/12257709/StockQuoteToH
TMLString.java
package org.mule.example.stockquote;
import
import
import
import
java.util.ArrayList;
org.mule.RequestContext;
org.mule.transformer.AbstractTransformer;
org.mule.api.transformer.TransformerException;
72
Chapter 3 Tutorial
}
/*
* (non-Javadoc)
*
* @see
org.mule.transformers.AbstractTransformer#doTransform(java.lang.Object)
*/
public Object doTransform(Object src, String encoding) throws
TransformerException
{
ArrayList list;
//RequestContext.getEventContext().getMessage().setProperty("Content-Ty
pe", "text/html");
//StockQuote quote;
System.out.println("StockQuote Instance of: '" +
src.getClass().getName() + "'");
System.out.println("StockQuote: " + src);
if (src instanceof String) {
return src;
}
StringBuffer sb = new StringBuffer();
sb.append("<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'");
sb.append("'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>");
sb.append("<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en'
lang='en'><body>");
73
Chapter 3 Tutorial
74
Chapter 3 Tutorial
Overview
Message routers control how messages are routed among the services in your Mule
application. Following is a description of the key concepts:
Inbound routers control how a service handles incoming messages, such as selectively
consuming only those messages that meet specific criteria or grouping messages together
that share a group ID before forwarding them on.
Outbound routers control how a message is dispatched after the service has processed it,
such as sending it to a list of recipients or splitting up the message and sending the parts
to different endpoints.
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.
Catch-all strategies are 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.
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.
75
Chapter 3 Tutorial
Asynchronous
If you simply want to put a message on a SEDA queue after processing it, and no response to
the caller is required, you can use the asynchronous message style.
For example:
<model name="Asynchronous_Message_Pattern">
<service name="AsynchronousService">
<inbound>
<jms:inbound-endpoint queue="test.in" synchronous="false"/>
</inbound>
<component class="org.myorg.WidgetHandler" />
<outbound>
<pass-through-router>
<jms:outbound-endpoint queue="test.out">
<pass-through-router>
</outbound>
</service>
</model>
Request-Response
In simple scenarios that require a response, a service receives a request on a synchronous
inbound endpoint, processes the request, and then sends it back to the caller as a reply. For
example, if a user enters a value in an HTML form, and you want to transform that value
76
Chapter 3 Tutorial
and display the results in the same page, you can simply configure a synchronous inbound
endpoint on the service that does the transformation. This scenario does not use an
outbound router. This is the request-response message style.
For example:
<model name="Request-Response_Message_Pattern">
<service name="SynchronousService">
<inbound>
<http:inbound-endpoint host="localhost" port="8080"
path="/mule/services" synchronous="true"/>
</inbound>
<component class="org.myorg.WidgetHandler" />
</service>
</model>
Synchronous
If you need to pass the message to a second service for additional processing, you would
configure an outbound router on the first service to pass the message to the second service.
After the second service processes the message, the first service sends it back to the caller as a
77
Chapter 3 Tutorial
reply. Note that setting the synchronous inbound endpoint on the first service means that the
message is treated synchronously throughout all subsequent services, so you do not need to
set the synchronous flag on the second service. This is the synchronous message style.
For example:
<model name="Synchronous_Message_Pattern">
<service name="SynchronousService">
<inbound>
<jms:inbound-endpoint queue="test.in" synchronous="true"/>
</inbound>
<component class="org.myorg.WidgetHandler" />
<outbound>
<chaining-router>
<jms:outbound-endpoint queue="test.out"/>
</chaining-router>
</outbound>
</service>
<service>
<inbound>
<jms:inbound-endpoint queue="test.out"/>
</inbound>
<component class="org.myorg.WidgetPackager" />
</service>
</model>
Asynchronous Request-Response
In the most complex scenario, you can enable request-response messaging and allow the
back-end process to be forked to invoke other services, returning a reply asynchronously
based on the results of multiple service invocations. You can set the inbound endpoint's
78
Chapter 3 Tutorial
synchronous flag to false, since the response will be handled by the asynchronous reply
router, unless you also want to send a response to the caller. This is the asynchronous
request-response message style.
In the following example, a request comes in on an HTTP endpoint, is broadcast to two
endpoints using the Multicast router, and the results are sent asynchronously to a JMS
endpoint.
<model name="Async_Request-Response_Message_Pattern">
<service name="AsyncRequestResponseService">
<inbound>
<http:inbound-endpoint host="localhost" port="8080"
path="/mule/services" synchronous="false"/>
</inbound>
<component class="org.myorg.WidgetHandler" />
<async-reply timeout="5000">
<collection-async-reply-router/>
<jms:inbound-endpoint queue="reply.queue"/>
</async-reply>
<outbound>
<multicasting-router>
<reply-to address="jms://reply.queue"/>
<jms:outbound-endpoint queue="service1" synchronous="false"/>
<jms:outbound-endpoint queue="service2" synchronous="false"/>
</multicasting-router>
</outbound>
</service>
</model>
Summary
This lesson described the different message styles you can use. For complete information, see
the appendix on Mule messaging styles in the Mule Configuration Guide.
Now that you understand which message styles to use for routing in different scenarios,
Lesson Five describes several routers you can use for achieving finer control over message
routing.
79
Chapter 3 Tutorial
Filtering Messages
You can control which messages a service handles by using filters. The Selective Consumer
Router works on inbound endpoints to control which messages that service will process. The
Filtering Router works on outbound endpoints to control which messages the service sends
along to the next endpoint. You can use a combination of these approaches to control the
message flow.
For example, if you only want to process messages that don't have errors, you can use a
selective consumer to ensure that only those with the result code success are processed. You
can then use a Catch-all Strategy to forward all other messages to another endpoint for error
handling:
<inbound>
<selective-consumer-router>
<mulexml:jxpath-filter expression="msg/header/resultcode = 'success'"/>
</selective-consumer-router>
<forwarding-catch-all-strategy>
<jms:endpoint topic="error.topic"/>
</forwarding-catch-all-strategy>
</inbound>
If you want the service to process all messages but then want to specify criteria to determine
where the message is sent next, you can use filtering outbound routers. In the following
example, messages that contain an exception are sent to the system administrators email
address, messages whose payload contains a specific string are sent to the string queue, and all
other messages are picked up by the forwarding catch-all router and sent to an error queue:
<outbound>
<forwarding-catch-all-strategy>
<jms:outbound-endpoint queue="error.queue"/>
</forwarding-catch-all-strategy>
80
Chapter 3 Tutorial
<filtering-router>
<smtp:outbound-endpoint to="ross@muleumo.org"/>
<payload-type-filter expectedType="java.lang.Exception"/>
</filtering-router>
<filtering-router>
<jms:outbound-endpoint queue="string.queue"/>
<and-filter>
<payload-type-filter expectedType="java.lang.String"/>
<regex-filter pattern="the quick brown (.*)"/>
</and-filter>
</filtering-router>
</outbound>
Similar routers are the forwarding router, which allows you to process some messages and
selectively forward others, and the wiretap router, which allows you to process all messages
and send them on as normal but also send a copy to another endpoint. For more
information, see the section on inbound routers in the Mule Configuration Guide.
You can also use the chaining router to perform protocol bridging to a single outbound
endpoint. Unlike the pass-through router, the chaining router always returns a response. For
example:
81
Chapter 3 Tutorial
<service name="HttpProxyService">
<inbound>
<!-- WSDL URL: http://localhost:8888/stockquote.asmx?wsdl -->
<inbound-endpoint address="http://localhost:8888" synchronous="true"/>
</inbound>
<outbound>
<chaining-router>
<outbound-endpoint
address="http://www.webservicex.net#\[header:http.request\]"
synchronous="true"/>
</chaining-router>
</outbound>
</service>
Splitting Messages
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. For example, in an
order-processing application, you might want to send different parts of the message to
different services for processing. You could do this using one of the following routers:
List Message Splitter: accepts a list of objects that will be routed to different endpoints. For
example:
<outbound>
<list-message-splitter-router">
<jms:outbound-endpoint queue="order.queue">
<payload-type-filter expectedType="com.foo.Order"/>
</jms:outbound-endpoint>
<jms:outbound-endpoint queue="item.queue">
<payload-type-filter expectedType="com.foo.Item"/>
</jms:outbound-endpoint>
</list-message-splitter-router>
</outbound>
82
Chapter 3 Tutorial
Filtering XML Message Splitter: similar to the List Message Splitter but operates on XML
documents. For example:
<outbound>
<mulexml:filter-based-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>
</mulexml:filter-based-splitter>
</outbound>
Expression Splitter Router: similar to the List Message Splitter but splits the message based
on an expression that returns one or more message parts. For example:
<outbound>
<expression-splitter-router evaluator="xpath"
expression="/mule:mule/mule:model/mule:service"
disableRoundRobin="true" failIfNoMatch="false">
<outbound-endpoint ref="service1">
<expression-filter evaluator="xpath" expression="/mule:service/@name =
'service splitter'"/>
</outbound-endpoint>
<outbound-endpoint ref="service2">
<expression-filter evaluator="xpath" expression="/mule:service/@name =
'round robin deterministic'"/>
</outbound-endpoint>
</expression-splitter-router>
</outbound>
83
Chapter 3 Tutorial
You could also split a message into parts to improve performance. The Round Robin
Message Splitter splits the message into parts and sends them to endpoints in a round-robin
approach. The Message Chunking Router splits a single message into a number of
fixed-length messages that will all be routed to the same endpoint.
After splitting messages, you use the Message Chunking Aggregator to aggregate the
message parts back together again. The aggregator uses the correlation ID, which is set by the
outbound router, to identify which parts belong to the same message.
<inbound>
<message-chunking-aggregator-router>
<expression-message-info-mapping
correlationIdExpression="#[header:correlation]"/>
<payload-type-filter expectedType="org.foo.some.Object"/>
</message-chunking-aggregator-router>
</inbound>
84
Chapter 3 Tutorial
Summary
This lesson provided a sampling of some of the routers you can use to control how messages
are processed and routed. For complete information on message routers, see the chapter on
using message routers in the Mule Configuration Guide.
To see additional examples, such as the Stock Quote Example, which illustrates how to add a
proxy service, and the Bookstore Example, which illustrates using CXF, see the Examples
page at http://www.mulesource.org/x/wAm7. The Mule Cookbook
(http://www.mulesource.org/x/dgi7) provides additional code snippets and examples
that users and Mule developers have submitted.
For more information on all topics related to configuring and using Mule, see the Mule
Configuration Guide.
85
Chapter 4
1 Choose File > New > Project, expand the Mule folder and select Mule Project, and
then click Next.
2 Enter a name for the project, ensuring that there is no space in the project name. If you
want to put the project in a location other than the default workspace, clear the Use
default location check box and specify a new file location.
3 Do one of the following:
z
To use the default Mule distribution you configured, leave Use default Mule
distribution selected.
If you want to specify a non-default Mule distribution, select if from the drop-down
list.
86
If you want to use a new Mule distribution, click Configure Default..., add it to the
Mule Distributions list, and then select it from the list.
4 If you want your project to include the source and configuration from one of the Mule
example applications, click Add sample project content and select the example you
want to use. Note that not all of the examples that ship with Mule are supported.
5 Click Next, and then click the Libraries tab and verify that the Java 5 or later library is
87
The project is added to the Package Explorer pane. The Mule libraries from the distribution
you selected are contained in the project. If you selected an example, the source and
configuration from that example are also in the project.
1 Choose File > New > Other, expand the Mule folder and select Mule Configuration,
and then click Next.
2 Click Browse..., expand the project in which you're creating the file, select the conf
directory, and then click OK.
3 Change the default name from mule-config.xml to a unique name in the File Name
box.
Warning Make sure you use a unique name. If you specify the name of an existing file, the
new file you are creating will overwrite the existing file.
4 Select each of the Mule modules or transports you want to include in your configuration.
Mule IDE will prepopulate the namespace declarations based on your selections.
Note that the Mule core namespace will be populated by default and does not need to be
selected. If you want to include a custom module or transport or one from MuleForge,
simply add its JAR file to the \lib\user sub-directory under the Mule home directory.
As long as the JAR includes a Spring-based schema file, Mule IDE will include it in the
list.
5 Click Finish.
88
Mule IDE creates the configuration file in the conf directory of the project you selected. The
namespaces are populated based on the transports and modules you selected and the
distribution version of your project.
89
1 Choose Run > Run Configurations in Eclipse Ganymede or Run > Open Run Dialog
in Eclipse Europa.
2 Click Local Mule Server, and then click New.
3 Enter a name for the configuration youre creating.
4 Specify the project that contains the Mule configuration files you want to test.
5 Click Add and select one or more Mule configuration files in the project.
6 If you want to use a different Mule distribution for the configuration, select Use a
project specific Mule distribution and select the distribution to use.
7 Click the Arguments tab, and then enter any additional arguments or properties you need
to pass to the JVM using -M-DPropertyName=PropertyValue just as you would if you
90
8 Click Apply.
You can now click Run to launch the Mule server and test this configuration immediately, or
run this configuration at a later time.
91
If a launch configuration exists that contains the selected Mule configuration file, it is used to
launch a Mule server. Otherwise, a new run configuration is created automatically and the
server is started. If multiple run configurations already exist that contain the selected Mule
configuration file, you are prompted to choose which one to use.
92
If your application requires multiple configuration files, you must create the run
configuration manually as described on page 90.
93
Appendix A
Distribution Contents
The Mule distribution contains the following directories and files:
/bin
Shell and batch scripts for controlling Mule from the command
line
/conf
Configuration files
/docs
/examples
/lib/boot
/lib/endorsed
/lib/mule
Mule libraries
/lib/opt
Third-party libraries
/lib/user
/licences
/logs
/sbin
/src
The source code for all Mule modules. You can import this into
your IDE
LICENSE.txt
README.txt or
README.pdf
94
Appendix B
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.
Some components of Mule Enterprise may also contain other software that is commercially
licensed. For more information, contact MuleSoft.
Third-party Software
95
Software
License
Acegi
Apache 2.0
Antlr
BSD Style
AOP Alliance
Public Domain
Apache Axis
Apache 2.0
Apache2.0
Apache Catalina
Apache 2.0
Apache 2.0
Apache 2.0
Apache 2.0
Apache Commons-cli
Apache 1.1
Apache 2.0
Apache 2.0
Apache 2.0
Apache 2.0
Apache Commons IO
Apache 2.0
96
Software
License
Apache 2.0
Apache 2.0
Apache 2.0
Apache 2.0
Apache 2.0
Apache CXF
Apache 2.0
Apache Derby
Apache 2.0
Apache Geronimo
Apache 2.0
Apache 2.0
Apache Maven
Apache 2.0
Apache 2.0
Apache Velocity
Apache 2.0
Apache 2.0
Apache 2.0
Apache 2.0
Apache Xalan
Apache 2.0
Apache Xerces
Apache 2.
Apache 2.0
Apache 2.0
Apache 2.0
Apache 2.0
Apache Xpath
Apache 2.0
BSD
ApsectJ
EPL 1.0
License
Axis-Saaj Project
Apache 2.0
Axis/Web Services
Apache 2.0
Backport-util-concurrent
BeanShell
LGPL 2.1
LGPL 2.1
LGPL 2.1
CGLIB
Apache 2.0
Cryptix
Cryptix OpenPGP
Dom4j
BSD
Apache Style
Fast Infoset
Apache 2.0
Groovy
Apache 2.0
Hibernate
LGPL 2.1
Howl-logger
BSD
iHarder Base64
Public Domain/Permissive
IzPack
Apache 2.0
Apache 2.0
Jakarta-Oro
Apache 1.1
Sun BCLA
97
98
Software
License
Apache 2.0
Javaassist
MPL 1.1
Sun BCLA
BSD
JavaMail
CDDL 1.0
Jaxen
LGPL 2.1
JBoss Transactions
LGPL 2.1
JDOM
Jetty 6.1.11
Apache 2.0
Jruby
CPL/GPL/LGPL
JUnit
CPL 1.0
Jython
Python License
Linguine Maps
LGPL 2.1
Log4j
Apache 2.0
Mockobjects
Apache 2.0
Mx4j
Neethi
Apache 2.0
OGNL
OpenSAML
Apache 1.1
Propertyset
Quartz
Apache 2.0
License
Retrotranslator
BSD
SAAJ
Saxon-B
MPL 1.1
Servlet Specification
CDDL 1.0
MIT Style
Smack
Apache 2.0
Spring Framework/Modules
Apache 2.0
StaX
Apache 2.0
Sun JNDI
Sun BCLA
SXC
Apache 2.0
Truelicense
Apache 2.0
TrueXML
Apache 2.0
CPL 1.0
Apache 2.0
WSS4J
Apache 2.0
XAPool
LGPL 2.1
XMLUnit
BSD style
XPP3
XStream
BSD
Commercial
99
Glossary
Following are the terms youll see as you work with Mule. Because of the dynamic
open-source history of Mule, there are sometimes multiple terms used to describe the same
thing. This glossary lists all terms but refers to the preferred term when there are synonyms.
agent
A service such as the Mule JMX agent that is used by or associated with Mule but is not a
Mule-managed service component. An agent is registered with the Mule Manager and
has the same lifecycle as the Mule instance, so you can initialize and destroy resources when
the Mule instance starts or stops.
channel
A logical pathway on which messages are sent on a messaging framework.
component
See service component
configuration builder
A class that knows how to parse a given configuration file. The default configuration builder
is the org.mule.config.MuleXmlConfigurationBuilder class that knows how to parse a
Mule XML configuration file.
connector
The heart of a transport that maintains the configuration and state for the transport.
100
Glossary
endpoint
A configuration entity specifying how and where a message should be routed. The endpoint
is configured in an inbound or outbound router and specifies where the message should be
sent or from where it should be received, using which transport (and optionally which
connector in that transport), and which filters should be applied before routing the message.
Endpoints can also be defined globally instead of in a specific router,.
event
See message
filter
Specifies logic for determining which messages are routed to a component. You can set filters
on an inbound router to filter which messages that service component can receive, or you
can set filters on an outbound router to indicate how you want to route messages after they
have been processed by the service component.
Galaxy
See Mule Service Registry
HQ
See Mule Management Console
inbound router
A Java class that you configure in the Mule configuration file to determine how a service
component will receive messages. The inbound router includes an endpoint that indicates
where the messages will come from.
101
Glossary
interceptor
A Java class that is used to intercept message flow into a service component. An
interceptor can be used to trigger or monitor events or interrupt the flow of the message.
management console
See Mule Management Console
message
A packet of data that can be handled and sent between applications on a specific channel.
Data is always wrapped in a message before it is transported by Mule. A message has a header,
which contains metadata about the message (such as the sender information), and the body,
which contains the actual data.
message receiver
A Java class used by a connector to read the incoming data, package it as a message, and
passes it to a service components inbound router. The message receiver can use a
transformer if necessary to convert the data.
message dispatcher
A Java class used by a connector to receive the messages and routing instructions from an
outbound router and send the message to the next service component.
Mule Enterprise
The enterprise version of Mule, available for 30-day trial download from
http://www.mulesource.com/download. Mule Enterprise includes full development
cycles, testing, technical support, maintenance releases and hot fixes, and management and
monitoring tools from MuleSoft. If you are deploying Mule in a mission-critical
102
Glossary
environment, want to ensure that you always have a stable, high-quality release, and want
additional tools for managing and monitoring your deployment, you should purchase a
subscription of Mule Enterprise.
Mule Manager
Manages the Mule objects, including connectors, endpoints, and transformers. The Mule
Manager constructs these objects and provides them to the service components in the
Mule Model. Each Mule instance has one Mule Manager and one or more Mule Models.
Mule Model
A service container that hosts the service components and manages their runtime
behavior.
103
Glossary
outbound router
A Java class that you configure in the Mule configuration file to determine how a service
component will dispatch messages. The outbound router can include an endpoint to
indicate where the messages should go next, or if no endpoint is configured, it returns the
completed message back to the sender.
POJO
An acronym for plain old Java object, a POJO is a simple Java object, not an enterprise
JavaBean. One advantage of Mule is that your service components can be simple POJOs,
which Mule then wraps and exposes as services.
provider
See transport
queue
See channel
router
A Java class that determines where and how messages are transported between applications.
See also inbound router and outbound router
SEDA
See Staged Event-driven Architecture (SEDA)
service component
A POJO, Spring bean, Java bean, or web service containing the business logic for processing
data in a specific way. Mule simply manages the service component, bundles it with
configuration settings and exposes it as a service, and ensures that the right information is
passed to and from it based on the settings you specified for the service in the Mule
configuration file. In early versions of Mule, service components were called Universal
Message Objects, and UMO is still part of the nomenclature in the Mule APIs today.
104
Glossary
service registry
See Mule Service Registry
transformer
A Java class that transforms message payloads (data) to and from different types.
transport
A construct that handles and carries messages on a specific messaging protocol, such as
HTTP, moving the message from one service component to another and transforming
the data as needed along the way
transport provider
See transport
UMO
See service component
Wire Tap
A router that makes copies of messages and forwards them to another endpoint. It can either
forward a copy of all messages that it receives or it can be configured to use a filter and send a
sub-set of these messages only. This router will not prevent messages from being delivered to
service components. See also interceptor.
105
Index
C
ActiveMQ 29
adapters 12
administrator
what to read in this guide 7
aggregating messages 15
ANT_HOME environment variable 33
Apache CXF 29
application developer
what to read in this guide 7
application layer 47
applications
creating manually 54
creating with Mule IDE 51
modifying 60
architect
what to read in this guide 7
architecture
about 12
asynchronous message style 76
asynchronous reply routers 75
asynchronous request-response message
style 78
audience for this guide 6
B
basic usage 47
building Mule 31
business analyst
what to read in this guide 7
business logic
in the Mule architecture 13
catch-all strategies 75
chaining routers 15
channels
about 11
CIO
what to read in this guide 7
client/server topology 21
community release
about 31
installing 36
compression tools 31
configuring endpoints 18
configuring Mule
tutorial 54
configuring routers 18
CXF 29
D
data 15
logical flow in Mule 18
processing 13
debugging applications 93
decision makers
what to read in this guide 7
destinations
see endpoints
developer
what to read in this guide 7
developer release 31
director of Software Architecture
what to read in this guide 7
dispatching messages 15
distributed topology 22
65
Index
inbound routers 75
about 14
installing Mule
about 30
community release 36
Enterprise 35
snapshot release 36
installing multiple Mule instances 37
integrating applications
with endpoints 17
integration developer
what to read in this guide 7
integration layer 47
introduction to Mule 9
IT manager
what to read in this guide 7
documentation
typographic conventions 8
downloading Mule
about 30
E
Eclipse 38
EJB 21
endorsing the JDK 44
endpoints
about 17
configuring 18
Enterprise edition
about 31
Enterprise Integration Patterns
about 12
Enterprise Service Bus (ESB) 10, 12
enterprise service network 21
ESB
see Enterprise Service Bus
examples 51
exercises 51
J
Java beans
creating service components from 14
Java Developer Kit (JDK) 32
JAVA_HOME environment variable 33
JAXP 44
JDK 32
JMS
in ESBs 21
F
failover
distributing Mule for 22
file systems 21
filtering messages 15
in endpoints 18
filters 75
K
knowledge base 8
L
G
GZip 31
H
hub-and-spoke topology 21
I
IBM WebSphere MQ 21
implementing Mule 21
66
M
mainframe applications 21
Maven 33
MAVEN_HOME environment variable 33
message routing 75
Index
message styles 75
messages
about 11
aggregating 15
dispatching 15
filtering 15
payload 15
protocols 15
receiving 14
resequencing 15
routing 14
messaging framework
about 11
MSMQ 21
Mule architecture
about 12
Mule community release 31
Mule configuration file. 88
Mule Enterprise 31
installing 35
Mule IDE 86
tutorial 51
Mule snapshot release 31
Mule User Guide 30
MULE_BASE environment variable 38
MULE_HOME environment variable 34, 38
MuleSoft Technical Support 8
multiple instances
installing 37
multiple instances of Mule 22
O
operating systems 32
outbound router
about 14
outbound routers 75
P
PATH environment variable 34
payload 15
peer network topology 21
pipeline topology 21
Q
queues
about 11
quick start 7
R
receiving messages 14
request-response message style 76
resequencing messages 15
routers
about 14
chaining 15
configuring 18
routing messages 14
RSS feed
service components and 15
S
scalability of mule 21
sending messages 14
service components
about 14
routing messages between 14
service-oriented architecture
about 13
services
about 13
setup_local_instance script 37
snapshot release 31
installing 36
SOA
see service-oriented architecture
sockets 21
67
Index
source code 31
spaces
in the target path 34
Spring beans
creating service components from 14
support 8
Synchronous message style 77
Xerces 44
X-Windows
downloading without 37
T
technical support 8
testing applications 89
TIBCO Rendezvous 21
topologies 21
transformers
about 15
transport layer 47
transports
about 15
configuring endpoints for 17
tutorial 51
typographic conventions 8
U
uniform resource indicators (URI)
in endpoints 17
URIs
in endpoints 17
V
versions
switching 93
W
web services
creating service components from 14
WinZip 31
X
Xalan, JDK
endorsing 44
68
30 Maiden Lane
Suite 500
San Francisco, CA 94108
Phone: 877-MULE-OSS (877-685-3677)
Fax: 415-227-0842
www.mulesoft.com