Understanding Spring Boot Executable JAR Packaging and the JarLauncher Mechanism

Spring Boot provides the

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
</plugin>

plugin to package an application as an executable JAR; adding it to the <build><plugins>... section of the pom enables this feature.

After packaging, the generated executable-jar-1.0-SNAPSHOT.jar contains a structured layout with META-INF (including MANIFEST.MF), a lib directory for third‑party dependencies, Spring Boot loader classes, and the application’s own classes.

The manifest file defines entries such as

Start-Class: spring.study.executablejar.ExecutableJarApplication

and Main-Class: org.springframework.boot.loader.JarLauncher. When the JAR is started with java -jar executable-jar-1.0-SNAPSHOT.jar, the JarLauncher class is invoked instead of the application’s SpringApplication. JarLauncher is part of Spring Boot Loader, which abstracts launchers ( JarLauncher, WarLauncher, PropertiesLauncher) and archives ( Archive, JarFileArchive, ExplodedArchive). It uses a custom URL protocol handler ( org.springframework.boot.loader.jar.Handler) to resolve nested JAR URLs like

jar:file:/.../executable-jar-1.0-SNAPSHOT.jar!/lib/spring-boot-loader-1.3.5.RELEASE.jar!/

.

The JarLauncher main method simply creates a new JarLauncher instance and calls its launch(args) method. During launch, it registers the custom URL handler, builds a classpath from the lib directory, creates a LaunchedURLClassLoader, retrieves the Start-Class from the manifest, and invokes the application’s main method via MainMethodRunner.

The custom class loader overrides loadClass with three steps: (1) delegate to the root class loader if present, (2) attempt a local lookup using findClass, and (3) fall back to the standard parent‑first loading. Its findClass method converts a class name to a resource path, searches the URLs of nested JARs, and defines the class if found.

A test snippet demonstrates registering the URL handler, constructing a LaunchedURLClassLoader with two JAR URLs, and loading classes such as org.springframework.boot.loader.JarLauncher, org.springframework.boot.SpringApplication, and

org.springframework.boot.autoconfigure.web.DispatcherServletAutoConfiguration

.

Overall, Spring Boot’s executable JAR mechanism defines a self‑contained packaging rule where dependencies reside in /lib, a custom URL protocol handles nested JARs, and the JarLauncher starts the application in a separate thread, all orchestrated by the spring-boot-maven-plugin.