Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (4.12)
  3. Maven Support in Mule

  4. Package a Mule Application

Package a Mule Application

Mule Maven plugin versions 3.0.0, 3.1.0, 3.1.1, 3.1.2, 3.1.3, 3.1.4, 3.1.5, 3.1.6, 3.1.7, and 3.8.3 are deprecated.

You can package your Mule applications using Mule Maven Plugin(command line) or Anypoint Studio. See Exporting Projects from Studio for details about this procedure.

Mule applications are packaged into a deployable JAR file that you can later deploy to a running Mule runtime engine. The package contains the application and all its dependencies whether those be JAR files required by the application or by its plugins.

Every Mule application has two descriptors. These descriptors define your Mule application’s dependencies:

  • A mule-artifact.json file.
    This file describes how your application is composed.

  • A pom.xml file.
    This file describes all the dependencies required by the package to work properly.

Compatibility

Mule 4 applications are compatible with these Anypoint Studio and Mule Maven Plugin versions:

  • Anypoint Studio 7.x

  • Mule Maven Plugin 3.x

Prerequisites

Specify the Mule Runtime Version for Packaging

Starting with Mule Maven plugin 4.6.0, you can specify the Mule runtime version that the Mule framework uses during the packaging process by adding the runtimeVersion property in the Mule Maven plugin configuration in your pom.xml file:

<plugin>
  <groupId>org.mule.tools.maven</groupId>
  <artifactId>mule-maven-plugin</artifactId>
  <version>${mule.maven.plugin.version}</version>
  <extensions>true</extensions>
  <configuration>
    <runtimeVersion>4.9.6</runtimeVersion>
  </configuration>
</plugin>
By default, Mule Maven plugin selects a Mule runtime version that is compatible with the plugin’s framework version. If you set a specific runtimeVersion to use a particular Mule runtime patch, you can encounter compatibility issues if that patch isn’t supported by the framework version in use.

Mule Application Structure Reference

At design time, your Mule application must have at least these three basic components:

Component Type Description

src

Folder

The source directory for your application’s productive source code and tests.
See a reference for this folder below.

pom.xml

Descriptor

The POM file of your Mule application.
This file describes all of your application’s required dependencies.

mule-artifact.json

Descriptor

The mule-artifact file of your Mule application.
This file describes how your Mule application is composed.

These three components are mandatory. If one of them is missing, the project cannot be packaged into a deployable JAR file.
Additionally, the packaging process does not consider any other directory or file in the root folder of your Mule application.

Application Descriptor Reference (mule-artifact.json)

The mule-artifact.json file is the application descriptor. It describes how your Mule application is composed and the requirements it has to run on a Mule runtime engine. This table describes the most common fields:

Field Type Description

name

String

The name of the application.

minMuleVersion

String

The minimum Mule version required to run the application, for example, 4.9.0. The application can’t be deployed to a runtime later than this version. See minMuleVersion and Runtime Compatibility for details.

requiredProduct

String

The Mule runtime edition required to run the application. Valid values are MULE (Community edition) and MULE_EE (Enterprise edition).

configs

Array of strings

The list of configuration files that make up the application. See Declaring Multiple Configurations.

redeploymentEnabled

Boolean

Whether the application supports hot redeployment. Defaults to true.

secureProperties

Array of strings

The names of the properties whose values must be treated as secrets. Their values aren’t displayed in the Runtime Manager UI when viewing the artifact’s deployment configuration. See Secure Configuration Properties.

This example shows a typical mule-artifact.json file:

{
  "name": "retail-api",
  "minMuleVersion": "4.9.0",
  "requiredProduct": "MULE_EE",
  "configs": [
    "http-api.xml", "jms-messaging-api.xml"
  ],
  "redeploymentEnabled": true
}
Anypoint Studio and the Mule Maven plugin manage the application descriptor automatically. You typically don’t edit mule-artifact.json manually.

minMuleVersion and Runtime Compatibility

The minMuleVersion field declares the minimum Mule runtime version that the application requires. Deployment fails if you deploy the application to a runtime whose version is later than minMuleVersion, because the runtime can’t guarantee that the features the application depends on are available.

