Startup: AOT cache and native images

Start-up time is the time from typing java to the first useful result. Before a Java program does its own work, the JVM loads, links and initialises every class it needs, often more than a thousand of them, and runs the program’s code in the interpreter until the JIT compiler has compiled the busy parts. The AOT cache (ahead-of-time cache) removes much of that work: a training run of the program records which classes it uses, and later runs find those classes already loaded and linked in one file. JDK 24 added it (JEP 483), JDK 25 made it a single option, -XX:AOTCacheOutput (JEP 514), and also stores method profiles in it (JEP 515). Native images, built with GraalVM’s native-image tool, go further: they compile the whole program ahead of time into an executable for one operating system and processor. This lesson measures the first and explains when the second is worth its costs.

Where start-up time goes

A small command-line tool shows the work. It reads five invoices from XML, checks each tax registration number against its pattern, totals the amounts by state and prints a summary:

import java.io.ByteArrayInputStream;
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.nio.charset.StandardCharsets;
import java.text.NumberFormat;
import java.time.LocalDate;
import java.time.temporal.ChronoUnit;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.TreeMap;
import java.util.logging.Logger;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import javax.xml.parsers.DocumentBuilderFactory;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;

/** A command-line tool that reads invoices from XML, checks their GSTIN, totals them by state and prints a summary. */
public class InvoiceTool {
    record Invoice(String gstin, String state, LocalDate date, BigDecimal amount) {}

    static final String XML = """
        <invoices>
          <invoice gstin="27AAPFU0939F1ZV" state="Maharashtra" date="2026-09-01" amount="11800.00"/>
          <invoice gstin="29AAGCB7383J1Z4" state="Karnataka" date="2026-09-02" amount="2360.50"/>
          <invoice gstin="27AAPFU0939F1ZV" state="Maharashtra" date="2026-09-05" amount="590.00"/>
          <invoice gstin="33AABCT1332L1ZZ" state="Tamil Nadu" date="2026-09-07" amount="47200.00"/>
          <invoice gstin="BADGSTIN" state="Kerala" date="2026-09-09" amount="100.00"/>
        </invoices>
        """;
    static final Pattern GSTIN = Pattern.compile("\\d{2}[A-Z]{5}\\d{4}[A-Z][1-9A-Z]Z[0-9A-Z]");

    public static void main(String[] args) throws Exception {
        Logger.getLogger("invoice").fine("starting");
        var doc = DocumentBuilderFactory.newInstance().newDocumentBuilder()
                .parse(new ByteArrayInputStream(XML.getBytes(StandardCharsets.UTF_8)));
        NodeList nodes = doc.getElementsByTagName("invoice");
        List<Invoice> invoices = new ArrayList<>();
        for (int i = 0; i < nodes.getLength(); i++) {
            Element e = (Element) nodes.item(i);
            invoices.add(new Invoice(e.getAttribute("gstin"), e.getAttribute("state"),
                    LocalDate.parse(e.getAttribute("date")), new BigDecimal(e.getAttribute("amount"))));
        }
        var valid = invoices.stream().filter(inv -> GSTIN.matcher(inv.gstin()).matches()).toList();
        Map<String, BigDecimal> byState = valid.stream().collect(Collectors.groupingBy(Invoice::state, TreeMap::new,
                Collectors.reducing(BigDecimal.ZERO, Invoice::amount, BigDecimal::add)));
        var rupees = NumberFormat.getCurrencyInstance(Locale.of("en", "IN"));
        long days = ChronoUnit.DAYS.between(valid.getFirst().date(), valid.getLast().date()) + 1;
        System.out.printf("%d invoices, %d with a valid GSTIN, issued over %d days%n", invoices.size(), valid.size(), days);
        byState.forEach((state, total) -> System.out.println("  " + state + ": " + rupees.format(total.setScale(2, RoundingMode.HALF_UP))));
    }
}

To print four lines, it uses XML parsing, regular expressions, streams, records, decimal arithmetic and currency formatting, and each of these brings its classes, well over a thousand in all. The JDK already ships a class data sharing (CDS) archive: about 1,400 of its own most common classes, listed in its lib/classlist file and stored in their parsed form in a 16 MB file, lib/server/classes.jsa, which the JVM maps into memory at start-up instead of reading those classes one by one. The tool’s other classes, from the XML parser to its own InvoiceTool, are still read, parsed, verified and linked in every run, and the code that initialises them runs every time too.

