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 user@myco.com, 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