Summary

Update the javadoc for the methods: getTimeZone(String ID), setID(String ID), getDisplayName(boolean daylight, int style, Locale locale), and inDaylightTime(Date date) in java.util.TimeZone. Additionally, update the javadoc for inDaylightTime(Date date) in java.util.SimpleTimeZone.

Problem

TimeZone.getTimeZone(String ID), TimeZone.setID(String ID), TimeZone.inDaylightTime(Date date), and SimpleTimeZone.inDaylightTime(Date date) all throw a NullPointerException if their input is null, however this is not apparent in the javadoc in the form of a throws: section.

Solution

The mentioned methods will be updated to make their exceptions apparent. Abstract methods may throw an NPE, instance methods may throw an NPE paired with @ImplSpec which states the particular method will throw an NPE, and static methods will throw an NPE.

Specification

--- a/src/java.base/share/classes/java/util/SimpleTimeZone.java
+++ b/src/java.base/share/classes/java/util/SimpleTimeZone.java
@@ -841,6 +841,7 @@ public class SimpleTimeZone extends TimeZone {
     /**
      * Queries if the given date is in daylight saving time.
+     * @implSpec The default implementation throws a
+     * {@code NullPointerException} if {@code date} is {@code null}
      * @return true if daylight saving time is in effective at the
      * given date; false otherwise.
+     * @throws NullPointerException This method may throw a
+     * {@code NullPointerException} if {@code date} is {@code null}
      */
     public boolean inDaylightTime(Date date)
     {

--- a/src/java.base/share/classes/java/util/TimeZone.java
+++ b/src/java.base/share/classes/java/util/TimeZone.java
@@ -293,7 +293,11 @@ public abstract class TimeZone implements Serializable, Cloneable {
     /**
      * Sets the time zone ID. This does not change any other data in
      * the time zone object.
+     * @implSpec The default implementation throws a
+     * {@code NullPointerException} if {@code ID} is {@code null}
      * @param ID the new time zone ID.
+     * @throws NullPointerException This method may throw a
+     * {@code NullPointerException} if {@code ID} is {@code null}
      */
     public void setID(String ID)
     {
@@ -391,13 +395,18 @@ public abstract class TimeZone implements Serializable, Cloneable {
      * found, the name is returned. Otherwise, a string in the
      * <a href="#NormalizedCustomID">normalized custom ID format</a> is returned.
      *
+     * @implSpec The default implementation throws an
+     * {@code IllegalArgumentException} if {@code style} is invalid or a
+     * {@code NullPointerException} if {@code ID} is {@code null}.
      * @param daylight {@code true} specifying a Daylight Saving Time name, or
      *                 {@code false} specifying a Standard Time name
      * @param style either {@link #LONG} or {@link #SHORT}
      * @param locale   the locale in which to supply the display name.
      * @return the human-readable name of this time zone in the given locale.
-     * @throws    IllegalArgumentException if {@code style} is invalid.
-     * @throws    NullPointerException if {@code locale} is {@code null}.
+     * @throws IllegalArgumentException This method may throw an
+     * {@code IllegalArgumentException} if {@code style} is invalid.
+     * @throws NullPointerException This method may throw a
+     * {@code NullPointerException} if {@code ID} is {@code null}
      * @since 1.2
      * @see java.text.DateFormatSymbols#getZoneStrings()
      */
     public String getDisplayName(boolean daylight, int style, Locale locale) {
@@ -507,6 +516,8 @@ public abstract class TimeZone implements Serializable, Cloneable {
      * @param date the given Date.
      * @return {@code true} if the given date is in Daylight Saving Time,
      *         {@code false}, otherwise.
+     * @throws NullPointerException This method may throw a
+     * {@code NullPointerException} if {@code date} is {@code null}
      */
     public abstract boolean inDaylightTime(Date date);

@@ -520,6 +531,7 @@ public abstract class TimeZone implements Serializable, Cloneable {
      *
      * @return the specified {@code TimeZone}, or the GMT zone if the given ID
      * cannot be understood.
+     * @throws NullPointerException if {@code ID} is {@code null}
      */
     public static synchronized TimeZone getTimeZone(String ID) {
         return getTimeZone(ID, true);