{"id":6128,"date":"2025-12-17T03:03:45","date_gmt":"2025-12-17T03:03:45","guid":{"rendered":"https:\/\/www.javaadvent.com\/?p=6128"},"modified":"2025-12-08T09:03:13","modified_gmt":"2025-12-08T09:03:13","slug":"run-java-aot-cache-optimizations","status":"publish","type":"post","link":"https:\/\/www.javaadvent.com\/2025\/12\/run-java-aot-cache-optimizations.html","title":{"rendered":"Run Into the New Year with Java\u2019s Ahead-of-Time Cache Features"},"content":{"rendered":"

As the year comes to a close, turn your focus to boosting your Java application performance by applying Ahead-of-Time (AOT) cache features in recent JDK releases. This article guides you through using AOT cache optimizations in your application, thereby minimizing startup time and achieving faster peak performance.<\/p>\n

What is the Ahead-of-time cache in the jdk<\/h2>\n

JDK 24 introduced the Ahead-Of-Time (AOT) cache, a HotSpot JVM feature that stores classes after they are read, parsed, loaded, and linked. Creating an AOT cache is specific to an application, and you can reuse it in subsequent runs of that application to improve the time to the first functional unit of work (startup time).<\/p>\n

To generate an AOT cache, you need to perform two steps:<\/p>\n

    \n
  1. Training by recording observations of the application in action. You can trigger a recording by setting an argument for the -XX:AOTMode<\/code>\u00a0option and giving a destination for the configuration file via\u00a0-XX:AOTConfiguration<\/code>:\n
    java -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf \n     -cp app.jar com.example.App ...<\/pre>\n
    This step aims to answer questions like “Which classes does the application load and initialize?”, “Which methods become hot?” and store the results in a configuration file (app.aotconf<\/code>).<\/li>\n
  2. Assembly that converts the observations from the configuration file into an AOT cache (app.aot<\/code>).\n
    java -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf \n     -XX:AOTCache=app.aot -cp app.jar<\/pre>\n<\/li>\n<\/ol>\n
    To benefit from a better startup time, run the application by pointing the -XX:AOTCache flag to the resulting AOT cache.<\/p>\n
    java -XX:AOTCache=app.aot -cp app.jar com.example.App ...<\/pre>\n
    The improved startup time is the result of shifting work, usually done just-in-time when the program runs, earlier to the second step, which creates the cache. Thereafter, the program starts up faster in the third phase because its classes are available from the cache immediately.<\/p>\n
    The three-step workflow (train+assemble+run) became available starting with JDK 24, via\u00a0JEP 483: Ahead-of-Time Class Loading & Linking<\/a>, the first feature merged from the research done by Project Leyden<\/a>. A set of\u00a0benchmarks<\/a> prove the effectiveness of this feature and other Leyden performance-related ones, as displayed by Figure 1<\/em>.<\/p>\n
    \"Figure<\/a>
    Figure 1: AOT Cache Benchmarks as of JDK 24<\/p><\/div>\n
    In JDK 25, the changes in\u00a0<\/span>JEP 515 – Ahead-of-Time Method Profiling<\/span><\/a> enabled frequently executed method profiles to be part of the AOT cache. This addition improves application warm up by allowing the JIT to start generating native code immediately at application startup. The new AOT feature does not require you to add more constraints to your application execution; just use the existing AOT cache creation commands. Moreover,\u00a0<\/span>benchmarks<\/span><\/a> showed improved startup time too (<\/span>Figure 2<\/span><\/em>).<\/span><\/p>\n
    \"Figure
    Figure 2: AOT Cache Benchmarks as of JDK 25<\/p><\/div>\n
    JDK 25 also simplified the process for generating an AOT cache by making it possible to do it in a single step, through setting the argument for\u00a0-XX:AOTCacheOutput<\/code>\u00a0flag:<\/p>\n
    # Training Run + Assembly Phase\njava -XX:AOTCacheOutput=app.aot \\\n     -cp app.jar com.example.App ...<\/pre>\n
    Upon passing\u00a0-XX:AOTCacheOutput=[cache\u00a0<\/span>location]<\/code>, the JVM creates the cache on its shutdown. JEP 514 – Ahead-of-Time Command-Line Ergonomics<\/a>\u00a0introduced the two-step process for creating and using the AOT cache.<\/p>\n
    # Training Run + Assembly Phase\njava -XX:AOTCacheOutput=app.aot \\\n     -cp app.jar com.example.App ...\n\n# Deployment Run\njava -XX:AOTCache=app.aot -cp app.jar com.example.App ...<\/pre>\n
    The two-step workflow may not work as expected in resource-constrained environments. The sub-invocation that creates the AOT cache uses its own Java heap with the same size as the heap used for the\u00a0training run<\/a>. As a result, the memory needed to complete the one-step AOT cache generation is double the heap size specified on the command line. For example, if the one-step workflow\u00a0java\u00a0<\/span>-XX:AOTCacheOutput=...<\/code>\u00a0is accompanied by\u00a0-Xms2g\u00a0<\/span>-Xmx2g<\/code>, specifying a 2GB heap, then the environment needs 4GB to complete the workflow.<\/p>\n
    A division of steps, as in a three-phase workflow, may be a better choice if you intend to deploy an application to small cloud tenancies. In such cases, you could run the training on a small instance while creating the AOT cache on a larger one. That way, the training run reflects the deployment environment, while the AOT cache creation can leverage the additional CPU cores and memory of the large instance.<\/p>\n
    Regardless of which workflow you choose, let\u2019s take a closer look at AOT cache requirements and how to set it up to serve your application needs best.<\/p>\n
    How to Craft the AOT Cache Your Application Needs<\/h2>\n
    Training and production runs should produce consistent results, just faster in deployment runs. To achieve that, the assembly phase intermediates what happens between training and production runs (Figure 3<\/em>).<\/p>\n
    \"Figure<\/a>
    Figure 3: Training \/ Assembly \/ Deployment<\/p><\/div>\n
    For consistent training runs and the subsequent ones, make sure that:<\/p>\n