Summary

This API was first previewed in JDK 25 via JEP 502: Stable Values. Based on experience and feedback, we propose to rename and simplify the API.

Problem

The design goal of the StableValue API was to provide a safe wrapper around @Stable VM fields. While the API we previewed successfully met that goal, experience with the API revealed that the imperative methods of the StableValue API, such as StableValue::trySet are hard to use correctly. In addition, overwhelmingly common use cases (such as creating a stable value from a lambda expressions) were pushed out to ancillary APIs (such as caching suppliers) with limited discoverability.

Solution

The following actions are proposed:

• Re-orient the API to focus on high-level use cases, removing the low-level methods orElseSet, setOrThrow, and trySet, leaving only factory methods that take value-computing functions.

• Rename the API from StableValue to LazyConstant. The former was appropriate for a low-level API that was close to the underlying JVM mechanism upon which it is implemented; the latter better captures the primary intended high-level use case, namely that of a single constant value that is initialized lazily.

• Enhance discoverability by moving the factory methods for lazy lists and maps into the java.util.List and java.util.Map interfaces, respectively.

• Further simplify the API by removing the function and intFunction factory methods, which provided only marginal benefits over lazy lists and maps.

• Disallow null as a computed value in order to improve performance and better align lazy constants with constructs such as unmodifiable collections and ScopedValue.

Specification

See attachment.