executable-packer-maven-plugin

Project No Longer Maintained

As of 11/2023, this project is archived. It will no longer be maintained. The plugin is likely incompatible with new Java or Maven versions.

Introduction

This maven plugin is designed to create executable JAR files for stand-alone applications containing all dependencies as JAR files as well (referred to as jar-in-jar-packaging).

Quick start

Quickly want to create a packaged JAR file? No problem!

1. Add the following snippet to your pom.xml, in between <build><plugins> </plugins></build>:

   <plugin>
   	<groupId>de.ntcomputer</groupId>
   	<artifactId>executable-packer-maven-plugin</artifactId>
   	<version>1.0.1</version>
   	<configuration>
   		<mainClass>com.example.MyMainClass</mainClass>
   	</configuration>
   	<executions>
   		<execution>
   			<goals>
   				<goal>pack-executable-jar</goal>
   			</goals>
   		</execution>
   	</executions>
   </plugin>
   

   Be sure to replace the <mainClass> value with your own main class which should be executed when running the JAR.

2. Run maven with goal package, e.g. mvn package

3. The created JAR file is located at target/<YourProjectAndVersion>-pkg.jar - you can simply run it by using java -jar <YourProjectAndVersion>-pkg.jar

How it works

The plugin includes transitive compile-time and run-time project dependencies as JAR files inside the packaged JAR file (jar-in-jar-packaging). Since the standard classloaders are not able to load classes from JAR files inside JAR files, the plugin also adds boilerplate code that provides a jar-in-jar-classloader and redirects the main class invocation to register this classloader on startup.

The steps that are taken in detail:

At compile-time (when you run mvn package):

1. Search for all compile-time and run-time JAR dependency artifacts
2. Configure JAR manifest: add application's main class, launcher's main class, dependency library path and list of dependency JARs to the manifest
3. Add all classes and resources to the created JAR file
4. Add all dependency JAR files (found in step 1) to the JAR file
5. Add launcher classes to the JAR file
6. Attach the created JAR file as an additional artifact to the project

At run-time (when you run java -jar <YourProjectAndVersion>-pkg.jar)

1. Start the launcher's main method
2. Read the JAR's manifest, extract information about the application's main class and dependencies
3. Register the custom jij (jar-in-jar) URL protocol
4. Create a single URLClassLoader for the classes contained directly in the JAR file and URLs to all dependencies
5. Register the classloader with the main thread
6. Call the application's main method

Configuration

The executable-packer-maven-plugin supports most parameters that the maven-jar-plugin supports too. The following parameters can be specified in the <configuration> section:

Example

Complete pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>de.ntcomputer</groupId>
	<artifactId>executable-packer-maven-plugin-test</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>3.5.1</version>
				<configuration>
					<source>1.8</source>
					<target>1.8</target>
				</configuration>
			</plugin>
			<plugin>
				<groupId>de.ntcomputer</groupId>
				<artifactId>executable-packer-maven-plugin</artifactId>
				<version>1.0.1</version>
				<configuration>
					<mainClass>de.ntcomputer.executablepacker.test.Test</mainClass>
				</configuration>
				<executions>
					<execution>
						<goals>
							<goal>pack-executable-jar</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
	<dependencies>
		<dependency>
			<groupId>com.examlpe</groupId>
			<artifactId>example-dependency</artifactId>
			<version>1.2.0</version>
		</dependency>
	</dependencies>
</project>

Caveats

The runtime launcher registers the custom URL protocol jij in order to correctly resolve classes and resources. It sets a global URLStreamHandlerFactory to do so (using URL.setURLStreamHandlerFactory()). If your application attempts to use URL.setURLStreamHandlerFactory() too, it will fail. Applications relying on setting a custom URLStreamHandlerFactory will not work in conjunction with this plugin.

Credits

This plugin uses mostly the same parameters (including their descriptions) as the maven-jar-plugin. The jar-in-jar classloader is inspired by the Eclipse jarinjarloader package used by the Export to Runnable JAR File functionality.

Alternatives

• maven-assembly-plugin with jar-with-dependencies
• maven-shade-plugin
• eclipse-jarinjarloader