0
# Spring Boot Loader Tools
1
2
A comprehensive Java library that provides essential tools and utilities for packaging Spring Boot applications into executable JAR and WAR files. The library includes classes for JAR writing, entry management, layout configuration, library handling, and loader implementation that enable the creation of self-contained, executable archives with embedded containers.
3
4
## Package Information
5
6
- **Package Name**: org.springframework.boot:spring-boot-loader-tools
7
- **Language**: Java
8
- **Package Type**: Maven
9
- **Installation**:
10
```xml
11
<dependency>
12
<groupId>org.springframework.boot</groupId>
13
<artifactId>spring-boot-loader-tools</artifactId>
14
<version>3.5.3</version>
15
</dependency>
16
```
17
18
Gradle:
19
```groovy
20
implementation 'org.springframework.boot:spring-boot-loader-tools:3.5.3'
21
```
22
23
## Core Imports
24
25
```java
26
import org.springframework.boot.loader.tools.Repackager;
27
import org.springframework.boot.loader.tools.Libraries;
28
import org.springframework.boot.loader.tools.Library;
29
import org.springframework.boot.loader.tools.LibraryScope;
30
```
31
32
For specific functionality:
33
```java
34
import org.springframework.boot.loader.tools.MainClassFinder;
35
import org.springframework.boot.loader.tools.Layout;
36
import org.springframework.boot.loader.tools.Layouts;
37
import org.springframework.boot.loader.tools.JarWriter;
38
import org.springframework.boot.loader.tools.ImagePackager;
39
import org.springframework.boot.loader.tools.BuildPropertiesWriter;
40
import java.nio.file.attribute.FileTime;
41
import java.time.Instant;
42
```
43
44
## Basic Usage
45
46
```java
47
import org.springframework.boot.loader.tools.Repackager;
48
import org.springframework.boot.loader.tools.Libraries;
49
import org.springframework.boot.loader.tools.Library;
50
import org.springframework.boot.loader.tools.LibraryScope;
51
import java.io.File;
52
import java.io.IOException;
53
54
// Basic repackaging of a JAR file
55
File sourceJar = new File("myapp.jar");
56
Repackager repackager = new Repackager(sourceJar);
57
58
// Define libraries to include
59
Libraries libraries = new Libraries() {
60
@Override
61
public void doWithLibraries(LibraryCallback callback) throws IOException {
62
// Add runtime dependencies
63
callback.library(new Library(new File("lib/spring-core.jar"), LibraryScope.COMPILE));
64
callback.library(new Library(new File("lib/logback-classic.jar"), LibraryScope.RUNTIME));
65
}
66
};
67
68
// Repackage into executable JAR
69
repackager.repackage(libraries);
70
```
71
72
## Architecture
73
74
The Spring Boot Loader Tools library is built around several key architectural components:
75
76
- **Repackager**: Main entry point that orchestrates the repackaging process
77
- **Layout System**: Defines where classes and libraries are placed in the archive (JAR, WAR, expanded)
78
- **Library Management**: Handles dependency libraries with scope and coordinate tracking
79
- **JAR Writers**: Low-level classes for writing JAR file entries and managing archive structure
80
- **Layer Support**: Enables Docker image optimization through strategic content layering
81
- **Loader Implementation**: Provides the runtime loader classes that enable executable JARs
82
83
This design supports Spring Boot's "fat JAR" packaging model, allowing applications to run with `java -jar` while maintaining all necessary dependencies and configuration within a single executable file.
84
85
## Capabilities
86
87
### JAR/WAR Repackaging
88
89
Core functionality for transforming regular JAR/WAR files into executable Spring Boot archives. Handles main class detection, library inclusion, manifest generation, and loader class integration.
90
91
```java { .api }
92
public class Repackager {
93
public Repackager(File source);
94
public void repackage(Libraries libraries) throws IOException;
95
public void repackage(File destination, Libraries libraries) throws IOException;
96
public void repackage(File destination, Libraries libraries, LaunchScript launchScript) throws IOException;
97
public void repackage(File destination, Libraries libraries, LaunchScript launchScript, FileTime lastModifiedTime) throws IOException;
98
public void setBackupSource(boolean backupSource);
99
}
100
```
101
102
[Repackaging](./repackaging.md)
103
104
### Main Class Detection
105
106
Automatic discovery of classes with public static main methods using breadth-first search. Supports both directory and JAR file analysis with annotation-based filtering.
107
108
```java { .api }
109
public abstract class MainClassFinder {
110
public static String findMainClass(File rootDirectory) throws IOException;
111
public static String findSingleMainClass(File rootDirectory) throws IOException;
112
public static String findSingleMainClass(File rootDirectory, String annotationName) throws IOException;
113
public static String findMainClass(JarFile jarFile, String classesLocation) throws IOException;
114
public static String findSingleMainClass(JarFile jarFile, String classesLocation) throws IOException;
115
public static String findSingleMainClass(JarFile jarFile, String classesLocation, String annotationName) throws IOException;
116
}
117
```
118
119
[Main Class Detection](./main-class-detection.md)
120
121
### Archive Layout Management
122
123
Strategy-based system for determining how classes and libraries are organized within different archive types. Supports JAR, WAR, and expanded directory layouts with customization options.
124
125
```java { .api }
126
public interface Layout {
127
String getLauncherClassName();
128
String getLibraryLocation(String libraryName, LibraryScope scope);
129
String getClassesLocation();
130
boolean isExecutable();
131
}
132
133
public final class Layouts {
134
public static Layout forFile(File file);
135
public static class Jar implements RepackagingLayout { }
136
public static class War implements Layout { }
137
}
138
```
139
140
[Layout Management](./layout-management.md)
141
142
### Library Management
143
144
Comprehensive system for handling dependency libraries including scope classification, coordinate tracking, and inclusion/exclusion logic. Integrates with build tools and dependency resolution.
145
146
```java { .api }
147
public class Library {
148
public Library(File file, LibraryScope scope);
149
public String getName();
150
public LibraryScope getScope();
151
public LibraryCoordinates getCoordinates();
152
}
153
154
public interface Libraries {
155
void doWithLibraries(LibraryCallback callback) throws IOException;
156
}
157
```
158
159
[Library Management](./library-management.md)
160
161
### JAR Writing and Entry Management
162
163
Low-level utilities for writing JAR files with proper directory structure, duplicate handling, manifest generation, and nested library support.
164
165
```java { .api }
166
public class JarWriter implements AutoCloseable {
167
public JarWriter(File file) throws FileNotFoundException, IOException;
168
public JarWriter(File file, LaunchScript launchScript) throws FileNotFoundException, IOException;
169
public JarWriter(File file, LaunchScript launchScript, FileTime lastModifiedTime) throws FileNotFoundException, IOException;
170
public void close() throws IOException;
171
}
172
173
public abstract class AbstractJarWriter implements LoaderClassesWriter {
174
public void writeManifest(Manifest manifest) throws IOException;
175
public void writeEntry(String entryName, InputStream inputStream) throws IOException;
176
public void writeNestedLibrary(String location, Library library) throws IOException;
177
}
178
```
179
180
[JAR Writing](./jar-writing.md)
181
182
### Layer Support for Docker Optimization
183
184
Advanced layering system for optimizing Docker image builds by strategically separating application code, dependencies, and Spring Boot loader components into distinct layers.
185
186
```java { .api }
187
public class Layer {
188
public Layer(String name);
189
}
190
191
public interface Layers extends Iterable<Layer> {
192
Layer getLayer(String applicationResource);
193
Layer getLayer(Library library);
194
}
195
196
public abstract class StandardLayers implements Layers {
197
public static final Layer DEPENDENCIES;
198
public static final Layer SPRING_BOOT_LOADER;
199
public static final Layer SNAPSHOT_DEPENDENCIES;
200
public static final Layer APPLICATION;
201
}
202
```
203
204
[Layer Support](./layer-support.md)
205
206
### Launch Script Generation
207
208
Tools for creating launch scripts that make JAR files directly executable on Unix-like systems, supporting customizable script templates and property substitution.
209
210
```java { .api }
211
public interface LaunchScript {
212
byte[] toByteArray();
213
}
214
215
public class DefaultLaunchScript implements LaunchScript {
216
public DefaultLaunchScript(File file, Map<?, ?> properties) throws IOException;
217
}
218
```
219
220
[Launch Scripts](./launch-scripts.md)
221
222
### Build Integration
223
224
Utilities for integrating with build tools and generating build metadata for Spring Boot Actuator endpoints, including project details and build information.
225
226
```java { .api }
227
public final class BuildPropertiesWriter {
228
public BuildPropertiesWriter(File outputFile);
229
public void writeBuildProperties(ProjectDetails projectDetails) throws IOException;
230
231
public static final class ProjectDetails {
232
public ProjectDetails(String group, String artifact, String version, String name, Instant time, Map<String, String> additionalProperties);
233
public String getGroup();
234
public String getArtifact();
235
public String getName();
236
public String getVersion();
237
public Instant getTime();
238
public Map<String, String> getAdditionalProperties();
239
}
240
241
public static class NullAdditionalPropertyValueException extends IllegalArgumentException {
242
public NullAdditionalPropertyValueException(String name);
243
}
244
}
245
```
246
247
[Build Integration](./build-integration.md)
248
249
### OCI Image Packaging
250
251
Specialized packager for exporting fully packaged archives to OCI (Open Container Initiative) images. Designed for Docker integration and container deployment workflows.
252
253
```java { .api }
254
public class ImagePackager extends Packager {
255
public ImagePackager(File source, File backupFile);
256
public void packageImage(Libraries libraries, BiConsumer<ZipEntry, EntryWriter> exporter) throws IOException;
257
}
258
```
259
260
[Image Packaging](./image-packaging.md)
261
262
## Core Types
263
264
```java { .api }
265
public interface LibraryScope {
266
LibraryScope COMPILE = /* ... */;
267
LibraryScope RUNTIME = /* ... */;
268
LibraryScope PROVIDED = /* ... */;
269
LibraryScope CUSTOM = /* ... */;
270
}
271
272
public interface LibraryCoordinates {
273
String getGroupId();
274
String getArtifactId();
275
String getVersion();
276
static LibraryCoordinates of(String groupId, String artifactId, String version);
277
}
278
279
public interface LibraryCallback {
280
void library(Library library) throws IOException;
281
}
282
283
public enum LoaderImplementation {
284
DEFAULT, CLASSIC;
285
String getJarResourceName();
286
}
287
288
public interface EntryWriter {
289
void write(OutputStream outputStream) throws IOException;
290
default int size() { return -1; }
291
}
292
```