A Simple Mojo

Listed below is a simple mojo class which has no parameters. This is about as simple as a mojo can be. After the listing is a description of the various parts of the source.

package sample.plugin;

import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugins.annotations.Mojo;

/**
 * Says "Hi" to the user.
 *
 */
@Mojo( name = "sayhi")
public class GreetingMojo extends AbstractMojo
{
    public void execute() throws MojoExecutionException
    {
        getLog().info( "Hello, world." );
    }
}

• The class org.apache.maven.plugin.AbstractMojo provides most of the infrastructure required to implement a mojo except for the execute method.
• The annotation "@Mojo" is required and control how and when the mojo is executed.
• The execute method can throw two exceptions:
  • org.apache.maven.plugin.MojoExecutionException if an unexpected problem occurs. Throwing this exception causes a "BUILD ERROR" message to be displayed.
  • org.apache.maven.plugin.MojoFailureException if an expected problem (such as a compilation failure) occurs. Throwing this exception causes a "BUILD FAILURE" message to be displayed.
• The getLog method (defined in AbstractMojo) returns a log4j-like logger object which allows plugins to create messages at levels of "debug", "info", "warn", and "error". This logger is the accepted means to display information to the user. Please have a look at the section Retrieving the Mojo Logger for a hint on its proper usage.

All Mojo annotations are described by the Mojo API Specification.

Shortening the Command Line

There are several ways to reduce the amount of required typing:

• If you need to run the latest version of a plugin installed in your local repository, you can omit its version number. So just use "mvn sample.plugin:hello-maven-plugin:sayhi" to run your plugin.
• You can assign a shortened prefix to your plugin, such as mvn hello:sayhi. This is done automatically if you follow the convention of using ${prefix}-maven-plugin (or maven-${prefix}-plugin if the plugin is part of the Apache Maven project). You may also assign one through additional configuration - for more information see Introduction to Plugin Prefix Mapping.
• Finally, you can also add your plugin's groupId to the list of groupIds searched by default. To do this, you need to add the following to your ${user.home}/.m2/settings.xml file:

  <pluginGroups>
    <pluginGroup>sample.plugin</pluginGroup>
  </pluginGroups>

At this point, you can run the mojo with "mvn hello:sayhi".

Attaching the Mojo to the Build Lifecycle

You can also configure your plugin to attach specific goals to a particular phase of the build lifecycle. Here is an example:

  <build>
    <plugins>
      <plugin>
        <groupId>sample.plugin</groupId>
        <artifactId>hello-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
        <executions>
          <execution>
            <phase>compile</phase>
            <goals>
              <goal>sayhi</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

This causes the simple mojo to be executed whenever Java code is compiled. For more information on binding a mojo to phases in the lifecycle, please refer to the Build Lifecycle document.

Boolean

This includes variables typed boolean and Boolean. When reading the configuration, the text "true" causes the parameter to be set to true and all other text causes the parameter to be set to false. Example:

    /**
     * My boolean.
     */
    @Parameter
    private boolean myBoolean;

<myBoolean>true</myBoolean>

Fixed-Point Numbers

This includes variables typed byte, Byte, int, Integer, long, Long, short, and Short. When reading the configuration, the text in the XML file is converted to an integer value using either Integer.parseInt() or the valueOf() method of the appropriate class. This means that the strings must be valid decimal integer values, consisting only of the digits 0 to 9 with an optional - in front for a negative value. Example:

    /**
     * My Integer.
     */
    @Parameter
    private Integer myInteger;

<myInteger>10</myInteger>

Floating-Point Numbers

This includes variables typed double, Double, float, and Float. When reading the configuration, the text in the XML file is converted to binary form using the valueOf() method for the appropriate class. This means that the strings can take on any format specified in section 3.10.2 of the Java Language Specification. Some samples of valid values are 1.0 and 6.02E+23.

    /**
     * My Double.
     */
    @Parameter
    private Double myDouble;

<myDouble>1.0</myDouble>

Dates

