Maven custom packaging with the assembly plugin

It's not uncommon to need a custom packaging or assembly for a given project for some reason or another, this can be accomplished in a certain number of ways

Recently I needed an application to be packaged as the following structure :

|- runnable-jar.jar
|- lib
    |-- axis.jar
    |-- commons.logging.jar 
|- certificates
   |-- cacerts.jks
|- config
   |-- config.properties
|- logs
   

The schema is pretty self-explanatory I needed a runnable JAR at the root of my dist folder with a few other folders such as config, logs, etc.

One way to accomplish this with maven is to use maven-assembly-plugin

The Assembly Plugin for Maven is primarily intended to allow users to aggregate the project output along with its dependencies, modules, site documentation, and other files into a single distributable archive.

Your project can build distribution assemblies easily, using one of the convenient, prefabricated assembly descriptors.

These descriptors handle many common operations, such as packaging a project's artifact along with generated documentation into a single ZIP archive. Alternatively, your project can provide its own descriptor and assume a much higher level of control over how dependencies, modules, file-sets, and individual files are packaged in the assembly.

Currently the plugin can create distributions in the following formats:

• zip
• tar
• tar.gz
• tar.bz2
• jar
• dir
• war
• format that the ArchiveManager has been configured

For this tutorial we will be using the dir format in order to output the project structure described above

Let's start with the easy part first, the maven assembly plugin configuration where we will tell the plugin where to find our assembly file and where to output the result of the assembly operation

    
...

    
        
            
                maven-assembly-plugin
                
                    false
                    
                        
                        src/main/resources/assembly.xml
                    
                    
                    ${project.build.directory}/dist/
                
            

            
                maven-resources-plugin
                
                    UTF-8
                
            
            
                maven-compiler-plugin
                
                    ${java.version}
                    ${java.version}
                    ${project.build.sourceEncoding}
                
            
        
    
...

Now since in our case we want all the files in the resource directory to be handled by the assembly plugin we will configure the maven resources plugin to ignore everything inside the resources folder (please note that this is an optional step and it might not apply to your project)

...  

    
       
          ${basedir}/src/main/resources
          
              **/**
           
        
     

...

Once the maven part is done we can get started with the core code

If you remember we will end up with a runnable JAR file so go ahead and create a Main class like so :

package com.ufasoli.maven.custom.assembly;

/**
 * User: Ulises Fasoli
 * Date: 23.06.2014
 * Time: 18:03
 * Project : maven-custom-assembly
 */
public class Main {

    public static void main(String[] args) {
        System.out.println("HELLO WORLD !");
    }
}

Since this is going to be a runnable JAR file we will need to configure the maven JAR plugin to generate the manifest file with our main class

   org.apache.maven.plugins
   maven-jar-plugin
   2.4
   
      
         
            com.ufasoli.maven.custom.assembly.Main
            lib/
            true
         
       
   

Now we get to the core of the subject, the assembly file :

    paynet-dir
    
        dir
    
    false
    
        
        
            /lib
            
                ${project.groupId}:${project.artifactId}
            

        
             
            
                /
                
                    ${project.groupId}:${project.artifactId}
                
            

    

    
        
            src/main/resources/keystore/Certificate.SSL
            /certificates
        
        
            src/main/resources/config
            /config
        

        
            src/main/resources/config
            /logs
            
                *
            
            false
        

        
            src/main/resources/docs
            /docs
            
                *
            
        
    

Now this file is pretty self-explanatory but below are the highlights :

• format --> the output format for our assembly (directory in our case)
• dependencySets--> which artifacts to include in the final structure and where to put them
• fileSets--> which files to include in the final structure and where to put them

Now you can build your assembly by running the following maven goal :

    mvn clean package assembly:single

Once the goal completed under the /target folder you should find your custom project structure

As usual you can find the code source for this tutorial over at my github account here