Creating Module Archetypes

Mule provides Maven archetypes that you can use as code templates for your Mule modules that you want to include with the Mule distribution. These templates include a set of implementation notes and "todo" pointers that help you get started quickly. The Mule module archetype will help you generate a tailored boilerplate module in seconds.

Updating Existing Modules and Transports

The Module archetype allows developers to create new Mule modules or upgrade existing Mule modules adding support for schemas and registry bootstrapping. See Updating an Existing Module for more information.

Follow the instructions below to create template files for a new Mule module, including all the necessary Java boilerplate and detailed implementation instructions in comments.

Configuring Maven

Add the following to the file settings.xml (usually in your Maven conf or $HOME/.m2 directory) so that Maven will allow you to execute Mule plug-ins.

settings.xml

<settings>
    <pluginGroups>
        <pluginGroup>org.mule.tools</pluginGroup>
    </pluginGroups>
    ...
</settings>

Using the Archetype

First, open a command shell and change to the directory where you want to create your module.

 > cd yourDir

Next, you will execute the archetype and generate the code. If this is your first time running this command, Maven will download the archetype for you.

> mvn mule-module-archetype:create -DartifactId=xxx -DmuleVersion=3.1.1                                   -DarchetypeArtifactId=mule-module-archetype

At minimum, you pass in these system parameters:

artifactId: The short name for the project (such as 'myApp'). This must be a single word in lower case with no spaces, periods, hyphens, etc.
muleVersion: The version of the Mule project archetype you want to use. This will also be the default Mule version used for the generated artifact.

archetypeArtifactId: Enter mule-module-archetype when running the module archetype.

Running the archetype

Maven uses by default the latest available version of the archetype. This can cause problems if you want to create a module for an earlier version of Mule. In this case, run the mule-module-archetype specifying the full version of the plugin like this:

mvn org.mule.tools:mule-module-archetype:3.1.1:create ...

artifactId

The artifactId can contain characters such as underscore or hyphen. However, the plug-in will convert the name into a usable form suitable for Java. For example, if the argument is specified as -DartifactId=My#Awesome-Mule_Project, the project will be created in a directory of that name, but the project name will be MyAwesomeMuleProject and the package name will be .myawesomemuleproject

The plug-in will ask various questions (described below) and then generate the files. You can also use this plug-in without user prompts by entering all the arguments at the command line. For a full list of arguments that can be passed in, see the Command Line Options.

After you have answered all the questions, the archetype creates a directory using the module name you specified that includes a POM file for building with Maven, a Mule configuration file (src\main\resources\mule-config.xml) that includes the namespaces for the transports and modules you specified and has placeholder elements for creating your first flow, and a package.html file under src\main\java using the package path you specified. Lastly, it creates some template files under src\test to help you get started creating a unit test for the module. A new MULE-README.txt file will be created in the root of your project explaining what files were created.

Example Console Output

The plug-in prompts you to answer several questions about the project you are writing. These may vary according to the options you select. An example of the output is shown below.

In the example that follows, MuleForge hosting no longer exists. Enter n at the MuleForge prompt.

********************************************************************************

Are you creating a new module (rather than updating an existing one)? [y] or [n]
                                                                    [default: y]
********************************************************************************
y
[INFO] description:
********************************************************************************

                 Provide a description of what the module does:
                                                                     [default: ]
********************************************************************************
foo Bar
[INFO] muleVersion:
********************************************************************************

               Which version of Mule is this module targeted at?
                                                                [default: 3.1.1]
********************************************************************************

[INFO] forgeProject:
********************************************************************************

              Will this module be hosted on MuleForge? [y] or [n]
                                                                    [default: y]
********************************************************************************
n
[INFO] transports:
********************************************************************************

Which Mule transports do you want to include in this module?

(options: axis, cxf, ejb, file, ftp, http, https, imap, imaps, jdbc,
          jetty, jetty-ssl, jms, jnp, multicast, pop3, pop3s, quartz, rmi, servlet,
          smtp, smtps, servlet, ssl, tls, stdio, tcp, udp, vm, xmpp):
                                                                   [default: vm]
********************************************************************************

[INFO] modules:
********************************************************************************

Which Mule modules do you want to include in this module?

(options: builders, client, jaas, jbossts, management, ognl, pgp, scripting,
spring-extras, sxc, xml):
                                                               [default: client]
