RFR: 8177418: NPE is not apparent for methods in java.util.TimeZone API docs [v8]

[Justin Lu]

On Wed, 25 Jan 2023 20:21:11 GMT, Justin Lu <jlu at openjdk.org> wrote:

>> When their input is null, the following methods in java.util.TimeZone throw a NullPointerException:
>> 
>> _TimeZone.getTimeZone(String ID)
>> TimeZone.setID(String ID)
>> TimeZone.inDaylightTime(Date date)_
>> 
>> For example, 
>> 
>> 
>> String someID = null;
>> TimeZone tz1 = TimeZone.getTimeZone(someID);
>> ``` 
>> 
>> throws a `NullPointerException`
>> 
>> 
>> This PR adds the missing  _ at throws:_ for the mentioned methods. The wording and specification is also adjusted for the overridable methods in TZ to use "_may throw_" over "_will throw_" because of the possibility of external sub-classes that may override the method.
>
> Justin Lu has updated the pull request incrementally with one additional commit since the last revision:
> 
>   STZ.inDT can also be overriden

The CSR has been approved and all the methods have been updated with the following specifications


- (Overridden) Instance methods **may** throw an NPE and (via implSpec) the particular method **will** indeed throw an NPE: _TimeZone.getDisplayName(boolean daylight, int style, Locale locale), TimeZone.setID(String ID), SimpleTimeZone.inDaylightTime(Date date)_
- (Overridden) Abstract methods **may** throw an NPE: _TimeZone.inDaylightTime(Date date)_
-  Static methods **will** throw an NPE: _Timezone.getTimeZone(String ID)_


Will "/integrate" once approved.

-------------

PR: https://git.openjdk.org/jdk/pull/11888