Mule 2.2.1 Users Guide

Space DetailsKey: Name: Description: Creator (Creation Date): MULE2USER Mule 2.x User GuideMule Users Guide for the 2.x release line

ross (Jan 30, 2008)

Last Modifier (Mod. Date): tcarlson (Apr 15, 2008)

Available Pages Configuring a Mule Instance Escape URI Credentials Home 3.x Features Using JSON Configuring Encoding Hot Deploying Mule Applications Deploying Mule as a Service to Tomcat Starting Mule with the Configuration About Mule Configuration About Configuration Builders Configuring Properties Mule High Availability Storing Objects in the Registry About Transports Available Transports BPM Transport CXF Transport Building a CXF Web Service CXF Transport Configuration Reference Enabling WS-Addressing Enabling WS-Security Supported Web Service Standards Using a Web Service Client as an Outbound Endpoint Using a Web Service Client Directly Using HTTP GET Requests

Using MTOM EJB Transport Email Transport File Transport FTP Transport HTTPS Transport HTTP Transport IMAPS TransportPage 1

Document generated by Confluence on Feb 07, 2010 23:59

IMAP Transport JDBC Transport JDBC Transport Configuration Reference JDBC Transport Examples JDBC Transport Performance Benchmark Results Jetty Transport Jetty SSL Transport JMS Transport Tibco EMS Integration JBoss Jms Integration Fiorano Integration OpenJms Integration SwiftMQ Integration Sun JMS Grid Integration SonicMQ Integration SeeBeyond JMS Server Integration Open MQ Integration ActiveMQ Integration

WebLogic JMS Integration Mule MSMQ Transport Mule WMQ Transport Multicast Transport POP3S Transport POP3 Transport Quartz Transport RMI Transport Servlet Transport SMTPS Transport SMTP Transport SOAP Transport SSL Transport STDIO Transport TCP Transport UDP Transport VM Transport WSDL Connectors

XMPP Transport Bootstrapping the Registry Choosing the Right Topology Configuration Overview Configuration Reference Asynchronous Reply Router Configuration Reference Page 2


Catch-all Strategy Configuration Reference Component Configuration Reference Endpoint Configuration Reference Exception Strategy Configuration Reference Filters Configuration Reference Global Settings Configuration Reference Inbound Router Configuration Reference Model Configuration Reference Notifications Configuration Reference Outbound Router Configuration Reference Properties Configuration Reference Security Manager Configuration Reference Service Configuration Reference

Transactions Configuration Reference Configuring Endpoints Mule Endpoint URIs Configuring a Transport Configuring Retry Policies Configuring Logging Configuring Queues Configuring Security Component Authorization Using Acegi Component Authorization Using Spring Security Configuring the Acegi Security Manager Configuring the Spring Security Manager Encryption Strategies SAML Module Setting up LDAP Provider for Acegi Setting up LDAP Provider for Spring Security

Upgrading from Acegi to Spring Security Controlling the Infrastructure with the Service Registry Creating a Custom XML Namespace Creating Custom Routers Creating Transports Transport Archetype Transport Service Descriptors Deployment Scenarios Deploying Mule to WebLogic Deploying Mule to WebSphere Embedding Mule in a Java Application or Webapp JBoss Integration Mule as MBean


Page 3

Developing Service Components Entry Point Resolver Configuration Reference Error Handling Functional Testing Installing a Standalone Mule Instance Installing Upgrades and Hot Fixes Internationalizing Strings Introduction to Extending Mule Introduction to Testing Mule Models Mule Agents JMX Management Mule Server Notifications Profiling Mule Resource Adapter Suggested Reading Third-party Software in Mule Transaction Management Tuning Performance Unit Testing Using Filters Using IDEs Using the Mule Management Console Installing the Management Console with an External Database Management Console Agent Settings Using Mule Modules Acegi Module JAAS Module JBoss Transaction Manager Scripting Module Spring Extras Module SXC Module XML Module DomToXml Transformer JXPath Extractor Transformer XmlObject Transformers XmlToXMLStreamReader Transformer XPath Extractor Transformer

XSLT Transformer Using Mule with Spring Sending and Receiving Mule Events in Spring Spring Application Contexts


Page 4

Using Spring Beans as Service Components Using the Mule Client Using the Mule RESTpack Architecting RESTful HTTP applications Making Sense of REST Using Transformers Creating Custom Transformers Transformers Configuration Reference XmlPrettyPrinter Transformer Using Web Services Axis Axis SOAP Styles Axis SOAP Transports Axis Transport Axis Web Services and Mule

Configuring Axis Proxying Web Services Using .NET Web Services with Mule

Web Service Wrapper Working with Services Configuring Components Configuring Java Components Using Interceptors Configuring the Service MEPs Mule Messaging Styles Using Message Routers Inbound Routers Outbound Routers Asynchronous Reply Routers Catch-all Strategies

Example Archetype Jaas Security

