Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.3)
  3. Extending Mule ESB 3

  4. Creating Catalog Archetypes

Creating Catalog Archetypes

Configuration patterns are elements that simplify configuring specific and recurring activities. Mule comes with some ready made patterns that cover generic scenarios.

You can create your own configuration patterns and even build catalogs of patterns tailored to your needs. The benefits of such catalogs are numerous. Indeed, encapsulating bits of know-how in ready-to-be-consumed configuration elements can increase the productivity of your development teams, reduce the risk of errors, and facilitate the application of good practices.

Implementation Overview

A dedicated Mule module makes the best host for your patterns, as it provides all the necessary infrastructure for supporting the custom XML configuration elements your patterns will be based on.

A configuration pattern is actually composed of core class, a builder, and two configuration-related classes. These all rely on existing abstract classes for the bulk of their behavior.

On top of these classes, you also need specific XML schema elements. These schema elements allow the pattern to be used in any Mule configuration file.

Since creating all these artifacts by hand can be tedious, the best approach is to use the Maven archetype we have created to generate most of the pattern automatically.

The Pattern Catalog Archetype is available in Mule 3.0.1 and above.

Using Maven

The next sections describe how to configure and use the Maven archetype so that it automatically generates the bulk of a pattern.

Configuring Maven

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

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

Creating a New Pattern Catalog

A pattern catalog is actually a regular Mule module. If you already have an existing module (most probably created with the Module Archetype) and are happy storing your patterns in it, you can directly proceed to the next section.

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 module to host the catalog later. If this your first time running this command, Maven will download the archetype for you.

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

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 Maven version used for the generated artifact.

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-catalog-archetype:3.1.0:create ...

artifactId

The artifactId can contain characters such as underscore or hyphen. However, the plug-in will convert the name into a usable from 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 module archetype will ask various questions 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 namespace for the transports and modules you specified and has a placeholder elements for creating your first service, 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.

Creating a New Pattern

First, open a command shell and change to the root directory of your pattern catalog.

> cd yourPatternCatalog

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

> mvn mule-catalog-archetype:new-pattern -DmuleVersion=3.1.0

At minimum, you pass in this system parameters:

  • 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.

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 plug-in like this:

mvn org.mule.tools:mule-catalog-archetype:3.1.0:new-pattern ...

The plug-in will ask various questions and then generate the files.

After you have answered all the questions, the archetype will have created all the classes mentioned above. It will have also created a TODO file named after your pattern (like: my-pattern.todo) that contains information on how to finish the implementation of the pattern.

The Questions Explained

The plug-in prompts you to answer several questions about the pattern you are creating.

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

If you are create a brand new Mule module, choose 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 and Existing Module for more information. The follow questions get asked if you are a creating a new module.

What XML tag name should be used for the new pattern?

This name will be used in your XML configuration. It usually is all lower case with dash (-) used as a separator.

What is the fully qualified class name of the new pattern?

All the scaffolding classes and their package names will be inferred from the fully qualified name of the core pattern class. you must not target the default package.

What will be the type of this pattern?

This specifies what will be the level of flexibility your pattern will allow in its configuration.

  • mp: The pattern is a pure message processor designed to be used with a flow alongside other message processors. It doesn’t support an inbound source of message like an endpoint or a router.

  • ms: The pattern receives messages from any kind of message source, like endpoints or routers.

  • si: The pattern receives messages from a single inbound endpoint. It can optionally be configured with inbound transformers. The Simple Service pattern is of this kind.

  • siso: The pattern receives messages from a single inbound endpoint and dispatches to a single outbound endpoint. The Bridge Validator and Web Service Proxy patterns are of this kind.

Example Console Output

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

What XML tag name should be used for the new pattern?

(Prefer lower-case and use dashes as separators, like: my-pattern)
                                                                 [default: null]
********************************************************************************
my-pattern

[INFO] patternFQCN:
********************************************************************************

What is the fully qualified class name of the new pattern?

(For example: com.acme.pattern.MyPattern
 Note that supporting classes will be created in: com.acme.pattern.builder and com.acme.pattern.config)
                                                                 [default: null]
********************************************************************************
com.acme.pattern.MyPattern

[INFO] patternType:
********************************************************************************

What will be the type of this pattern? [mp] or [ms] or [si] or [siso]

(Details of each type:
 mp:   the pattern is a pure message processor designed to be used within a flow alongside other message processors
 ms:   the pattern receives messages from any kind of message source, like endpoints or routers
 si:   the pattern receives messages from a single inbound endpoint
 siso: the pattern receives messages from a single inbound endpoint and dispatches to a single outbound endpoint)
                                                                   [default: mp]
********************************************************************************
siso