Summary

Some methods in the java.time.chrono interfaces (ChronoLocalDate, ChronoLocalDateTime, ChronoZonedDateTime) override methods from java.time.temporal.Temporal that may throw UnsupportedTemporalTypeException, but they do not document this exception in their Javadoc.

Problem

Overridden methods in interfaces (ChronoLocalDate, ChronoLocalDateTime, ChronoZonedDateTime)

• with(TemporalField, long)

• plus(long, TemporalUnit)

• minus(long, TemporalUnit)

can throw UnsupportedTemporalTypeException if the field or unit is not supported.

However, the corresponding Javadoc does not mention this exception, leading to incomplete documentation. Although the parent interface (java.time.temporal.Temporal) properly documents it.

Solution

Update the Javadoc of these methods in the affected interfaces to include the missing exception.

Specification

Github reference: https://github.com/openjdk/jdk/pull/25836/files

Attached doc difference generated with apidiff: doc_diff.zip

In ChronoLocalDate:

/**
 * {@inheritDoc}
 * @throws DateTimeException {@inheritDoc}
 * @throws UnsupportedTemporalTypeException {@inheritDoc}  // <--- ADDED
 * @throws ArithmeticException {@inheritDoc}
 */
@Override
default ChronoLocalDate plus(long amountToAdd, TemporalUnit unit) {
    if (unit instanceof ChronoUnit) {
        throw new UnsupportedTemporalTypeException("Unsupported unit: " + unit);
    }
    return ChronoLocalDateImpl.ensureValid(getChronology(), unit.addTo(this, amountToAdd));
}

In ChronoLocalDateTime:

   /**
     * {@inheritDoc}
     * @throws DateTimeException {@inheritDoc}
     * @throws UnsupportedTemporalTypeException {@inheritDoc} // <--- ADDED
     * @throws ArithmeticException {@inheritDoc}
     */
    @Override
    ChronoLocalDateTime<D> with(TemporalField field, long newValue);

   /**
     * {@inheritDoc}
     * @throws DateTimeException {@inheritDoc}
     * @throws UnsupportedTemporalTypeException {@inheritDoc} // <--- ADDED
     * @throws ArithmeticException {@inheritDoc}
     */
    @Override
    ChronoLocalDateTime<D> plus(long amountToAdd, TemporalUnit unit);

   /**
     * {@inheritDoc}
     * @throws DateTimeException {@inheritDoc}
     * @throws UnsupportedTemporalTypeException {@inheritDoc} // <--- ADDED
     * @throws ArithmeticException {@inheritDoc}
     */
    @Override
    default ChronoLocalDateTime<D> minus(long amountToSubtract, TemporalUnit unit) {
        return ChronoLocalDateTimeImpl.ensureValid(getChronology(), Temporal.super.minus(amountToSubtract, unit));
    }

In ChronoZonedDateTime:

   /**
     * {@inheritDoc}
     * @throws DateTimeException {@inheritDoc}
     * @throws UnsupportedTemporalTypeException {@inheritDoc} // <--- ADDED
     * @throws ArithmeticException {@inheritDoc}
     */
    @Override
    ChronoZonedDateTime<D> with(TemporalField field, long newValue);

   /**
     * {@inheritDoc}
     * @throws DateTimeException {@inheritDoc}
     * @throws UnsupportedTemporalTypeException {@inheritDoc} // <--- ADDED
     * @throws ArithmeticException {@inheritDoc}
     */
    @Override
    ChronoZonedDateTime<D> plus(long amountToAdd, TemporalUnit unit);

   /**
     * {@inheritDoc}
     * @throws DateTimeException {@inheritDoc}
     * @throws UnsupportedTemporalTypeException {@inheritDoc} // <--- ADDED
     * @throws ArithmeticException {@inheritDoc}
     */
    @Override
    default ChronoZonedDateTime<D> minus(long amountToSubtract, TemporalUnit unit) {
        return ChronoZonedDateTimeImpl.ensureValid(getChronology(), Temporal.super.minus(amountToSubtract, unit));
    }