Understanding Spring Boot Executable JAR Packaging and the Role of JarLauncher

Spring Boot provides the spring-boot-maven-plugin to package an application as an executable fat JAR. Adding the plugin to the pom.xml is sufficient to produce a self‑contained archive.

The generated JAR has a well‑defined layout:

├── META-INF
│   └── MANIFEST.MF
├── lib
│   ├── aopalliance-1.0.jar
│   ├── classmate-1.1.0.jar
│   ├── spring-boot-1.3.5.RELEASE.jar
│   └── ...
├── org
│   └── springframework
│       └── boot
│           └── loader
│               ├── ExecutableArchiveLauncher$1.class
│               └── ...
└── spring
    └── study
        └── executablejar
            └── ExecutableJarApplication.class

Running the JAR with java -jar executable-jar-1.0-SNAPSHOT.jar starts the application because the JAR’s Main-Class is org.springframework.boot.loader.JarLauncher . The JarLauncher is part of Spring Boot Loader, a set of utilities that locate the Start-Class defined in the manifest and launch it in a separate thread.

Spring Boot Loader defines several abstract concepts:

Launcher : the base class for all launchers (JarLauncher, WarLauncher, PropertiesLauncher).

Archive : abstraction of an archive file; JarFileArchive represents a JAR and provides access to its manifest and entries.

JarFile : wraps a physical JAR file and enumerates its entries, handling nested JARs via the custom org.springframework.boot.loader.jar.Handler URL protocol (e.g., jar:file:/path/to/app.jar!/lib/inner.jar!/ ).

The launch process of JarLauncher :

public static void main(String[] args) {
    new JarLauncher().launch(args);
}

protected void launch(String[] args) {
    JarFile.registerUrlProtocolHandler();
    ClassLoader classLoader = createClassLoader(getClassPathArchives());
    launch(args, getMainClass(), classLoader);
}

protected void launch(String[] args, String mainClass, ClassLoader classLoader) {
    Runnable runner = createMainMethodRunner(mainClass, args, classLoader);
    Thread runnerThread = new Thread(runner);
    runnerThread.setContextClassLoader(classLoader);
    runnerThread.start();
}

The getMainClass() method reads the Start-Class attribute from META-INF/MANIFEST.MF , which in this example is spring.study.executablejar.ExecutableJarApplication . The MainMethodRunner then reflects on that class and invokes its main method.

Spring Boot also provides a custom class loader LaunchedURLClassLoader . Its loadClass method follows three steps:

Delegate to a root class loader if present.

Attempt a local lookup using findClass , which searches the URLs of the nested JARs.

Fall back to the standard parent‑first loading mechanism.

Example of loading a class with this loader:

// Register the custom URL protocol handler
JarFile.registerUrlProtocolHandler();

LaunchedURLClassLoader classLoader = new LaunchedURLClassLoader(
    new URL[] {
        new URL("jar:file:/path/to/app.jar!/lib/spring-boot-loader-1.3.5.RELEASE.jar!/"),
        new URL("jar:file:/path/to/app.jar!/lib/spring-boot-1.3.5.RELEASE.jar!/")
    },
    LaunchedURLClassLoaderTest.class.getClassLoader()
);

classLoader.loadClass("org.springframework.boot.loader.JarLauncher");
classLoader.loadClass("org.springframework.boot.SpringApplication");
classLoader.loadClass("org.springframework.boot.autoconfigure.web.DispatcherServletAutoConfiguration");

In summary, Spring Boot’s executable JAR mechanism relies on the spring-boot-maven-plugin to assemble a fat JAR, a manifest that points to JarLauncher , and a custom class‑loading infrastructure that can handle nested JAR URLs, locate the application’s main class, and start the Spring context.