Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p><table class="wysiwyg-macro" data-macro-name="excerpt" data-macro-parameters="atlassian-macro-output-type=BLOCK" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2V4Y2VycHQ6YXRsYXNzaWFuLW1hY3JvLW91dHB1dC10eXBlPUJMT0NLfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>Implementing Maven plugins has never been Groovier!</p></td></tr></table></p>
<img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e3RvYzptYXhMZXZlbD0yfG1pbkxldmVsPTF9&amp;locale=en_GB&amp;version=2" data-macro-name="toc" data-macro-parameters="maxLevel=2|minLevel=1">
<p>Groovy Maven plugins are very similar to Java Maven plugins.  Actually a Groovy Maven plugin is compiled into Java byte-code, and once built, Maven can not tell the difference between a plugin which has been implemented in Java or Groovy.</p>

<p>For the most part, the existing guide for <a href="http://maven.apache.org/guides/plugin/guide-java-plugin-development.html">Developing Maven plugins with Java</a> will also apply to developing plugins with Groovy.  There are some differences though, which are covered here which can make Maven plugin development with Groovy better, faster, stronger <img class="emoticon emoticon-smile" data-emoticon-name="smile" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/smile.png" alt="(smile)" title="(smile)" /></p>

<p>Be sure to read over the documentation for <a class="confluence-link" href="/display/GMAVEN/Building+Groovy+Projects" data-linked-resource-id="77333433" data-linked-resource-type="page" data-linked-resource-default-alias="Building Groovy Projects" data-base-url="http://docs.codehaus.org">Building Groovy Projects</a>.  A Groovy Maven plugin is a Groovy project, so most of the information there is relevant here as well.</p>

<h1>Groovy Mojos</h1>

<p>Just like Java-based Mojo's at its simplest, a Groovy Mojo consists of a single class. For more complicated plugins you are free to use as many classes as needed of course, just like Java... and you can even write Java classes too if you need too.</p>

<p>Groovy Mojo implementations are denoted by the <code>@goal</code> Javadoc annotation on the class (er, just like Java). Actually, <strong>all</strong> of the Javadoc annotations which are supported by Java plugins are also supported by Groovy plugins.  This is because, when building a Groovy project, the sub-generator spits out Java sources with Javadocs intact, which the <a href="http://maven.apache.org/plugins/maven-plugin-plugin">Maven Plugin Plugin</a> then parses for annotations <img class="emoticon emoticon-wink" data-emoticon-name="wink" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/wink.png" alt="(wink)" title="(wink)" /></p>

<h2>A Simple Groovy Mojo</h2>

<p>Here is our simple Mojo class which has no parameters and spits out a relatively meaningless string via logging:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
package sample.plugin

import org.codehaus.gmaven.mojo.GroovyMojo

/**
 * Says "Hi" to the user... er well not really :-P.
 *
 * @goal sayhi
 */
public class GreetingMojo
    extends GroovyMojo
{
    void execute() {
        log.info('Groovy baby!')
    }
}
</pre></td></tr></table>
<p>There are a few minor points to note here. First, we are referencing the plugins logger via <code>log.info()</code>, where in Java one would need to <code>getLog().info()</code>.</p>

<p>Second, there is no need to mark the <code>execute()</code> method as throwing any exceptions, though you can still throw any exceptions you need to. You can of course declare what your methods are throwing if you want to.</p>

<p>Lastly, this example mojo extends from <a href="http://groovy.codehaus.org/gmaven-generated/gmaven-mojo/apidocs/org/codehaus/groovy/maven/mojo/GroovyMojo.html">org.codehaus.groovy.maven.mojo.GroovyMojo</a>, which is recommended for most Groovy mojos.  Of course you can always use <code>org.apache.maven.plugin.AbstractMojo</code> at the cost of some additional bits of happiness which help make your Mojo's groovier.</p>

<h1>Building Plugins</h1>

<h2>Project Definition</h2>

<p>Groovy plugins use the same Java plugin descriptor extractor. The Java extractor uses the generated stubs to build the descriptor, so be sure to invoke the <code>generateStubs</code> goal.</p>

<p>Instead of depending on <code>maven-plugin-api</code> Groovy plugins depend on <code>gmaven-mojo</code>, which picks up the required Maven dependencies and the default Groovy runtime provider.</p>

<p>And of course, we need to hook up the <code>gmaven-plugin</code> to compile the Groovy sources into class files (as well as a few others).</p>

