Merge branch '3.5.x' into 4.0.x

Closes gh-50484

Author: philwebb

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/aot-cache.adoc

@@ -4,16 +4,18 @@
 
 AOT cache is a https://openjdk.org/jeps/483[JVM feature] that can help reduce the startup time and memory footprint of Java applications.
 
-If you're using Java < 24, you should read the sections about CDS.
+If you are not yet using Java 25 or above, you should read the sections about CDS.
 CDS is the predecessor of AOT cache, but works similarly.
 
-Spring Boot supports both CDS and AOT cache, and it is recommended that you use AOT cache if it is available in the JVM version you are using (Java 24 or later).
+NOTE: Spring Boot supports both CDS and AOT cache, however, we recommend using the AOT cache whenever possible.
+
+
 
 [[packaging.aot-cache.aot-cache]]
 == AOT Cache
 
-NOTE: If you're using Java < 24, AOT cache is not available.
-You have to use CDS instead.
+NOTE: Spring Boot supports the AOT cache for Java 25 and above.
+If you're using an earlier version of Java, you have to use CDS instead.
 
 To use the AOT cache feature, you should first perform a training run on your application in extracted form:
 
@@ -40,7 +42,7 @@ NOTE: You have to use the cache file with the extracted form of the application,
 [[packaging.aot-cache.cds]]
 == CDS
 
-NOTE: If you're using Java 24 or later, please use AOT cache instead of CDS.
+NOTE: If you're using Java 25 or above, please use AOT cache instead of CDS.
 
 To use CDS, you should first perform a training run on your application in extracted form:
 

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/packaging/container-images/dockerfiles.adoc

@@ -77,6 +77,27 @@ As the last steps, it creates the AOT cache file by doing a training run and pas
 
 
 
+[[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
 
@@ -86,8 +107,10 @@ If you want to additionally enable xref:reference:packaging/aot-cache.adoc#packa
 [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
@@ -96,3 +119,5 @@ 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`.
+
+NOTE: If you are using Java 25 or above, we recommend using an AOT cache instead of CDS.

documentation/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:25-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:25-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