Using the Maven Assembly Plugin to build a ZIP distribution

If you have been creating Java programs you are surely familiar with Maven. Maven [1] is a project build and management tool that can be used to build your Java code into a running application. A Maven project has a pom.xml [2] file which contains all the configurations details that will be used by Maven to build the project. Inside this pom.xml we can define plugins that we can use during the building process.

One such plugin is the Maven Assembly Plugin [3]. This plugin can be used to aggregate all the project output along with its dependencies, configurations and other required files into a single distribution archive.

A Sample Program

Let’s create a sample Maven project including a configuration file and a dependency. (source code can be found from here )

Create a Maven project and add the following Main.java under src/main/java

The program will read the config.properties and display the output if it is not empty.

Create a “conf” directory under the project root directory and create a config.properties file with the following content

name = Kasun

This program uses the org.apache.commons.lang3.StringUtils [4] library to check whether a string is empty. As this is an external dependancy, I have added it into the pom.xml of the project.

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.0</version>
</dependency>

Our final goal is to create a distribution with the config.properties file and the dependent library. This is where the Maven Assembly Plugin comes into play.

As we are planning to create a zip archive with all the required files, we need to create an assembly descriptor [5] mentioning the required files that we need for the final zip distribution.

Creating an assembly descriptor

Create zip.xml file under src/main/assembly and add the following configurations.

<format> — specifies the format of the assembly. We can have multiple formats and the assembly plugin will create archives for each format. The supported formats are as follows.

• “zip” — Creates a ZIP file format
• “tar” — Creates a TAR format
• “tar.gz” or “tgz” — Creates a gzip’d TAR format
• “tar.bz2” or “tbz2” — Creates a bzip’d TAR format
• “tar.snappy” — Creates a snappy’d TAR format
• “tar.xz” or “txz” — Creates a xz’d TAR format
• “jar” — Creates a JAR format
• “dir” — Creates an exploded directory format
• “war” — Creates a WAR format

Since we are creating a zip archive, I have added the format as zip.

<fileSet> — defines the directories that need to be included in the assembly. I have added the conf directory which contains the config.properties file.

<file> — As <fileSet> can be used to add directories, <file> can be used to add individual files. I have added this project’s jar file that gets built to be included in the final archive. (the path ${project.build.directory}/${project.artifactId}-${project.version}.jar file gets resolved into target/assemblyPluginTutorial-1.0-SNAPSHOT.jar). Since I would want the project jar to be in the root of the zip archive, <outputDirectory> value has been added as “/”.

<dependencySet> — Defines the location for the all the dependency libraries. Note that I have excluded my project jar being copied into the dependency directory as I have already included it in the archive root directory.

Adding the plugins into POM

Finally, we can edit the pom.xml file to include the Maven Assembly Plugin as follows.

Here, I have also added the Maven Jar Plugin [6] that will be used to create the MANIFEST.MF. The MANIFEST.MF file will be used to specify the project main class and the classpath of the libraries.

Build the program

Building the program (mvn clean install) will create the final assemblyPluginTutorial-1.0-SNAPSHOT.zip in the target directory. If we list the files inside this zip archive, we can seen that the config.properties file has been packed inside the conf folder and the dependent commons library is packed inside the lib directory.

References

[1] https://maven.apache.org/
[2] https://maven.apache.org/guides/introduction/introduction-to-the-pom.html
[3] https://maven.apache.org/plugins/maven-assembly-plugin/
[4] https://commons.apache.org/proper/commons-lang/javadocs/api-2.6/org/apache/commons/lang/StringUtils.html
[5] https://maven.apache.org/plugins/maven-assembly-plugin/assembly.html
[6] https://maven.apache.org/plugins/maven-jar-plugin/