RFR: 8366829: Add constants for the Duration MIN/MAX values [v2]

[Pavel Rappo]

On Tue, 30 Sep 2025 18:51:17 GMT, Stephen Colebourne <scolebourne at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Update copyright years
>>    
>>    Note: any commit hashes below might be outdated due to subsequent
>>    history rewriting (e.g. git rebase).
>>    
>>     + update src/java.base/share/classes/java/time/temporal/ChronoUnit.java due to 9a54ba1d353
>>     + update test/jdk/java/time/tck/java/time/TCKDuration.java due to 9a54ba1d353
>>  - Provide @apiNote as suggested
>
> src/java.base/share/classes/java/time/Duration.java line 151:
> 
>> 149:      * instant}, as doing so will cause overflow. Extreme care should be taken
>> 150:      * when performing {@code Duration} arithmetic on them, such as adding
>> 151:      * them to or subtracting them from another duration.
> 
> https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/Instant.html#MIN
> 
> Suggestion:
> 
>      * The minimum supported Duration, which is {@code Long.MIN_VALUE} seconds.
>      *
>      * @apiNote This constant represents the smallest possible instance of {@code Duration}.
>      * Since Durations are directed, the smallest possible duration is negative.
>      * <p>
>      * The constant is intended to be used as a sentinel value, such as in
>      * comparisons and tests. Care should be taken when performing arithmetic
>      * on {@code MIN} as there is a high risk that {@code ArithmeticException}
>      * will be thrown.
> 
> 
> Similar for MAX. But it can repeat the class header comment about being longer than the age of the universe,

> Care should be taken when performing arithmetic on `MIN` as there is a high risk that `ArithmeticException` will be thrown.

It's a bit less specific than what I had. I also note that aside from `ArithmeticException`, `DateTimeException` might be thrown too. The former is thrown for long overflow, while the latter is for exceeding `Instant` boundaries.

@RogerRiggs, @naotoj any comments for this suggestion from @jodastephen?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/27534#discussion_r2392595410