Using Container Descriptor Handlers

Introduction

Container descriptor handlers can be used to filter dynamically the content of files configured in a descriptor, for example by aggregating multiple files into a single file, or customizing the content of specific files.

This example demonstrate the use of <containerDescriptorHandlers> in the assembly descriptor format.

Built-in container descriptor handlers

The plugin comes with several handlers already defined.

file-aggregator
This handler matches the files according to the given regular expression filePattern, aggregates their content, and stores the output in the assembly at the given outputPath. A sample descriptor which matches all file.txt files configured in the assembly and aggregates them, by appending their content, into a single file.txt located under the base directory of the assembly, is:
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd">
  ....
  <containerDescriptorHandlers>
    <containerDescriptorHandler>
      <handlerName>file-aggregator</handlerName>
      <configuration>
        <filePattern>.*/file.txt</filePattern>
        <outputPath>file.txt</outputPath>
      </configuration>
    </containerDescriptorHandler>
  </containerDescriptorHandlers>
</assembly>
metaInf-services
This handler matches every META-INF/services file and aggregates them into a single META-INF/services. The content of the files are appended together.
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd">
  ....
  <containerDescriptorHandlers>
    <containerDescriptorHandler>
      <handlerName>metaInf-services</handlerName>
    </containerDescriptorHandler>
  </containerDescriptorHandlers>
</assembly>
metaInf-spring
This handler is similar to metaInf-services. It matches every file with a name starting with META-INF/spring..
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd">
  ....
  <containerDescriptorHandlers>
    <containerDescriptorHandler>
      <handlerName>metaInf-spring</handlerName>
    </containerDescriptorHandler>
  </containerDescriptorHandlers>
</assembly>
plexus
This handler matches every META-INF/plexus/components.xml file and aggregates them into a single valid META-INF/plexus/components.xml.
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd">
  ....
  <containerDescriptorHandlers>
    <containerDescriptorHandler>
      <handlerName>plexus</handlerName>
    </containerDescriptorHandler>
  </containerDescriptorHandlers>
</assembly>

Custom container descriptor handlers

You can create your own container descriptor handler by creating a class implementing ContainerDescriptorHandler. As an example, let's create a handler that will prepend a configured comment to every properties file configured in an assembly descriptor.

We start by creating a new Maven project named custom-container-descriptor-handler with the following POM:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.test</groupId>
  <artifactId>custom-container-descriptor-handler</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-assembly-plugin</artifactId>
      <version>3.7.0-SNAPSHOT</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.plexus</groupId>
        <artifactId>plexus-component-metadata</artifactId>
        <version>1.7.1</version>
        <executions>
          <execution>
            <goals>
              <goal>generate-metadata</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

This POM declares a dependency on the Assembly Plugin so that we can create our handler, and generates a Plexus configuration file so that it can be found through dependency injection during assembling.

Implementing ContainerDescriptorHandler requires defining a couple of methods:

isSelected
Tells whether a given file or directory, configured in the assembly descriptor, should be added to the final assembly. A typical set-up would be to prevent the addition of certain files, and let the handler do its work on them.
getVirtualFiles
Returns the list of file paths, from the root of the assembly, of each file this handler will add.
finalizeArchiveCreation
Callback that is invoked when an assembly is going to be created. This method can be used to add files that resulted from the handler's work on each selected file. Cave-at: Because of the way archive finalization is performed, we need to loop through each resource in the archive before doing anything.
finalizeArchiveExtraction
Callback that is invoked when an assembly has been extracted into a directory. This method can be used to process files that resulted from the handler's work on each selected file.

Our handler that prepends a comment to each properties file could look like the following (using here Java 8 features):

package com.test;

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.File;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

import org.apache.maven.plugins.assembly.filter.ContainerDescriptorHandler;
import org.apache.maven.plugins.assembly.utils.AssemblyFileUtils;
import org.codehaus.plexus.archiver.Archiver;
import org.codehaus.plexus.archiver.ArchiverException;
import org.codehaus.plexus.archiver.UnArchiver;
import org.codehaus.plexus.component.annotations.Component;
import org.codehaus.plexus.components.io.fileselectors.FileInfo;

@Component(role = ContainerDescriptorHandler.class, hint = "custom")
public class MyCustomDescriptorHandler implements ContainerDescriptorHandler {