Component Bindings About the XML Configuration File

JavaRebel Integration Module Archetype PGP Security Project Archetype Streaming Using Expressions Creating Expression Evaluators Expressions Configuration Reference Page 5


Configuring a Mule InstanceThis page last changed on Jun 30, 2009 by jwheeler.

Configuring a Mule InstanceA Mule configuration file can become an elaborate tree of elements, however, the basic things to configure at the top level are: Connectors - Non-default configuration of any transports used Endpoints - Global definition of endpoints is encouraged to clearly describe where your integration channels are Transformers - Transformers may be defined globally and later referenced from your services Filters - Filters may be defined globally and later referenced from your services Models - One or more models that logically group together your services Services - One or more services that wrap your components and configure routers, endpoints, transformers, and filters specifically for that service

Following is an example of a simple Mule configuration file:


Page 6

Advanced ConfigurationOther, more advanced things you may configure at this level: Agents - Agents are typically used for cross-cutting concerns such as logging or management Notifications - Be notified upon certain lifecycle events Security Manager - Authenticates requests based on one or more security providers Transaction Management - Mule transactions are configured on inbound endpoints, where an endpoint can be configured to start a new transaction or join an existing one. Global Configuration Options - Miscellaneous global settings Global Properties - Placeholder values


Page 7

Escape URI CredentialsThis page last changed on Nov 26, 2008 by jackie.wheeler.

Escape Your Credentials If you use a URI-style endpoint and you include the user name and password, escape any characters that are illegal for URIs, such as the @ character. For example, if the user name is [email protected], you should enter it as user%40myco.com.


Page 8

HomeThis page last changed on Dec 17, 2009 by jwheeler.

Welcome to the documentation for Mule ESB. Some of the documentation on this site is under construction for the current release. If you have any feedback on the content, or would like to sign up to become a site contributor or editor, please contact us. 3.x snapshots are now available! For a list of features in progress for 3.x, click here.

Getting Started(Click the arrow to expand the topics from the Getting Started guide, including an introduction to Mule, steps to get started, and migration information.) Click here to expand... Introduction What is Mule? Understanding the Messaging Framework Understanding the Mule Architecture Understanding the Logical Data Flow Integrating Mule into Your Environment Summary Getting Started Quick Start Where Should I Go Next? Download Page Installing Mule Running Mule Setting Up Eclipse for Use with Maven Examples Tutorial Basic Usage What's New in This Release Migrating Mule

Using Transports About Transports Available Transports Configuring a Transport

Mule Deployment Architecture Deployment Scenarios Choosing the Right Topology Hot Deploying Mule Applications Mule High Availability

Mule Administration Controlling the Infrastructure with the Service Registry Managing and Monitoring Deployments Using the Mule Management Console JMX Management

Extending Mule Using Mule Configuration Overview About Mule Configuration About the XML Configuration File About Configuration Builders Starting Mule with the Configuration Working with Services About Models Configuring the Service Configuring Endpoints Using Filters Using Transformers Using Mule Data Integrator Using Message Routers Mule Messaging Styles Configuring Components Using Web Services Introduction to Extending Mule Creating Transports Creating a Custom XML Namespace Creating Expression Evaluators Bootstrapping the Registry Internationalizing Strings Using MuleForge

Testing Mule Introduction to Testing Mule Functional Testing Unit Testing Running Benchmark Tests Profiling Mule


Page 9

Using Spring Beans as Service Components Customizing Behavior Developing Service Components Creating Custom Filters Creating Custom Transformers Creating Custom Routers Using Interceptors Configuring Retry Policies Beyond the Basics Configuring Encoding Configuring Properties Using Expressions Using Mule with Spring Using the Mule RESTpack Using Mule Modules Streaming Error Handling Storing Objects in the Registry Configuring Security Using the Mule Client Tuning Performance Configuring Queues Managing Transactions Using Agents Mule Server Notifications Configuring Logging Mule Cookbook

Development Tools Developer's Guide Using IDEs Mule IDE User Guide Using Maven

ReferenceGlossary Configuration Reference API Reference Test API Reference Third-party Software in Mule Suggested Reading Distribution Contents PDF versions of the User's Guide for offline reading Documentation for Previous Releases Mule 1.x Getting Started Mule 1.x User Guide


Page 10

3.x FeaturesThis page last changed on Dec 17, 2009 by jwheeler.

3.x Features[ Hot Deployment ] [ Additional New Features and Fixed Issues ] The next generation of Mule ESB, version 3.x, is under development. You can download 3.x snapshots here. Keep in mind that these features are under development, and snapshots contain the "bleeding edge" code that has not been thoroughly tested. Therefore, snapshots are great for development but should not be used in production. There is no support for 3.x features until Mule ESB 3.x has been released for general availability (GA). This page describes each of the 3.x features and the milestone in which it is available.