Creating and using an AOT cache

Since JDK 25, one extra option on a normal run creates the cache. The cache is tied to the class path, so the tool is packaged as a JAR first:

from pathlib import Path

from session import run
from startup import show, times

# The tool as a JAR, then a training run that writes an AOT cache (JDK 25, JEP 514), then five timed runs of the
# tool without the cache and five with it.
run("""
javac -d out InvoiceTool.java
jar --create --file app.jar --main-class InvoiceTool -C out .
java -jar app.jar
java -XX:AOTCacheOutput=app.aot -jar app.jar > /dev/null
""")
print(f"# The cache: {Path('app.aot').stat().st_size / 1e6:.1f} MB")
print("# Five runs each, wall-clock time from start to exit")
show("java -jar app.jar", times("java -jar app.jar"))
show("... -XX:AOTCache=app.aot", times("java -XX:AOTCache=app.aot -jar app.jar"))

# JDK in use: openjdk version "25.0.4.1" LTS
$ javac -d out InvoiceTool.java
$ jar --create --file app.jar --main-class InvoiceTool -C out .
$ java -jar app.jar
5 invoices, 4 with a valid GSTIN, issued over 7 days
  Karnataka: ₹2,360.50
  Maharashtra: ₹12,390.00
  Tamil Nadu: ₹47,200.00
$ java -XX:AOTCacheOutput=app.aot -jar app.jar > /dev/null
Picked up JAVA_TOOL_OPTIONS: -Djava.class.path=app.jar -XX:AOTCacheOutput=app.aot -XX:AOTConfiguration=app.aot.config -XX:AOTMode=create
# The cache: 17.0 MB
# Five runs each, wall-clock time from start to exit
java -jar app.jar              768   813   750   576   766   median   766 ms
... -XX:AOTCache=app.aot       714   424   246   212   373   median   373 ms

-XX:AOTCacheOutput=app.aot turns the run into a training run. The tool runs as usual, and the JVM notes every class it loads and links. When the tool ends, the JVM starts a second JVM that reads those notes and writes the cache: the line Picked up JAVA_TOOL_OPTIONS comes from that second JVM, which received its instructions through an environment variable. Later runs use the cache with -XX:AOTCache=app.aot.

In the recorded runs, the cache was 17 MB, and the median start-up fell from 766 ms to 373 ms, about half. Each figure is the median of five runs, measured from starting the process to its exit, on a computer that was busy with other work, which is why single runs vary by a few hundred milliseconds. The cache is also specific: JEP 483 lists the same JDK release, the same operating system and processor, and the same class path, made of JAR files only, as conditions for using it. With -XX:AOTMode=on, a JVM that cannot use its cache stops with an error instead of starting without it.

The training run should do what production does, because the cache can only hold what that run loaded and, since JDK 25, how its methods behaved; JEP 515 states plainly that the benefit depends on the training run resembling production. A training run that only prints a help text produces a small cache that covers little of a real start-up. The gain also grows with the number of classes a program loads beyond the JDK’s own archive: JEP 483 reports Spring PetClinic, which loads about 21,000 classes, starting in 2.604 seconds instead of 4.486 with a 130 MB cache.

Three ways to start faster, compared

The JDK’s archive is always there. An AOT cache asks one extra run and keeps everything else about the JVM, including its JIT compiler. A native image changes the deployment: GraalVM’s documentation describes it as starting in milliseconds without warm-up, and as needing configuration for reflection, dynamic proxies and resources.

Check yourself

Measuring start-up honestly: classes, a tiny program and warm-up Pro: opens with a Pro, Premium or Ultimate pass

Stale caches, wrong training runs, and what they cost Pro: opens with a Pro, Premium or Ultimate pass

AOT cache or native image: a decision with its costs Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Key takeaways

• Start-up is class loading, linking, initialisation and interpreted code before the JIT compiler catches up.
• On JDK 25, java -XX:AOTCacheOutput=app.aot trains and writes an AOT cache, and -XX:AOTCache=app.aot uses it.
• Measure start-up as a median of several runs from process start to exit, with the same workload before and after.
• A native image starts faster still, but it is a different build with different rules.