Maven Plugin Configuration

Till now we used a basic POM that has only the project coordinates, and explored the out-of-the-box behavior of Maven core and plugins. In this tutorial, we cover the plugin configuration.

To configure plugins, we use project build element in pom.xml. The next listing shows the top level elements used to configure a plugin.

pom.xml

<project>
...
  <build>
    ...
    <plugins>
      <plugin>
        <groupId>...</groupId>
        <artifactId>...</artifactId>
        <version>...</version>
        <configuration>...</configuration>        
        <executions>
           <execution>...</executions>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

The elements are

  • build : defines the project build.

  • plugins : parent element for one or more <plugin> elements.

  • plugin : the plugin to configure.

  • groupId, artifactId, version : coordinates of the plugin to configure.

  • configuration : holds the parameters and properties to be passed to the plugin.

  • executions : parent element for one or more <execution> element.

  • execution : configures the execution of a goal of the plugin.

Configure Plugin Parameters

With <configuration> we can set plugin parameters. For example, by default maven-compiler-plugin set -source and -target arguments of Java compiler to 1.5. We can use source and target parameters of the compiler plugin to modify this behavior.

Modify the pom.xml of Simple App Project as shown in the next listing. To recap the structure of pom.xml, we are presenting the complete file. Normally, the <build> block is placed after the project coordinates block and before the dependencies block.

simple-app/pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

        <modelVersion>4.0.0</modelVersion>

        <!-- set encoding to make build platform independent -->
        <properties>
                <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        </properties>

        <!-- project coordinates -->
        <groupId>com.xyz</groupId>
        <artifactId>simple-app</artifactId>
        <version>1.0</version>

        <!-- project build -->
        <build>
                <plugins>
                        <plugin>
                                <groupId>org.apache.maven.plugins</groupId>
                                <artifactId>maven-compiler-plugin</artifactId>
                                <version>3.1</version>
                                <configuration>
                                        <source>1.6</source>
                                        <target>1.6</target>
                                </configuration>
                        </plugin>
                </plugins>
        </build>

        <!-- project dependencies -->
        <dependencies>
                <dependency>
                        <groupId>junit</groupId>
                        <artifactId>junit</artifactId>
                        <version>4.12</version>
                        <scope>test</scope>
                </dependency>
                <dependency>
                        <groupId>commons-lang</groupId>
                        <artifactId>commons-lang</artifactId>
                        <version>2.4</version>
                </dependency>
        </dependencies>
</project>

The above listing configures the compiler plugin to use 1.6 for source and target. The configuration defined in <plugin> element is applied to all goals of the plugin. In other words, their scope is plugin and Maven applies it to both compiler:compile and compiler:testCompile goals.

 
 

List Plugin Parameters

Easiest way to know the available parameters for a goal is to run plugin help goal.

$ mvn compiler:help -Dgoal=compile -Ddetail

It will list the available parameters for compile goal of compiler.

But it will not show the default value of the parameters and to know the available parameters and also, the default value for each parameter, run help:describe goal of Maven Help plugin (maven-help-plugin).

$ mvn help:describe -Dplugin=compiler -Dmojo=compile -Ddetail

Note that maven-help-plugins uses -Dmojo for goal, instead of -Dgoal,

Below, we present some more examples of plugin configuration. To include or exclude certain files or directories in the project Jar, configure Maven Jar Plugin with <include> and <exclude> parameters.

simple-app/pom.xml

  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <configuration>
          <includes>
            <include>**/service/*</include>
          </includes>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...

Next one is, Maven Clean Plugin deletes the target directory by default and we may configure it to delete additional directories and files.

simple-app/pom.xml

  ...
  <build>
   <plugins>
    <plugin>
      <artifactId>maven-clean-plugin</artifactId>
      <configuration>
        <filesets>
        <filesets>
          <fileset>
            <directory>src/main/generated</directory>
            <followSymlinks>false</followSymlinks>
            <useDefaultExcludes>true</useDefaultExcludes>
            <includes>
              <include>*.java</include>
            </includes>
            <excludes>
              <exclude>Template*</exclude>
            </excludes>
          </fileset>
        </filesets>
      </configuration>
    </plugin>
   </plugins>
  </build>
  ...

The above configuration forces the clean plugin to delete *.java files in src/main/generated directory, but excludes the Template*.

 
 

More Examples

Plugin Documentation contains many configuration and usage examples and you can find links to the documentation in Maven Plugin Directory.

In the next section, we cover the configuration of plugin goal execution.