********************************************************************************

[INFO] hasCustomSchema:
********************************************************************************

Will this module have a custom schema for configuring the module in Xml? [y] or [n]
                                                                    [default: y]
********************************************************************************

[INFO] hasBootstrap:
********************************************************************************

Will this module make objects available in the Registry as soon as it's loaded? [y] or [n]
                                                                    [default: n]
********************************************************************************

Note: OGNL is deprecated in Mule 3.6 and will be removed in Mule 4.0.

The Questions Explained

Are you creating a new module (rather than updating an existing one)?

If you are creating an brand new Mule module, chose yes here. The wizard will then ask you what resources you want to create. If you are updating an existing module, choose no, and see Updating an Existing Module for more information. The following questions get asked if you are creating a new module.

Provide a description of what the project does:

You should provide an accurate description of the module with any high-level details of what you can or cannot do with it. This text will be used where a description of the module is required.

Which version of Mule is this project targeted at?

The version of Mule you want to use for your module. This will default to the archetype version passed in on the command line.

Which Mule transports do you want to include in this project?

A comma-separated list of the transports you plan to use in this module (such as HTTP and VM). This will add the namespaces for those transports to the configuration file.

Which Mule modules to you want to include in this project?

A comma-separated list of the modules you are extending with this module (such as XML and Scripting). This will add the namespaces for those modules to the configuration file.

Will this module have a custom schema for configuring the module in Xml?

All new modules should define an XML schema that defines how the module is configured. If you do not use this option, users will have to use generic configuration to use your module.

Will this module make objects available in the Registry as soon as it’s loaded?

The registry bootstrap is a properties file that specifies class names of simple objects that can be made available in the Mule Registry as soon as the module is loaded. This is useful for registering custom transformers or expression evaluators.

Updating an Existing Module

The module archetype can be used for updating existing modules and transports. It allows developers to add template code for schema configurations and bootstrap the registry. It will leave your existing code untouched.

For example, if your existing module or transport is located under /projects/foo, you update the project by running the following commands:

cd /project/foo && mvn mule-module-archetype:create -DartifactId=foo -DmuleVersion=3.1.1 -DarchetypeArtifactId=mule-module-archetype

Notice that the artifactId must be set to the name of your project. This ensures that any new classes will be created with the same naming scheme.

When you run this command, you will be prompted with three questions. The first question will ask you whether this is a new project. Make sure you select 'n' so that the wizard will upgrade your existing module or transport. It then asks you the last two questions about the custom schema and registry bootstrap. After you answer the questions, the code will be created and a new MULE-UPDATE-README.txt file will be created in the root of your project explaining what files were created.

Command Line Options

By default, this plug-in runs in interactive mode, but it’s possible to run it in 'silent' mode by using the following option:

-DinteractiveMode=false

The following options can be passed in:

Name	Example	Default Value
groupId	-DgroupId=org.mule.applicationxxx	org.mule.application.<artifactId>
packagePath	-DpackagePath=org/mule/application	none
transports	-Dtransports=http,vm	cxf,file,http,jdbc,jms,stdio,vm
muleVersion	-DmuleVersion=3.1.1	none
packageName	-DpackageName=myPkg	none
description	-Ddescription="some text"	none
modules	-Dmodules=xml,scripting	client,management,scripting,xml
basedir	-Dbasedir=/projects/mule/tools	<current dir>
package	-Dpackage=org/mule/application/myPkg	none
artifactId	-DartifactId=myMuleProject	mule-application-<artifactId>
version	-Dversion=1.0-SNAPSHOT	<muleVersion>

Name

Example

Default Value

groupId

-DgroupId=org.mule.applicationxxx

org.mule.application.<artifactId>

packagePath

-DpackagePath=org/mule/application

none

transports

-Dtransports=http,vm

cxf,file,http,jdbc,jms,stdio,vm

muleVersion

-DmuleVersion=3.1.1

none

packageName

-DpackageName=myPkg

none

description

-Ddescription="some text"

none

modules

-Dmodules=xml,scripting

client,management,scripting,xml

basedir

-Dbasedir=/projects/mule/tools

package

-Dpackage=org/mule/application/myPkg

none

artifactId

-DartifactId=myMuleProject

mule-application-<artifactId>

version

-Dversion=1.0-SNAPSHOT