Ahead-of-Time Class Loading & Linking

1. Introduction

JDK 24 introduced AOT Cache with JEP 483. This cache allows applications to start faster by pre-loading and also pre-linking classes. However, the workflow of creating the cache effectively required two separate java invocations.

As a result, JDK 25 improves on that with two new JEPs. First, JEP 514 simplifies the AOT cache creation into a single command. And second, JEP 515 extends the cache to store method execution profiles, improving application warmup time.

In this article, we’ll explore both new JEPs and see how they work together. It is also important to note that we’re going ot need JDK 25 to take advantage of these features.

2. How AOT Cache Worked in JDK 24

Before we delve into the JDK 25 ways of doing AOT Caches, let’s quickly recap how AOT caching worked with JDK 24.

To create an AOT cache back then, we had to invoke the java utility twice, and thus create two separate java processes. The first invocation runs the application in record mode. It means that Runtime observes how the application behaves during a training run and saves that information into an AOT configuration file:

$ java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf -cp app.jar com.example.App

The second invocation uses that configuration generated on the previous step to actually build the cache:

$ java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf  -XX:AOTCache=app.aot

And finally, we can run the application with the generated cache, which, theoretically, should significantly reduce startup time:

$ java -XX:AOTCache=app.aot -cp app.jar com.example.App

This workflow, while it of course works, leaves us with a temporary configuration file and requires managing two separate commands. The experienced readers may note that a similar clumsy process with two phases was with AppCDS archives (effectively, a predecessor to AOT Cache). So, JEP 514 addresses exactly that for AOT Caches now.

3. One-Shot AOT Cache Creation (JEP 514)

JEP 514 introduces a new command-line non-standard (-XX) VM option: AOTCacheOutput. When we use this option alone, without any other AOT flags, the launcher automatically splits the invocation into two internal sub-invocations—one for training and one for cache creation.

So, instead of the two-step workflow above, we can simply do:

$ java -XX:AOTCacheOutput=app.aot -cp app.jar com.example.App

This single command replaces the two commands that were initially used to create the AOT Cache. The JVM runs the application as a training exercise, records the dynamics, and then just creates the AOT cache in one shot.

The production command (providing the cache to the production workload) remains the same since JDK 24:

$ java -XX:AOTCache=app.aot -cp app.jar com.example.App

But here is the thing – there is still a two-phase procedure done in the background. Effectively, the java launcher creates two subprocesses to complete the cache creation. That is important, and it has its implications.

4. The Downsides of the One-Shot Approach

One may think that a two-process setup is just the obvious choice, and it is the way to go – not quite.

As mentioned, these are two distinct java processes that are going to get launched, and both of them have their own heaps. And because they are both launched by the java launcher process (literally the one that is created by calling the java binary), the peak memory consumption is potentially doubled. So, if we specify -Xmx4g, the one-step workflow, potentially, at most, will need 8GB of heap memory in total to complete.

So, the one-step workflow is great for most scenarios, but the two-step approach also has its place, in particular in memory-constrained environments. It may easily be the case that the cloud VM that is going to host our application will not have sufficient RAM resources to serve the double-sized heap. In that case, the explicit two-step workflow is the preferred option.

5. AOT Method Profiling (JEP 515)

While JEP 514 simplifies the process of AOT cache creation, JEP 515 enhances what information the cache stores.

To understand JEP 515, we need to recall how HotSpot reaches peak performance. The JIT compiler identifies hot methods (the methods that are executed relatively frequently) and then compiles them to optimized native code. But in order to do this, it has to collect some profiling information for those methods. And this process takes time. Usually, this time is called a warmup period, and during this period, the application runs slower than it potentially can.

And frankly, it is often the case that the execution patterns of our application are roughly the same. Our production workloads often took similar if branches under the same circumstances. So the profiling information won’t really change from one app launch to another. Thus, it also makes sense to cache it ahead of time.

So, JEP 515 solves this by extending the AOT cache to include method execution profiles from the training run. When the application starts in production, those profiles are instantly available, so the JIT compiler can begin generating optimized code right away, without waiting for warmup.

The cool thing is that we don’t need to change the launch command, let alone the application code, to benefit from this feature. Profiling data is automatically collected during the training run and then stored in the AOT cache. So, this just works out-of-the-box with the one-step workflow from JEP 514:

# Training + cache creation (profiles are included automatically)
$ java -XX:AOTCacheOutput=app.aot -cp app.jar com.example.App

# Production run (benefits from both cached classes and cached profiling info)
$ java -XX:AOTCache=app.aot -cp app.jar com.example.App

In the case above, the JVM starts with the code cache that already contains certain profiling information.

6. Runtime Profiling vs. Cached Profiling

An important note here is that cached profiles don’t prevent additional profiling during production. The HotSpot JVM continues to profile and optimize the application as it runs, combining the benefits of AOT profiles, online profiling, and JIT compilation.

It is important since an application’s behavior in production can still possibly diverge from what was observed during the training run. Cached profiles just give the JIT a quick start, allowing it to compile some methods sooner. As the app runs, the HotSpot re-evaluates its understanding of workload patterns and then recompiles methods if needed.

7. Conclusion

JEP 514 and JEP 515 are both part of the OpenJDK Project Leyden effort to improve Java startup and warmup performance. JEP 514 brings a practical quality-of-life improvement — collapsing the two-step AOT cache creation into a single command. While often the preferred approach, still, in memory-constrained environments, the two-phase process might be the right way to go.

JEP 515 enriches the cached data by including method profiles, so the JIT compiler can start compiling from the very start of the app.