<p>Below is a POM for the simple sample groovy mojo:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;project>
    &lt;modelVersion>4.0.0&lt;/modelVersion>
    &lt;groupId>sample.plugin&lt;/groupId>
    &lt;artifactId>maven-hello-plugin&lt;/artifactId>
    &lt;packaging>maven-plugin&lt;/packaging>
    &lt;version>1.0-SNAPSHOT&lt;/version>
    &lt;name>Sample Maven Plugin&lt;/name>

&lt;dependencies>
        &lt;dependency>
            &lt;groupId>org.codehaus.gmaven&lt;/groupId>
            &lt;artifactId>gmaven-mojo&lt;/artifactId>
        &lt;/dependency>
    &lt;/dependencies>

&lt;build>
        &lt;plugins>
            &lt;plugin>
                &lt;groupId>org.codehaus.gmaven&lt;/groupId>
                &lt;artifactId>gmaven-plugin&lt;/artifactId>
                &lt;executions>
                    &lt;execution>
                        &lt;goals>
                            &lt;goal>generateStubs&lt;/goal>
                            &lt;goal>compile&lt;/goal>
                            &lt;goal>generateTestStubs&lt;/goal>
                            &lt;goal>testCompile&lt;/goal>
                        &lt;/goals>
                    &lt;/execution>
                &lt;/executions>
            &lt;/plugin>
        &lt;/plugins>
    &lt;/build>
&lt;/project>
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="note" data-macro-parameters="title=Dependency and Plugin Versions" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vdGU6dGl0bGU9RGVwZW5kZW5jeSBhbmQgUGx1Z2luIFZlcnNpb25zfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>To use the above example you must configure the <code>&lt;version&gt;</code> element for the dependencies and plugins.</p></td></tr></table>
<p>Once you have your pom setup then you can build the plugin in the normal way via:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
mvn install
</pre></td></tr></table>

<h2>Mojo Parameters</h2>

<p>Mojo parameters work <strong>exactly</strong> the same as they do for Java plugins. Simply define a field in your Mojo implementation and annotate the field with a <code>@parameter</code> Javadoc tag.</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
/**
 * The greeting to display.
 *
 * @parameter default-value="Groovy baby!"
 */
private String greeting
</pre></td></tr></table>
<p>Configuration of Mojo parameters is... as you might expect, the same as with Java Mojos:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;plugin>
    &lt;groupId>sample.plugin&lt;/groupId>
    &lt;artifactId>maven-hello-plugin&lt;/artifactId>
    &lt;configuration>
        &lt;greeting>what say, you, we go out on the down and swing, baby? Yea&lt;/greeting>
    &lt;/configuration>
&lt;/plugin>
</pre></td></tr></table>
<p>The main thing to note about Groovy Mojos and parameters, is that fields should be typed so that Maven (or well, Plexus) can inject objects of the proper type. Using the def keyword is the same as typing the field as and Object which Maven will probably still inject just fine, but it won't perform any conversion.</p>

<h1>Putting More Groove into your Mojo</h1>

<h2>Using <code>ant</code></h2>

<p>Using <code>ant</code> allows your Mojo access to any <a href="http://ant.apache.org">Ant</a> tasks.  Groovy Mojo's which extend from <code>GroovyMojo</code> have access to an <code>AntBuilder</code> instance bound to the <code>ant</code> field.<br />
This field is lazily initialized when you first reference it.</p>

<p>Below are some small examples of using <code>ant</code> to perform common tasks, but really the sky is the limit on what you can do. See the <a href="http://ant.apache.org/manual/index.html">Ant User Manual</a> for more tasks you can execute <img class="emoticon emoticon-wink" data-emoticon-name="wink" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/wink.png" alt="(wink)" title="(wink)" /></p>
<table class="wysiwyg-macro" data-macro-name="note" data-macro-parameters="title=NOTE" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vdGU6dGl0bGU9Tk9URX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>The following examples assume that your Mojo implementation has already defined a project property as in:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
/**
 * @parameter expression="${project}"
 * @required
 * @readonly
 */
org.apache.maven.project.MavenProject project
</pre></td></tr></table></td></tr></table>

<h3>Touching a File</h3>

<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
ant.touch(file: "${project.build.directory}/stamp")
</pre></td></tr></table>

<h3>Copying Files</h3>

