Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 41 ยท Lifecycle and Plugins

The Core Plugins in Practice

Configure Maven's core plugins in practice: compiler (release vs source/target), resources filtering, surefire, jar, clean, install and deploy, with safe settings.

A handful of plugins do almost all the work in a typical Maven build: compiler, resources, surefire, jar, clean, install and deploy. They are bound by default, so they run without any configuration, but you will sooner or later want to change how they behave: add a compiler flag, filter a resource, pass options to the test JVM, or put a Main-Class into the JAR manifest.

This lesson goes through each one with the settings you actually use. The configurations are read-only, because the real Maven cannot run on this site. Two TryIts are Java stand-ins: one that models how the compiler plugin turns settings into a javac command (and why release matters), and one that models resource filtering.

Seven plugins, one pipeline

resources Copies and filters resource files.
compiler Runs javac for you.
surefire Runs unit tests.
jar Builds the archive.
1 / 2

The compiler plugin

maven-compiler-plugin runs javac twice: compile for src/main/java and testCompile for src/test/java. The settings you need most are these.

XML
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.13.0</version>
  <configuration>
    <release>25</release>
    <parameters>true</parameters>
    <showWarnings>true</showWarnings>
    <compilerArgs>
      <arg>-Xlint:all</arg>
      <arg>-Werror</arg>
    </compilerArgs>
  </configuration>
</plugin>
  • release passes --release to javac. It is the same as the property maven.compiler.release, so you rarely need to write the element if you set the property (see Properties and Build Settings).
  • parameters keeps method parameter names in the class files, which some frameworks use.
  • compilerArgs passes any extra flag. -Xlint:all turns on every warning category, and -Werror makes warnings fail the build. Use -Werror only when your team is ready for it.
  • Annotation processors (such as MapStruct or Lombok) are put on a separate path with annotationProcessorPaths, so they do not leak onto your runtime classpath.

release versus source and target

The old pair source and target only tell javac which language features to accept and which bytecode version to write. The compiler still reads the current JDK's class library, so with JDK 25 and -source 11 -target 11 you can call APIs that did not exist in Java 11. The code compiles, then fails on a real Java 11 runtime with NoSuchMethodError.

release also uses a stored description of the API of that Java version, and the compiler rejects any call that did not exist. That is why it is the right choice. The stand-in below makes the difference visible.

