Example: Command-line variant invocation of the assembly plugin

Consider the case where the user wants to execute the assembly:assembly mojo directly on the command line, but already has a configuration for the assembly:single mojo that runs during the main build lifecycle. Since these configurations require different options, the user cannot use the plugin-level configuration section to specify common elements.

In this case, the assembly-plugin configuration might look like this:

<plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <configuration>
    <tarLongFileMode>gnu</tarLongFileMode>    
  </configuration>
  <executions>
    <execution>
      <id>build-distros</id>
      <phase>package</phase>
      <goals>
        <goal>single</goal>
      </goals>
      <configuration>
        <descriptors>
          <descriptor>src/main/assembly/bin.xml</descriptor>
          <descriptor>src/main/assembly/src.xml</descriptor>
        </descriptors>
      </configuration>
    </execution>
    <execution>
      <id>default-cli</id>
      <configuration>
        <descriptorRefs>
          <descriptorRef>jar-with-dependencies</descriptorRef>
          <descriptorRef>project</descriptorRef>
        </descriptorRefs>
      </configuration>
    </execution>
  </executions>
</plugin>

In the above example, you can see several interesting things. First, the main build process will invoke the assembly:single mojo during the package phase of the build, and produce both binary and source distribution artifacts using custom assembly descriptors included with the project. Second, all invocations of the assembly plugin should use a tarLongFileMode strategy of gnu. Finally, when the assembly plugin is invoked from the command line, it will build the standard jar-with-dependencies and project artifacts for the project, and ignore the custom assembly descriptors in src/main/assembly.

Now, notice the difference in the way the two execution blocks reference assembly descriptors. One uses custom descriptors via the descriptors section, and the other uses standard descriptors via the descriptorRefs section. These two sections cannot override one another, so it's impossible to setup one section - say, descriptorRefs - in the plugin-level configuration block (to provide CLI access to it, as historical versions of Maven would require), then have the build-distros invocation override it with the custom descriptors specified in the descriptors section. This configuration is not possible in versions of Maven before 2.2.0.

Example: Configuring compile to run twice

In this scenario, the user wants to run the compiler:compile mojo twice for his jar packaging project. The main reason for this is to provide an entry point into the application that will warn the user if he's using a Java version older than 1.5, then exit gracefully. Without such an entry point, the user would be confronted with a stacktrace in the event he tried to run this application with a 1.4 or older JRE.

Therefore, the user needs to compile tha bulk of his application to target the 1.5 Java specification, then compile the rest (the entry point) to target an older specification...say, 1.3. The first execution will specify the source and target values at 1.5, and add an excludes section to avoid compiling the entry point for the application. The second pass will then re-specify source and target to 1.3, and basically invert the original excludes section to be an includes section, so as to compile only the entry point class.

The resulting configuration might look something like this:

<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <source>1.5</source>
    <target>1.5</target>
  </configuration>
  <executions>
    <execution>
      <id>default-compile</id>
      <configuration>
        <excludes>
          <exclude>**/cli/*</exclude>
        </excludes>
      </configuration>
    </execution>
    <execution>
      <id>build-java14-cli</id>
      <phase>compile</phase>
      <goals>
        <goal>compile</goal>
      </goals>
      <configuration>
        <source>1.3</source>
        <target>1.3</target>
        <includes>
          <include>**/cli/*</include>
        </includes>
      </configuration>
    </execution>
  </executions>
</plugin>

There are three important things to notice in the above compiler-plugin configuration:

# The default source and target compatibility levels are for Java 1.5. This means that the compiler will generate binaries for Java 1.5 from both the main codebase and the test codebase, unless otherwise overridden.

# The default pass of the compile goal will exclude the **/cli/* path pattern, but will compile everything else in src/main/java to run under Java 1.5.

# The second pass of the compile mojo - in the execution called build-java14-cli - resets the source and target versions to 1.3, and inverts the exclude rule from the first pass. This means the second time around, the compiler will produce 1.4-targeted binaries for the classes matching the **/cli/* path pattern.

Note that prior to Maven 2.2.0, it was much more difficult - if not impossible - to compile different subpaths within your project's codebase to target different Java versions.

Example: Configuring compile and testCompile mojos separately

Finally, building on our use of the compiler plugin to tease out these different use cases, consider the case where a user wants to target version 1.4 of the Java specification as his runtime platform. However, he still wants the convenience and other advantages to be found in a unit-testing framework like TestNG. This forces the user to configure the compile mojo with one set of source and target values - specifically, 1.4 - and the testCompile mojo with another (1.5).

The resulting compiler-plugin configuration might look something like the following:

<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <executions>
    <execution>
      <id>default-compile</id>
      <configuration>
        <source>1.3</source>
        <target>1.3</target>
      </configuration>
    </execution>
    <execution>
      <id>default-testCompile</id>
      <configuration>
        <source>1.5</source>
        <target>1.5</target>
      </configuration>
    </execution>
  </executions>
</plugin>

This example is fairly simple and straightforward. First, the default-compile execution sets the source and target values to 1.3 to allow older Java versions to run the project. Then, the default-testCompile execution resets the source and target values to 1.5, which enables the project to use tools like TestNG that use annotations.

Incidentally, it's perhaps useful to point out that the example above is a little bit contrived; the compiler plugin targets Java 1.3 by default, so the only configuration that's really required is the default-testCompile execution. The default-compile execution respecifies plugin defaults. The only time this might be useful is when a parent POM defines a plugin-level configuration for source and target that needs to be changed for the purposes of these different compiler executions. This example is meant to be illustrative of the potential for separate configuration of default lifecycle mojos to be found in Maven 2.2.0.

Again, the above configuration would not be possible in older versions of Maven. Starting with Maven 2.2.0, these advanced configurations have become a reality.