Hot Deployment(As of milestone 1) You can now modify your configuration files and custom classes and have them reloaded without having to restart Mule. To take advantage of this feature, do the following: 1. Create a directory for your application anywhere under the $MULE_HOME/apps directory and create a subdirectory called lib. For example, if your application is called MyApp, you would create $MULE_HOME/apps/MyApp and $MULE_HOME/apps/MyApp/lib. 2. Save your application as a JAR file and copy it to the lib directory (e.g., $MULE_HOME/apps/MyApp/ lib). 3. Copy your configuration file to your application's directory (e.g., $MULE_HOME/apps/MyApp). 4. After making a change to your application, simply update the timestamp on the configuration file using the touch command (if available on your operating system) or by saving your configuration file (e.g., add and delete a character, and then save). Mule checks every three seconds for updated configuration files under the $MULE_HOME/apps directory, and when it finds one, it reloads the configuration file and the JARs in that applications lib directory. Therefore, if you want to change one of your custom classes, you modify and rejar it, copy the updated JAR to the lib directory, and then touch or save the configuration file. Currently, Mule checks only the first configuration file in your application's directory, so right now hot deployment works best with applications that have a single configuration file. For an example of how hot deployment works, see the Hot Deployment blog post.

Additional New Features and Fixed IssuesMilestone 1

Jira Issues Priority Type Key MULE-4199 component Summary Examples / Tutorials Errorhandler example logic is broken - not routing messages to Email and JMS endpoints Transport: HTTP/ Servlet transport HTTPS has headers which shouldn't be there Core: API Synchronous inbound endpoint with PassThroughComponent and synchronous

MULE-4246

MULE-4248


Page 11

MULE-3615

MULE-3611 MULE-4044

MULE-3625

MULE-4245

MULE-4324 MULE-4323

MULE-64

MULE-115 MULE-340 MULE-399 MULE-114

MULE-3953

MULE-4226

MULE-4222 MULE-4225

MULE-4229

MULE-4295

MULE-4330 MULE-4349

outbound endpoint should return a NullPayload if outbound endpoint has no result Core: Configuration Move custom-agent element to the core schema Transport: CXF / MultipleWsdlCxfCallsTestCase XFire fails Core: (other) Remove version numbers from schema namespaces Transport: JDBC Registering transaction manager causes non xa transaction to fail Transport: File java.io.NotSerializableException: java.io.FileInputStream with Transport: (new Add Cometd Ajax transport) support to Mule Modules: (other) Add the Json transformers project to Mule Transport: TCP / Add NIO based UDP / SSL / socket Provider Multicast Transport: (new Add a JGroups transport) provider Transport: (new Add a transport transport) provider for FIX Core: Deployment / A component Federation repository for Mule Core: Deployment / Mule-based Federation Clustering support for mule instances Modules: Spring, The base XSD Modules: XML, XSLT, filterType has an XPath attribute 'not' which isn't used Core: API, Core: Mule 2 Expression Configuration regex doesn't detect all expresssions Core: API CorrelationEventResequencer must not be abstract Transport: CXF / Don't add MULE XFire SOAP headers unless specified Core: Routing / Outbound Routing Filters breaks order created by Core: Configuration Update jms config schema to support exception listener registration flag Modules: XML, XSLT, Add XQuery support XPath to the Xml module Transport: Email The MailMesageAdapter should use the


Page 12

MULE-4357

MULE-4346

MULE-4135

MULE-4321

MULE-3671

MULE-3673

MULE-4067

MULE-4097

MULE-4099

MULE-4134

MULE-4157

MULE-4146

MULE-4313

MULE-4354

MailMessage as the payload Examples / Tutorials New Example: GPS Walker. Plots GPS coords generated by Mule on a map in the browser Transport: Email The secure email schemas require that the user set TLS and client store info. This is unnessary for many email servers (certainly the public servcies) Core: Routing / Nested routers / Filters bindings do not correctly handle NullPayload Core: Transports Add an 'initialStateStopped' flag to connectors to allow connectors to be started based on external events Modules: Security KeyBasedEncryptionStrategyTestC (Acegi, PGP, JAAS, disabled others) Modules: Security KBEStrategyUsingEncryptionTrans (Acegi, PGP, JAAS, is disabled others) Tools Improve template for MessageReceiver class doesn't work for Polling Receivers Core: Configuration, Support declarative Core: Deployment / Mule serverId Federation configuration when embedded in webapp Core: (other) FunctionalTestCase closes JMS session too early with transactions Tools Modify transport archetype to add transformMessage() Transport: CXF / Support sending XFire whole SOAP Envelope with CXF proxies Transport: File Global file endpoint ignores the filename wildcard filter Core: Routing / configuring Filters, Transport: jms:transaction on JMS inbound-endpoint throws: The session is closed(JMS Code: null) (javax.jms.IllegalStateException) Core: Bootstrap / Custom expression Java Service evalutor configured


Page 13

MULE-3512

Wrapper, Core: Configuration Transport: JDBC

