Java does not provide any standard way to load nested jar files (i.e. jar files that are themselves contained within a jar). This can be problematic if you are looking to distribute a self contained application that you can just run from the command line without unpacking.

To solve this problem, many developers use “shaded” jars. A shaded jar simply packages all classes, from all jars, into a single uber jar. The problem with shaded jars is that it becomes hard to see which libraries you are actually using in your application. It can also be problematic if the the same filename is used (but with different content) in multiple jars. Spring Boot takes a different approach and allows you to actually nest jars directly.

example.jar
 |
 +-META-INF
 |  +-MANIFEST.MF
 +-org
 |  +-springframework
 |     +-boot
 |        +-loader
 |           +-<spring boot loader classes>
 +-com
 |  +-mycompany
 |     + project
 |        +-YouClasses.class
 +-lib
    +-dependency1.jar
    +-dependency2.jar

example.jar
 |
 +-META-INF
 |  +-MANIFEST.MF
 +-org
 |  +-springframework
 |     +-boot
 |        +-loader
 |           +-<spring boot loader classes>
 +-WEB-INF
    +-classes
    |  +-com
    |     +-mycompany
    |        +-project
    |           +-YouClasses.class
    +-lib
    |  +-dependency1.jar
    |  +-dependency2.jar
    +-lib-provided
       +-servlet-api.jar
       +-dependency3.jar

The core class used to support loading nested jars is org.springframework.boot.loader.jar.JarFile. It allows you load jar content from a standard jar file, or from nested child jar data. When first loaded, the location of each JarEntry is mapped to a physical file offset of the outer jar:

myapp.jar
+---------+---------------------+
|         | /lib/mylib.jar      |
| A.class |+---------+---------+|
|         || B.class | B.class ||
|         |+---------+---------+|
+---------+---------------------+
^          ^          ^
0063       3452       3980

The example above shows how A.class can be found in myapp.jar position 0063. B.class from the nested jar can actually be found in myapp.jar position 3452 and B.class is at position 3980.

Armed with this information, we can load specific nested entries by simply seeking to appropriate part if the outer jar. We don’t need to unpack the archive and we don’t need to read all entry data into memory.

The org.springframework.boot.loader.Launcher class is a special bootstrap class that is used as an executable jars main entry point. It is the actual Main-Class in your jar file and it’s used to setup an appropriate URLClassLoader and ultimately call your main() method.

There are 3 launcher subclasses (JarLauncher, WarLauncher and PropertiesLauncher). Their purpose is to load resources (.class files etc.) from nested jar files or war files in directories (as opposed to explicitly on the classpath). In the case of the [Jar|War]Launcher the nested paths are fixed (lib/*.jar and lib-provided/*.jar for the war case) so you just add extra jars in those locations if you want more. The PropertiesLauncher looks in lib/ by default, but you can add additional locations by setting an environment variable LOADER_PATH or loader.path in application.properties (comma-separated list of directories or archives).

C.3.1 Launcher manifest

You need to specify an appropriate Launcher as the Main-Class attribute of META-INF/MANIFEST.MF. The actual class that you want to launch (i.e. the class that you wrote that contains a main method) should be specified in the Start-Class attribute.

For example, here is a typical MANIFEST.MF for an executable jar file:

Main-Class: org.springframework.boot.loader.JarLauncher
Start-Class: com.mycompany.project.MyApplication

For a war file, it would be:

Main-Class: org.springframework.boot.loader.WarLauncher
Start-Class: com.mycompany.project.MyApplication

	Note
	You do not need to specify Class-Path entries in your manifest file, the classpath will be deduced from the nested jars.

$ unzip -q myapp.jar
$ java org.springframework.boot.loader.JarLauncher

PropertiesLauncher has a few special features that can be enabled with external properties (System properties, environment variables, manifest entries or application.properties).

Manifest entry keys are formed by capitalizing initial letters of words and changing the separator to "-" from "." (e.g. Loader-Path). The exception is loader.main which is looked up as Start-Class in the manifest for compatibility with JarLauncher).

Environment variables can be capitalized with underscore separators instead of periods.

There are a number of restrictions that you need to consider when working with a Spring Boot Loader packaged application.

If the above restrictions mean that you cannot use Spring Boot Loader the following alternatives could be considered: