Quick overview of Maven plugin configuration

This article tries to give a quick generic overview of Maven plugins. In the end a pluginin usage is given and explained, so you can get a feeling of how maven plugins look like as a whole. plugins refer to maven plugins in the following context.

1. Plugin naming rules

The naming convention for official plugins is maven-<plugin name>-plugin. For example, maven-surefire-plugin

The recommand third-party and user-defined plugin should be named <plugin name>-maven-plugin. For example the plugin for spring boot is named spring-boot-maven-plugin

2. Plugins type

Build plugins will be executed during the build and they should be configured in the <build/> element from the POM.
Reporting plugins will be executed during the site generation and they should be configured in the <reporting/> element from the POM.

Build plugins ( <build/>) are more common to see.

3. Available plugins list

Here is the complete availble plugins from official, you can also find a plugin is a build plugin or a report plugin or both on that page.

4. Plugin goal

A plugin goal represents a specific task (finer than a build phase) which contributes to the building and managing of a project. It may be bound to zero or more build phases.

If a goal is bound to one or more build phases, that goal will be called in all those phases automatically. For example if a plugin has goal bound to phase 'package', then when run 'mvn package' that plugin's goal will be executed.

A goal not bound to any build phase could be executed outside of the build lifecycle by direct invocation.

#============================================================================
# Syntax for invoke a plugin's goal from command line:
# mvn <plugin name>:<goal> [-D<plugin name>.<property name>=<property value>]
#============================================================================
#For example, use 'exec' plugin, goal is 'java', set the plugin property of 'mainClass'
mvn exec:java -Dexec.mainClass="com.shengwang.demo.DemoMain"

All official plugins support a goal called 'help'. It has 2 properties 'detail' and 'goal'. See example below.

5. How to get available goals of a certain plugin.

Search keyword "maven <plugin name> plugin" on google, jump to plugin's official web to learn how to use it. It's suitable for first time using a plugin.
In command line, run 'mvn <plugin name>:help', get all available goals. It's more convinient for experienced users for just missing some details.

For example here is the output of the 'mvn exec:help'

6. How to get more usage help from command line.

First run 'mvn <plugin name>:help' for all goals, then run 'mvn <plugin name>:help -Ddetail=true -Dgoal=<goal>' for more usage details of a certain goal. You can try to run 'mvn exec:help -Dgoal=java -Ddetail=true' to see the output. (Don't forget the -D)

7. Basic configuration structure of plugins

For Build plugins, it's included in <build/>. it has <executions/>, which is the real actiion that are intened to do during bounded build lifecycle. Let's examine an example:

<build>
  <plugins>
   
    <!-- .... other plugins ...-->
   
    <!-- =========================================== -->
    <!-- make sure antrun is after packaging plugins -->
    <!-- =========================================== -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-antrun-plugin</artifactId>
      <version>1.8</version>
      <executions>
        <execution>
          <id>scp-to-remote</id>
          <phase>package</phase>
          <goals>
            <goal>run</goal>
          </goals>
          <configuration>
            <target>
              <!-- keyfile+passphrase or  password, choose one -->
              <!-- 
              <scp localFile="${project.basedir}/target/qos-spark-1.0.jar"
                remoteToFile="root@192.168.203.156:/usr/sanss" verbose="true"
                keyfile="C:\Users\shengw\.ssh\192.168.203.156\id_rsa"
                passphrase="">
              </scp>
               -->
              <scp localFile="${project.basedir}/target/qos-spark-1.0.jar"
                remoteToFile="root@192.168.203.156:/usr/sanss" verbose="true"
                password="passwordForSSH" trust="true">
              </scp>
            </target>
          </configuration>
        </execution>
      </executions>
      <!-- libraries for scp impl      -->
      <!-- antrun doesn't use os's scp -->
      <dependencies>
        <dependency>
          <groupId>com.jcraft</groupId>
          <artifactId>jsch</artifactId>
          <version>0.1.53</version>
        </dependency>
        <dependency>
          <groupId>ant</groupId>
          <artifactId>ant-jsch</artifactId>
          <version>1.6.5</version>
        </dependency>
      </dependencies>
    </plugin>
    <!-- =========================================== -->
    <!--   antrun plugin end                         -->
    <!-- =========================================== -->
   
  </plugins>
</build>

It's a long one, but no need to be panic. This example has the common configuration structure for maven plugins. Most of the plugins' configuration are shorter.

It's included in <build/> because its a build plugin.

The first part of plugin configuration is trival: <groupId>, <artifactId> and <version>.

Then there's one <execution> defined in above example. There are <id>, <phase>, <goal> and <configuration> in this <execution>.

<id> - identify this execution. If more pom.xml has the same plugin bound to same phase and has the same id, these <execution> will be merged when building. Normally just give a meanful string for this execution.
<phase> - bind the execution to a build lifecycle. So it can get executed automatically at that build lifecycle. The above demo, executing antrun plugin when use 'mvn package'
<goal> - which behavior of this plugin to be used. In the example, the goal "run" will run some ant tasks. The tasks are defined in <configuration>.
<configuration> - Set property for the plugin. Normally any parameter in <configuration> has a corresponding field variable in the plugin class definition, just like a jave bean. For the <target> property, AntRunMojo.java from antrun plugin's source has the variable. Just treat the properties in <configuration> as setting values for these field variables.

If there are more <execution>, every one can has its own <configuration>. If <configuration> is out of <executions>, it's for all <execution>.

Finally, <dependencies> in the <plugin>, to set external libraries only used for this plugin. Most plugins don't need to specify <dependencies> for plugin itself.