MULE-3862

MULE-4289

MULE-4304

MULE-478

MULE-3847 MULE-4231

MULE-4322

MULE-4355

MULE-4374

MULE-4348

MULE-4009

MULE-4356

MULE-3991

MULE-4301

MULE-4303

MULE-4065 MULE-4236

declaratively is ignored JDBC Dispatcher does not copy message properties over Core: Lifecycle Mule's lifecycle is broken after XML parser exception on startup Transport: CXF / ClassCastException XFire when defing CXF logging interceptors on CXF web service proxy Core: (other), Improve registry Core: API, Core: lookups to Deployment / select(type) Federation, Core: instead of Lifecycle select(all).filter(type) Core: Deployment / A virtual file system Federation to allow single location deployment of a Mule application Build: Distributions Upgrade YourKit integration to v8.0.1 Transport: CXF / Add a namespace XFire attribute to the CXF endpoint schema Core: Configuration Custom security filter element missing Core: Containers Create Message Data Transfer objects that can be used to create readable serialized messages Transport: JMS Support URI compliant definition of Jms Topics Transport: (other) The servlet endpoints should have a path attribute Transport: Email backupFolder attribute xsd needs to be updated Core: Transformers Create Map to Bean and Bean to Map transformers Core: Expressions Expression evaluator's parse is confused by 'strange' values Transport: JMS returnClass in ObjectToJMSMessage should be used to Transport: Email ObjectToMimeMessageTransformer ignores attachment file names Tools Typos in archetype prompts Build: Distributions mule-module-springsecurity is bundled in


Page 14

MULE-4347

MULE-4299

MULE-4363

lib/opt instead of lib/ mule Core: Configuration Make the MuleContext available on the servlet context Core: Transformers the 'returnClass' attribute on transformers needs to allow Array return type. Core: Expressions Header and Attachement Expresion evaluators should use "*" to denote all


Page 15

Using JSONThis page last changed on Jan 04, 2010 by jwheeler.

Using the JSON ModuleThis page is under construction. The JSON module will be available as of Mule 3.x. JavaScript Object Notation (JSON) is a lightweight computer data interchange format. It is a text-based, human-readable format for representing simple data structures and associative arrays (called objects). Mule uses the Jackson Framework to marshal and unmarshal JSON to Java objects.

Enabling the JSON ModuleOnce you have included the JSON module in your project or in the Mule distribution, you can use it by adding the JSON namespace to your Mule XML configuration file:

You can now start using JSON transformers and filters in your configuration.

Transformers Converts a java object to a JSON encoded object that can be consumed by other languages such as Javascript or Ruby. The JSON engine can be configured using the jsonConfig attribute. This is an object reference to an instance of: net.sf.json.JsonConfig. This can be created as a spring bean. Users can configure a comma-separated list of property names to exclude or include i.e. excludeProperties="address,postcode". The returnClass for this transformer is always java.lang.String, there is no need to set this.

Attributes

Name jsonConfig-ref

Type string

Required no

Default

Description The JSON engine can be configured using the jsonConfig attribute. This is an object reference to an instance of:


Page 16

net.sf.json.JsonConfig. This can be created as a spring bean. excludeProperties string no

Users can configure a comma-separated list of property names to exclude i.e. excludeProperties="address,pos

includeProperties

string

no

Configure a commaseparated list of property names to include i.e. includeProperties="name,email"

sourceClass

string

no

Restrict the accepted source class object to a specific type. If not set the transformer will handle all source types. Note that if you need to specify an array type you need to postfix the class name with '[]'. For example, if you want to ensure the transformer only accepts an Orange[], you set the sourceClass to 'org.mule.tck.testmodels.fruit.O

Child Elements

Name

Cardinality

Description

ExampleIn this example, we configure a transformer to convert from a JavaBean to a JSON encoded string. The transformer by default will encode any JavaBean, but we have restricted the object type it can handle by setting sourceClass to org.mule.tck.models.fruit.Orange. We also exclude the brand and radius properties, so these will not be serialized.

