- 1. Space DetailsKey: MULE2USERName:Mule 2.x User
GuideDescription: Mule Users Guide for the 2.x release lineCreator
(Creation Date): ross (Jan 30, 2008)Last Modifier (Mod. Date):
tcarlson (Apr 15, 2008)Available PagesConfiguring a Mule
InstanceEscape URI CredentialsHome 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
ReferenceEnabling WS-AddressingEnabling WS-SecuritySupported Web
Service StandardsUsing a Web Service Client as an Outbound
EndpointUsing a Web Service Client DirectlyUsing HTTP GET Requests
Using MTOM EJB Transport Email Transport File Transport FTP
Transport HTTPS Transport HTTP Transport IMAPS TransportDocument
generated by Confluence on Feb 07, 2010 23:59 Page 1
2. IMAP Transport JDBC TransportJDBC Transport Configuration
ReferenceJDBC Transport ExamplesJDBC Transport Performance
Benchmark Results Jetty TransportJetty SSL Transport JMS
TransportTibco EMS IntegrationJBoss Jms IntegrationFiorano
IntegrationOpenJms IntegrationSwiftMQ IntegrationSun JMS Grid
IntegrationSonicMQ IntegrationSeeBeyond JMS Server IntegrationOpen
MQ IntegrationActiveMQ 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 ReferenceDocument generated
by Confluence on Feb 07, 2010 23:59Page 2 3. 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 MBeanDocument generated by Confluence on Feb
07, 2010 23:59 Page 3 4. 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 ModuleDomToXml
TransformerJXPath Extractor TransformerXmlObject
TransformersXmlToXMLStreamReader TransformerXPath Extractor
Transformer XSLT Transformer Using Mule with Spring Sending and
Receiving Mule Events in Spring Spring Application ContextsDocument
generated by Confluence on Feb 07, 2010 23:59Page 4 5. 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 AxisAxis SOAP StylesAxis SOAP TransportsAxis TransportAxis
Web Services and Mule Configuring Axis Proxying Web Services Using
.NET Web Services with MuleWeb Service Wrapper Working with
ServicesConfiguring Components Configuring Java Components Using
Interceptors Configuring the Service MEPs Mule Messaging Styles
Using Message Routers Inbound Routers Outbound RoutersAsynchronous
Reply RoutersCatch-all Strategies Component Bindings About the XML
Configuration FileExample ArchetypeJaas SecurityJavaRebel
IntegrationModule ArchetypePGP SecurityProject
ArchetypeStreamingUsing Expressions Creating Expression Evaluators
Expressions Configuration ReferenceDocument generated by Confluence
on Feb 07, 2010 23:59 Page 5 6. 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 toconfigure 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
serviceFollowing is an example of a simple Mule configuration file:
Document generated by Confluence on Feb 07, 2010 23:59Page 6 7.
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 valuesDocument
generated by Confluence on Feb 07, 2010 23:59 Page 7 8. Escape URI
CredentialsThis page last changed on Nov 26, 2008 by
jackie.wheeler.Escape Your CredentialsIf you use a URI-style
endpoint and you include the user name and password, escape
anycharacters that are illegal for URIs, such as the @ character.
For example, if the user nameis [email protected], you should enter it
as user%40myco.com.Document generated by Confluence on Feb 07, 2010
23:59 Page 8 9. 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 underconstruction for the current
release. If you have any feedback on the content, or would like to
sign up tobecome 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 Using Transports
(Click the arrow to expand the topics from the About Transports
Getting Started guide, including an introduction Available
Transports to Mule, steps to get started, and migration Configuring
a Transport information.) Mule Deployment Click here to expand...
Architecture Introduction What is Mule? Deployment Scenarios
Understanding the Messaging Choosing the Right Topology Framework
Understanding the Mule ArchitectureHot Deploying Mule Applications
Understanding the Logical Data Flow Integrating Mule into Your
Environment Mule High Availability Summary Getting Started Quick
Start Mule Administration Where Should I Go Next? Download Page
Controlling the Infrastructure with the Installing Mule Running
Mule Service Registry Setting Up Eclipse for Use with Maven
Managing and Monitoring Deployments Examples Using the Mule
Management Console Tutorial Basic Usage Whats New in This Release
JMX Management Migrating Mule Extending Mule Using Mule
Introduction to Extending Mule Creating Transports Creating a
Custom XML Namespace Configuration Overview Creating Expression
Evaluators About Mule Configuration Bootstrapping the Registry
About the XML Configuration File Internationalizing Strings About
Configuration Builders Using MuleForge Starting Mule with the
Configuration Working with Services About Models Testing Mule
Configuring the Service Configuring Endpoints Introduction to
Testing Mule Using Filters Functional Testing Using Transformers
Unit Testing Using Mule Data Integrator Running Benchmark Tests
Using Message Routers Profiling Mule Mule Messaging Styles
Configuring Components Using Web ServicesDocument generated by
Confluence on Feb 07, 2010 23:59Page 9 10. Using Spring Beans as
Service Components Development Tools Customizing Behavior
Developing Service Components Developers Guide Creating Custom
Filters Using IDEs Creating Custom Transformers Mule IDE User Guide
Creating Custom Routers Using Maven Using Interceptors Configuring
Retry Policies Beyond the Basics Reference Configuring Encoding
Configuring Properties Glossary Using Expressions Configuration
Reference Using Mule with Spring API Reference Using the Mule
RESTpack Test API Reference Using Mule Modules Third-party Software
in Mule Streaming Suggested Reading Error Handling Distribution
Contents Storing Objects in the Registry PDF versions of the Users
Guide for offline Configuring Security reading Using the Mule
Client Documentation for Previous Releases Tuning Performance Mule
1.x Getting Started Configuring Queues Mule 1.x User Guide Managing
Transactions Using Agents Mule Server Notifications Configuring
Logging Mule CookbookDocument generated by Confluence on Feb 07,
2010 23:59Page 10 11. 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 snapshotshere. Keep
in mind that these features are under development, and snapshots
contain the "bleedingedge" code that has not been thoroughly
tested. Therefore, snapshots are great for development butshould
not be used in production. There is no support for 3.x features
until Mule ESB 3.x has beenreleased 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
themreloaded 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 applications 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
updatedJAR to the lib directory, and then touch or save the
configuration file. Currently, Mule checks onlythe first
configuration file in your applications directory, so right now hot
deployment works best withapplications 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 1Jira IssuesPriority Type Keycomponent Summary
MULE-4199 Examples / Tutorials Errorhandlerexample logic isbroken -
not routingmessages to Emailand JMS endpoints MULE-4246 Transport:
HTTP/ Servlet transport HTTPShas headers whichshouldnt be there
MULE-4248 Core: APISynchronousinboundendpoint
withPassThroughComponentand synchronousDocument generated by
Confluence on Feb 07, 2010 23:59Page 11 12. outbound endpoint
should return a NullPayload if outbound endpoint has no result
MULE-3615 Core: Configuration Move custom-agent element to the core
schema MULE-3611 Transport: CXF /MultipleWsdlCxfCallsTestCase XFire
fails MULE-4044 Core: (other) Remove version numbers from schema
namespaces MULE-3625 Transport: JDBC Registering transaction
manager causes non xa transaction to fail MULE-4245 Transport: File
java.io.NotSerializableException: java.io.FileInputStream with
MULE-4324 Transport: (new Add Cometd Ajax transport)support to Mule
MULE-4323 Modules: (other)Add the Json transformers project to Mule
MULE-64 Transport: TCP /Add NIO based UDP / SSL / socket Provider
Multicast MULE-115Transport: (new Add a JGroups transport)provider
MULE-340Transport: (new Add a transport transport)provider for FIX
MULE-399Core: Deployment / A component Federationrepository for
Mule MULE-114Core: Deployment / Mule-based FederationClustering
support for mule instances MULE-3953 Modules: Spring,The base XSD
Modules: XML, XSLT, filterType has an XPath attribute not which
isnt used MULE-4226 Core: API, Core:Mule 2 Expression Configuration
regex doesnt detect all expresssions MULE-4222 Core: API
CorrelationEventResequencer must not be abstract MULE-4225
Transport: CXF /Dont add MULE XFire SOAP headers unless specified
MULE-4229 Core: Routing / Outbound Routing Filters breaks order
created by MULE-4295 Core: Configuration Update jms config schema
to support exception listener registration flag MULE-4330 Modules:
XML, XSLT, Add XQuery support XPath to the Xml module MULE-4349
Transport: EmailThe MailMesageAdapter should use theDocument
generated by Confluence on Feb 07, 2010 23:59 Page 12 13.
MailMessage as thepayload MULE-4357 Examples / Tutorials New
Example: GPSWalker. Plots GPScoords generated byMule on a map in
thebrowser MULE-4346 Transport: Email The secure emailschemas
requirethat the user set TLSand client store info.This is unnessary
formany email servers(certainly the publicservcies) MULE-4135 Core:
Routing /Nested routers / Filtersbindings do notcorrectly
handleNullPayload MULE-4321 Core: Transports Add
aninitialStateStoppedflag to connectors toallow connectors tobe
started based onexternal events MULE-3671 Modules:
SecurityKeyBasedEncryptionStrategyTestC (Acegi, PGP, JAAS, disabled
others) MULE-3673 Modules: SecurityKBEStrategyUsingEncryptionTrans
(Acegi, PGP, JAAS, is disabled others) MULE-4067 ToolsImprove
templatefor MessageReceiverclass doesnt workfor Polling Receivers
MULE-4097 Core: Configuration, Support declarative Core: Deployment
/ Mule serverId Federation configurationwhen embedded inwebapp
MULE-4099 Core: (other)FunctionalTestCasecloses JMS sessiontoo
early withtransactions MULE-4134 ToolsModify transportarchetype to
addtransformMessage() MULE-4157 Transport: CXF / Support sending
XFirewhole SOAPEnvelope with CXFproxies MULE-4146 Transport:
FileGlobal file endpointignores the filenamewildcard filter
MULE-4313 Core: Routing /configuring Filters,
Transport:jms:transaction on JMSinbound-endpointthrows: The
sessionis closed(JMSCode: null)(javax.jms.IllegalStateException)
MULE-4354 Core: Bootstrap /Custom expression Java Service evalutor
configuredDocument generated by Confluence on Feb 07, 2010 23:59
Page 13 14. Wrapper, Core: declaratively is Configurationignored
MULE-3512 Transport: JDBCJDBC Dispatcherdoes not copymessage
propertiesover MULE-3862 Core: LifecycleMules lifecycle isbroken
after XMLparser exception onstartup MULE-4289 Transport: CXF /
ClassCastException XFirewhen defing CXFlogging interceptorson CXF
web serviceproxy MULE-4304 Core: (other), Improve registry Core:
API, Core: lookups to Deployment / select(type) Federation,
Core:instead of Lifecycleselect(all).filter(type) MULE-478Core:
Deployment / A virtual file system Federation to allow
singlelocation deploymentof a Mule application MULE-3847 Build:
Distributions Upgrade YourKitintegration to v8.0.1 MULE-4231
Transport: CXF / Add a namespace XFireattribute to the CXFendpoint
schema MULE-4322 Core: Configuration Custom securityfilter
elementmissing MULE-4355 Core: Containers Create Message
DataTransfer objectsthat can be usedto create readableserialized
messages MULE-4374 Transport: JMS Support URIcompliant definitionof
Jms Topics MULE-4348 Transport: (other) The servletendpoints
shouldhave a path attribute MULE-4009 Transport: Email
backupFolderattribute xsd needsto be updated MULE-4356 Core:
Transformers Create Map to Beanand Bean to Maptransformers
MULE-3991 Core: ExpressionsExpressionevaluators parse isconfused by
strangevalues MULE-4301 Transport: JMS returnClass
inObjectToJMSMessageshould be used to MULE-4303 Transport: Email
ObjectToMimeMessageTransformerignores attachmentfile names
MULE-4065 ToolsTypos in archetypeprompts MULE-4236 Build:
Distributions mule-module-spring-security is bundled inDocument
generated by Confluence on Feb 07, 2010 23:59 Page 14 15. lib/opt
instead of lib/ mule MULE-4347 Core: Configuration Make the
MuleContext available on the servlet context MULE-4299 Core:
Transformers the returnClass attribute on transformers needs to
allow Array return type. MULE-4363 Core: Expressions Header and
Attachement Expresion evaluators should use "*" to denote
allDocument generated by Confluence on Feb 07, 2010 23:59 Page 15
16. 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
byadding the JSON namespace to your Mule XML configuration file:You
can now start using JSON transformers and filters in your
configuration.TransformersConverts a java object to a JSON encoded
object that can be consumed by other languages suchas Javascript or
Ruby. The JSON engine can be configured using the jsonConfig
attribute. Thisis an object reference to an instance of:
net.sf.json.JsonConfig. This can be created as a springbean. 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.AttributesName Type
RequiredDefaultDescriptionjsonConfig-refstring noThe 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:59Page 16 17. net.sf.json.JsonConfig.This can becreated
as aspring bean.excludePropertiesstringno Users canconfigure
acomma-separatedlist of propertynames toexclude
i.e.excludeProperties="address,posincludePropertiesstringno
Configurea comma-separated list ofproperty namesto include
i.e.includeProperties="name,email"sourceClassstringno Restrict
theaccepted sourceclass object toa specific type.If not set
thetransformer willhandle all sourcetypes. Note thatif you need
tospecify an arraytype you need topostfix the classname with [].
Forexample, if youwant to ensurethe transformeronly accepts
anOrange[], you setthe sourceClass
toorg.mule.tck.testmodels.fruit.OChild ElementsNameCardinality
DescriptionExampleIn this example, we configure a transformer to
convert from a JavaBean to a JSON encoded string. Thetransformer by
default will encode any JavaBean, but we have restricted the object
type it can handle bysetting sourceClass to
org.mule.tck.models.fruit.Orange. We also exclude the brand and
radiusproperties, so these will not be serialized.A transformer
that will convert a JSON encoded object graph to a java object. The
objecttype is determined by the returnClass attribute. Note that
this transformers supports Arraysand Lists. For example, to convert
a JSON string to an array of org.foo.Person, set the
thereturnClass=[Lorg.foo.Person; . The JSON engine can be
configured using the jsonConfig attribute. This isan object
reference to an instance of: net.sf.json.JsonConfig. This can be
created as a spring bean.AttributesNameTypeRequired Default
DescriptionjsonConfig-ref stringnoThe 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 ElementsNameCardinalityDescriptionExampleIn 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 theobject that will get populated with the JSON data.
Mixins are useful when you do not control the beanclass.Document
generated by Confluence on Feb 07, 2010 23:59 Page 18 19. Converts
a JSON encoded object representation in to an XML representation.
Each property and enclosingelement 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 forthis transformer is always
java.lang.String, there is no need to set
this.AttributesNameTypeRequired DefaultDescriptionobjectElementName
name (no spaces) no The XML elementname to use
forrepresentingobjects in theJSON ecodedobject. The defaultis
o.arrayElementNamename (no spaces) no The XML elementname to use
forrepresentingobjects in theJSON ecodedobject. The defaultis
a.valueElementNamename (no spaces) no The XML elementname to use
forrepresentingobject values(properties) inthe JSON ecodedobject.
The defaultis e.Document generated by Confluence on Feb 07, 2010
23:59Page 19 20. Child ElementsName CardinalityDescriptionFiltersA
filter that will determine if the current message payload is a JSON
encoded message.AttributesChild ElementsName TypeRequiredDefault
DescriptionName Cardinality DescriptionExampleThere are no
configuration parameters for this filter.Document generated by
Confluence on Feb 07, 2010 23:59 Page 20 21. 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 encloseencoding
information in their messages as metadata. For other transports
like File, FTP, and JMS, youmust configure the encoding, either on
the endpoint or globally for the Mule instance. If you do
notspecify 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 asdescribed 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-31JDocument
generated by Confluence on Feb 07, 2010 23:59 Page 21 22. 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 MuleApplication ] [ 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 runas
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 6How it WorksA Mule application is one or more
configuration files packaged up with any dependencies that are
notalready provided by Mule. In a hot deployment scenario, each
Mule application shares a single Muleinstance running in an
application server or web container. To hot deploy Mule
applications, you do thefollowing: 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 applicationsWhen you
deploy the WAR file, Mule reads the Mule configuration file and
creates and starts all therequired objects just as when running
Mule standalone. When you undeploy a Mule application, onlythe
objects created and started for that Mule application are stopped
and disposed of without affectingany other applications sharing the
same Mule instance. In this way, multiple Mule applications can
bedeployed, 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 dont
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 23. Deploying Mule as a ServiceTo deploy Mule as
a service to an application server (JBoss, Geronimo), you simply
deploy the JCAresource adapter distribution. You dont need to open
or repackage the resource adapter archive butcan just deploy it as
unless you need to edit the MuleConfiguration properties or the
default Muleconfiguration 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
plussupporting 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 webapplication.To enable Mule to find and load your
configuration, you must include a web.xml file that points to
yourconfiguration 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 onthe
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,
yousimply copy your WAR to the Tomcat webapps directory. For more
information, see the documentation foryour 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:59Page 23 24. 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 ApplicationFiles ] [ 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 applicationsfor hot deployment.
For more information on hot deploying Mule applications, see Hot
Deploying MuleApplications.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.jar6. 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/*.jarCopying the Mule Application
FilesAfter you package your configuration files and custom Java
classes in a WAR file (see Hot Deploying MuleApplications), 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, Tomcatdeploys it. If you need to make a change to a
configuration or Java file in the webapp, simply modifythe 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
theapplication. Alternatively, you could modify the source files,
repackage them as a WAR, and drop the newWAR into the /webapps
directory to trigger Tomcat to redeploy the application.Document
generated by Confluence on Feb 07, 2010 23:59Page 24 25. 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.xmlmule
-config foo-config.xml,bar-config.xmlIf you want to start Mule by
calling it from your code, you specify the configuration file as a
parameter tothe 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 informationon accessing the existing
configuration from your code after startup, see Accessing the
ConfigurationProgrammatically.For more information on Mule
configuration files, see About the XML Configuration File and
ScriptingModule.Document generated by Confluence on Feb 07, 2010
23:59 Page 25 26. About Mule ConfigurationThis page last changed on
Sep 14, 2009 by jwheeler.About Mule Configuration[ Overview of
Configuration Elements ] [ Global Configuration Settings ] [
Accessing the ConfigurationProgrammatically ]By default, Mule ESB
starts up with a simple configuration in which only some
system-level services areconfigured. You must configure services,
transformers, and the rest of the elements required for
yourapplication.Following is an introduction to configuring Mule
ESB via the Spring XML file. For details on this file, seeAbout the
XML Configuration File. For information on starting Mule with the
configuration file or accessingthe 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 dont 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 serviceFollowing is an example of a simple
Mule configuration file:Document generated by Confluence on Feb 07,
2010 23:59Page 26 27. 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
defaultthreading 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
becomesimmutable 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:59Page 27 28. 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 thats used at run time
from theconfiguration files you provide. Mule ESB provides two
standard configuration builders, or you can createyour
own.SpringXmlConfigurationBuilderThe default configuration builder
used to configure Mule is the SpringXmlConfigurationBuilder.
Thisconfiguration builder uses Spring to configure Mule based on
one or more XML files leveraging customMule 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
configureMule. For more information, see Scripting Module.Custom
Configuration BuildersYou can easily create your own custom
configuration builder by implementing the
ConfigurationBuilderinterface, which has a method configure.
Typically, you call configure(MuleContextmuleContext.getRegistry())
to get access to Mules internal registry, which contains the
configurationinformation, and to register services and other
elements.In most cases, you will want to inherit from the class
AbstractResourceConfigurationBuilder , whichwill make any
configuration files specified on the command line available in an
instance variable calledconfigResources.Specifying the
Configuration BuilderSpringXmlConfigurationBuilder is the default
configuration builder. If you want to use anotherconfiguration
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.groovyYou can also specify the configuration
builder as a parameter to the MuleContextFactory when startingMule
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 29.
Configuring PropertiesThis page last changed on Sep 14, 2009 by
jwheeler.Configuring Properties[ Property Placeholders ] [ Global
Properties ] [ Properties Files ] [ Message Properties ] [
SystemProperties ] [ 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 sectionsbelow.Global PropertiesYou can use the
element to set a placeholder value from within your
Muleconfiguration, 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/contexthttp://www.springframework.org/schema/context/spring-context-2.5.xsd"where
the contents of smtp.properties
is:smtp.username=JSmithsmtp.password=ChangeMeThe placeholderPrefix
value can be anything other than "#[", which is what Mule uses to
parse itsmessage properties in expressions. We recommend you set
the value to "${". Note that you do nothave to change anything in
your Spring configuration or properties file to match this value;
it simplydifferentiates Spring properties from Mule
properties.Document generated by Confluence on Feb 07, 2010 23:59
Page 29 30. 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
moreinformation, 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.xmlor edit the system properties in
conf/wrapper.conf if you are deploying Mule as a webapp.
Whenrunning Mule in a container, as of Mule 2.2.2 you can also
specify the server ID in the web.xml file asfollows: mule.serverId
MyServerIf you start Mule programmatically, you would specify the
properties as follows before creating andstarting 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 customizethe
MuleConfiguration using the set method for the property (such as
setId for the system ID), createa MuleContextBuilder, load the
configuration to the builder, and then create the context from
thebuilder.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:59Page 30 31. muleContext.start();For information on the set
methods you can use to set system properties,
seeorg.mule.config.DefaultMuleConfiguration . For information on
configuration builders, see AboutConfiguration Builders.Environment
VariablesThere is no standard way in Java to access environment
variables. However, this link has some optionsyou might find
useful.Document generated by Confluence on Feb 07, 2010 23:59Page
31 32. Mule High AvailabilityThis page last changed on Sep 14, 2009
by jwheeler.Mule High Availability[ Supported Architecture ] [
Installation and Configuration ] [ Running Mule High Availability ]
[ ExampleApplication ] [ 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
its 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 backupinstance. 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:59Page 32 33. 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 libmule 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 inthe 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
topologywrapper.java.additional.5=-Dmule.clusterId=DEFAULTwrapper.java.additional.6=-Dmule.clusterNodeId=1#
Uncomment for all but one node in the
cluster#wrapper.java.additional.7=-Dmule.clusterNodeBackupId=1Alternatively,
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 "SystemProperties" on the Configuring Properties
page.Modifying Your Configuration FilesTo use the Mule High
Availability capabilities, you must make some changes to your Mule
XMLconfiguration file(s).Future versions of Mule will make high
availability support more transparent, and thefollowing changes to
your configuration may no longer be necessary. The Mule
EnterpriseMigration Tool will help with any migration of
configuration when this occurs. Import the "cluster" Namespace