How can I merge resource files in a Maven assembly?

Question

I'm using Maven and its assembly plugin to build a distribution package of my project like this:

• one project assembles a basic runtime (based on Felix), with the appropriate directories and bundles, in a ZIP file.
• third-party libraries are collected in one project each and either converted to OSGi bundles or, if they are already OSGi compatible, they are just copied
• my own project consists of several modules that are built into OSGi bundles, too.

Now, I'm adding another project that unpacks the ZIP, drops all the other JARs into the proper directories, and repackages it for distribution. Now, my bundles might contain configuration files that I want to merge into, rather than replacing, identically named ones in the runtime assembly. How do I do that?

The files are plain text (property files), but I might run into a similar situation with XML files later.

Answer 1

Expanding a bit on Juergen's answer for those who stumble on this - the containerDescriptorHandler in the descriptor can take four values (v2.3), these are metaInf-services, file-aggregator, plexus, metaInf-spring. It's a bit buried in the code (found in the package org.apache.maven.plugin.assembly.filter) but it is possible to aggregate config/properties files.

Here's an example descriptor that aggregates the META-INF/services and named property files located in com.mycompany.actions.

descriptor.xml

<assembly>

...

<containerDescriptorHandlers>

    <containerDescriptorHandler>
        <handlerName>metaInf-services</handlerName>
    </containerDescriptorHandler>

    <containerDescriptorHandler>
        <handlerName>file-aggregator</handlerName>
        <configuration>
            <filePattern>com/mycompany/actions/action.properties</filePattern>
            <outputPath>com/mycompany/actions/action.properties</outputPath>
        </configuration>
    </containerDescriptorHandler>

</containerDescriptorHandlers>

....

</assembly>

The file-aggregator can contain a regular expression in the filePattern to match multiple files. The following would match all files names 'action.properties'.

<filePattern>.+/action.properties</filePattern>

The metaInf-services and metaInf-spring are used for aggregating SPI and spring config files respectively whilst the plexus handler will aggregate META-INF/plexus/components.xml together.

If you need something more specialised you can add your own configuration handler by implementing ContainerDescriptorHandler and defining the component in META-INF/plexus/components.xml. You can do this by creating an upstream project which has a dependency on maven-assembly-plugin and contains your custom handler. It might be possible to do this in the same project you're assembling but I didn't try that. Implementations of the handlers can be found in org.apache.maven.plugin.assembly.filter.* package of the assembly source code.

CustomHandler.java

package com.mycompany;

import org.apache.maven.plugin.assembly.filter.ContainerDescriptorHandler;

public class CustomHandler implements ContainerDescriptorHandler {
    // body not shown
}

then define the component in /src/main/resources/META-INF/plexus/components.xml

components.xml

<?xml version='1.0' encoding='UTF-8'?>
<component-set>
    <components>
        <component>
            <role>org.apache.maven.plugin.assembly.filter.ContainerDescriptorHandler</role>
            <role-hint>custom-handler</role-hint>
            <implementation>com.mycompany.CustomHandler</implementation>
            <instantiation-strategy>per-lookup</instantiation-strategy>
        </component>
    </components>
</component-set>

Finally you add this as a dependency on the assembly plugin in the project you wish to assemble

pom.xml

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>2.2.1</version>
    <configuration>
        <descriptors>
            <descriptor>...</descriptor>
        </descriptors>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>com.mycompany</groupId>
            <artifactId>sample-handler</artifactId>
            <version>1.0</version>
        </dependency>
    </dependencies>
</plugin>

and define the handlerName in the descriptor

descriptor.xml

...
<containerDescriptorHandler>
    <handlerName>custom-handler</handlerName>
</containerDescriptorHandler>
...

The maven-shade-plugin can also create 'uber-jars' and has some resource transforms for handling XML, licences and manifests.

J