Clarification to TimeUnit.convert(Duration)

[Pavel Rappo]

It's not really a specification, as it's @apiNote. IMO, referring to
specific methods is good, it aids quick grasping of the idea. No
matter what method Duration might have later, e.g. toMicros(), any
sub-second conversion method can overflow. Maybe we can say that and
add a few examples of the conversion methods that do?

On Tue, Oct 14, 2025 at 10:44 PM Chen Liang <chen.l.liang at oracle.com> wrote:
>
> Hi Pavel,
>
> I don't think specifying the enum constants is particularly meaningful - maybe future constants also have overflowing operations. Wording like "conversion methods on Duration" instead of just toNanos/toMillis would be more helpful though.
>
> Chen
> ________________________________
> From: concurrency-discuss <concurrency-discuss-retn at openjdk.org> on behalf of Pavel Rappo <pavel.rappo at gmail.com>
> Sent: Monday, October 13, 2025 10:11 AM
> To: concurrency-discuss at openjdk.org <concurrency-discuss at openjdk.org>
> Subject: Re: Clarification to TimeUnit.convert(Duration)
>
> ping
>
> On Fri, Oct 3, 2025 at 9:54 PM Pavel Rappo <pavel.rappo at gmail.com> wrote:
> >
> > TimeUnit.covert(Duration)'s receiver is an enum constant. Different
> > constants result in different converstions. So, it's a bit vague to
> > contrast "this method" to a specific conversion (in this case,
> > nanoseconds). Would this small clarification benefit the reader? If
> > so, I could create a PR.
> >
> > diff --git a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
> > b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
> > index d116fb9b22b..6135461cf48 100644
> > --- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
> > +++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
> > @@ -203,8 +203,11 @@ public long convert(long sourceDuration, TimeUnit
> > sourceUnit) {
> >       * is equivalent to {@code n} (in the absence of overflow).
> >       *
> >       * @apiNote
> > -     * This method differs from {@link Duration#toNanos()} in that it
> > -     * does not throw {@link ArithmeticException} on numeric overflow.
> > +     * {@link #NANOSECONDS}{@code .convert(Duration)} and
> > +     * {@link #MILLISECONDS}{@code .convert(Duration)} differ from
> > +     * {@link Duration#toNanos()} and {@link Duration#toMillis()} respectively
> > +     * in that they do not throw {@link ArithmeticException} on numeric
> > +     * overflow.
> >       *
> >       * @param duration the time duration
> >       * @return the converted duration in this unit,