Lazy Constants in Java

1. Overview

In this tutorial, we’ll provide an overview of JEP 526. While this preview API was first introduced under the name “Stable Values” in Java 25 (JEP 502), it has now been renamed “Lazy Constants” as of Java 26, with some minor API adjustments. Note that in order to make use of Lazy Constants, we must enable preview features when compiling and running our program.

2. Understanding the Problem

As Java developers, we constantly balance the trade-offs associated with making our fields final.

On one hand, final instance fields are a requirement in order to make our classes immutable, which helps promote cleaner and more robust code. In addition, the JVM compilers, javac and JIT, will consider certain final fields when making constant fold optimizations. This eliminates unnecessary computation from our compiled code by simplifying/computing constant expressions ahead of time.

However, there’s a major limitation to using final fields. We must initialize a final field immediately. This is problematic if the field is expensive to create.

Let’s pretend we have an immutable class with an expensive object:

class ImmutableClass {
 
    private final ExpensiveObject expensiveObject = new ExpensiveObject(); 
    
    public ImmutableClass() {}
    
    void methodThatUsesInstanceField() {
        // logic that uses instance field
    }
}

We can see that upon instantiation of our class, we’ll incur the cost of initializing the expensiveObject field immediately. Alternatively, if this were a static field, we’d incur this cost at class loading time instead:

static final ExpensiveObject expensiveObject = new ExpensiveObject();

Incurring initialization costs ahead of time can result in long start-ups for Java applications. Ideally, we want to push these initialization costs until we actually need to use these fields. One way to achieve this would be to drop the final modifier, allowing us to set the field at a later point (typically immediately prior to use). However, such an approach isn’t thread-safe.

Instead, the Lazy Constants API offers a solution by providing “deferred immutability”.

3. What’s a LazyConstant?

A LazyConstant (formerly StableValue) acts as a wrapper around a field, which we refer to as its contents. This field is annotated with @Stable (an internal JDK annotation), guaranteeing that it’ll be initialized at most once during its lifecycle, even under concurrency in a multi-threaded environment.

As a result of this guarantee and as long as a LazyConstant field is final, the JVM can make constant fold optimizations in much the same way it does for trusted final fields like those in records. In addition to ensuring that the contents will always point to the same object once initialized, we can also delay this initialization.

3.1. Using the LazyConstant.of() Method to Create an Uninitialized LazyConstant

The Lazy Constants API provides the static factory method LazyConstant.of(Supplier<? extends T> computingFunction) to create an uninitialized LazyConstant: 

LazyConstant<ExpensiveObject> lazyEO = LazyConstant.of(() -> new ExpensiveObject());

Under the hood, the LazyConstant object holds both the provided supplier and a field that will represent its contents. We consider the LazyConstant to be uninitialized as its contents haven’t been set using the provided supplier yet. Thus, invoking the isInitialized() method for the LazyConstant will return false.

3.2. Initializing a LazyConstant

In order to retrieve the contents of a LazyConstant, we can invoke the get() method:

final ExpensiveObject expensiveObject = lazyConstant.get();

If the LazyConstant is uninitialized, the provided supplier is invoked, with the result being used to set its contents, and the contents are then returned, thereby achieving delayed initialization for our expensive object. Note that if the LazyConstant was already initialized, the get() method would simply return its contents.

Applying this to our ImmutableClass, we can maintain its immutability while delaying initialization of our expensive object:

class ImmutableClass {

    private final LazyConstant<ExpensiveObject> lazyEO = LazyConstant.of(() -> new ExpensiveObject());

    void methodThatUsesInstanceField() {
        final ExpensiveObject expensiveObject = lazyEO.get();
        // logic that uses expensiveObject
    }
}

However, what if we had a collection of variables we wanted to delay initialization for? We can achieve this with LazyCollections.

4. Lazy Collections

4.1. Lazy List

The List<E> interface now provides a new static factory method List.ofLazy(int size, IntFunction<? extends E> computingFunction). This method takes two parameters. The first parameter is an int that determines the size of the List. The second parameter is an IntFunction that accepts the index of a certain element to compute its intended value.

Importantly, this computation occurs only when we access an element for the first time. Any subsequent access to that element returns the cached result stored in the contents of a LazyConstant for that particular index. Thus, we can think of a LazyList as a list of LazyConstants. We access the elements through the typical methods of the List interface, such as get(int index).

Let’s say we want to calculate the 5s times table out to a multiple of 10. We could write the code as:

List<Integer> fiveTimesTable = List.of(0 * 5, 1 * 5,..., 10 * 5);

However, let’s pretend that the computation to calculate each multiple is quite expensive. Thus, we want to calculate each element only when it’s first accessed and cached thereafter for future use. We can use a LazyList to achieve this:

@Test
void givenLazyListForFiveTimesTable_thenVerifyElementsAreExpected() {
    List<Integer> fiveTimesTable = List.ofLazy(11, index -> index * 5);
    
    assertThat(fiveTimesTable.get(0)).isEqualTo(0);
    assertThat(fiveTimesTable.get(1)).isEqualTo(5);
    // ...
    assertThat(fiveTimesTable.get(10)).isEqualTo(50);
}

It’s important to note that if we had the following statements instead:

assertThat(fiveTimesTable.get(0)).isEqualTo(0);
assertThat(fiveTimesTable.get(0)).isEqualTo(0); // returns the already-computed value

Then we would only compute the expression 0 * 5 for the first statement.

4.2. Lazy Map

A LazyMap is similar in nature to a LazyList. This time, however, we want to delay the initialization of expensive values for a Set of keys instead. These keys are provided to the static factory method Map.ofLazy(Set<? extends K> keys, Function<? super K, ? extends V> mapper) as well as a mapper function that computes a value for a certain key.

When we access the value for a key for the first time, the function is invoked, initializing a LazyConstant for that key.

Let’s pretend we have a Set of cities and an expensive function that determines what country a particular city resides in:

Set<String> cities = Set.of("London", "Madrid", "Paris");

We can use a LazyMap to ensure we only incur the cost of computing the countries we’re concerned with:

@Test
void givenLazyMapForCityToCountry_thenVerifyValuesAreExpected() {
    Map<String, String> cityToCountry = Map.ofLazy(cities, city -> expensiveMethodToGetCountry(city));

    assertThat(cityToCountry.get("London")).isEqualTo("England");
    assertThat(cityToCountry.get("Madrid")).isEqualTo("Spain");
    assertThat(cityToCountry.get("Paris")).isEqualTo("France");
}

In addition, we’ve also ensured the computation for each value only occurs upon first access.

5. Conclusion

In this article, we explored the purpose of the Lazy Constants API and discussed in depth how we can use higher-level objects built on LazyConstants to address different use cases. Further, these higher-level objects are eligible for constant folding optimizations due to the use of LazyConstants for their internals.