Space DetailsKey: Name: Description: Creator (Creation Date):
MULE2USER Mule 2.x User GuideMule Users Guide for the 2.x release
line
ross (Jan 30, 2008)
Last Modifier (Mod. Date): tcarlson (Apr 15, 2008)
Available Pages Configuring a Mule Instance Escape URI
Credentials Home 3.x Features Using JSON Configuring Encoding Hot
Deploying Mule Applications Deploying Mule as a Service to Tomcat
Starting Mule with the Configuration About Mule Configuration About
Configuration Builders Configuring Properties Mule High
Availability Storing Objects in the Registry About Transports
Available Transports BPM Transport CXF Transport Building a CXF Web
Service CXF Transport Configuration Reference Enabling
WS-Addressing Enabling WS-Security Supported Web Service Standards
Using a Web Service Client as an Outbound Endpoint Using a Web
Service Client Directly Using HTTP GET Requests
Using MTOM EJB Transport Email Transport File Transport FTP
Transport HTTPS Transport HTTP Transport IMAPS TransportPage 1
Document generated by Confluence on Feb 07, 2010 23:59
IMAP Transport JDBC Transport JDBC Transport Configuration
Reference JDBC Transport Examples JDBC Transport Performance
Benchmark Results Jetty Transport Jetty SSL Transport JMS Transport
Tibco EMS Integration JBoss Jms Integration Fiorano Integration
OpenJms Integration SwiftMQ Integration Sun JMS Grid Integration
SonicMQ Integration SeeBeyond JMS Server Integration Open MQ
Integration ActiveMQ Integration
WebLogic JMS Integration Mule MSMQ Transport Mule WMQ Transport
Multicast Transport POP3S Transport POP3 Transport Quartz Transport
RMI Transport Servlet Transport SMTPS Transport SMTP Transport SOAP
Transport SSL Transport STDIO Transport TCP Transport UDP Transport
VM Transport WSDL Connectors
XMPP Transport Bootstrapping the Registry Choosing the Right
Topology Configuration Overview Configuration Reference
Asynchronous Reply Router Configuration Reference Page 2
Document generated by Confluence on Feb 07, 2010 23:59
Catch-all Strategy Configuration Reference Component
Configuration Reference Endpoint Configuration Reference Exception
Strategy Configuration Reference Filters Configuration Reference
Global Settings Configuration Reference Inbound Router
Configuration Reference Model Configuration Reference Notifications
Configuration Reference Outbound Router Configuration Reference
Properties Configuration Reference Security Manager Configuration
Reference Service Configuration Reference
Transactions Configuration Reference Configuring Endpoints Mule
Endpoint URIs Configuring a Transport Configuring Retry Policies
Configuring Logging Configuring Queues Configuring Security
Component Authorization Using Acegi Component Authorization Using
Spring Security Configuring the Acegi Security Manager Configuring
the Spring Security Manager Encryption Strategies SAML Module
Setting up LDAP Provider for Acegi Setting up LDAP Provider for
Spring Security
Upgrading from Acegi to Spring Security Controlling the
Infrastructure with the Service Registry Creating a Custom XML
Namespace Creating Custom Routers Creating Transports Transport
Archetype Transport Service Descriptors Deployment Scenarios
Deploying Mule to WebLogic Deploying Mule to WebSphere Embedding
Mule in a Java Application or Webapp JBoss Integration Mule as
MBean
Document generated by Confluence on Feb 07, 2010 23:59
Page 3
Developing Service Components Entry Point Resolver Configuration
Reference Error Handling Functional Testing Installing a Standalone
Mule Instance Installing Upgrades and Hot Fixes Internationalizing
Strings Introduction to Extending Mule Introduction to Testing Mule
Models Mule Agents JMX Management Mule Server Notifications
Profiling Mule Resource Adapter Suggested Reading Third-party
Software in Mule Transaction Management Tuning Performance Unit
Testing Using Filters Using IDEs Using the Mule Management Console
Installing the Management Console with an External Database
Management Console Agent Settings Using Mule Modules Acegi Module
JAAS Module JBoss Transaction Manager Scripting Module Spring
Extras Module SXC Module XML Module DomToXml Transformer JXPath
Extractor Transformer XmlObject Transformers XmlToXMLStreamReader
Transformer XPath Extractor Transformer
XSLT Transformer Using Mule with Spring Sending and Receiving
Mule Events in Spring Spring Application Contexts
Document generated by Confluence on Feb 07, 2010 23:59
Page 4
Using Spring Beans as Service Components Using the Mule Client
Using the Mule RESTpack Architecting RESTful HTTP applications
Making Sense of REST Using Transformers Creating Custom
Transformers Transformers Configuration Reference XmlPrettyPrinter
Transformer Using Web Services Axis Axis SOAP Styles Axis SOAP
Transports Axis Transport Axis Web Services and Mule
Configuring Axis Proxying Web Services Using .NET Web Services
with Mule
Web Service Wrapper Working with Services Configuring Components
Configuring Java Components Using Interceptors Configuring the
Service MEPs Mule Messaging Styles Using Message Routers Inbound
Routers Outbound Routers Asynchronous Reply Routers Catch-all
Strategies
Example Archetype Jaas Security
Component Bindings About the XML Configuration File
JavaRebel Integration Module Archetype PGP Security Project
Archetype Streaming Using Expressions Creating Expression
Evaluators Expressions Configuration Reference Page 5
Document generated by Confluence on Feb 07, 2010 23:59
Configuring a Mule InstanceThis page last changed on Jun 30,
2009 by jwheeler.
Configuring a Mule InstanceA Mule configuration file can become
an elaborate tree of elements, however, the basic things to
configure at the top level are: Connectors - Non-default
configuration of any transports used Endpoints - Global definition
of endpoints is encouraged to clearly describe where your
integration channels are Transformers - Transformers may be defined
globally and later referenced from your services Filters - Filters
may be defined globally and later referenced from your services
Models - One or more models that logically group together your
services Services - One or more services that wrap your components
and configure routers, endpoints, transformers, and filters
specifically for that service
Following is an example of a simple Mule configuration file:
Document generated by Confluence on Feb 07, 2010 23:59
Page 6
Advanced ConfigurationOther, more advanced things you may
configure at this level: Agents - Agents are typically used for
cross-cutting concerns such as logging or management Notifications
- Be notified upon certain lifecycle events Security Manager -
Authenticates requests based on one or more security providers
Transaction Management - Mule transactions are configured on
inbound endpoints, where an endpoint can be configured to start a
new transaction or join an existing one. Global Configuration
Options - Miscellaneous global settings Global Properties -
Placeholder values
Document generated by Confluence on Feb 07, 2010 23:59
Page 7
Escape URI CredentialsThis page last changed on Nov 26, 2008 by
jackie.wheeler.
Escape Your Credentials If you use a URI-style endpoint and you
include the user name and password, escape any characters that are
illegal for URIs, such as the @ character. For example, if the user
name is [email protected], you should enter it as user%40myco.com.
Document generated by Confluence on Feb 07, 2010 23:59
Page 8
HomeThis page last changed on Dec 17, 2009 by jwheeler.
Welcome to the documentation for Mule ESB. Some of the
documentation on this site is under construction for the current
release. If you have any feedback on the content, or would like to
sign up to become a site contributor or editor, please contact us.
3.x snapshots are now available! For a list of features in progress
for 3.x, click here.
Getting Started(Click the arrow to expand the topics from the
Getting Started guide, including an introduction to Mule, steps to
get started, and migration information.) Click here to expand...
Introduction What is Mule? Understanding the Messaging Framework
Understanding the Mule Architecture Understanding the Logical Data
Flow Integrating Mule into Your Environment Summary Getting Started
Quick Start Where Should I Go Next? Download Page Installing Mule
Running Mule Setting Up Eclipse for Use with Maven Examples
Tutorial Basic Usage What's New in This Release Migrating Mule
Using Transports About Transports Available Transports
Configuring a Transport
Mule Deployment Architecture Deployment Scenarios Choosing the
Right Topology Hot Deploying Mule Applications Mule High
Availability
Mule Administration Controlling the Infrastructure with the
Service Registry Managing and Monitoring Deployments Using the Mule
Management Console JMX Management
Extending Mule Using Mule Configuration Overview About Mule
Configuration About the XML Configuration File About Configuration
Builders Starting Mule with the Configuration Working with Services
About Models Configuring the Service Configuring Endpoints Using
Filters Using Transformers Using Mule Data Integrator Using Message
Routers Mule Messaging Styles Configuring Components Using Web
Services Introduction to Extending Mule Creating Transports
Creating a Custom XML Namespace Creating Expression Evaluators
Bootstrapping the Registry Internationalizing Strings Using
MuleForge
Testing Mule Introduction to Testing Mule Functional Testing
Unit Testing Running Benchmark Tests Profiling Mule
Document generated by Confluence on Feb 07, 2010 23:59
Page 9
Using Spring Beans as Service Components Customizing Behavior
Developing Service Components Creating Custom Filters Creating
Custom Transformers Creating Custom Routers Using Interceptors
Configuring Retry Policies Beyond the Basics Configuring Encoding
Configuring Properties Using Expressions Using Mule with Spring
Using the Mule RESTpack Using Mule Modules Streaming Error Handling
Storing Objects in the Registry Configuring Security Using the Mule
Client Tuning Performance Configuring Queues Managing Transactions
Using Agents Mule Server Notifications Configuring Logging Mule
Cookbook
Development Tools Developer's Guide Using IDEs Mule IDE User
Guide Using Maven
ReferenceGlossary Configuration Reference API Reference Test API
Reference Third-party Software in Mule Suggested Reading
Distribution Contents PDF versions of the User's Guide for offline
reading Documentation for Previous Releases Mule 1.x Getting
Started Mule 1.x User Guide
Document generated by Confluence on Feb 07, 2010 23:59
Page 10
3.x FeaturesThis page last changed on Dec 17, 2009 by
jwheeler.
3.x Features[ Hot Deployment ] [ Additional New Features and
Fixed Issues ] The next generation of Mule ESB, version 3.x, is
under development. You can download 3.x snapshots here. Keep in
mind that these features are under development, and snapshots
contain the "bleeding edge" code that has not been thoroughly
tested. Therefore, snapshots are great for development but should
not be used in production. There is no support for 3.x features
until Mule ESB 3.x has been released for general availability (GA).
This page describes each of the 3.x features and the milestone in
which it is available.
Hot Deployment(As of milestone 1) You can now modify your
configuration files and custom classes and have them reloaded
without having to restart Mule. To take advantage of this feature,
do the following: 1. Create a directory for your application
anywhere under the $MULE_HOME/apps directory and create a
subdirectory called lib. For example, if your application is called
MyApp, you would create $MULE_HOME/apps/MyApp and
$MULE_HOME/apps/MyApp/lib. 2. Save your application as a JAR file
and copy it to the lib directory (e.g., $MULE_HOME/apps/MyApp/
lib). 3. Copy your configuration file to your application's
directory (e.g., $MULE_HOME/apps/MyApp). 4. After making a change
to your application, simply update the timestamp on the
configuration file using the touch command (if available on your
operating system) or by saving your configuration file (e.g., add
and delete a character, and then save). Mule checks every three
seconds for updated configuration files under the $MULE_HOME/apps
directory, and when it finds one, it reloads the configuration file
and the JARs in that applications lib directory. Therefore, if you
want to change one of your custom classes, you modify and rejar it,
copy the updated JAR to the lib directory, and then touch or save
the configuration file. Currently, Mule checks only the first
configuration file in your application's directory, so right now
hot deployment works best with applications that have a single
configuration file. For an example of how hot deployment works, see
the Hot Deployment blog post.
Additional New Features and Fixed IssuesMilestone 1
Jira Issues Priority Type Key MULE-4199 component Summary
Examples / Tutorials Errorhandler example logic is broken - not
routing messages to Email and JMS endpoints Transport: HTTP/
Servlet transport HTTPS has headers which shouldn't be there Core:
API Synchronous inbound endpoint with PassThroughComponent and
synchronous
MULE-4246
MULE-4248
Document generated by Confluence on Feb 07, 2010 23:59
Page 11
MULE-3615
MULE-3611 MULE-4044
MULE-3625
MULE-4245
MULE-4324 MULE-4323
MULE-64
MULE-115 MULE-340 MULE-399 MULE-114
MULE-3953
MULE-4226
MULE-4222 MULE-4225
MULE-4229
MULE-4295
MULE-4330 MULE-4349
outbound endpoint should return a NullPayload if outbound
endpoint has no result Core: Configuration Move custom-agent
element to the core schema Transport: CXF /
MultipleWsdlCxfCallsTestCase XFire fails Core: (other) Remove
version numbers from schema namespaces Transport: JDBC Registering
transaction manager causes non xa transaction to fail Transport:
File java.io.NotSerializableException: java.io.FileInputStream with
Transport: (new Add Cometd Ajax transport) support to Mule Modules:
(other) Add the Json transformers project to Mule Transport: TCP /
Add NIO based UDP / SSL / socket Provider Multicast Transport: (new
Add a JGroups transport) provider Transport: (new Add a transport
transport) provider for FIX Core: Deployment / A component
Federation repository for Mule Core: Deployment / Mule-based
Federation Clustering support for mule instances Modules: Spring,
The base XSD Modules: XML, XSLT, filterType has an XPath attribute
'not' which isn't used Core: API, Core: Mule 2 Expression
Configuration regex doesn't detect all expresssions Core: API
CorrelationEventResequencer must not be abstract Transport: CXF /
Don't add MULE XFire SOAP headers unless specified Core: Routing /
Outbound Routing Filters breaks order created by Core:
Configuration Update jms config schema to support exception
listener registration flag Modules: XML, XSLT, Add XQuery support
XPath to the Xml module Transport: Email The MailMesageAdapter
should use the
Document generated by Confluence on Feb 07, 2010 23:59
Page 12
MULE-4357
MULE-4346
MULE-4135
MULE-4321
MULE-3671
MULE-3673
MULE-4067
MULE-4097
MULE-4099
MULE-4134
MULE-4157
MULE-4146
MULE-4313
MULE-4354
MailMessage as the payload Examples / Tutorials New Example: GPS
Walker. Plots GPS coords generated by Mule on a map in the browser
Transport: Email The secure email schemas require that the user set
TLS and client store info. This is unnessary for many email servers
(certainly the public servcies) Core: Routing / Nested routers /
Filters bindings do not correctly handle NullPayload Core:
Transports Add an 'initialStateStopped' flag to connectors to allow
connectors to be started based on external events Modules: Security
KeyBasedEncryptionStrategyTestC (Acegi, PGP, JAAS, disabled others)
Modules: Security KBEStrategyUsingEncryptionTrans (Acegi, PGP,
JAAS, is disabled others) Tools Improve template for
MessageReceiver class doesn't work for Polling Receivers Core:
Configuration, Support declarative Core: Deployment / Mule serverId
Federation configuration when embedded in webapp Core: (other)
FunctionalTestCase closes JMS session too early with transactions
Tools Modify transport archetype to add transformMessage()
Transport: CXF / Support sending XFire whole SOAP Envelope with CXF
proxies Transport: File Global file endpoint ignores the filename
wildcard filter Core: Routing / configuring Filters, Transport:
jms:transaction on JMS inbound-endpoint throws: The session is
closed(JMS Code: null) (javax.jms.IllegalStateException) Core:
Bootstrap / Custom expression Java Service evalutor configured
Document generated by Confluence on Feb 07, 2010 23:59
Page 13
MULE-3512
Wrapper, Core: Configuration Transport: JDBC
MULE-3862
MULE-4289
MULE-4304
MULE-478
MULE-3847 MULE-4231
MULE-4322
MULE-4355
MULE-4374
MULE-4348
MULE-4009
MULE-4356
MULE-3991
MULE-4301
MULE-4303
MULE-4065 MULE-4236
declaratively is ignored JDBC Dispatcher does not copy message
properties over Core: Lifecycle Mule's lifecycle is broken after
XML parser exception on startup Transport: CXF / ClassCastException
XFire when defing CXF logging interceptors on CXF web service proxy
Core: (other), Improve registry Core: API, Core: lookups to
Deployment / select(type) Federation, Core: instead of Lifecycle
select(all).filter(type) Core: Deployment / A virtual file system
Federation to allow single location deployment of a Mule
application Build: Distributions Upgrade YourKit integration to
v8.0.1 Transport: CXF / Add a namespace XFire attribute to the CXF
endpoint schema Core: Configuration Custom security filter element
missing Core: Containers Create Message Data Transfer objects that
can be used to create readable serialized messages Transport: JMS
Support URI compliant definition of Jms Topics Transport: (other)
The servlet endpoints should have a path attribute Transport: Email
backupFolder attribute xsd needs to be updated Core: Transformers
Create Map to Bean and Bean to Map transformers Core: Expressions
Expression evaluator's parse is confused by 'strange' values
Transport: JMS returnClass in ObjectToJMSMessage should be used to
Transport: Email ObjectToMimeMessageTransformer ignores attachment
file names Tools Typos in archetype prompts Build: Distributions
mule-module-springsecurity is bundled in
Document generated by Confluence on Feb 07, 2010 23:59
Page 14
MULE-4347
MULE-4299
MULE-4363
lib/opt instead of lib/ mule Core: Configuration Make the
MuleContext available on the servlet context Core: Transformers the
'returnClass' attribute on transformers needs to allow Array return
type. Core: Expressions Header and Attachement Expresion evaluators
should use "*" to denote all
Document generated by Confluence on Feb 07, 2010 23:59
Page 15
Using JSONThis page last changed on Jan 04, 2010 by
jwheeler.
Using the JSON ModuleThis page is under construction. The JSON
module will be available as of Mule 3.x. JavaScript Object Notation
(JSON) is a lightweight computer data interchange format. It is a
text-based, human-readable format for representing simple data
structures and associative arrays (called objects). Mule uses the
Jackson Framework to marshal and unmarshal JSON to Java
objects.
Enabling the JSON ModuleOnce you have included the JSON module
in your project or in the Mule distribution, you can use it by
adding the JSON namespace to your Mule XML configuration file:
You can now start using JSON transformers and filters in your
configuration.
Transformers Converts a java object to a JSON encoded object
that can be consumed by other languages such as Javascript or Ruby.
The JSON engine can be configured using the jsonConfig attribute.
This is an object reference to an instance of:
net.sf.json.JsonConfig. This can be created as a spring bean. Users
can configure a comma-separated list of property names to exclude
or include i.e. excludeProperties="address,postcode". The
returnClass for this transformer is always java.lang.String, there
is no need to set this.
Attributes
Name jsonConfig-ref
Type string
Required no
Default
Description The JSON engine can be configured using the
jsonConfig attribute. This is an object reference to an instance
of:
Document generated by Confluence on Feb 07, 2010 23:59
Page 16
net.sf.json.JsonConfig. This can be created as a spring bean.
excludeProperties string no
Users can configure a comma-separated list of property names to
exclude i.e. excludeProperties="address,pos
includeProperties
string
no
Configure a commaseparated list of property names to include
i.e. includeProperties="name,email"
sourceClass
string
no
Restrict the accepted source class object to a specific type. If
not set the transformer will handle all source types. Note that if
you need to specify an array type you need to postfix the class
name with '[]'. For example, if you want to ensure the transformer
only accepts an Orange[], you set the sourceClass to
'org.mule.tck.testmodels.fruit.O
Child Elements
Name
Cardinality
Description
ExampleIn this example, we configure a transformer to convert
from a JavaBean to a JSON encoded string. The transformer by
default will encode any JavaBean, but we have restricted the object
type it can handle by setting sourceClass to
org.mule.tck.models.fruit.Orange. We also exclude the brand and
radius properties, so these will not be serialized.
A transformer that will convert a JSON encoded object graph to a
java object. The object type is determined by the 'returnClass'
attribute. Note that this transformers supports Arrays and Lists.
For example, to convert a JSON string to an array of
org.foo.Person, set the the returnClass=[Lorg.foo.Person; . The
JSON engine can be configured using the jsonConfig attribute. This
is an object reference to an instance of: net.sf.json.JsonConfig.
This can be created as a spring bean.
Attributes
Name jsonConfig-ref
Type string
Required no
Default
Description The JSON engine can be configured using the
jsonConfig attribute. This is an object reference to an instance
of: net.sf.json.JsonConfig. This can be created as a spring
bean.
Child Elements
Name
Cardinality
Description
ExampleIn this example, we convert JSON data to JavaBeans and
use a powerful feature of Jackson called mixins. Mixins allow you
to add annotations to an interface or abstract class that can then
be mixed in with the object that will get populated with the JSON
data. Mixins are useful when you do not control the bean class.
Document generated by Confluence on Feb 07, 2010 23:59
Page 18
Converts a JSON encoded object representation in to an XML
representation. Each property and enclosing element are wrapped in
XML elements these generated element names can be set on the
transformer. Names can be configured for Object elements, array
elements and value elements. The returnClass for this transformer
is always java.lang.String, there is no need to set this.
Attributes
Name
Type
Required no
Default
Description The XML element name to use for representing objects
in the JSON ecoded object. The default is 'o'. The XML element name
to use for representing objects in the JSON ecoded object. The
default is 'a'. The XML element name to use for representing object
values (properties) in the JSON ecoded object. The default is
'e'.
objectElementName name (no spaces)
arrayElementName
name (no spaces)
no
valueElementName
name (no spaces)
no
Document generated by Confluence on Feb 07, 2010 23:59
Page 19
Child Elements
Name
Cardinality
Description
Filters A filter that will determine if the current message
payload is a JSON encoded message.
Attributes Child Elements
Name Name
Type Cardinality
Required Description
Default
Description
ExampleThere are no configuration parameters for this
filter.
Document generated by Confluence on Feb 07, 2010 23:59
Page 20
Configuring EncodingThis page last changed on Sep 14, 2009 by
jwheeler.
Configuring EncodingMule ESB supports multibyte messages. Most
modern transports like SMTP, HTTP, and SOAP enclose encoding
information in their messages as metadata. For other transports
like File, FTP, and JMS, you must configure the encoding, either on
the endpoint or globally for the Mule instance. If you do not
specify the encoding explicitly, Mule uses the default encoding of
UTF-8.
Endpoint EncodingTo configure the encoding on the endpoint, you
use the message properties transformer as follows:
Note that the encoding attribute on the endpoint element does
not currently work. Use the transformer as described above
instead.
Global EncodingTo configure the encoding globally for a Mule
instance, you specify it as a Java system property in conf/
wrapper.conf:
wrapper.java.additional.=-Dmule.encoding=Windows-31J
Document generated by Confluence on Feb 07, 2010 23:59
Page 21
Hot Deploying Mule ApplicationsThis page last changed on Jan 27,
2010 by jwheeler.
Hot Deploying Mule Applications[ How it Works ] [ Preparing the
Configuration File ] [ Deploying Mule as a Service ] [ Packaging
the Mule Application ] [ Deploying the Mule Application ] Hot
deployment is currently in beta and is available as a preview
release in the enterprise edition of Mule ESB 2.2.3. Hot deployment
is not yet available in the Mule 3.x CE snapshots. Hot deploying
your Mule applications allows you to update your configuration
files and/or transformers, filters, or component implementations
without restarting Mule. When you hot deploy a Mule application,
only that application will stop/start, and any other Mule
applications that are deployed will continue to run as before. Hot
deployment is currently supported with: JBoss 4.2.x (JBoss 5.x is
not currently supported) Geronimo 2.1.x Tomcat 6.0.x MuleSoft Tcat
Server 6
How it WorksA Mule application is one or more configuration
files packaged up with any dependencies that are not already
provided by Mule. In a hot deployment scenario, each Mule
application shares a single Mule instance running in an application
server or web container. To hot deploy Mule applications, you do
the following: Configure Mule to run as a service in the container
Package your Mule applications as WAR files so that you can deploy
them as web applications When you deploy the WAR file, Mule reads
the Mule configuration file and creates and starts all the required
objects just as when running Mule standalone. When you undeploy a
Mule application, only the objects created and started for that
Mule application are stopped and disposed of without affecting any
other applications sharing the same Mule instance. In this way,
multiple Mule applications can be deployed, undeployed, and
redeployed independently with no downtime for any other services.
Two of the key advantages of using a single shared Mule instance
are: A greatly reduced memory footprint over using multiple Mule
instances. The ability to share objects across applications. For
example, you could have a single webapp that defines the
connectors, filters, and transformers that are then used by the
other webapps. Note: If you share objects across applications, be
sure to first deploy the webapp that creates the shared objects,
and then deploy the remaining webapps that use those objects.
Preparing the Configuration FileWhen defining the scope of your
applications and their configurations, keep the following points in
mind: Each Mule application uses an instance of Mule that is
already started. Therefore, your application cannot modify anything
in the element, including attributes and child elements, which are
required to be configured before Mule startup. If you need to
modify these settings, you must modify them on the Mule instance
and restart it. If you don't explicitly define the connector that
should be used by an endpoint, and another web application that is
already deployed defines a connector that supports the same
protocol, that existing connector defined will be used.
Document generated by Confluence on Feb 07, 2010 23:59
Page 22
Deploying Mule as a ServiceTo deploy Mule as a service to an
application server (JBoss, Geronimo), you simply deploy the JCA
resource adapter distribution. You don't need to open or repackage
the resource adapter archive but can just deploy it as unless you
need to edit the MuleConfiguration properties or the default Mule
configuration file. You can also safely ignore the "EJB
Configuration" section. To deploy Mule as a service to Tomcat or
Tcat Server, see Deploying Mule as a Service to Tomcat.
Packaging the Mule ApplicationEach Mule application you set up
for hot deployment consists of one or more configuration files plus
supporting custom classes, all packaged as a standard web
application (WAR deployment archive file). You can create the WAR
using your favorite IDE or build tool as you would create any
standard web application. To enable Mule to find and load your
configuration, you must include a web.xml file that points to your
configuration files and to the deployable listener, as shown
below:
MuleEchoExample Mule Echo Example org.mule.config
echo-cxf-config.xml
org.mule.config.builders.DeployableMuleXmlContextListener
Deploying the Mule ApplicationYou deploy your Mule application
WAR file in exactly the same way you deploy any web application on
the application server or web container you are using. That is, you
can use a web administration console, command-line deployment tool,
Maven, or your IDE. For example, if you are deploying to Tomcat,
you simply copy your WAR to the Tomcat webapps directory. For more
information, see the documentation for your application server or
web container. If your Mule applications share objects, be sure to
first deploy the application that creates those objects, and then
deploy the applications that use them.
Document generated by Confluence on Feb 07, 2010 23:59
Page 23
Deploying Mule as a Service to TomcatThis page last changed on
Jan 27, 2010 by jwheeler.
[ Deploying Mule as a Service to Tomcat ] [ Installing Mule in
Tomcat ] [ Copying the Mule Application Files ] [ Hot Deploying
Mule Applications ]
Deploying Mule as a Service to TomcatThis page describes how to
install Mule as a service in Apache Tomcat and set up your Mule
applications for hot deployment. For more information on hot
deploying Mule applications, see Hot Deploying Mule
Applications.
Installing Mule in TomcatTo install Mule in Tomcat so that you
can hot deploy your Mule applications, you take the following
steps: 1. Download and install Apache Tomcat 6 from the Apache web
site following the standard installation instructions. 2. In the
Tomcat home directory, add the following line to the
conf/server.xml file: 3. Copy the contents of the Mule lib folder
with all its subdirectories except /boot to the mule-libs/
directory under your Tomcat home directory (create one if
necessary). You do not need to flatten the directories. 4. Copy the
mule-module-tomcat-.jar file to the mule-libs/mule/ directory under
your Tomcat home directory (if it is not there already). 5. Copy
the following libraries from your Mule lib/boot/ directory to your
Tomcat mule-libs/opt/ directory: jcl104-over-slf4j-1.5.0.jar
log4j-1.2.14.jar slf4j-api-1.5.0.jar slf4j-log4j12-1.5.0.jar 6. In
the Tomcat conf/catalina.properties file, add the following to
common.loader (precede with a comma to separate it from existing
values):
${catalina.home}/mule-libs/user/*.jar,${catalina.home}/mule-libs/mule/*.jar,
${catalina.home}/mule-libs/opt/*.jar
Copying the Mule Application FilesAfter you package your
configuration files and custom Java classes in a WAR file (see Hot
Deploying Mule Applications), copy your Mule applications WAR files
to the Tomcat /webapps directory.
Hot Deploying Mule ApplicationsAfter you have copied the WAR
file for your Mule application to the Tomcat /webapps directory,
Tomcat deploys it. If you need to make a change to a configuration
or Java file in the webapp, simply modify the file in the exploded
directory under the Tomcat /webapps directory, and then touch the
web.xml file (or you can simply add and delete a space in the file
and then save it) to trigger Tomcat to redeploy the application.
Alternatively, you could modify the source files, repackage them as
a WAR, and drop the new WAR into the /webapps directory to trigger
Tomcat to redeploy the application.
Document generated by Confluence on Feb 07, 2010 23:59
Page 24
Starting Mule with the ConfigurationThis page last changed on
Sep 14, 2009 by jwheeler.
Staring Mule with the ConfigurationWhen you start Mule ESB from
the command line, you simply specify the configuration file(s) with
the config parameter:
mule -config foo-config.xml
mule -config foo-config.xml,bar-config.xml
If you want to start Mule by calling it from your code, you
specify the configuration file as a parameter to the configuration
builder:
MuleContext context = new
DefaultMuleContextFactory().createMuleContext(new
SpringXmlConfigurationBuilder("foo-config.xml"));
context.start();
For information on setting system properties from your code, see
Configuring Properties. For information on accessing the existing
configuration from your code after startup, see Accessing the
Configuration Programmatically. For more information on Mule
configuration files, see About the XML Configuration File and
Scripting Module.
Document generated by Confluence on Feb 07, 2010 23:59
Page 25
About Mule ConfigurationThis page last changed on Sep 14, 2009
by jwheeler.
About Mule Configuration[ Overview of Configuration Elements ] [
Global Configuration Settings ] [ Accessing the Configuration
Programmatically ] By default, Mule ESB starts up with a simple
configuration in which only some system-level services are
configured. You must configure services, transformers, and the rest
of the elements required for your application. Following is an
introduction to configuring Mule ESB via the Spring XML file. For
details on this file, see About the XML Configuration File. For
information on starting Mule with the configuration file or
accessing the configuration programmatically, see Starting Mule
with the Configuration.
Overview of Configuration ElementsA Mule ESB configuration file
is a tree of elements, as shown in the following illustration:
Following is a brief description of these elements: Mule Global
Configuration - Global settings, such as the default transaction
time-out, that apply to the entire Mule configuration Connectors -
Non-default configuration of any transports used Endpoints - Define
the channel and address or path where messages are sent or
received. You can define them globally and use them in multiple
services. Transformers - Convert data from one format to another.
You can define them globally and use them in multiple services.
Filters - Filter out the messages that don't match specific
criteria. You can define them globally and use them in multiple
services. Models - One or more models that logically group together
your services. Services - One or more services that wrap your
components (business logic) and configure routers, endpoints,
transformers, and filters specifically for that service Following
is an example of a simple Mule configuration file:
Document generated by Confluence on Feb 07, 2010 23:59
Page 26
Other, more advanced things you may configure at this level:
Security Manager - Authenticates requests based on one or more
security providers Agents - Agents are typically used for
cross-cutting concerns such as logging or management Notifications
- Allow you to be notified upon certain lifecycle events
Transaction Management - Mule transactions are configured on
inbound endpoints, where an endpoint can be configured to start a
new transaction or join an existing one. Properties - Property
placeholders, message properties, and system properties.
Global Configuration SettingsYou can configure global
configuration settings such as the default transaction timeout and
default threading profile in the element. For example:
... ...
For a list of the available global configuration settings, see
Global Settings Configuration Reference.
Accessing the Configuration ProgrammaticallyAll Mule
configuration is accessible from a single object:
org.mule.api.config.MuleConfiguration . Configurations in a
MuleConfiguration are set when a MuleContext is created. The object
becomes immutable after it is started and can be accessed using the
following:
MuleContext context = MuleServer.getMuleContext();
MuleConfiguration configuration = context.getConfiguration();
Document generated by Confluence on Feb 07, 2010 23:59
Page 27
About Configuration BuildersThis page last changed on Sep 14,
2009 by jwheeler.
About Configuration Builders[ SpringXmlConfigurationBuilder ] [
ScriptConfigurationBuilder ] [ Custom Configuration Builders ] [
Specifying the Configuration Builder ] The configuration builder is
responsible for creating the configuration that's used at run time
from the configuration files you provide. Mule ESB provides two
standard configuration builders, or you can create your own.
SpringXmlConfigurationBuilderThe default configuration builder
used to configure Mule is the SpringXmlConfigurationBuilder. This
configuration builder uses Spring to configure Mule based on one or
more XML files leveraging custom Mule namespaces. For more
information, see About the XML Configuration File.
ScriptConfigurationBuilderThis configuration builder allows a
JSR-223 compliant script engine such as Groovy or Jython to
configure Mule. For more information, see Scripting Module.
Custom Configuration BuildersYou can easily create your own
custom configuration builder by implementing the
ConfigurationBuilder interface, which has a method configure.
Typically, you call configure(MuleContext
muleContext.getRegistry()) to get access to Mule's internal
registry, which contains the configuration information, and to
register services and other elements. In most cases, you will want
to inherit from the class AbstractResourceConfigurationBuilder ,
which will make any configuration files specified on the command
line available in an instance variable called configResources.
Specifying the Configuration
BuilderSpringXmlConfigurationBuilder is the default configuration
builder. If you want to use another configuration builder, you can
specify it on the command line at startup with the -builder
parameter:
mule -builder
org.mule.module.scripting.builders.ScriptConfigurationBuilder
-config mule-config.groovy
You can also specify the configuration builder as a parameter to
the MuleContextFactory when starting Mule programatically:
MuleContext context = new
DefaultMuleContextFactory().createMuleContext(new
ScriptConfigurationBuilder("mule-config.groovy"));
context.start();
Document generated by Confluence on Feb 07, 2010 23:59
Page 28
Configuring PropertiesThis page last changed on Sep 14, 2009 by
jwheeler.
Configuring Properties[ Property Placeholders ] [ Global
Properties ] [ Properties Files ] [ Message Properties ] [ System
Properties ] [ Environment Variables ] This page describes
configuring properties, such as property placeholders and system
properties.
Property PlaceholdersYou can use Ant-style property placeholders
in your Mule ESB configuration. For example:
The values for these placeholders can be made available in a
variety of ways, as described in the sections below.
Global PropertiesYou can use the element to set a placeholder
value from within your Mule configuration, such as from within
another Mule configuration file:
Properties FilesTo load properties from a file, you can use the
standard Spring element :
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-2.5.xsd"
where the contents of smtp.properties is:
smtp.username=JSmith smtp.password=ChangeMe
The placeholderPrefix value can be anything other than "#[",
which is what Mule uses to parse its message properties in
expressions. We recommend you set the value to "${". Note that you
do not have to change anything in your Spring configuration or
properties file to match this value; it simply differentiates
Spring properties from Mule properties.
Document generated by Confluence on Feb 07, 2010 23:59
Page 29
To load multiple properties files, separate them with
commas:
Message PropertiesYou can use placeholders to perform logic on
message properties such as the header. For example, if you wanted
to evaluate the content-type portion of the message header, you
would specify it as #[header:Content-Type]. Typically, you use
message property placeholders with expressions. For more
information, see Using Expressions.
System PropertiesThe placeholder value can come from a JDK
system property. If you start Mule from the command line, you would
specify the properties as follows:
mule -M-Dsmtp.username=JSmith -M-Dsmtp.password=ChangeMe -config
my-config.xml
or edit the system properties in conf/wrapper.conf if you are
deploying Mule as a webapp. When running Mule in a container, as of
Mule 2.2.2 you can also specify the server ID in the web.xml file
as follows:
mule.serverId MyServer
If you start Mule programmatically, you would specify the
properties as follows before creating and starting the Mule
context:
System.getProperties().put("smtp.username", "JSmith");
System.getProperties().put("smtp.password", "ChangeMe");
There are also several system properties that are immutable
after startup. To set these, you customize the MuleConfiguration
using the set method for the property (such as setId for the system
ID), create a MuleContextBuilder, load the configuration to the
builder, and then create the context from the builder. For
example:
SpringXmlConfigurationBuilder configBuilder = new
SpringXmlConfigurationBuilder("my-config.xml");
DefaultMuleConfiguration muleConfig = new
DefaultMuleConfiguration(); muleConfig.setId("MY_SERVER_ID");
MuleContextBuilder contextBuilder = new
DefaultMuleContextBuilder();
contextBuilder.setMuleConfiguration(muleConfig); MuleContextFactory
contextFactory = new DefaultMuleContextFactory(); MuleContext
muleContext = contextFactory.createMuleContext(configBuilder,
contextBuilder);
Document generated by Confluence on Feb 07, 2010 23:59
Page 30
muleContext.start();
For information on the set methods you can use to set system
properties, see org.mule.config.DefaultMuleConfiguration . For
information on configuration builders, see About Configuration
Builders.
Environment VariablesThere is no standard way in Java to access
environment variables. However, this link has some options you
might find useful.
Document generated by Confluence on Feb 07, 2010 23:59
Page 31
Mule High AvailabilityThis page last changed on Sep 14, 2009 by
jwheeler.
Mule High Availability[ Supported Architecture ] [ Installation
and Configuration ] [ Running Mule High Availability ] [ Example
Application ] [ Disabling Mule High Availability ] [ Limitations ]
Mule High Availability provides basic failover capability for Mule
ESB. When the primary Mule instance become unavailable (e.g.,
because of a fatal JVM or hardware failure or it's taken offline
for maintenance), a backup Mule instance immediately becomes the
primary node and resumes processing where the failed instance left
off. After a system administrator has recovered the failed Mule
instance and brought it back online, it automatically becomes the
backup node. Seamless failover is made possible by a distributed
memory store that shares all transient state information among
clustered Mule instances. This can include information in SEDA
service event queues and in-memory message queues. Mule High
Availability is currently available for the following transports:
HTTP (including CXF Web Services) JMS WebSphere MQ JDBC File FTP
Clustered (replaces the local VM transport)
Mule High Availability is available with Mule Enterprise
subscriptions. For details, contact us.
Supported ArchitectureMule High Availability supports the
following architecture: Two Mule 2.2.1 or later instances (hotfix
patch required for Mule 2.2.1) running standalone Active-Passive
topology: one primary node, one backup Reverse proxy server (such
as Apache) required for socket-based transports (HTTP, Web
services, and TCP) to forward requests to the currently active node
Multicasting must be enabled on each server where Mule is installed
High Availability is not a replacement for transactions and does
not guarantee reliability. If your message flow is not
transactional, you will likely suffer from lost, partial, or
duplicated messages in the case a failover should occur. For
details on specific features that are not supported in the current
release, see Limitations below.
Installation and ConfigurationYou must have two identical Mule
instances installed and configured: a primary instance and a backup
instance. Although these instances could be on the same machine,
they should ideally be separated (different machines in different
physical locations) to avoid having a single point of failure. Be
sure to follow the steps in this section for both instances of
Mule.
Document generated by Confluence on Feb 07, 2010 23:59
Page 32
Installing Mule High Availability1. Make sure the Mule instance
is stopped. 2. If you have made changes to your wrapper.conf,
extra-bootstrap-modules.xml, or log4j.properties files in the conf
directory, make backup copies of them so that you can merge your
changes back in after installing Mule High Availability. 3.
Download the Mule High Availability ZIP file from the location
provided by your MuleSoft sales representative. 4. Unzip the ZIP
file to the Mule installation directory. The files are installed on
top of your existing Mule installation. If you are using the Mule
IDE, also copy the mule-module-cluster JAR into the lib\mule
directory under your Mule installation directory. This will enable
you to select the Cluster transport when creating a configuration
file.
Configuring the System PropertiesAfter installing Mule High
Availability, you will find some new system properties in your
conf/ wrapper.conf file. These parameters are used to constitute
the unique ID of each instance in the cluster. You do not need to
change their values, but you do need to uncomment the last line
(clusterNodeBackupId) for one of your two Mule instances (but not
both!).
# Cluster topology
wrapper.java.additional.5=-Dmule.clusterId=DEFAULT
wrapper.java.additional.6=-Dmule.clusterNodeId=1 # Uncomment for
all but one node in the cluster
#wrapper.java.additional.7=-Dmule.clusterNodeBackupId=1
Alternatively, you could set these properties from the command
line when you start Mule, or set them in Java code if you start
Mule programmatically. For details, see "System Properties" on the
Configuring Properties page.
Modifying Your Configuration FilesTo use the Mule High
Availability capabilities, you must make some changes to your Mule
XML configuration file(s). Future versions of Mule will make high
availability support more transparent, and the following changes to
your configuration may no longer be necessary. The Mule Enterprise
Migration Tool will help with any migration of configuration when
this occurs. Import the "cluster" Namespace