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

[Pavel Rappo]

On Wed, 8 Oct 2025 18:17:39 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fix copy-paste typos
>
> 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.

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

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