Maven Assembly Plugin

In the previous chapter we saw various ways to distribute Maven Project. However when packing the project for distribution we require more control over the way package is done. The Maven Assembly Plugin allows finegrain control to assemble the project.

The Maven Assembly Plugin allows users to package the project output with its dependencies, modules, site documentation, and other files into a single distributable archive.

Assembly Plugin ships with four Pre-defined Descriptor Files.

• bin - creates a binary distribution archive of the project.

• jar-with-dependencies - creates a JAR which contains the binary output of the project, along its the unpacked dependencies.

• src - creates source archives for the project.

• project - creates archives containing the entire project, minus any build output that lands in the target directory.

Example

Let’s create a source distribution of Simple App to understand how assembly works.

$ cd simple-app
$ mvn assembly:single -DdescriptorId=src

For types, src, bin and project, assembly creates archives in zip, gz and bz2 formats and for jar-with-dependencies it produces just the jar.

We can also build assemblies as part of project build cycle by binding assembly:single goal to package phase.

Add following snippet to Simple App’s pom.xml.

simple-app/pom.xml

  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>2.5.4</version>
        <executions>
          <execution>
            <id>dist</id>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
            <configuration>
              <descriptorRefs>
                 <descriptorRef>
                    src
                 </descriptorRef>
              </descriptorRefs>
            </configuration>
          </execution>
        </executions>
      </plugin>    
    </plugins>
  </build>
  ...

Run mvn package and package phase, along with regular jar, creates source archives in zip, gz and bz2 formats.

Maven Assembly Plugin is highly configurable and allows you to define custom Assembly Descriptors.

Pre-defined Descriptor Files are sufficient for majority of the projects and as such custom assemblies are not covered in this guide. For more information on custom descriptor, refer Maven Reference Book.

Javadoc

Many Open Source Java Projects typically ships source and javadoc jars along with the application jar. While, custom assembly descriptor can be configured to package javadoc, there is much easier alternative.

Add following snippet to pom.xml and run mvn package.

simple-app/pom.xml

  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <executions>
          <execution>
            <id>attach-sources</id>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <executions>
          <execution>
            <id>attach-javadocs</id>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...

As part of package phase, it produces source and javadoc jars along with the regular jar. The example is from the Maven Cookbook.

Uber Jar

While covering assembly, Maven documentation often uses a term uber-jar. Uber is a German word for above or over and an uber-jar contains not only the project packages and resources but also all its dependencies in one single JAR file.

The assembly plugin provides only basic support for uber-jar and for more control, use Maven Shade Plugin.

In last six chapters, we introduced the essential Maven Plugins. In the next chapter, we look at Maven Profiles.