From 29a1eece0c6685a09daf1cd3e8e45903f670903a Mon Sep 17 00:00:00 2001 From: halo Date: Fri, 22 May 2026 17:32:08 +0900 Subject: [PATCH 1/3] Document Java 25 requirement for AOT cache See gh-50482 Signed-off-by: halo --- .../modules/reference/pages/packaging/class-data-sharing.adoc | 3 ++- .../pages/packaging/container-images/dockerfiles.adoc | 3 +-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/class-data-sharing.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/class-data-sharing.adoc index 65a32c1831a2..08293e11260c 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/class-data-sharing.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/class-data-sharing.adoc @@ -4,7 +4,8 @@ Class Data Sharing (CDS) is a https://docs.oracle.com/en/java/javase/17/vm/class-data-sharing.html[JVM feature] that can help reduce the startup time and memory footprint of Java applications. In Java 24, CDS is succeeded by the AOT Cache via https://openjdk.org/jeps/483[JEP 483]. -Spring Boot supports both CDS and AOT cache, and it is recommended that you use the latter if it is available in the JVM version you are using (Java 24+). +Spring Boot supports both CDS and AOT cache. +As Java 24 is no longer supported, Java 25 is the minimum supported version where AOT cache can be used. [[packaging.class-data-sharing.cds]] == CDS diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc index 0e43466a1714..3575cd343301 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc @@ -83,8 +83,7 @@ If you want to additionally enable the xref:reference:packaging/class-data-shari ---- include::reference:partial$dockerfile[] # Execute the AOT cache training run -RUN java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf -Dspring.context.exit=onRefresh -jar application.jar -RUN java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf -XX:AOTCache=app.aot -jar application.jar && rm app.aotconf +RUN java -XX:AOTCacheOutput=app.aot -Dspring.context.exit=onRefresh -jar application.jar # Start the application jar with AOT cache enabled - this is not the uber jar used by the builder # This jar only contains application code and references to the extracted jar files # This layout is efficient to start up and AOT cache friendly From b44bb3863988cae73e075fb1d47e265c14c786f6 Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Fri, 22 May 2026 12:14:46 -0700 Subject: [PATCH 2/3] Polish "Document Java 25 requirement for AOT cache" See gh-50482 --- .../pages/packaging/class-data-sharing.adoc | 10 +++-- .../container-images/dockerfiles.adoc | 41 +++++++++++-------- .../modules/reference/partials/dockerfile | 4 ++ 3 files changed, 35 insertions(+), 20 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/class-data-sharing.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/class-data-sharing.adoc index 08293e11260c..d4409558bc2a 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/class-data-sharing.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/class-data-sharing.adoc @@ -3,9 +3,11 @@ Class Data Sharing (CDS) is a https://docs.oracle.com/en/java/javase/17/vm/class-data-sharing.html[JVM feature] that can help reduce the startup time and memory footprint of Java applications. -In Java 24, CDS is succeeded by the AOT Cache via https://openjdk.org/jeps/483[JEP 483]. -Spring Boot supports both CDS and AOT cache. -As Java 24 is no longer supported, Java 25 is the minimum supported version where AOT cache can be used. +If you are using Java 25 or above, CDS has been succeeded by the AOT Cache via https://openjdk.org/jeps/483[JEP 483]. + +NOTE: Spring Boot supports both CDS and AOT cache, however, we recommend using the AOT cache whenever possible. + + [[packaging.class-data-sharing.cds]] == CDS @@ -30,6 +32,8 @@ $ java -XX:SharedArchiveFile=application.jsa -jar my-app.jar NOTE: For more details about CDS, refer to the xref:how-to:class-data-sharing.adoc[CDS how-to guide] and the {url-spring-framework-docs}/integration/cds.html[Spring Framework reference documentation]. + + [[packaging.class-data-sharing.aot-cache]] == AOT Cache diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc index 3575cd343301..34fd3f4fd6bf 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc @@ -57,6 +57,27 @@ Additionally, the layout created by the `jarmode` is CDS and AOT cache friendly +[[packaging.container-images.dockerfiles.aot-cache]] +== AOT cache + +If you are using Java 25 or above, and want to additionally enable the xref:reference:packaging/class-data-sharing.adoc#packaging.class-data-sharing.aot-cache[AOT cache], you can use this `Dockerfile`: +[source,dockerfile] +---- +include::reference:partial$dockerfile[] + +# Execute the AOT cache training run +RUN java -XX:AOTCacheOutput=app.aot -Dspring.context.exit=onRefresh -jar application.jar + +# Start the application jar with AOT cache enabled - this is not the uber jar used by the builder +# This jar only contains application code and references to the extracted jar files +# This layout is efficient to start up and AOT cache friendly +ENTRYPOINT ["java", "-XX:AOTCache=app.aot", "-jar", "application.jar"] +---- + +This is mostly the same as the above `Dockerfile`. +As the last steps, it creates the AOT cache file by doing a training run and passes the AOT cache parameter to `java -jar`. + + [[packaging.container-images.dockerfiles.cds]] == CDS @@ -64,8 +85,10 @@ If you want to additionally enable xref:reference:packaging/class-data-sharing.a [source,dockerfile] ---- include::reference:partial$dockerfile[] + # Execute the CDS training run RUN java -XX:ArchiveClassesAtExit=application.jsa -Dspring.context.exit=onRefresh -jar application.jar + # Start the application jar with CDS enabled - this is not the uber jar used by the builder # This jar only contains application code and references to the extracted jar files # This layout is efficient to start up and CDS friendly @@ -75,20 +98,4 @@ ENTRYPOINT ["java", "-XX:SharedArchiveFile=application.jsa", "-jar", "applicatio This is mostly the same as the above `Dockerfile`. As the last steps, it creates the CDS archive by doing a training run and passes the CDS parameter to `java -jar`. -[[packaging.container-images.dockerfiles.aot-cache]] -== AOT cache - -If you want to additionally enable the xref:reference:packaging/class-data-sharing.adoc#packaging.class-data-sharing.aot-cache[AOT cache], you can use this `Dockerfile`: -[source,dockerfile] ----- -include::reference:partial$dockerfile[] -# Execute the AOT cache training run -RUN java -XX:AOTCacheOutput=app.aot -Dspring.context.exit=onRefresh -jar application.jar -# Start the application jar with AOT cache enabled - this is not the uber jar used by the builder -# This jar only contains application code and references to the extracted jar files -# This layout is efficient to start up and AOT cache friendly -ENTRYPOINT ["java", "-XX:AOTCache=app.aot", "-jar", "application.jar"] ----- - -This is mostly the same as the above `Dockerfile`. -As the last steps, it creates the AOT cache file by doing a training run and passes the AOT cache parameter to `java -jar`. +NOTE: If you are using Java 25 or above, we recommend using an AOT cache instead of CDS. diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/partials/dockerfile b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/partials/dockerfile index 8acc7aa9b69b..a8afa1bd851b 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/partials/dockerfile +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/partials/dockerfile @@ -1,17 +1,21 @@ # Perform the extraction in a separate builder container FROM bellsoft/liberica-openjre-debian:24-cds AS builder WORKDIR /builder + # This points to the built jar file in the target folder # Adjust this to 'build/libs/*.jar' if you're using Gradle ARG JAR_FILE=target/*.jar + # Copy the jar file to the working directory and rename it to application.jar COPY ${JAR_FILE} application.jar + # Extract the jar file using an efficient layout RUN java -Djarmode=tools -jar application.jar extract --layers --destination extracted # This is the runtime container FROM bellsoft/liberica-openjre-debian:24-cds WORKDIR /application + # Copy the extracted jar contents from the builder container into the working directory in the runtime container # Every copy step creates a new docker layer # This allows docker to only pull the changes it really needs From 2e6d53e664150112ed8dc814851e75626b922cc1 Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Fri, 22 May 2026 14:42:43 -0700 Subject: [PATCH 3/3] Remove accidentally duplicated dockerfile documentation Remove duplication accidentally introduced during merge. See gh-50482 --- .../container-images/dockerfiles.adoc | 25 +------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc index 39de055dcbb9..e188df664c60 100644 --- a/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc +++ b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc @@ -54,33 +54,10 @@ Additionally, the layout created by the `jarmode` is AOT cache (and CDS) friendl -[[packaging.container-images.dockerfiles.aot-cache]] -== AOT Cache - -NOTE: If you're using Java < 24, AOT cache is not available. -You have to use CDS instead. - -If you want to additionally enable the xref:reference:packaging/aot-cache.adoc#packaging.aot-cache.aot-cache[AOT cache], you can use this `Dockerfile`: -[source,dockerfile] ----- -include::reference:partial$dockerfile[] -# Execute the AOT cache training run -RUN java -XX:AOTCacheOutput=app.aot -Dspring.context.exit=onRefresh -jar application.jar -# Start the application jar with AOT cache enabled - this is not the uber jar used by the builder -# This jar only contains application code and references to the extracted jar files -# This layout is efficient to start up and AOT cache friendly -ENTRYPOINT ["java", "-XX:AOTCache=app.aot", "-jar", "application.jar"] ----- - -This is mostly the same as the above `Dockerfile`. -As the last steps, it creates the AOT cache file by doing a training run and passes the AOT cache parameter to `java -jar`. - - - [[packaging.container-images.dockerfiles.aot-cache]] == AOT cache -If you are using Java 25 or above, and want to additionally enable the xref:reference:packaging/class-data-sharing.adoc#packaging.class-data-sharing.aot-cache[AOT cache], you can use this `Dockerfile`: +If you are using Java 25 or above, and want to additionally enable the xref:reference:packaging/aot-cache.adoc#packaging.aot-cache.aot-cache[AOT cache], you can use this `Dockerfile`: [source,dockerfile] ---- include::reference:partial$dockerfile[]