This includes variables typed Date. When reading the configuration, the text in the XML file is converted using one of the following date formats: "yyyy-MM-dd HH:mm:ss.S a" (a sample date is "2005-10-06 2:22:55.1 PM") or "yyyy-MM-dd HH:mm:ssa" (a sample date is "2005-10-06 2:22:55PM"). Note that parsing is done using DateFormat.parse() which allows some leniency in formatting. If the method can parse a date and time out of what is specified it will do so even if it doesn't exactly match the patterns above. Example:

    /**
     * My Date.
     */
    @Parameter
    private Date myDate;

<myDate>2005-10-06 2:22:55.1 PM</myDate>

Files and Directories

This includes variables typed File. When reading the configuration, the text in the XML file is used as the path to the desired file or directory. If the path is relative (does not start with / or a drive letter like C:), the path is relative to the directory containing the POM. Example:

    /**
     * My File.
     */
    @Parameter
    private File myFile;

<myFile>c:\temp</myFile>

URLs

This includes variables typed URL. When reading the configuration, the text in the XML file is used as the URL. The format must follow the RFC 2396 guidelines, and looks like any web browser URL (scheme://host:port/path/to/file). No restrictions are placed on the content of any of the parts of the URL while converting the URL.

    /**
     * My URL.
     */
    @Parameter
    private URL myURL;

<myURL>http://maven.apache.org</myURL>

Plain Text

This includes variables typed char, Character, StringBuffer, and String. When reading the configuration, the text in the XML file is used as the value to be assigned to the parameter. For char and Character parameters, only the first character of the text is used.

Enums

Enumeration type parameters can also be used. First you need to define your enumeration type and afterwards you can use the enumeration type in the parameter definition:

    public enum Color {
      GREEN,
      RED,
      BLUE
    }

    /**
     * My Enum
     */
    @Parameter
    private Color myColor;

So lets have a look like you can use such enumeration in your pom configuration:

<myColor>GREEN</myColor>

You can also use elements from the enumeration type as defaultValues like the following:

    public enum Color {
      GREEN,
      RED,
      BLUE
    }

    /**
     * My Enum
     */
    @Parameter(defaultValue = "GREEN")
    private Color myColor;

Arrays

Array type parameters are configured by specifying the parameter multiple times. Example:

    /**
     * My Array.
     */
    @Parameter
    private String[] myArray;

<myArray>
  <param>value1</param>
  <param>value2</param>
</myArray>

Collections

This category covers any class which implements java.util.Collection such as ArrayList or HashSet. These parameters are configured by specifying the parameter multiple times just like an array. Example:

    /**
     * My List.
     */
    @Parameter
    private List myList;

<myList>
  <param>value1</param>
  <param>value2</param>
</myList>

For details on the mapping of the individual collection elements, see Mapping Lists.

Maps

This category covers any class which implements java.util.Map such as HashMap but does not implement java.util.Properties. These parameters are configured by including XML tags in the form <key>value</key> in the parameter configuration. Example:

    /**
     * My Map.
     */
    @Parameter
    private Map myMap;

<myMap>
  <key1>value1</key1>
  <key2>value2</key2>
</myMap>

Properties

This category covers any map which implements java.util.Properties. These parameters are configured by including XML tags in the form <property><name>myName</name> <value>myValue</value> </property> in the parameter configuration. Example:

    /**
     * My Properties.
     */
    @Parameter
    private Properties myProperties;

<myProperties>
  <property>
    <name>propertyName1</name>
    <value>propertyValue1</value>
  <property>
  <property>
    <name>propertyName2</name>
    <value>propertyValue2</value>
  <property>
</myProperties>

Other Object Classes

This category covers any class which does not implement java.util.Map, java.util.Collection, or java.util.Dictionary. Example:

    /**
     * My Object.
     */
    @Parameter
    private MyObject myObject;

<myObject>
  <myField>test</myField>
</myObject>

Please see Mapping Complex Objects for details on the strategy used to configure those kind of parameters.