Creating a Shaded Jar

Java applications of a certain complexity often run into dependency conflicts due to their nature of bringing in many external dependencies, each with their own set of transitive dependencies. One way of resolving this issue is to introduce a 'shaded Jar' - a single jar file including the library code, as well as the code of all of its dependencies, with the dependency package names renamed into a different namespace to avoid conflicts.

The following guide will shade your application using apache shade plugin. This plugin can be used to create a self contained version of the application, which is a single Uber JAR that contains the application package and all of its dependency packages (both immediate and transitive dependencies). The same plugin can be used to relocate the conflicting dependency packages in this Uber JAR to prevent their path names from conflicting with those that ADB bring into the class-path. The resulting JAR after applying relocation to Uber JAR is called Shaded JAR.

Creating Shaded JAR, example

To create Uber version of your application and to relocate conflicting Jackson dependency in the Uber JAR, add following shaded plugin entry under <build><plugins> section of application POM.

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.0.0</version>
<executions>
    <execution>
    <phase>package</phase>
    <goals>
        <goal>shade</goal>
    </goals>
    <configuration>
        <transformers>
        <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
            <mainClass><!-- YOUR_APPLICATION_MAIN_CLASS --></mainClass>
        </transformer>
        </transformers>
        <finalName>${project.arifactId}-${project.version}-shaded</finalName>
        <filters>
        <filter>
            <artifact>*:*</artifact>
            <excludes>
            <exclude>META-INF/maven/**</exclude>
            <exclude>META-INF/*.SF</exclude>
            <exclude>META-INF/*.DSA</exclude>
            <exclude>META-INF/*.RSA</exclude>
            </excludes>
        </filter>
        </filters>
        <relocations>
        <relocation>
            <pattern>com</pattern>
            <shadedPattern>com.microsoft.shaded.com.fasterxml.jackson</shadedPattern>
            <includes>
            <include>com.fasterxml.jackson.**</include>
            </includes>
        </relocation>
        </relocations>
    </configuration>
    </execution>
</executions>
</plugin>

then run:

mvn package

This will generate a shaded version of the application in target directory. For example: if your application POM has following maven co-ordinates defined:

<artifactId>adb-app</artifactId>
<version>1.0-SNAPSHOT</version>

then the shaded jar will be named as:

adb-app-1.0-SNAPSHOT-shaded.jar

This name is derived from the finalName entry in shaded plugin ${project.arifactId}-${project.version}-shaded.

The Jackson relocation configuration defined in the plugin will result in renaming the com.fasterxml.jackson package in the Uber JAR to com.microsoft.shaded.com.fasterxml.jackson and update all references to the classes from the original package.