-
CSR
-
Resolution: Approved
-
P4
-
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
- csr of
-
JDK-8177352 Calendar.getDisplayName(s) in non-lenient mode inconsistent, does not match spec
- Resolved