Embedding Mule in a Java Application or Web app

This page describes how to start and stop Mule from a Java application or to embed it in a Web app (such as a JSP or servlet), and how to interact with Mule from your code in both scenarios.

Starting Mule from a Java Application

Before running Mule in embedded mode in either a Java application or a Web app, be sure to manually update all the required dependencies for your application. The Mule Embedded Runtime JAR contains all Mule classes, but you need to include the dependencies manually.

Download the Mule Embedded Runtime JAR from https://developer.mulesoft.com/download-mule-esb-runtime to add to the classpath for your application before starting Mule.

To start Mule from a Java application, call one of its configuration builders.

To use Mule XML configuration:

DefaultMuleContextFactory muleContextFactory = new DefaultMuleContextFactory();
SpringXmlConfigurationBuilder configBuilder = new SpringXmlConfigurationBuilder("mule-config.xml");
muleContext = muleContextFactory.createMuleContext(configBuilder);

Make sure you store a reference to the MuleContext, as you need it to stop Mule.

If you have multiple configuration files, you can provide a comma-separated list or an array of configuration files:

SpringXmlConfigurationBuilder configBuilder =
     new SpringXmlConfigurationBuilder(new String[] { "mule-config.xml", "another-config.xml" });

Call the start method to start the server:

muleContext.start();

Stopping Mule from a Java Application

To stop Mule, stop its context like this:

muleContext.stop();
muleContext.dispose();

Embedding Mule in a Webapp

Mule Standalone vs. Application Server

Listed below are some of the advantages of running Mule standalone vs running it as a web application deployed in an application server (Tomcat, WebSphere, JBoss, etc.)

Wrapper control: Mule Standalone makes use of a Java Service Wrapper 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.
Smaller memory footprint: Mule standalone loads only the required resources for an application; an application server adds its own resources.
Anypoint DataMapper support: DataMapper is supported only on a Mule Enterprise Standalone runtime; other application servers do not support DataMapper.
Deployment and Application Management: Through the Mule Management Console, you have full control of the applications running on Mule Standalone, allowing you to deploy/undeploy applications and restart/stop the server. Other application servers do not support this visibility.

To embed Mule inside a webapp, provide one or more configuration file locations as context params and include a context listener to initialize the Mule Server. If you are using Mule XML configuration, use the following:

<context-param>
    <param-name>org.mule.config</param-name>
    <param-value>mule-config-main.xml,mule-components.xml</param-value>
</context-param>

<listener>
    <listener-class>org.mule.config.builders.MuleXmlBuilderContextListener</listener-class>
</listener>

The configuration parameter can be a classpath location or file location. You can also specify multiple configuration files on the classpath or in the file system.

Interacting with Mule from Your Code

To interact with the Mule server from your application, JSP, or servlet, you can use the Mule Client.

// In your servlet init() method, save servletConfig.getServletContext() to a field
MuleContext muleContext = servletContext.getAttribute(MuleProperties.MULE_CONTEXT_PROPERTY);
// Create a client
MuleClient client = new MuleClient(muleContext);

// Send a JMS message asynchronously
client.dispatch("jms://my.queue", "some data", null);

// Or to receive a pop3 message via a configured mailbox
MuleMessage message = client.receive("pop3://myInboxProvider", 3000);

// Or synchronous send a inter-vm message
MuleMessage message2 = client.send("vm://my.object", "Some more data", null);

Licensing an Embedded Application for Testing

Mule requires that a license be present to run tests in embedded mode. Without a license, one of these errors appears:

site-specific-info. license.NoLicenseInstalledException
This Module requires an Enterprise license

To overcome this error:

Generate a digested license from a Mule license (the one that you were provided with and is available in the Customer Portal).
For this you have two alternatives:
- Generate the license at http://mulelicenseverifier.cloudhub.io
- Run the standard procedure for installing a license in Mule standalone so that the digested license is in {MULE_HOME}/conf/muleLicense.lic
Copy the digested license file to a location in the classpath of your application.

Set the following system property:

-Djava.util.prefs.PreferencesFactory=com.mulesource.licm.pref.MulePreferencesFactory

If you still experience errors after all this changes, verify that the path where the license is located doesn’t contain any space as this prevents the license verification mechanism from finding it.