Shading Libraries

DevKit is compatible only with Studio 6 and Mule 3. To build Mule 4 connectors, see the Mule SDK documentation.

DevKit version 3.5.3 and later supports creating a "shaded" .jar file (i.e. an "uber" .jar containing the classes and packages of its dependency libraries with optional relocation of various packages and classes) using the Apache Maven Shade Plugin.

The Maven Shade plugin can be used to build your custom connector library .jar bundled with all of its library class dependencies which ensures its library class dependencies do not collide/conflict at runtime with other versions of any libraries already being used within Mule.

Before Using

Before moving forward with the Maven Shade plugin, it is advisable to first consider one of the following approaches as an alternative to shading:

Use the same version of the library that Mule is using
Use an entirely different library with packages and classes that do not collide with ones being used by Mule

When neither of the two alternate approaches above are feasible for your custom connector, use of the Maven Shade plugin may be the last viable option.

What Shade Plugin Does

The Maven Shade plugin takes care of renaming the packages of colliding classes. It also alters the byte code of calling classes to instead use the relocated classes in the shaded package. By doing these things, the Maven Shade plugin ensures that classes needed by your connector—that would have collided with another version of the same classes being used by Mule—can co-exist peacefully in the same JVM classpath, thereby preventing the appearance of "Not Found" errors for classes and methods at runtime.

To Use the Shade Plugin

Add a dependency entry to the custom connector’s pom.xml file for any dependency .jar which has a transitive dependency on one or more library .jars that contain classes which collide with classes in use by Mule.
Add the shade plugin to the build plugins section of your custom connector project’s pom.xml file.
(Optional) Add an explicit configuration for the "mule-devkit-maven-plugin" to ensure that the shaded connector jar is built properly for installation into Anypoint Studio

The following example configuration is for dealing with a conflicting Apache Commons Compress library:

<dependencies>
   <dependency>
       <groupId>org.apache.commons</groupId>
       <artifactId>commons-compress</artifactId>
       <version>1.8.1</version>
   </dependency>
</dependencies>

<build>
 <plugins>
   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-shade-plugin</artifactId>
     <version>3.0.0</version>
     <configuration>
       <!-- Custom shade configuration -->
       <artifactSet>
         <includes>
            <include>org.apache.commons:commons-compress</include> <!-- the.group.id:the-artifact-id -->
         </includes>
       </artifactSet>
       <relocations>
         <relocation>
            <pattern>org.apache.commons.compress</pattern> <-- original.package.name -->
            <shadedPattern>com.mycompany.shaded.org.apache.commons.compress</shadedPattern> <!-- new.shaded.package.name -->
         </relocation>
       </relocations>
      </configuration>
   </plugin>

   <plugin> <!-- Use this explicit plugin configuration to properly install a shaded custom connector in Anypoint Studio -->
     <groupId>org.mule.tools.devkit</groupId>
     <artifactId>mule-devkit-maven-plugin</artifactId>
     <version>${mule.devkit.version}</version>
     <extensions>true</extensions>
     <configuration>
       <attachShadedJar>true</attachShadedJar>
       <attachConnectorLibs>false</attachConnectorLibs>
       <skipStudioPluginPackage>${devkit.studio.package.skip}</skipStudioPluginPackage>
     </configuration>
   </plugin>

   <!-- Other plugins -->
 </plugins>
</build>