RFR: 8368856: Add a method that performs saturating addition of a Duration to an Instant [v8]

[Naoto Sato]

On Mon, 13 Oct 2025 21:12:40 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> We recently [discussed] the possibility of introducing saturating arithmetic for deadline computation. Consider this PR as a starting point. Once we agree on the implementation, I'll file a CSR.
>> 
>> I created a method in `Instant` to add `Duration`. One could argue that the proper way would be to go all the way and create a method in `Temporal` to add `TemporalAmount`. Or maybe even expand the functionality, and create an additional method in `Temporal` to subtract `TemporalAmount`.
>> 
>> My current thinking is that if we were to do that, there would be a lot of expensive, unused code. Saturating logic seems to be only useful for `Instant` and `Duration`.
>> 
>> Even if we decide to extend `Temporal` to add/subtract `TemporalAmount`, it could always be done later. From the perspective of `Instant`, `plus(TemporalAmount)` will be just an overload of `plus(Duration)`.
>> 
>> [discussed]: https://mail.openjdk.org/pipermail/core-libs-dev/2025-September/151098.html
>
> Pavel Rappo has updated the pull request incrementally with four additional commits since the last revision:
> 
>  - Simplify impl
>  - Clarify spec
>  - Revert "Add Instant.minusSaturating(Duration)"
>    
>    This reverts commit 35537856f1759c7abbe2b5c5bbb267a90612f729.
>  - Add test for null

src/java.base/share/classes/java/time/Instant.java line 797:

> 795:      * If the result is "earlier" than {@link Instant#MIN}, this method returns
> 796:      * {@code MIN}. If the result is "later" than {@link Instant#MAX}, it
> 797:      * returns {@code MAX}. Otherwise it returns {@code this.}{@link #plus plus(duration)}.

Since there are multiple overloaded methods for `plus`, It'd be safer to specify argument to the method reference `#plus`. (It seems to work as `plus(TemporalAmount)` is the first candidate)

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/27549#discussion_r2433512742