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 .