Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Working with Maven

Note that this page is intended for developers who are contributing to the Mule source code. If you are looking for documentation on how to use Maven to work with Mule applications, please visit Mule and Maven.

Maven is a project management utility that you can use to develop projects in Mule.  Though highly recommended, Maven is not strictly necessary to develop applications in Mule.  However, to modify or add to Mule source code, we insist on using Maven to keep the source code project’s hierarchy organized and intact. 

You can use Maven to quickly set up and configure your Mule ESB project. To help you get productive quickly, Mule provides five archetypes that create template files, including all the necessary Java boilerplate content and detailed implementation instructions in comments:

Note that if you run an archetype on an existing project or module that you created, it updates rather creates a new project file. For example, if a project included File and VM transports, and now you want it to include the File and JMS transports, you can re-run the project archetype specifying the same project name. When you specify the transports you want to use in the project, the archetype updates your project files, adding the JMS namespace and removing VM. Access the Maven documentation for more details about Maven.

Maven default local repository location on Windows

In Windows, Maven stores the libraries in the .m2 repository in your home directory.  For example, C:\Documents and Settings\<username>\.m2\repository.  Because RMI tests fail where a directory name includes spaces, you must move the Maven local repository to a directory with a name that does not include spaces, such as %M2_HOME%/conf or %USERPROFILE%/.m2

Mule Source Code Sub-projects

The Mule source code project is neatly organized into a hierarchy of sub-projects. (Sub-projects are sometimes referred to as "modules," but to avoid confusion with Mule modules, we use "sub-projects".) Each sub-project generally produces one Maven artifact, usually a JAR file. The Mule build is structured using intermediate project object models (POMs) to group common sub-projects together. These intermediate sub-projects are sub-folders of the source code’s mule folder, and are described in the table below.

Sub-project Description

buildtools

tools to build Mule, scripts, and checkstyle configuration

core

Mule’s core API and functionality that is required by all transports

distributions

builds the various distributions (refer to the Distributions section below for further details)

examples

examples that come with the full Mule distribution

modules

non-transport extensions to Mule, such as XML processing, Spring extras, or scripting support

tests

integration tests that can be run as part of the Mule build

tools

tools for Mule, such as the transport and project Maven archetypes

transports

Mule transports such as the JMS, VM, and TCP transports

Building Mule

The following table lists common goals to execute for building Mule.

mvn clean

purges any built artifacts or intermediate files (such as .class) from the target directory
Default : target

mvn install

installs the artifact to your local repository
Default: ~/.m2/repository

mvn test

runs any unit tests for this sub-project

mvn -DskipTests install

By default, Maven runs all unit tests for each project for each build which, depending on the project, can take a long time to complete. If you wish, you can skip the tests using this command.

Distributions

When you package Mule for distribution, all distributions and related resources are located in the distributions sub-project. 

For performance’s sake, the distributions are not built from the project’s top-level directory by default. You may either build a distribution from its own directory, or enable the distributions profile by adding -Pdistributions to your Maven command line.

The table below offers a brief description of each type distribution.

Type

Sub-project

Description

Breadth

Full Standalone Server

/distributions/server/full

Packages Mule as a stand-alone server application. Includes all transports, extras and all dependencies. Includes the http://wrapper.tanukisoftware.org[Java Service Wrapper] for starting/stopping/restarting Mule from the native OS.

heavyweight

Custom Standalone Server

/distributions/server/custom

Packages Mule as a standalone server application without any dependencies. If the user’s project is based on Maven, this distribution can easily provide the exact libraries it depends upon because of m2’s intelligent resolution of transitive dependencies.

lightweight

JCA Resource Adapter

/distributions/jca

Packages Mule as a JCA-compatible Resource Adapter for deployment into a J2EE application server. Includes all transports, extras and all dependencies.

heavyweight

Embedded (Composite) JAR File

/distribution/embedded

Packages Mule as a single JAR file containing all Mule classes, including all transports and extras). This distribution is useful when embedding Mule into another application, or when using Mule with a non-Maven-based build. Note that when you use this approach, you are responsible for providing any needed Mule dependencies, as described in the next section.

lightweight

Dependencies

As with all Maven projects, you must add dependencies to the .pom file for your Mule application. 

If using the Enterprise Edition of Mule ESB, you must add dependencies for the Enterprise features you use in your application code. The following lists the Mule ESB Enterprise Edition dependencies.


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
<dependency>
    <groupId>com.mulesoft.muleesb</gropuId>
    <artifactId>mule-core-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-batch-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-boot-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-bti-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-cache-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-cluster-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-multi-tx-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-plugin-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-saml-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-spring-config-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-throttling-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-tracking-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.modules</gropuId>
    <artifactId>mule-module-xa-tx-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.transports</gropuId>
    <artifactId>mule-transport-ftp-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.transports</gropuId>
    <artifactId>mule-transport-jdbc-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.transports</gropuId>
    <artifactId>mule-transport-jms-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.transports</gropuId>
    <artifactId>mule-transport-jms</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.transports</gropuId>
    <artifactId>mule-transport-msmq-ee</artifactId>
    <version>${version}</version>
</dependency>
 
<dependency>
    <groupId>com.mulesoft.muleesb.transports</gropuId>
    <artifactId>mule-transport-wmq-ee</artifactId>
    <version>${version}</version>
</dependency>

Troubleshooting Maven

This section describes some problems you might experience using Maven and how to resolve or work around them.

Problem Description Solution

Files could not be retrieved

You are behind a firewall and get an error stating that repository metadata for org.mule.tools could not be retrieved from the central repository.

Check the proxy settings in your Maven settings.xml file to confirm that they are configured correctly.

OutOfMemory Error

You encounter OutOfMemoryError exceptions when attempting a full build of Mule.

Increasing the max heap and the PermGen space sizes. To do so, either export a MAVEN_OPTS variable in your shell, or add the variable to the original mvn script. Use the following:
MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=256m

Slow build

-

If you know your downloads are up-to-date, you can use the offline option using the following command:
mvn -o

Conflicting transitive dependencies

Transitive dependencies in m2 are both powerful and problematic at times. For example, you many have conflicting library versions or when unwanted libraries are in your classpath.

Use the debug option to display the effective classpath in a tree format, making it easy to see where each library is coming from:
mvn -x

Running a goal for a specific project

By default, Maven execute a goal for a project and all sub-projects in its hierarchy.

If you want to run the goal for a specific project only (and not its children), you can use the non-recursive option:
mvn -N 

Debugging test failures

Surefire, the default Maven test runner, outputs all reports as a set of XML and text files. Any test failure details and stack traces are written to those files instead of the console, so it can be time consuming to open files to find problems.

You can redirect the output to the console temporarily by adding the following option:
mvn -Dsurefire.useFile=false This option skips creation ofthe text report, but still makes the XML report available for transformation by tools.