When this happens, the deployment doesn’t complete and the runtime logs a fatal error similar to this one:

A Fatal error has occurred while the server was running: Artifact my-app
requires a newest runtime version. Artifact required version is 4.11.0 and
Mule Runtime version is 4.9.20

To resolve this error, take one of these actions:

  • Set minMuleVersion to a value equal to or earlier than the target runtime version.

  • Deploy the application to a runtime whose version is equal to or later than minMuleVersion.

The required Mule version can be a later one than the version you set if a connector or other application dependency requires a later Mule runtime version. In that case, the error message reports the version required by the dependency. Verify the required version in the error message, and then either upgrade the target Mule runtime version or use a dependency version that’s compatible with your runtime.

Source Directory Reference

The src directory has two main folders: main and test.
The plugin does not consider any other directory inside src when packaging the application.

src/main

src/main is the root folder for all the productive source code of the application.

Folder Folder Type Description

src/main/mule

source

The root folder of the Mule configuration files.
It can contain nested folders, in the way of Java packages.

This folder is mandatory.

src/main/resources

resource

It contains the application resources, such as XML, JSON, and properties files.
Jar files located here are loaded by the application classloader but as plain file resources.

The packaging process sends all files inside src/main/mule and src/main/resources to the root directory of your binary package.
Nested folders within src/main/mule are preserved as directories within the root directory of the binary package.

src/test

src/test is the root folder for all the test source code of the application.

Folder Folder Type Description

src/test/java

source

It’s the root folder of the test classes used to validate the custom Java code of the app.
It follows the conventions of any normal Java application.

src/test/munit

source

It contains the MUnit source code.
It can contain nested folders in the way of packages.

src/test/resources

resource

It contains resources, such as XML, JSON, and properties files.
This folder also contains files describing metadata being referenced in the mule-config.xml.

Package a Mule Application

From the command line in your project’s folder, execute the package goal:

mvn clean package

The plugin packages your application and creates the deployable JAR file into the target directory within your project’s folder.

If there is a dependency version conflict in your pom.xml, the latest version is used.

Create an Application Package to Import into Anypoint Studio

To generate a JAR file that can be imported into Anypoint Studio, you must package your application using the -DattachMuleSources parameter to include source files and metadata that Studio requires to reimport the deployable file as an open Mule project into your workspace.

From the command line in your project’s folder, run:

mvn clean package -DattachMuleSources

The -DattachMuleSources parameter tells the plugin to add a mule-src folder inside the META-INF directory with an exact copy of your application structure at design time. This option also packages project modules and dependencies required to create a functioning Mule deployable archive file that can be deployed into a Mule runtime engine.

Create a Lightweight Package

You can skip bundling the actual modules and external dependencies required to run the Mule application in a Mule runtime engine, and create a lightweight package with only the source files and metadata required to import the JAR package back into Anypoint Studio.

From the command line in your project’s folder, run:

mvn clean package -DlightweightPackage

When you specify this parameter, the plugin creates a lightweight JAR file that does not include any dependencies declared in the Mule application’s pom.xml file. This JAR file cannot be deployed to a Mule runtime engine, it only offers a way to archive just the Mule application’s source files. The result of this Maven parameter is the same as unchecking Include project modules and dependencies when exporting the Mule application from Anypoint Studio.

Specify Multiple Parameters

You can also combine the parameters together to create a lightweight Mule application package that also includes the source files and metadata to import the package back into Anypoint Studio.

From the command line in your project’s folder, run:

mvn clean package -DattachMuleSources -DlightweightPackage

Exclude Files from the Application Package

When you package an application, you can exclude certain files or directories. Create a _muleExclude file at the project root directory and edit its content to set the exclusion rules.

Each line in a _muleExclude file specifies a rule that follows the glob pattern.

For example, consider this _muleExclude file that contains two exclusion rules:

fileToBeExcluded.json
**/src/main/resources/local_directory

  • The first line indicates that all files named fileToBeExcluded.json, inside any directory, are excluded from the application package.

  • The second line indicates that only the directory named local_directory located under src/main/resources is excluded from the package.
    If **/src/main/resources/local_directory is replaced with local_directory then all directories named local_directory, inside the project, are excluded from the application package.

See Also