A transformer that will convert a JSON encoded object graph to a java object. The object type is determined by the 'returnClass' attribute. Note that this transformers supports Arrays and Lists. For example, to convert a JSON string to an array of org.foo.Person, set the the returnClass=[Lorg.foo.Person; . The JSON engine can be configured using the jsonConfig attribute. This is an object reference to an instance of: net.sf.json.JsonConfig. This can be created as a spring bean.

Attributes

Name jsonConfig-ref

Type string

Required no

Default

Description The JSON engine can be configured using the jsonConfig attribute. This is an object reference to an instance of: net.sf.json.JsonConfig. This can be created as a spring bean.

Child Elements

Name

Cardinality

Description

ExampleIn this example, we convert JSON data to JavaBeans and use a powerful feature of Jackson called mixins. Mixins allow you to add annotations to an interface or abstract class that can then be mixed in with the object that will get populated with the JSON data. Mixins are useful when you do not control the bean class.


Page 18

Converts a JSON encoded object representation in to an XML representation. Each property and enclosing element are wrapped in XML elements these generated element names can be set on the transformer. Names can be configured for Object elements, array elements and value elements. The returnClass for this transformer is always java.lang.String, there is no need to set this.

Attributes

Name

Type

Required no

Default

Description The XML element name to use for representing objects in the JSON ecoded object. The default is 'o'. The XML element name to use for representing objects in the JSON ecoded object. The default is 'a'. The XML element name to use for representing object values (properties) in the JSON ecoded object. The default is 'e'.

objectElementName name (no spaces)

arrayElementName

name (no spaces)

no

valueElementName

name (no spaces)

no


Page 19

Child Elements

Name

Cardinality

Description

Filters A filter that will determine if the current message payload is a JSON encoded message.

Attributes Child Elements

Name Name

Type Cardinality

Required Description

Default

Description

ExampleThere are no configuration parameters for this filter.


Page 20

Configuring EncodingThis page last changed on Sep 14, 2009 by jwheeler.

Configuring EncodingMule ESB supports multibyte messages. Most modern transports like SMTP, HTTP, and SOAP enclose encoding information in their messages as metadata. For other transports like File, FTP, and JMS, you must configure the encoding, either on the endpoint or globally for the Mule instance. If you do not specify the encoding explicitly, Mule uses the default encoding of UTF-8.

Endpoint EncodingTo configure the encoding on the endpoint, you use the message properties transformer as follows:

Note that the encoding attribute on the endpoint element does not currently work. Use the transformer as described above instead.

Global EncodingTo configure the encoding globally for a Mule instance, you specify it as a Java system property in conf/ wrapper.conf:

wrapper.java.additional.=-Dmule.encoding=Windows-31J


Page 21

Hot Deploying Mule ApplicationsThis page last changed on Jan 27, 2010 by jwheeler.

Hot Deploying Mule Applications[ How it Works ] [ Preparing the Configuration File ] [ Deploying Mule as a Service ] [ Packaging the Mule Application ] [ Deploying the Mule Application ] Hot deployment is currently in beta and is available as a preview release in the enterprise edition of Mule ESB 2.2.3. Hot deployment is not yet available in the Mule 3.x CE snapshots. Hot deploying your Mule applications allows you to update your configuration files and/or transformers, filters, or component implementations without restarting Mule. When you hot deploy a Mule application, only that application will stop/start, and any other Mule applications that are deployed will continue to run as before. Hot deployment is currently supported with: JBoss 4.2.x (JBoss 5.x is not currently supported) Geronimo 2.1.x Tomcat 6.0.x MuleSoft Tcat Server 6

How it WorksA Mule application is one or more configuration files packaged up with any dependencies that are not already provided by Mule. In a hot deployment scenario, each Mule application shares a single Mule instance running in an application server or web container. To hot deploy Mule applications, you do the following: Configure Mule to run as a service in the container Package your Mule applications as WAR files so that you can deploy them as web applications When you deploy the WAR file, Mule reads the Mule configuration file and creates and starts all the required objects just as when running Mule standalone. When you undeploy a Mule application, only the objects created and started for that Mule application are stopped and disposed of without affecting any other applications sharing the same Mule instance. In this way, multiple Mule applications can be deployed, undeployed, and redeployed independently with no downtime for any other services. Two of the key advantages of using a single shared Mule instance are: A greatly reduced memory footprint over using multiple Mule instances. The ability to share objects across applications. For example, you could have a single webapp that defines the connectors, filters, and transformers that are then used by the other webapps. Note: If you share objects across applications, be sure to first deploy the webapp that creates the shared objects, and then deploy the remaining webapps that use those objects.

Preparing the Configuration FileWhen defining the scope of your applications and their configurations, keep the following points in mind: Each Mule application uses an instance of Mule that is already started. Therefore, your application cannot modify anything in the element, including attributes and child elements, which are required to be configured before Mule startup. If you need to modify these settings, you must modify them on the Mule instance and restart it. If you don't explicitly define the connector that should be used by an endpoint, and another web application that is already deployed defines a connector that supports the same protocol, that existing connector defined will be used.


Page 22

Deploying Mule as a ServiceTo deploy Mule as a service to an application server (JBoss, Geronimo), you simply deploy the JCA resource adapter distribution. You don't need to open or repackage the resource adapter archive but can just deploy it as unless you need to edit the MuleConfiguration properties or the default Mule configuration file. You can also safely ignore the "EJB Configuration" section. To deploy Mule as a service to Tomcat or Tcat Server, see Deploying Mule as a Service to Tomcat.

Packaging the Mule ApplicationEach Mule application you set up for hot deployment consists of one or more configuration files plus supporting custom classes, all packaged as a standard web application (WAR deployment archive file). You can create the WAR using your favorite IDE or build tool as you would create any standard web application. To enable Mule to find and load your configuration, you must include a web.xml file that points to your configuration files and to the deployable listener, as shown below:

MuleEchoExample Mule Echo Example org.mule.config echo-cxf-config.xml org.mule.config.builders.DeployableMuleXmlContextListener

Deploying the Mule ApplicationYou deploy your Mule application WAR file in exactly the same way you deploy any web application on the application server or web container you are using. That is, you can use a web administration console, command-line deployment tool, Maven, or your IDE. For example, if you are deploying to Tomcat, you simply copy your WAR to the Tomcat webapps directory. For more information, see the documentation for your application server or web container. If your Mule applications share objects, be sure to first deploy the application that creates those objects, and then deploy the applications that use them.


Page 23

Deploying Mule as a Service to TomcatThis page last changed on Jan 27, 2010 by jwheeler.

[ Deploying Mule as a Service to Tomcat ] [ Installing Mule in Tomcat ] [ Copying the Mule Application Files ] [ Hot Deploying Mule Applications ]

Deploying Mule as a Service to TomcatThis page describes how to install Mule as a service in Apache Tomcat and set up your Mule applications for hot deployment. For more information on hot deploying Mule applications, see Hot Deploying Mule Applications.

Installing Mule in TomcatTo install Mule in Tomcat so that you can hot deploy your Mule applications, you take the following steps: 1. Download and install Apache Tomcat 6 from the Apache web site following the standard installation instructions. 2. In the Tomcat home directory, add the following line to the conf/server.xml file: 3. Copy the contents of the Mule lib folder with all its subdirectories except /boot to the mule-libs/ directory under your Tomcat home directory (create one if necessary). You do not need to flatten the directories. 4. Copy the mule-module-tomcat-.jar file to the mule-libs/mule/ directory under your Tomcat home directory (if it is not there already). 5. Copy the following libraries from your Mule lib/boot/ directory to your Tomcat mule-libs/opt/ directory: jcl104-over-slf4j-1.5.0.jar log4j-1.2.14.jar slf4j-api-1.5.0.jar slf4j-log4j12-1.5.0.jar 6. In the Tomcat conf/catalina.properties file, add the following to common.loader (precede with a comma to separate it from existing values): ${catalina.home}/mule-libs/user/*.jar,${catalina.home}/mule-libs/mule/*.jar, ${catalina.home}/mule-libs/opt/*.jar

Copying the Mule Application FilesAfter you package your configuration files and custom Java classes in a WAR file (see Hot Deploying Mule Applications), copy your Mule applications WAR files to the Tomcat /webapps directory.

Hot Deploying Mule ApplicationsAfter you have copied the WAR file for your Mule application to the Tomcat /webapps directory, Tomcat deploys it. If you need to make a change to a configuration or Java file in the webapp, simply modify the file in the exploded directory under the Tomcat /webapps directory, and then touch the web.xml file (or you can simply add and delete a space in the file and then save it) to trigger Tomcat to redeploy the application. Alternatively, you could modify the source files, repackage them as a WAR, and drop the new WAR into the /webapps directory to trigger Tomcat to redeploy the application.


Page 24

Starting Mule with the ConfigurationThis page last changed on Sep 14, 2009 by jwheeler.

Staring Mule with the ConfigurationWhen you start Mule ESB from the command line, you simply specify the configuration file(s) with the config parameter:

mule -config foo-config.xml

mule -config foo-config.xml,bar-config.xml

If you want to start Mule by calling it from your code, you specify the configuration file as a parameter to the configuration builder:

MuleContext context = new DefaultMuleContextFactory().createMuleContext(new SpringXmlConfigurationBuilder("foo-config.xml")); context.start();

For information on setting system properties from your code, see Configuring Properties. For information on accessing the existing configuration from your code after startup, see Accessing the Configuration Programmatically. For more information on Mule configuration files, see About the XML Configuration File and Scripting Module.


Page 25

About Mule ConfigurationThis page last changed on Sep 14, 2009 by jwheeler.

About Mule Configuration[ Overview of Configuration Elements ] [ Global Configuration Settings ] [ Accessing the Configuration Programmatically ] By default, Mule ESB starts up with a simple configuration in which only some system-level services are configured. You must configure services, transformers, and the rest of the elements required for your application. Following is an introduction to configuring Mule ESB via the Spring XML file. For details on this file, see About the XML Configuration File. For information on starting Mule with the configuration file or accessing the configuration programmatically, see Starting Mule with the Configuration.

Overview of Configuration ElementsA Mule ESB configuration file is a tree of elements, as shown in the following illustration:

Following is a brief description of these elements: Mule Global Configuration - Global settings, such as the default transaction time-out, that apply to the entire Mule configuration Connectors - Non-default configuration of any transports used Endpoints - Define the channel and address or path where messages are sent or received. You can define them globally and use them in multiple services. Transformers - Convert data from one format to another. You can define them globally and use them in multiple services. Filters - Filter out the messages that don't match specific criteria. You can define them globally and use them in multiple services. Models - One or more models that logically group together your services. Services - One or more services that wrap your components (business logic) and configure routers, endpoints, transformers, and filters specifically for that service Following is an example of a simple Mule configuration file:


Page 26

Other, more advanced things you may configure at this level: Security Manager - Authenticates requests based on one or more security providers Agents - Agents are typically used for cross-cutting concerns such as logging or management Notifications - Allow you to be notified upon certain lifecycle events Transaction Management - Mule transactions are configured on inbound endpoints, where an endpoint can be configured to start a new transaction or join an existing one. Properties - Property placeholders, message properties, and system properties.

Global Configuration SettingsYou can configure global configuration settings such as the default transaction timeout and default threading profile in the element. For example:

... ...

For a list of the available global configuration settings, see Global Settings Configuration Reference.

Accessing the Configuration ProgrammaticallyAll Mule configuration is accessible from a single object: org.mule.api.config.MuleConfiguration . Configurations in a MuleConfiguration are set when a MuleContext is created. The object becomes immutable after it is started and can be accessed using the following:

MuleContext context = MuleServer.getMuleContext(); MuleConfiguration configuration = context.getConfiguration();


Page 27

About Configuration BuildersThis page last changed on Sep 14, 2009 by jwheeler.

About Configuration Builders[ SpringXmlConfigurationBuilder ] [ ScriptConfigurationBuilder ] [ Custom Configuration Builders ] [ Specifying the Configuration Builder ] The configuration builder is responsible for creating the configuration that's used at run time from the configuration files you provide. Mule ESB provides two standard configuration builders, or you can create your own.

SpringXmlConfigurationBuilderThe default configuration builder used to configure Mule is the SpringXmlConfigurationBuilder. This configuration builder uses Spring to configure Mule based on one or more XML files leveraging custom Mule namespaces. For more information, see About the XML Configuration File.

ScriptConfigurationBuilderThis configuration builder allows a JSR-223 compliant script engine such as Groovy or Jython to configure Mule. For more information, see Scripting Module.

Custom Configuration BuildersYou can easily create your own custom configuration builder by implementing the ConfigurationBuilder interface, which has a method configure. Typically, you call configure(MuleContext muleContext.getRegistry()) to get access to Mule's internal registry, which contains the configuration information, and to register services and other elements. In most cases, you will want to inherit from the class AbstractResourceConfigurationBuilder , which will make any configuration files specified on the command line available in an instance variable called configResources.

Specifying the Configuration BuilderSpringXmlConfigurationBuilder is the default configuration builder. If you want to use another configuration builder, you can specify it on the command line at startup with the -builder parameter:

mule -builder org.mule.module.scripting.builders.ScriptConfigurationBuilder -config mule-config.groovy

You can also specify the configuration builder as a parameter to the MuleContextFactory when starting Mule programatically:

MuleContext context = new DefaultMuleContextFactory().createMuleContext(new ScriptConfigurationBuilder("mule-config.groovy")); context.start();


Page 28

Configuring PropertiesThis page last changed on Sep 14, 2009 by jwheeler.

Configuring Properties[ Property Placeholders ] [ Global Properties ] [ Properties Files ] [ Message Properties ] [ System Properties ] [ Environment Variables ] This page describes configuring properties, such as property placeholders and system properties.

Property PlaceholdersYou can use Ant-style property placeholders in your Mule ESB configuration. For example:

The values for these placeholders can be made available in a variety of ways, as described in the sections below.

Global PropertiesYou can use the element to set a placeholder value from within your Mule configuration, such as from within another Mule configuration file:

Properties FilesTo load properties from a file, you can use the standard Spring element :

xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd"

where the contents of smtp.properties is:

smtp.username=JSmith smtp.password=ChangeMe

The placeholderPrefix value can be anything other than "#[", which is what Mule uses to parse its message properties in expressions. We recommend you set the value to "${". Note that you do not have to change anything in your Spring configuration or properties file to match this value; it simply differentiates Spring properties from Mule properties.


Page 29

To load multiple properties files, separate them with commas:

Message PropertiesYou can use placeholders to perform logic on message properties such as the header. For example, if you wanted to evaluate the content-type portion of the message header, you would specify it as #[header:Content-Type]. Typically, you use message property placeholders with expressions. For more information, see Using Expressions.

System PropertiesThe placeholder value can come from a JDK system property. If you start Mule from the command line, you would specify the properties as follows:

mule -M-Dsmtp.username=JSmith -M-Dsmtp.password=ChangeMe -config my-config.xml

or edit the system properties in conf/wrapper.conf if you are deploying Mule as a webapp. When running Mule in a container, as of Mule 2.2.2 you can also specify the server ID in the web.xml file as follows:

mule.serverId MyServer

If you start Mule programmatically, you would specify the properties as follows before creating and starting the Mule context:

System.getProperties().put("smtp.username", "JSmith"); System.getProperties().put("smtp.password", "ChangeMe");

There are also several system properties that are immutable after startup. To set these, you customize the MuleConfiguration using the set method for the property (such as setId for the system ID), create a MuleContextBuilder, load the configuration to the builder, and then create the context from the builder. For example:

SpringXmlConfigurationBuilder configBuilder = new SpringXmlConfigurationBuilder("my-config.xml"); DefaultMuleConfiguration muleConfig = new DefaultMuleConfiguration(); muleConfig.setId("MY_SERVER_ID"); MuleContextBuilder contextBuilder = new DefaultMuleContextBuilder(); contextBuilder.setMuleConfiguration(muleConfig); MuleContextFactory contextFactory = new DefaultMuleContextFactory(); MuleContext muleContext = contextFactory.createMuleContext(configBuilder, contextBuilder);


Page 30

muleContext.start();

For information on the set methods you can use to set system properties, see org.mule.config.DefaultMuleConfiguration . For information on configuration builders, see About Configuration Builders.

Environment VariablesThere is no standard way in Java to access environment variables. However, this link has some options you might find useful.


Page 31

Mule High AvailabilityThis page last changed on Sep 14, 2009 by jwheeler.

Mule High Availability[ Supported Architecture ] [ Installation and Configuration ] [ Running Mule High Availability ] [ Example Application ] [ Disabling Mule High Availability ] [ Limitations ] Mule High Availability provides basic failover capability for Mule ESB. When the primary Mule instance become unavailable (e.g., because of a fatal JVM or hardware failure or it's taken offline for maintenance), a backup Mule instance immediately becomes the primary node and resumes processing where the failed instance left off. After a system administrator has recovered the failed Mule instance and brought it back online, it automatically becomes the backup node. Seamless failover is made possible by a distributed memory store that shares all transient state information among clustered Mule instances. This can include information in SEDA service event queues and in-memory message queues. Mule High Availability is currently available for the following transports: HTTP (including CXF Web Services) JMS WebSphere MQ JDBC File FTP Clustered (replaces the local VM transport)

Mule High Availability is available with Mule Enterprise subscriptions. For details, contact us.

Supported ArchitectureMule High Availability supports the following architecture: Two Mule 2.2.1 or later instances (hotfix patch required for Mule 2.2.1) running standalone Active-Passive topology: one primary node, one backup Reverse proxy server (such as Apache) required for socket-based transports (HTTP, Web services, and TCP) to forward requests to the currently active node Multicasting must be enabled on each server where Mule is installed High Availability is not a replacement for transactions and does not guarantee reliability. If your message flow is not transactional, you will likely suffer from lost, partial, or duplicated messages in the case a failover should occur. For details on specific features that are not supported in the current release, see Limitations below.

Installation and ConfigurationYou must have two identical Mule instances installed and configured: a primary instance and a backup instance. Although these instances could be on the same machine, they should ideally be separated (different machines in different physical locations) to avoid having a single point of failure. Be sure to follow the steps in this section for both instances of Mule.


Page 32

Installing Mule High Availability1. Make sure the Mule instance is stopped. 2. If you have made changes to your wrapper.conf, extra-bootstrap-modules.xml, or log4j.properties files in the conf directory, make backup copies of them so that you can merge your changes back in after installing Mule High Availability. 3. Download the Mule High Availability ZIP file from the location provided by your MuleSoft sales representative. 4. Unzip the ZIP file to the Mule installation directory. The files are installed on top of your existing Mule installation. If you are using the Mule IDE, also copy the mule-module-cluster JAR into the lib\mule directory under your Mule installation directory. This will enable you to select the Cluster transport when creating a configuration file.

Configuring the System PropertiesAfter installing Mule High Availability, you will find some new system properties in your conf/ wrapper.conf file. These parameters are used to constitute the unique ID of each instance in the cluster. You do not need to change their values, but you do need to uncomment the last line (clusterNodeBackupId) for one of your two Mule instances (but not both!).

# Cluster topology wrapper.java.additional.5=-Dmule.clusterId=DEFAULT wrapper.java.additional.6=-Dmule.clusterNodeId=1 # Uncomment for all but one node in the cluster #wrapper.java.additional.7=-Dmule.clusterNodeBackupId=1

Alternatively, you could set these properties from the command line when you start Mule, or set them in Java code if you start Mule programmatically. For details, see "System Properties" on the Configuring Properties page.

Modifying Your Configuration FilesTo use the Mule High Availability capabilities, you must make some changes to your Mule XML configuration file(s). Future versions of Mule will make high availability support more transparent, and the following changes to your configuration may no longer be necessary. The Mule Enterprise Migration Tool will help with any migration of configuration when this occurs. Import the "cluster" Namespace

Mule 2.2.1 Users Guide

Documents

Transcript of Mule 2.2.1 Users Guide