Creating Executable JAR with Dependencies Using Maven

Introduction

In Java development, Maven as the mainstream build tool generates JAR files that only contain the project's own class files and resources by default, excluding external library dependencies. This design is suitable for projects used as libraries, but when packaging projects as standalone running applications, it becomes necessary to include all dependencies in the final JAR file. Such JAR files containing all dependencies are commonly referred to as "uber JAR" or "fat JAR".

Limitations of Standard JAR Files

The default packaging mechanism of Maven generates JAR files that only contain compiled class files and resource files from the project. When running such JAR files, all dependent JAR file paths need to be manually specified through the -classpath parameter, which is inconvenient for deployment and distribution. Particularly when distributing applications to end users, manually managing dependencies is almost impractical.

Maven Assembly Plugin Solution

The Maven Assembly plugin is the most commonly used tool for creating executable JAR files containing dependencies. This plugin uses predefined descriptor files to define packaging rules, where the "jar-with-dependencies" descriptor is specifically designed for creating JAR files that include all dependencies.

Basic Configuration

Add the following configuration to the project's pom.xml file:

<build>
  <plugins>
    <plugin>
      <artifactId>maven-assembly-plugin</artifactId>
      <configuration>
        <archive>
          <manifest>
            <mainClass>fully.qualified.MainClass</mainClass>
          </manifest>
        </archive>
        <descriptorRefs>
          <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
      </configuration>
    </plugin>
  </plugins>
</build>

Executing Packaging Commands

After configuration, create the JAR file containing dependencies using the following command:

mvn clean compile assembly:single

It's important to note that the compile goal must be executed before assembly:single, otherwise the project's own code won't be included in the final JAR file.

Automated Build Configuration

To automatically generate executable JARs during standard Maven build processes, bind the Assembly plugin to specific build phases:

<build>
  <plugins>
    <plugin>
      <artifactId>maven-assembly-plugin</artifactId>
      <configuration>
        <archive>
          <manifest>
            <mainClass>fully.qualified.MainClass</mainClass>
          </manifest>
        </archive>
        <descriptorRefs>
          <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
      </configuration>
      <executions>
        <execution>
          <id>make-assembly</id>
          <phase>package</phase>
          <goals>
            <goal>single</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

This configuration ensures that executable JAR files are automatically generated when executing mvn install or performing deployment/release operations.

JAR File Content Analysis

JAR files generated using the Maven Assembly plugin don't contain other JAR files but extract class files from all dependencies and reorganize them according to package structure. For example, if the project depends on Apache Commons Lang library, the final JAR file will contain the /org/apache/commons/lang3/ directory and all class files under it.

It's important to note that the jar-with-dependencies descriptor doesn't collect dependencies with "provided" scope. These dependencies are typically provided by the runtime environment, such as Servlet API provided by web containers.

Alternative Solution Comparison

Maven Shade Plugin

The Maven Shade plugin provides more powerful resource transformation capabilities, better handling file conflicts between dependencies. When multiple dependencies contain resource files with the same path, the Shade plugin can resolve conflicts through resource transformers.

Spring-Boot Maven Plugin

The Spring Boot plugin adopts a different packaging strategy, keeping dependencies as JAR files stored in the BOOT-INF/lib/ directory rather than extracting class files. This approach uses custom class loaders to load dependencies, making it more suitable for complex applications.

Best Practice Recommendations

When choosing packaging solutions, consider the following factors: for simple applications, the Maven Assembly plugin is the most straightforward choice; when needing to handle resource file conflicts, the Maven Shade plugin is more appropriate; and for Spring Boot-based applications, the Spring Boot plugin should be used.

Conclusion

Creating executable JAR files containing dependencies through the Maven Assembly plugin is a common method for Java application distribution and deployment. Proper configuration ensures all application dependencies are correctly packaged, allowing end users to run the application without additional configuration. Understanding the characteristics and suitable scenarios of different plugins helps choose the most appropriate packaging solution for project requirements.