Summary

Update the javadoc of the class description and 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.

In both of these instances, these exceptions are not documented properly.

Solution

Part1)

The following methods in java.util.Calendar may throw an ArrayIndexOutOfBoundsException (which is not documented): internalGet(int), clear(int), isSet(int), getMaximum(int), getMinimum(int), getGreatestMinimum(int), getLeastMaximum(int), getActualMaximum(int), getActualMinimum(int).

Instead of adding "@throws ArrayIndexOutOfBoundsException ..." to each method description, java.util.Calendar should have a clause in the class description stating that any methods taking int field will throw an ArrayIndexOutOfBoundsException if field is out of range.

For consistency, the existing methods that already throw an ArrayIndexOutOfBoundsException in their method description should have the exception undocumented: get(int), internalSet(int), set(int).

Part 2)

Additionally, 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.

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.

Specification

--- a/src/java.base/share/classes/java/util/Calendar.java
+++ b/src/java.base/share/classes/java/util/Calendar.java
@@ -105,6 +105,10
  * <h2>Getting and Setting Calendar Field Values</h2>
  * 
  * <p>The calendar field values can be set by calling the {@code set}
  * methods. Any field values set in a {@code Calendar} will not be
  * interpreted until it needs to calculate its time value (milliseconds from
  * the Epoch) or values of the calendar fields. Calling the
  * {@code get}, {@code getTimeInMillis}, {@code getTime},
  * {@code add} and {@code roll} involves such calculation.
+ * Unless otherwise specified, any {@code Calendar} method containing the
+ * parameter {@code int field} will throw an {@code ArrayIndexOutOfBoundsException}
+ * if the specified field is out of range ({@code field} &lt; 0 ||
+ * {@code field} &gt;= {@link #FIELD_COUNT}).
  *

@@ -1839,8 +1843,8
      *
      * @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>).
+     * @throws IllegalArgumentException if this {@code Calendar} is non-lenient and any
+     * of the calendar fields have invalid values.
      * @see #set(int,int)
      * @see #complete()
      */
      public int get(int field)

@@ -1868,8 +1872,6
      * 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>).
      * @see #areFieldsSet
      * @see #isTimeSet
      * @see #areAllFieldsSet
      * @see #set(int,int)
      */
      final void internalSet(int field, int value)

@@ -1886,9 +1888,6
      *
      * @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.
      * @see #set(int,int,int)
      * @see #set(int,int,int,int,int)
      * @see #set(int,int,int,int,int,int)
      * @see #get(int)
      */
      public void set(int field, int value)

@@ -2801,6 +2800,9
      *
      * @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)
      */
      public abstract void add(int field, int amount);

@@ -2823,6 +2825,9
      * @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)
      */
      public abstract void roll(int field, boolean up);

@@ -2842,6 +2847,9
      *
      * @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)
      * @see #set(int,int)
      */
      public void roll(int field, int amount)