<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def dir = "${project.build.directory}/backup"
ant.mkdir(dir: dir)
ant.copy(todir: dir) {
    fileset(dir: "${project.build.outputDirectoy}") {
        include(name: '**/*')
    }
}
</pre></td></tr></table>

<h3>Execute Something</h3>

<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def propname = 'lsout'
ant.exec(executable: '/bin/ls', outputproperty: propname)
def value = ant.antProject.properties[propname]
</pre></td></tr></table>

<h2>Using <code>fail()</code></h2>

<p>Most mojos need to report back some failure status, which is normally done by throwing a <code>MojoExecutionException</code>. Groovy Mojos can simply invoke the <code>fail()</code> method, which handles the details of throwing for you.</p>

<p>Failing with a simple string:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
fail("That ain't no woman! It's a man, man!")
</pre></td></tr></table>
<p>Failing with an exception detail:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
try {
    ....
}
catch (Exception e) {
    fail(e)
}
</pre></td></tr></table>
<p>Failing with an exception detail and a message:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
try {
    ....
}
catch (Exception e) {
    fail("She's the village bicycle! Everybody's had a ride.", e)
}
</pre></td></tr></table>

<h1><code>gmaven-archetype-mojo</code> Archetype</h1>

<p>To help get Groovy plugins started faster, you can use the <code>gmaven-archetype-mojo</code>. This will create a new project with the basic POM configuration and an example Groovy-based Mojo class to get you started quickly:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
mvn archetype:generate -DarchetypeGroupId=org.codehaus.gmaven.archetypes -DarchetypeArtifactId=gmaven-archetype-mojo -DarchetypeVersion=1.0-rc-2
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="tip" data-macro-parameters="title=TIP" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3RpcDp0aXRsZT1USVB9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>To use a specific version of an archetype specify <code>-DarchetypeVersion=&lt;VERSION&gt;</code>.</p></td></tr></table>
<p>The <a href="http://maven.apache.org/plugins/maven-archetype-plugin">Maven Archetype Plugin</a> will ask a few questions about your new project:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
[INFO] [archetype:generate]
...
Define value for groupId: : org.mycompany.myproject
Define value for artifactId: : example-maven-plugin
Define value for version: : 1.0-SNAPSHOT
Define value for package: : org.mycompany.myproject.example
Confirm properties configuration:
name: Example Maven Plugin
groupId: org.mycompany.myproject
artifactId: example-maven-plugin
version: 1.0-SNAPSHOT
package: org.mycompany.myproject.example
 Y: : y
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="note" data-macro-parameters="title=NOTE" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vdGU6dGl0bGU9Tk9URX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>Please ignore any <code>ReferenceException</code> warnings about ${...}, they are harmless.</p></td></tr></table>
<p>The above example would have created the following project structure:</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
example-maven-plugin
example-maven-plugin/pom.xml
example-maven-plugin/src
example-maven-plugin/src/main
example-maven-plugin/src/main/groovy
example-maven-plugin/src/main/groovy/org
example-maven-plugin/src/main/groovy/org/mycompany
example-maven-plugin/src/main/groovy/org/mycompany/myproject
example-maven-plugin/src/main/groovy/org/mycompany/myproject/example
example-maven-plugin/src/main/groovy/org/mycompany/myproject/example/HelloMojo.groovy
</pre></td></tr></table>

<h1><code>gmaven-plugin</code> Packaging</h1>

<h1>Resources</h1>

<h2>Mojo Development</h2>

<ul>
	<li><a href="http://maven.apache.org/developers/mojo-api-specification.html">Mojo API specification</a></li>
	<li><a href="http://maven.apache.org/developers/mojo-api-specification.html">Guide to Developing Java Plugins</a></li>
</ul>

<h2>Groovy Development</h2>

<ul>
	<li><a class="confluence-link" href="/display/GROOVY/Using+Ant+from+Groovy" data-linked-resource-id="2713" data-linked-resource-type="page" data-linked-resource-default-alias="Using Ant from Groovy" data-base-url="http://docs.codehaus.org">Using Ant from Groovy</a></li>
	<li><a href="http://ant.apache.org/manual">Ant User Manual</a></li>
	<li><a href="http://groovy.codehaus.org/groovy-jdk">Groovy JDK Methods</a></li>
	<li><a href="http://groovy.codehaus.org/api">Groovy Javadocs</a></li>
</ul>