Summary

Update the javadoc of numerous methods in java.util.Calendar to declare missing exceptions, namely, ArrayIndexOutOfBoundsException and IllegalArgumentException.

Problem

Many java.util.Calendar methods that take in an int field parameter should throw an ArrayIndexOutOfBoundsException if field is not between 0 and Calendar.FIELD_COUNT.

In addition, the methods Calendar.add(int field, int amount), Calendar.roll(int field, int amount), and Calendar.roll(int field, boolean up), should throw IllegalArgumentException if the Calendar is non lenient and any value has an out of range value or if field is Calendar.ZONE_OFFSET, Calendar.DST_OFFSET, or unknown.

Solution

The following methods in java.util.Calendar should have documentation updated:

get(int) throws IllegalArgumentException if the calendar is non-lenient, and any fields have an out of range value.

set(int,int) does not need to be non-lenient to throw ArrayIndexOutOfBoundsException for an invalid field index.

internalGet(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

internalSet(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

clear(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

isSet(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

add(int, int) throws IllegalArgumentException with an invalid field index or if any field has an out-of-range value in non lenient.

roll(int,boolean) and roll(int,int) throw IllegalArgumentException with an invalid field index or if any field has an out-of-range value in non lenient.

getMaximum(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

getMinimum(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

getGreatestMinimum(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

getLeastMaximum(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

getActualMaximum(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

getActualMinimum(int) throws ArrayIndexOutOfBoundsException with an invalid field index.

Specification

--- a/src/java.base/share/classes/java/util/Calendar.java
+++ b/src/java.base/share/classes/java/util/Calendar.java
@@ -1840,7 +1840,9 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      * @param field the given calendar field.
      * @return the value for the given calendar field.
      * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
-     *             (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
+     * @throws IllegalArgumentException if this {@code Calendar} is non-lenient and any
+     * of the calendar fields have invalid values.
      * @see #set(int,int)
      * @see #complete()
      */
@@ -1856,6 +1858,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param field the given calendar field.
      * @return the value for the given calendar field.
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #get(int)
      */
     protected final int internalGet(int field)
@@ -1868,8 +1872,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      * not affect any setting state of the field in this
      * {@code Calendar} instance.
      *
-     * @throws IndexOutOfBoundsException if the specified field is out of range
-     *             (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #areFieldsSet
      * @see #isTimeSet
      * @see #areAllFieldsSet
@@ -1887,8 +1891,7 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      * @param field the given calendar field.
      * @param value the value to be set for the given calendar field.
      * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
-     *             (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
-     * in non-lenient mode.
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #set(int,int,int)
      * @see #set(int,int,int,int,int)
      * @see #set(int,int,int,int,int,int)
@@ -2030,6 +2033,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      * value.
      *
      * @param field the calendar field to be cleared.
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #clear()
      */
     public final void clear(int field)
@@ -2049,6 +2054,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param field the calendar field to test
      * @return {@code true} if the given calendar field has a value set;
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * {@code false} otherwise.
      */
     public final boolean isSet(int field)
@@ -2801,6 +2808,9 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param field the calendar field.
      * @param amount the amount of date or time to be added to the field.
+     * @throws IllegalArgumentException if this {@code Calendar} is non-lenient
+     * and any of the calendar fields have invalid values or if {@code field} is
+     * {@code ZONE_OFFSET}, {@code DST_OFFSET}, or unknown.
      * @see #roll(int,int)
      * @see #set(int,int)
      */
@@ -2823,6 +2833,9 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      * @param field the time field.
      * @param up indicates if the value of the specified time field is to be
      * rolled up or rolled down. Use true if rolling up, false otherwise.
+     * @throws IllegalArgumentException if this {@code Calendar} is non-lenient
+     * and any of the calendar fields have invalid values or if {@code field} is
+     * {@code ZONE_OFFSET}, {@code DST_OFFSET}, or unknown.
      * @see Calendar#add(int,int)
      * @see Calendar#set(int,int)
      */
@@ -2842,6 +2855,9 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param field the calendar field.
      * @param amount the signed amount to add to the calendar {@code field}.
+     * @throws IllegalArgumentException if this {@code Calendar} is non-lenient
+     * and any of the calendar fields have invalid values or if {@code field} is
+     * {@code ZONE_OFFSET}, {@code DST_OFFSET}, or unknown.
      * @since 1.2
      * @see #roll(int,boolean)
      * @see #add(int,int)
@@ -3107,6 +3123,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param field the calendar field.
      * @return the minimum value for the given calendar field.
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #getMaximum(int)
      * @see #getGreatestMinimum(int)
      * @see #getLeastMaximum(int)
@@ -3124,6 +3142,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param field the calendar field.
      * @return the maximum value for the given calendar field.
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #getMinimum(int)
      * @see #getGreatestMinimum(int)
      * @see #getLeastMaximum(int)
@@ -3142,6 +3162,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param field the calendar field.
      * @return the highest minimum value for the given calendar field.
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #getMinimum(int)
      * @see #getMaximum(int)
      * @see #getLeastMaximum(int)
@@ -3164,6 +3186,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param field the calendar field.
      * @return the lowest maximum value for the given calendar field.
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #getMinimum(int)
      * @see #getMaximum(int)
      * @see #getGreatestMinimum(int)
@@ -3185,6 +3209,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      * @param field the calendar field
      * @return the minimum of the given calendar field for the time
      * value of this {@code Calendar}
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #getMinimum(int)
      * @see #getMaximum(int)
      * @see #getGreatestMinimum(int)
@@ -3239,6 +3265,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      * @param field the calendar field
      * @return the maximum of the given calendar field for the time
      * value of this {@code Calendar}
+     * @throws ArrayIndexOutOfBoundsException if the specified field is out of range
+     * (<code>field &lt; 0 || field &gt;= FIELD_COUNT</code>).
      * @see #getMinimum(int)
      * @see #getMaximum(int)
      * @see #getGreatestMinimum(int)