Spring Boot Loader-compatible jar files should be structured in the following way:

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

Application classes should be placed in a nested BOOT-INF/classes directory. Dependencies should be placed in a nested BOOT-INF/lib directory.

Spring Boot Loader-compatible war files should be structured in the following way:

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

Dependencies should be placed in a nested WEB-INF/lib directory. Any dependencies that are required when running embedded but are not required when deploying to a traditional web container should be placed in WEB-INF/lib-provided .

Spring Boot Loader-compatible jar and war archives can include additional index files under the BOOT-INF/ directory. A classpath.idx file can be provided for both jars and wars, and it provides the ordering that jars should be added to the classpath. The layers.idx file can be used only for jars, and it allows a jar to be split into logical layers for Docker/OCI image creation.

Index files follow a YAML compatible syntax so that they can be easily parsed by third-party tools. These files, however, are not parsed internally as YAML and they must be written in exactly the formats described below in order to be used.

The classpath index file can be provided in BOOT-INF/classpath.idx . It provides a list of jar names (including the directory) in the order that they should be added to the classpath. Each line must start with dash space ( "-·" ) and names must be in double quotes.

For example, given the following jar:

example.jar
 +-META-INF
 |  +-...
 +-BOOT-INF
    +-classes
    |  +...
    +-lib
       +-dependency1.jar
       +-dependency2.jar

The index file would look like this:

- "BOOT-INF/lib/dependency2.jar"
- "BOOT-INF/lib/dependency1.jar"

The layers index file can be provided in BOOT-INF/layers.idx . It provides a list of layers and the parts of the jar that should be contained within them. Layers are written in the order that they should be added to the Docker/OCI image. Layers names are written as quoted strings prefixed with dash space ( "-·" ) and with a colon ( ":" ) suffix. Layer content is either a file or directory name written as a quoted string prefixed by space space dash space ( "··-·" ). A directory name ends with / , a file name does not. When a directory name is used it means that all files inside that directory are in the same layer.

A typical example of a layers index would be:

- "dependencies":
  - "BOOT-INF/lib/dependency1.jar"
  - "BOOT-INF/lib/dependency2.jar"
- "application":
  - "BOOT-INF/classes/"
  - "META-INF/"

The core class used to support loading nested jars is org.springframework.boot.loader.jar.JarFile . It lets 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, as shown in the following example:

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

The preceding example shows how A.class can be found in /BOOT-INF/classes in myapp.jar at position 0063 . B.class from the nested jar can actually be found in myapp.jar at position 3452 , and C.class is at position 3980 .

Armed with this information, we can load specific nested entries by seeking to the appropriate part of the outer jar. We do not need to unpack the archive, and we do not need to read all entry data into memory.

Spring Boot Loader strives to remain compatible with existing code and libraries. org.springframework.boot.loader.jar.JarFile extends from java.util.jar.JarFile and should work as a drop-in replacement. The getURL() method returns a URL that opens a connection compatible with java.net.JarURLConnection and can be used with Java’s URLClassLoader .

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

There are three launcher subclasses ( JarLauncher , WarLauncher , and PropertiesLauncher ). Their purpose is to load resources ( .class files and so on) from nested jar files or war files in directories (as opposed to those explicitly on the classpath). In the case of JarLauncher and WarLauncher , the nested paths are fixed. JarLauncher looks in BOOT-INF/lib/ , and WarLauncher looks in WEB-INF/lib/ and WEB-INF/lib-provided/ . You can add extra jars in those locations if you want more. The PropertiesLauncher looks in BOOT-INF/lib/ in your application archive by default. You can add additional locations by setting an environment variable called LOADER_PATH or loader.path in loader.properties (which is a comma-separated list of directories, archives, or directories within archives).

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 (that is, the class that contains a main method) should be specified in the Start-Class attribute.

The following example shows 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 as follows:

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

PropertiesLauncher has a few special features that can be enabled with external properties (System properties, environment variables, manifest entries, or loader.properties ). The following table describes these properties:

loader.path

Comma-separated Classpath, such as lib,${HOME}/app/lib . Earlier entries take precedence, like a regular -classpath on the javac command line.

loader.home