8276186: Require getAvailableLocales() methods to include Locale.ROOT

Reviewed-by: prappo, smarks, iris

Author: naotoj

src/java.base/share/classes/java/text/BreakIterator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -576,8 +576,9 @@ private static BreakIterator createBreakInstance(LocaleProviderAdapter adapter,
      * The returned array represents the union of locales supported by the Java
      * runtime and by installed
      * {@link java.text.spi.BreakIteratorProvider BreakIteratorProvider} implementations.
-     * It must contain at least a {@code Locale}
-     * instance equal to {@link java.util.Locale#US Locale.US}.
+     * At a minimum, the returned array must contain a {@code Locale} instance equal to
+     * {@link Locale#ROOT Locale.ROOT} and a {@code Locale} instance equal to
+     * {@link Locale#US Locale.US}.
      *
      * @return An array of locales for which localized
      *         {@code BreakIterator} instances are available.

src/java.base/share/classes/java/text/Collator.java

@@ -421,8 +421,9 @@ public synchronized void setDecomposition(int decompositionMode) {
      * The returned array represents the union of locales supported
      * by the Java runtime and by installed
      * {@link java.text.spi.CollatorProvider CollatorProvider} implementations.
-     * It must contain at least a Locale instance equal to
-     * {@link java.util.Locale#US Locale.US}.
+     * At a minimum, the returned array must contain a {@code Locale} instance equal to
+     * {@link Locale#ROOT Locale.ROOT} and a {@code Locale} instance equal to
+     * {@link Locale#US Locale.US}.
      *
      * @return An array of locales for which localized
      *         {@code Collator} instances are available.

src/java.base/share/classes/java/text/DateFormat.java

@@ -636,8 +636,9 @@ public static final DateFormat getInstance() {
      * The returned array represents the union of locales supported by the Java
      * runtime and by installed
      * {@link java.text.spi.DateFormatProvider DateFormatProvider} implementations.
-     * It must contain at least a {@code Locale} instance equal to
-     * {@link java.util.Locale#US Locale.US}.
+     * At a minimum, the returned array must contain a {@code Locale} instance equal to
+     * {@link Locale#ROOT Locale.ROOT} and a {@code Locale} instance equal to
+     * {@link Locale#US Locale.US}.
      *
      * @return An array of locales for which localized
      *         {@code DateFormat} instances are available.

src/java.base/share/classes/java/text/DateFormatSymbols.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -299,8 +299,9 @@ private DateFormatSymbols(boolean flag) {
      * The returned array represents the union of locales supported by the
      * Java runtime and by installed
      * {@link java.text.spi.DateFormatSymbolsProvider DateFormatSymbolsProvider}
-     * implementations.  It must contain at least a {@code Locale}
-     * instance equal to {@link java.util.Locale#US Locale.US}.
+     * implementations. At a minimum, the returned array must contain a
+     * {@code Locale} instance equal to {@link Locale#ROOT Locale.ROOT} and
+     * a {@code Locale} instance equal to {@link Locale#US Locale.US}.
      *
      * @return An array of locales for which localized
      *         {@code DateFormatSymbols} instances are available.

src/java.base/share/classes/java/text/DecimalFormatSymbols.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -122,8 +122,9 @@ public DecimalFormatSymbols( Locale locale ) {
      * The returned array represents the union of locales supported by the Java
      * runtime and by installed
      * {@link java.text.spi.DecimalFormatSymbolsProvider DecimalFormatSymbolsProvider}
-     * implementations.  It must contain at least a {@code Locale}
-     * instance equal to {@link java.util.Locale#US Locale.US}.
+     * implementations. At a minimum, the returned array must contain a
+     * {@code Locale} instance equal to {@link Locale#ROOT Locale.ROOT} and
+     * a {@code Locale} instance equal to {@link Locale#US Locale.US}.
      *
      * @return an array of locales for which localized
      *         {@code DecimalFormatSymbols} instances are available.

src/java.base/share/classes/java/text/NumberFormat.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -682,8 +682,9 @@ public static NumberFormat getCompactNumberInstance(Locale locale,
      * The returned array represents the union of locales supported by the Java
      * runtime and by installed
      * {@link java.text.spi.NumberFormatProvider NumberFormatProvider} implementations.
-     * It must contain at least a {@code Locale} instance equal to
-     * {@link java.util.Locale#US Locale.US}.
+     * At a minimum, the returned array must contain a {@code Locale} instance equal to
+     * {@link Locale#ROOT Locale.ROOT} and a {@code Locale} instance equal to
+     * {@link Locale#US Locale.US}.
      *
      * @return An array of locales for which localized
      *         {@code NumberFormat} instances are available.

src/java.base/share/classes/java/time/format/DecimalStyle.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -115,7 +115,9 @@ public final class DecimalStyle {
     /**
      * Lists all the locales that are supported.
      * <p>
-     * The locale 'en_US' will always be present.
+     * At a minimum, the returned {@code Set} must contain a {@code Locale} instance equal to
+     * {@link Locale#ROOT Locale.ROOT} and a {@code Locale} instance equal to
+     * {@link Locale#US Locale.US}.
      *
      * @return a Set of Locales for which localization is supported
      */

src/java.base/share/classes/java/util/Calendar.java

@@ -1730,8 +1730,9 @@ private static Calendar createCalendar(TimeZone zone,
     /**
      * Returns an array of all locales for which the {@code getInstance}
      * methods of this class can return localized instances.
-     * The array returned must contain at least a {@code Locale}
-     * instance equal to {@link java.util.Locale#US Locale.US}.
+     * At a minimum, the returned array must contain a {@code Locale} instance equal to
+     * {@link Locale#ROOT Locale.ROOT} and a {@code Locale} instance equal to
+     * {@link Locale#US Locale.US}.
      *
      * @return An array of locales for which localized
      *         {@code Calendar} instances are available.

src/java.base/share/classes/java/util/Locale.java

@@ -1126,8 +1126,9 @@ public static synchronized void setDefault(Locale.Category category,
      * The returned array represents the union of locales supported
      * by the Java runtime environment and by installed
      * {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider}
-     * implementations.  It must contain at least a {@code Locale}
-     * instance equal to {@link java.util.Locale#US Locale.US}.
+     * implementations. At a minimum, the returned array must contain a
+     * {@code Locale} instance equal to {@link Locale#ROOT Locale.ROOT} and
+     * a {@code Locale} instance equal to {@link Locale#US Locale.US}.
      *
      * @return An array of installed locales.
      */

test/jdk/java/util/Locale/RequiredAvailableLocalesTest.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+/**
+ * @test
+ * @bug 8276186
+ * @summary Checks whether getAvailableLocales() returns at least Locale.ROOT and
+ *      Locale.US instances.
+ * @run testng/othervm -Djava.locale.providers=COMPAT RequiredAvailableLocalesTest
+ * @run testng/othervm -Djava.locale.providers=CLDR RequiredAvailableLocalesTest
+ */
+
+import java.lang.invoke.MethodHandles;
+import java.lang.invoke.MethodType;
+import java.text.*;
+import java.time.format.DecimalStyle;
+import java.util.*;
+
+import org.testng.annotations.DataProvider;
+import org.testng.annotations.Test;
+import static org.testng.Assert.assertTrue;
+
+@Test
+public class RequiredAvailableLocalesTest {
+
+    private static final Set<Locale> REQUIRED_LOCALES = Set.of(Locale.ROOT, Locale.US);
+    private static final MethodType ARRAY_RETURN_TYPE = MethodType.methodType(Locale.class.arrayType());
+    private static final MethodType SET_RETURN_TYPE = MethodType.methodType(Set.class);
+
+    @DataProvider
+    public Object[][] availableLocalesClasses() {
+        return new Object[][] {
+            {BreakIterator.class, ARRAY_RETURN_TYPE},
+            {Calendar.class, ARRAY_RETURN_TYPE},
+            {Collator.class, ARRAY_RETURN_TYPE},
+            {DateFormat.class, ARRAY_RETURN_TYPE},
+            {DateFormatSymbols.class, ARRAY_RETURN_TYPE},
+            {DecimalFormatSymbols.class, ARRAY_RETURN_TYPE},
+            {DecimalStyle.class, SET_RETURN_TYPE},
+            {Locale.class, ARRAY_RETURN_TYPE},
+            {NumberFormat.class, ARRAY_RETURN_TYPE},
+        };
+    }
+
+    @Test (dataProvider = "availableLocalesClasses")
+    public void checkRequiredLocales(Class<?> c, MethodType mt) throws Throwable {
+        var ret = MethodHandles.lookup().findStatic(c, "getAvailableLocales", mt).invoke();
+
+        if (ret instanceof Locale[] a) {
+            assertTrue(Arrays.asList(a).containsAll(REQUIRED_LOCALES));
+        } else if (ret instanceof Set<?> s) {
+            assertTrue(s.containsAll(REQUIRED_LOCALES));
+        } else {
+            throw new RuntimeException("return type mismatch");
+        }
+    }
+}