Running Mule

Now that you have installed Mule, you are ready to get started! This page describes the various ways in which you can run Mule.

If you are using the 30-day trial version of Mule Enterprise, you will no longer be able to start the trial version after the 30 days has expired unless you purchase a license. (This does not affect the Community edition of Mule.) For information on purchasing Mule Enterprise, click here.

Starting with the Examples

To run Mule, you must specify a configuration file to use. Typically, this is an XML file called mule-config.xml. The examples directory provides you with several examples of Mule applications including their configuration files, which you can use as the starting point for creating your configuration file. For more information, see Examples.

Working with Configuration Files

If needed, you can specify more than one configuration file in a comma-separated list. This approach is useful for splitting up your Mule configuration to make it more manageable. All configuration files must be on the classpath prior to startup. A convenient way to achieve this is by placing them in the /conf or
/lib/user directory.

Alternatively, you can specify an explicit path to their location on the file system. If you make changes to a configuration file, you must restart Mule for the changes to take effect.

Using the Command Prompt

To run Mule, you enter the following command at the command prompt:

mule [-config <your-config.xml>]

where <your-config.xml> is the Mule configuration file you want to use. If you don't specify the configuration file, Mule looks for mule-config.xml, which is a generic name that does not exist in the default configuration. If you will have only one configuration file, you can name it mule-config.xml so that you can run Mule with it just by typing mule. To stop Mule, enter: Ctrl-C.

When you run the mule command, it launches the mule.bat or mule.sh script in your MULE_HOME/bin directory. These scripts invoke the Java Service Wrapper (http://wrapper.tanukisoftware.org), which controls the JVM from your operating system and starts Mule. The Wrapper can handle system signals and provides better interaction between the JVM and the underlying operating system. It also provides many advanced options and features that you can read about on the Wrapper website. For more information on passing in arguments, see Passing Additional Arguments to the JVM below.

The Java Service Wrapper allows you to run Mule as a UNIX daemon, and it can install (or remove) Mule as a Windows NT Service, as described in the next sections.

Running Mule as a Daemon

By default, the mule command runs Mule in the foreground. To run Mule in the background as a daemon, enter the following command instead, using start, stop, or restart as the first parameter as needed:

mule [start|stop|restart] [-config <your-config.xml>]

You can also create a wrapper script that specifies the configuration file and can set the environment variables if the script will be run by a different user. For example:

#!/bin/bash

# Set JDK related environment
JAVA_HOME=<path to JDK>
PATH=$PATH:$JAVA_HOME/bin

# Set Mule related environment
MULE_HOME=<path to Mule>
MULE_LIB=<path to application specific libraries>
PATH=$PATH:$MULE_HOME/bin

# Export environment variables
export JAVA_HOME MULE_HOME MULE_LIB PATH

# Invoke Mule
$MULE_HOME/bin/mule $1 -config <path to mule-conf.xml>

You must set the path to your JDK, Mule installation directory, and Mule configuration file(s). After you have saved this script as /etc/init.d/mule you should also set the appropriate ownership and mode on that script. For example:

chown root:root /etc/init.d/mule
chmod 755 /etc/init.d/mule

You can now use this script to manage the Mule daemon:

/etc/init.d/mule start|stop|restart|status

Running Mule as a Windows NT Service

If you want to install Mule as a Windows NT Service, type

mule install -config <your-config.xml>

Likewise, to remove Mule from your services, type:

mule remove

Once you have installed Mule as a service, you can invoke the service exactly as you did before, but with an additional parameter:

mule [start|stop|restart] [-config <your-config.xml>]

You can also use the Windows net utility:

net [start|stop] mule

Passing Additional Arguments to the JVM

The Wrapper provides several properties you can set as described here. If you want to pass additional arguments to the JVM that will run Mule, you can add wrapper.java.additional.n entries to the wrapper.conf file in the /conf directory under the Mule installation directory, or you can pass the arguments at the command line by adding the -M switch.

For example, to set Mule's encoding, you could add wrapper.java.additional.1=-Dmule.encoding=ISO-8859-1 to the Wrapper configuration file, or you could add -M-Dmule.encoding=ISO-8859-1 to the Mule script at the command line. Note that if you add wrapper.java.additional.n entries to the configuration file, you must change each instance of n to a consecutive number, or Java will not parse the properties correctly.

Starting Mule Directly

To start Mule from a script or from your IDE without using the Java Service Wrapper, you can use the org.mule.MuleServer class. This class accepts a couple of parameters.

org.mule.MuleServer -config mule-config.xml 

or

org.mule.MuleServer -builder <fully qualified classname> -config appContext.xml

• -config specifies one or more configuration files to use. If this argument is omitted, it will look for and use mule-config.xml if it exists.
• -builder is a fully qualified classname of the configuration builder to use. If this is not set, the default org.mule.config.builders.AutoConfigurationBuilder is used, which will try to auto-detect configuration files based on available builders. In the most common scenario, this will resolve to org.mule.config.spring.SpringXmlConfigurationBuilder.

The easiest way to set the classpath is to include all JARs in the ./lib/mule and ./lib/opt directories of the distribution. You can look at the dependency report for the server and each of the modules to see exactly which JARs are required for a particular module.

You can also start a Mule server from your code as follows:

//create a new server and configure it with two configuration files
MuleServer server = new MuleServer("mule-config1.xml,mule-config2.xml");

//Start the server. The boolean argument determines if the server should start
//in a new thread or use the current thread
server.start(true);

Often it will not be necessary to start the server like this. If you want to embed Mule in an application or a web application, see [Embedding Mule in a Java Application or Webapp] in the Mule User Guide. (You must log in to see links to the Mule User Guide. Registration is free and only takes a few moments.)

If you are using Mule Galaxy, you can also start Mule using NetBoot. For more information, see Using Mule NetBoot in the Galaxy User Guide.

For information on configuring Mule for performance, memory, and thread profiling, see [Tuning Performance] in the Mule User Guide.