Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8304371

Calendar.getDisplayName(s) in non-lenient mode inconsistent, does not match spec

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P4 P4
    • 21
    • core-libs
    • None
    • behavioral
    • minimal
    • The proposed change updates the Javadoc to reflect actual behavior, there is no change towards the implementation.
    • Java API
    • SE

      Summary

      Update the javadoc of java.util.Calendar.getDisplayName() and java.util.Calendar.getDisplayNames() to better reflect the actual behavior when the calendar is non-lenient.

      Problem

      java.util.Calendar.getDisplayNames(int field, int style, Locale locale) claims to throw an IllegalArgumentException, if the Calendar is in non-lenient mode, and any of the fields have an invalid value but does not.

      java.util.Calendar.getDisplayName(int field, int style, Locale locale) claims to throw an IllegalArgumentException if the Calendar is in non-lenient mode, and any of the fields have an invalid value. However, if any of the calendar fields have an invalid value and the field parameter is set to one that does not have a string representation, null will be returned instead of an IllegalArgumentException being thrown.

      Solution

      java.util.Calendar.getDisplayNames(int field, int style, Locale locale) should remove "or if this {@code Calendar} is non-lenient and any of the calendar fields have invalid values" from "it's "@throws IllegalArgumentException..". In addition, this distinction should be made clear between the similar methods.

      java.util.Calendar.getDisplayName(int field, int style, Locale locale) should include additional information that describes the behavior if both the conditions for returning null and throwing an IllegalArgumentException are true.

      Specification

      --- a/src/java.base/share/classes/java/util/Calendar.java
      +++ b/src/java.base/share/classes/java/util/Calendar.java
      @@ -2077,6 +2077,14 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
            * which a {@link DateFormatSymbols} has names in the given
            * {@code locale}.
            *
      +     * <p>If there is no string representation of the {@code Calendar} {@code field}
      +     * and the calendar is in non-lenient mode and any calendar fields have invalid values,
      +     * {@code null} is returned. If there is a string representation of the {@code Calendar}
      +     * {@code field} and the calendar is in non-lenient mode and any calendar fields
      +     * have invalid values, {@code IllegalArgumentException} will be thrown.
            *
            * @param field
            *        the calendar field for which the string representation
            *        is returned
      @@ -2170,6 +2178,10 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
            * all strings returned by {@link DateFormatSymbols#getShortMonths()}
            * and {@link DateFormatSymbols#getMonths()}.
            *
      +     * <p> Unlike {@link #getDisplayName(int, int, Locale)}, this
      +     * method will not throw an {@code IllegalArgumentException} if the
      +     * {@code Calendar} is non-lenient and any of the calendar fields have
      +     * invalid values. Instead, this method will return either {@code null} or
      +     * a {@code Map}.
            *
            * @param field
            *        the calendar field for which the display names are returned
            * @param style
      @@ -2184,9 +2196,7 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
            *        field values, or {@code null} if no display names
            *        are defined for {@code field}
            * @throws    IllegalArgumentException
      -     *        if {@code field} or {@code style} is invalid,
      -     *        or if this {@code Calendar} is non-lenient and any
      -     *        of the calendar fields have invalid values
      +     *        if {@code field} or {@code style} is invalid
            * @throws    NullPointerException
            *        if {@code locale} is null
            * @since 1.6

            jlu Justin Lu
            martin Martin Buchholz
            Naoto Sato
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: