Summary

Certain Calendar.getInstance() methods and GregorianCalendar constructors need to document possible NullPointerExceptions in their Javadoc.

Problem

The Calendar.getInstance() methods and the GregorianCalendar constructors that take TimeZone or Locale throw NullPointerException if the input is null, which is not listed in the javadoc.

Solution

Update the javadoc of the Calendar.getInstance() methods and the GregorianCalendar constructors that take TimeZone or Locale to document potential NullPointerExceptions using the @throws tag.

Specification

--- a/src/java.base/share/classes/java/util/Calendar.java
+++ b/src/java.base/share/classes/java/util/Calendar.java
@@ -1632,6 +1632,7 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param zone the time zone to use
      * @return a Calendar.
+     * @throws NullPointerException if {@code zone} is {@code null}
      */
     public static Calendar getInstance(TimeZone zone)
     {
@@ -1649,6 +1650,7 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      *
      * @param aLocale the locale for the week data
      * @return a Calendar.
+     * @throws NullPointerException if {@code aLocale} is {@code null}
      */
     public static Calendar getInstance(Locale aLocale)
     {
@@ -1663,6 +1665,8 @@ public abstract class Calendar implements Serializable, Cloneable, Comparable<Ca
      * @param zone the time zone to use
      * @param aLocale the locale for the week data
      * @return a Calendar.
+     * @throws NullPointerException if {@code zone} or (@code aLocale}
+     * is {@code null}
      */
     public static Calendar getInstance(TimeZone zone,
                                        Locale aLocale)

--- a/src/java.base/share/classes/java/util/GregorianCalendar.java
+++ b/src/java.base/share/classes/java/util/GregorianCalendar.java
@@ -599,6 +599,7 @@ public class GregorianCalendar extends Calendar {
      * {@link Locale.Category#FORMAT FORMAT} locale.
      *
      * @param zone the given time zone.
+     * @throws NullPointerException if {@code zone} is {@code null}
      */
     public GregorianCalendar(TimeZone zone) {
         this(zone, Locale.getDefault(Locale.Category.FORMAT));
@@ -609,6 +610,7 @@ public class GregorianCalendar extends Calendar {
      * in the default time zone with the given locale.
      *
      * @param aLocale the given locale.
+     * @throws NullPointerException if {@code aLocale} is {@code null}
      */
     public GregorianCalendar(Locale aLocale) {
         this(TimeZone.getDefaultRef(), aLocale);
@@ -621,6 +623,8 @@ public class GregorianCalendar extends Calendar {
      *
      * @param zone the given time zone.
      * @param aLocale the given locale.
+     * @throws NullPointerException if {@code zone} or (@code aLocale}
+     * is {@code null}
      */
     public GregorianCalendar(TimeZone zone, Locale aLocale) {
         super(zone, aLocale);