ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button

Extending Maven Through Plugins

by Eric Pugh
03/17/2004

You may already be using Maven, a build tool that attempts to put structure around your build environment. As part of this, Maven comes with a very rich set of plugins that provide enhanced functionality such as running JUnit tests; building .jar, .war, and .ear files; and generating reports like JCoverage, Clover, PMD, or Simian. However, what happens when your favorite tool doesn't have a corresponding Maven plugin? This is where writing your own Maven plugin allows you to add new functionality to Maven.

This article will cover creating a "Hello World" plugin for Maven. We will demonstrate the various aspects of Maven plugin development, starting with a simple "Hello World" goal, introducing the use of Java code in goals, and finally generating a web report. This article assumes you have already downloaded and installed the latest version of Maven. For more information about using Maven, please read Rob Herbst's ONJava article "Developing with Maven."

Step 1. Creating the "Hello World" Plug-in

All of the source code for this article is available as a .zip file. Just download and unzip it to a convenient location.

Our first example is a very simple plug-in that will emit "Hello World" to the console when you run maven helloworld.

Let's look at what makes up a plugin. In the step1 directory there are two files, project.xml and plugin.jelly. The project.xml file is your standard Maven POM (Project Object Model) file. Because there is no Java code, or any resources, it is a very short file. The plugin.jelly file is the heart of your plugin. The extension .jelly means that the plugin is written using Jelly, a XML-based scripting language that is similar to the one used by Ant. Indeed, Ant syntax can be used directly inside of Jelly scripts! More information is available in the ONJava article "Using the Jakarta Commons, Part 2."

When you look at plugin.jelly you can see how simple it is:

<project
  xmlns:ant="jelly:ant"
  >
  <goal name="helloworld"
        description="Emit Hello World">
    <ant:echo message="Hello World"/>
  </goal>
</project>

As you can see, we are just using the Ant tag echo to send "Hello World" to the console! We import the namespace ant with the XML xmlns:ant="jelly:ant". You can think of a namespace as a Java import statement for Jelly.

From the directory step1, install the plugin by entering maven plugin:install.

c:\[your dir]\step1\maven plugin:install

At the end of the output from the console, you will see that it has copied a file to your plugins directory.

plugin:install:
   [copy] Copying 1 file to C:\java\maven\plugins
BUILD SUCCESSFUL
Total time: 3 seconds
Finished at: Tue Feb 03 19:00:01 CET 2004

You are now ready to run your plugin. On the command line, enter the following (this is the Windows version):

c:\[your dir]\step1\maven -g

You will see a long list of all the goals available to Maven. The goals with a description are meant to be used by users; the goals without a description are internal goals for Maven. You should see your plugin has been registered:

[helloworld] : Emit Hello World

Now go ahead and run the plugin. Enter:

c:\[your dir]\step1\maven helloworld

You should see on the console a "Hello World" message like this:

 __  __
|  \/  |__ _Apache__ ___
| |\/| / _` \ V / -_) ' \  ~intelligent projects~
|_|  |_\__,_|\_/\___|_||_|  v. 1.0-rc2-SNAPSHOT

helloworld:
    [echo] Hello World
BUILD SUCCESSFUL
Total time: 1 seconds
Finished at: Tue Feb 03 19:06:18 CET 2004

If you want to generate the typical Maven documentation for the plugin, you use the site command:

c:\[your dir]\step1\maven site

Notice it generates all of the typical Maven documentation in step1/target/docs/. All the functionality of Maven that you would use in any other type of project is also available in a plugin project. There is nothing special that you need to configure to run unit tests, code coverage reports, etc.

Step 2. Parameterize "Hello World"

This is all well and good, but what if want to customize the message emitted when you enter maven helloworld? We can parameterize the plugin by providing a plugin.properties file. Look at step2/plugin.properties:

helloworld.message=Hello out there!

Notice the helloworld.message property? This is the default value used by the plugin. The plugin.properties file provides defaults for the plugin to use. If you want to customize this plugin property, then in your project.properties file, specify a different value, such as helloworld.message=My custom hello world message.

If you open step2/plugin.jelly, you will now see that the message has been replaced with ${helloworld.message}. Any parameter you need to replace can be done with the ${} syntax, just like in Ant!

When packaging this plugin, Maven needs to know to package the new plugin.properties file. Look at step2/project.xml and you can see we are explicitly including the various plugin-related files:

<resources>
 <resource>
  <directory></directory>
  <includes>
   <include>plugin.jelly</include>
   <include>plugin.properties</include>
   <include>project.properties</include>
   <include>project.xml</include>
  </includes>
 </resource>
</resources>

Go ahead and compile the step2 version of the plugin by switching to the step2 directory and running the install goal:

c:\helloworld\step2\maven plugin:install

The output should look something like this:

jar:jar:
    [jar] Building jar: C:\clients\jn\html\
helloworld\step2\target\helloworld-plugin-2.0.jar

    [copy] Copying 1 file to C:\java\maven\
repository\helloworld-plugin\plugins

plugin:uninstall:
    [delete] Deleting 1 files from
    C:\java\maven\plugins
    [delete] Deleting 8 files from
    C:\java\maven\plugins
    [delete] Deleted 2 directories from
    C:\java\maven\plugins

plugin:install:
    [copy] Copying 1 file to
    C:\java\maven\plugins
BUILD SUCCESSFUL

Did you notice in the output that you compiled a .jar that was set to version 2.0, and that the plugin:install goal deleted the older 1.0 version of the plug-in? Maven is smart enough to delete all other versions of this plugin when you install a new one.

Go ahead and run the plugin. You will see that it will emit Hello out there! if you don't have helloworld.message specified in your project.properties file.

Pages: 1, 2

Next Pagearrow