Filtering Some Distribution Files

Introduction

File filtering is used to substitute variable fields from inside a file to their represented values. For the Assembly Plugin, and most Maven filtering procedures, these variables are enclosed between ${ and }. For example, before a file is filtered, it contains ${project.artifactId}. But after filtering is complete, a new file is created with the project's artifactId substituting ${project.artifactId} and that this new file is used instead of the original one.

Although filtering can be done during the process-resources phase, not all files going into your distribution will be coming from a project resource. Thus, the Assembly Plugin allows filtering of files before copying them into the created assembly.

This example demonstrates how to filter files before adding them into the assembly. In this example, we need to filter distribution files into the archive. The files included in the distribution are:

  • README.txt
  • LICENSE.txt
  • NOTICE.txt

All the above files are in the root directory of the project but only the README and the NOTICE files should be filtered. The property file used to filter these are files is found in src/assembly/filter.properties.

A property file is a file which contains the names of the variables and their corresponding string value. The format of its contents is identical to how Java Property files are saved. Below is an example of a property file:

# lines beginning with the # sign are comments

variable1=value1
variable2=value2

The Assembly Descriptor

Filtering is only enabled inside <files> so that's what we will use. Thus, our assembly descriptor will be:

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
  <id>distribution</id>
  <formats>
    <format>jar</format>
  </formats>
  <files>
    <file>
      <source>README.txt</source>
      <outputDirectory>/</outputDirectory>
      <filtered>true</filtered>
    </file>
    <file>
      <source>LICENSE.txt</source>
      <outputDirectory>/</outputDirectory>
    </file>
    <file>
      <source>NOTICE.txt</source>
      <outputDirectory>/</outputDirectory>
      <filtered>true</filtered>
    </file>
  </files>
</assembly>

The above descriptor tells the Assembly Plugin to filter both the README.txt and the NOTICE.txt files and to just copy the LICENSE.txt file.

Alternatively, if there are many .txt files to include inside <files>, we can setup both <fileSets> and <files> like so:

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">
  <id>distribution</id>
  <formats>
    <format>jar</format>
  </formats>
  <fileSets>
    <fileSet>
      <directory>${basedir}</directory>
      <includes>
        <include>*.txt</include>
      </includes>
      <excludes>
        <exclude>README.txt</exclude>
        <exclude>NOTICE.txt</exclude>
      </excludes>
    </fileSet>
  </fileSets>
  <files>
    <file>
      <source>README.txt</source>
      <outputDirectory>/</outputDirectory>
      <filtered>true</filtered>
    </file>
    <file>
      <source>NOTICE.txt</source>
      <outputDirectory>/</outputDirectory>
      <filtered>true</filtered>
    </file>
  </files>
</assembly>

The above descriptor adds all .txt files to the assembly but filters README.txt and NOTICE.txt files.

The POM

The configuration of the Assembly Plugin inside pom.xml should not be different from the others, except for the configuration of the filter file, so:

<project>
  [...]
  <build>
    [...]
    <plugins>
      [...]
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>2.6</version>
        <configuration>
          <filters>
            <filter>src/assembly/filter.properties</filter>
          </filters>
          <descriptors>
            <descriptor>src/assembly/distribution.xml</descriptor>
          </descriptors>
        </configuration>
      </plugin>
   [...]
</project>

Generating The Assembly

To generate the distribution assembly, we then use:

mvn assembly:assembly