Java release versus source/target (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In the first run nothing complains about List.reversed(), which would crash at runtime on Java 11. With release 11 the error appears at build time, and with release 21 the code compiles. The real compiler plugin passes more options than shown (class path, source path, generated source directory), but the choice between --release and -source/-target is as modeled.

The resources plugin

maven-resources-plugin copies src/main/resources into target/classes (goal resources) and src/test/resources into target/test-classes (goal testResources). The point of using it, rather than copying files yourself, is filtering: replacing ${...} placeholders with property values.

XML
<build>
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering>
      <includes>
        <include>**/*.properties</include>
      </includes>
    </resource>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>false</filtering>
      <excludes>
        <exclude>**/*.properties</exclude>
      </excludes>
    </resource>
  </resources>
</build>

The two entries filter .properties files and copy everything else untouched, which protects images and certificates from corruption. A file such as app.properties containing version=${project.version} ends up in target/classes with the real number.

Java Resource filtering (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The placeholder ${team.owner} has no value, so it stays as written, just like in the interpolation rules from the earlier lesson.

The surefire plugin

maven-surefire-plugin runs your unit tests in a forked JVM during the test phase. It picks test classes by name patterns (*Test, Test*, *Tests, *TestCase) and writes reports to target/surefire-reports. Common settings:

XML
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.5.2</version>
  <configuration>
    <argLine>-Xmx512m -Dfile.encoding=UTF-8</argLine>
    <systemPropertyVariables>
      <app.env>test</app.env>
    </systemPropertyVariables>
    <trimStackTrace>false</trimStackTrace>
  </configuration>
</plugin>

argLine gives options to the forked test JVM. Details of test discovery, -Dtest filtering and reports are in Running Tests with Surefire.

The jar plugin

maven-jar-plugin packs target/classes into target/<artifactId>-<version>.jar. The most common change is to add manifest entries so the JAR can be started with java -jar.

XML
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <version>3.4.1</version>
  <configuration>
    <archive>
      <manifest>
        <mainClass>com.example.inventory.App</mainClass>
        <addClasspath>true</addClasspath>
        <classpathPrefix>lib/</classpathPrefix>
      </manifest>
    </archive>
  </configuration>
</plugin>

This plugin makes a thin JAR with only your own classes. A runnable "fat" JAR that includes dependencies is a job for other plugins; see Packaging. To build a second JAR from the same project (for example, one with a tests classifier), add an extra execution with a <classifier>.

The clean plugin

maven-clean-plugin deletes the target directory. That is what mvn clean means. It can also delete extra files if you configure a fileset:

XML
<plugin>
  <artifactId>maven-clean-plugin</artifactId>
  <version>3.4.0</version>
  <configuration>
    <filesets>
      <fileset>
        <directory>logs</directory>
        <includes><include>*.log</include></includes>
      </fileset>
    </filesets>
  </configuration>
</plugin>

Run mvn clean when you change the compiler settings, switch branches, or suspect stale class files. Do not run it before every build, since incremental builds are faster.

The install and deploy plugins

maven-install-plugin copies the built artifacts and the POM into your local repository (~/.m2/repository) so other projects on your machine can depend on them. maven-deploy-plugin uploads them to a remote repository. The deploy plugin needs a <distributionManagement> section (or -DaltDeploymentRepository) that says where to send the files, and credentials in settings.xml.

XML
<distributionManagement>
  <repository>
    <id>company-releases</id>
    <url>https://repo.example.com/releases</url>
  </repository>
  <snapshotRepository>
    <id>company-snapshots</id>
    <url>https://repo.example.com/snapshots</url>
  </snapshotRepository>
</distributionManagement>

Without it, mvn deploy fails with a message that the repository is not defined. Publishing is the topic of Publishing, and credentials of settings.xml, Mirrors and Credentials.

Plugin versions shown here are examples and change over time. Check the latest release of each plugin, then pin it in pluginManagement so your build stays repeatable.

Keeping versions in one place

A tidy parent POM manages all of them together:

XML
<build>
  <pluginManagement>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.13.0</version>
      </plugin>
      <plugin>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.2</version>
      </plugin>
      <plugin>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.4.1</version>
      </plugin>
    </plugins>
  </pluginManagement>
</build>

Plugins from org.apache.maven.plugins may omit groupId, since that is the default.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is <release>21</release> safer than source and target 21 when building with JDK 25?

    --release compiles against the API description of the chosen version. source and target alone still see the JDK 25 library, so newer methods can slip into code meant for an older runtime.
  2. 2. Why filter only some resource files instead of the whole resources folder?

    Filtering rewrites file content. Images and certificates can be corrupted, and text that happens to contain ${...} gets replaced. Filter only the files that need it.
  3. 3. Which plugin and goal puts the built JAR into ~/.m2/repository?

    install:install copies artifacts to the local repository. deploy:deploy uploads to a remote repository, and jar:jar only creates the file in target.
  4. 4. What does mvn deploy need that mvn install does not?

    deploy must know where to upload. It reads distributionManagement and, for secured repositories, credentials from settings.xml.

Summary

  • The default pipeline uses resources, compiler, surefire, jar, install and deploy, with clean in its own lifecycle.
  • Prefer maven.compiler.release (or <release>) over source and target, because it also restricts the API.
  • Filter only resource files that need placeholders replaced.
  • Surefire's argLine configures the test JVM; the jar plugin's manifest settings make a JAR runnable.
  • install copies to the local repository, deploy uploads to a remote one defined in distributionManagement.
  • Pin versions in pluginManagement. The TryIts are stand-ins; the real plugins do far more.

Next, learn the flags that control all of these: The Command Line Toolbox.