    private String comment;

    private Map<String, List<String>> catalog = new HashMap<>();

    private boolean excludeOverride = false;

    @Override
    public void finalizeArchiveCreation(Archiver archiver) throws ArchiverException {
        archiver.getResources().forEachRemaining(a -> {}); // necessary to prompt the isSelected() call

        for (Map.Entry<String, List<String>> entry : catalog.entrySet())
        {
            String name = entry.getKey();
            String fname = new File(name).getName();

            Path p;
            try {
                p = Files.createTempFile("assembly-" + fname, ".tmp");
            } catch (IOException e) {
                throw new ArchiverException("Cannot create temporary file to finalize archive creation", e);
            }

            try (BufferedWriter writer = Files.newBufferedWriter(p, StandardCharsets.ISO_8859_1)) {
                writer.write("# " + comment);
                for (String line : entry.getValue()) {
                    writer.newLine();
                    writer.write(line);
                }
            } catch (IOException e) {
                throw new ArchiverException("Error adding content of " + fname + " to finalize archive creation", e);
            }

            File file = p.toFile();
            file.deleteOnExit();
            excludeOverride = true;
            archiver.addFile(file, name);
            excludeOverride = false;
        }
    }

    @Override
    public void finalizeArchiveExtraction(UnArchiver unarchiver) throws ArchiverException { }

    @Override
    public List<String> getVirtualFiles() {
        return new ArrayList<>(catalog.keySet());
    }

    @Override
    public boolean isSelected(FileInfo fileInfo) throws IOException {
        if (excludeOverride) {
            return true;
        }
        String name = AssemblyFileUtils.normalizeFileInfo(fileInfo);
        if (fileInfo.isFile() && AssemblyFileUtils.isPropertyFile(name)) {
            catalog.put(name, readLines(fileInfo));
            return false;
        }
        return true;
    }

    private List<String> readLines(FileInfo fileInfo) throws IOException {
        try (BufferedReader reader = new BufferedReader(new InputStreamReader(fileInfo.getContents(), StandardCharsets.ISO_8859_1))) {
            return reader.lines().collect(Collectors.toList());
        }
    }

    public void setComment(String comment) {
        this.comment = comment;
    }

}

It is a Plexus component, having the ContainerDescriptorHandler role, that is distinguished from the other handlers with its hint of custom.

It selects each properties file and stores their content into a catalog map, where the key is the name of the file and the value is a list of its lines. Those matched files are not added to the assembly, because the handler needs to process them first. During assembly creation, it creates temporary files whose content are the previously read lines, prepended by a custom comment. They are then added back into the archive with their previous name. Note that this simple handler does not aggregate files with the same name - it could be enhanced to do it. When the temporary files are added to the archive, the isSelected method is automatically called, hence we need to set a boolean excludeOverride to true to make sure the catalog processing part is not done.

The last ingredient is using our custom handler in an assembly descriptor of some Maven project. Suppose there is a src/samples directory in this project, containing an XML file named test.xml and a properties file named test.properties. With the following descriptor format

<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.2.0 http://maven.apache.org/xsd/assembly-2.2.0.xsd">
  <id>dist</id>
  <formats>
    <format>zip</format>
  </formats>
  <containerDescriptorHandlers>
    <containerDescriptorHandler>
      <handlerName>custom</handlerName>
      <configuration>
        <comment>A comment</comment>
      </configuration>
    </containerDescriptorHandler>
  </containerDescriptorHandlers>
  <fileSets>
    <fileSet>
      <directory>src/samples</directory>
      <outputDirectory></outputDirectory>
    </fileSet>
  </fileSets>
</assembly>

and the following Assembly plugin configuration

<project>
  [...]
  <build>
    [...]
    <plugins>
      [...]
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.7.0-SNAPSHOT</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
            <configuration>
              <descriptors>
                <descriptor>src/assemble/assembly.xml</descriptor>
              </descriptors>
            </configuration>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>com.test</groupId>
            <artifactId>custom-container-descriptor-handler</artifactId>
            <version>0.0.1-SNAPSHOT</version>
          </dependency>
        </dependencies>
      </plugin>
  [...]
</project>

the resulting assembly would contain both test.xml and test.properties under the base directory, with only the latter starting with # A comment.