Summary

Update the specification of the MessageFormat constructor that takes locale as input and the instance format() methods to make an NPE apparent when locale is null.

Problem

Currently, the javadoc of MessageFormat(String pattern, Locale locale) makes no mention of an NPE if locale is null. However, if locale is null, there is a possibility for an NPE to be thrown in two scenarios which ultimately depend on subformats that are used by MessageFormat. First, during the object creation of the MessageFormat itself through the invocation of the applyPattern(pattern) method. Second, during a future call of format() by the MessageFormat instance that was created with the null locale. Regarding the second scenario, the null locale can either be set by through the constructor, or by calling setLocale(null) as well.

An associated PR is already filed with a test that has examples of both scenarios.

Solution

Both the MessageFormat constructor that takes locale as an argument, and the format() methods that may be affected should document the potential NPE. That is, it should be explicitly stated that if locale is null, an NPE will be thrown if a locale-dependent subformat is utilized by the implementation.

Specification

--- a/src/java.base/share/classes/java/text/MessageFormat.java
+++ b/src/java.base/share/classes/java/text/MessageFormat.java
@@ -390,11 +390,18 {
      * Patterns and their interpretation are specified in the
      * <a href="#patterns">class description</a>.
      *
+     * @implSpec The default implementation throws a
+     * {@code NullPointerException} if {@code locale} is {@code null}
+     * either during the creation of the {@code MessageFormat} object or later
+     * when {@code format()} is called by a {@code MessageFormat}
+     * instance with a null locale and the implementation utilizes a locale-dependent subformat.
+     *
      * @param pattern the pattern for this message format
      * @param locale the locale for this message format
      * @throws    IllegalArgumentException if the pattern is invalid
      * @throws    NullPointerException if {@code pattern} is
-     *            {@code null}
+     *            {@code null} or {@code locale} is {@code null} and the
+     *            implementation uses a locale-dependent subformat.
      * @since 1.4
      */
     public MessageFormat(String pattern, Locale locale) {
@@ -843,7 +850,10 {
      * @throws    IllegalArgumentException if an argument in the
      *            {@code arguments} array is not of the type
      *            expected by the format element(s) that use it.
-     * @throws    NullPointerException if {@code result} is {@code null}
+     * @throws    NullPointerException if {@code result} is {@code null} or
+     *            if the {@code MessageFormat} instance that calls this method
+     *            has locale set to null, and the implementation
+     *            uses a locale-dependent subformat.
      */
     public final StringBuffer format(Object[] arguments, StringBuffer result,
                                      FieldPosition pos)
@@ -889,7 +899,10 {
      * @throws    IllegalArgumentException if an argument in the
      *            {@code arguments} array is not of the type
      *            expected by the format element(s) that use it.
-     * @throws    NullPointerException if {@code result} is {@code null}
+     * @throws    NullPointerException if {@code result} is {@code null} or
+     *            if the {@code MessageFormat} instance that calls this method
+     *            has locale set to null, and the implementation
+     *            uses a locale-dependent subformat.
      */
     public final StringBuffer format(Object arguments, StringBuffer result,
                                     FieldPosition pos)