RFR: 8368856: Add methods for saturating Duration arithmetic to Instant [v7]

[Roger Riggs]

On Wed, 8 Oct 2025 19:59:17 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/java.base/share/classes/java/time/Instant.java line 814:
>> 
>>> 812:                     ? this.plus(duration) : Instant.MAX;
>>> 813:         }
>>> 814:     }
>> 
>> Can this be generalized to work across Temporals? To allow expansion later.
>> Addi a default method to the Temporal interface for `plusSaturating(TemporalAmount amount)`.
>> The default method can throw Unsupported Exception.
>> The override in Instant can be implemented as above and throw UnsupportedTemporalType for all other temporalAmounts.
>> The javadoc can use Duration for the example.
>> This would allow more types to consistently support saturating arithmetic.
>
> It sure can be generalised like you said. The question is how useful that would be as far as the main use case is concerned.
> 
> Also, `java.time` is a kind of API that makes it hard to tell if a particular call would work unless you know the exact types of the receiver and the arguments. Having a method that throws an exception for everything but one particular type of the receiver and the argument -- even if temporarily -- can be confusing. (I've done my fair share of attempts to add a `Period` to an `Instant`.) But we can try, experiment, and see what happens.

A Period with only day units *can* be added to an Instant.  (Because the day can be converted to seconds).

jshell> import java.time.*
jshell> var i = Instant.now()
i ==> 2025-10-08T20:02:15.231622Z
jshell> var p = Period.of(0,0,1)
p ==> P1D
jshell> i.plus(p)
$4 ==> 2025-10-09T20:02:15.231622Z

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

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