Summary

Adjust the specifications of several getAvailableLocales() methods to require that the returned array or Set include Locale.ROOT.

Problem

Locale.ROOT, introduced in JDK 1.6, is intended to be a locale that is always available. Prior to JDK 1.6, Locale.US had been fulfilling the role of the always-available locale. However, the specifications of the getAvailableLocales() methods in several locale-sensitive classes still requires only Locale.US in the array or Set of returned locales. Locale.ROOT should also be required.

Solution

Change those minimum required locales sentence also to include Locale.ROOT in locale-sensitive classes' getAvailableLocales() specifications. The requirement for Locale.US remains in place. Removing it would allow incompatible changes to occur, as existing code expects Locale.US always to be present.

Specification

diff a/src/java.base/share/classes/java/text/BreakIterator.java b/src/java.base/share/classes/java/text/BreakIterator.java
--- a/src/java.base/share/classes/java/text/BreakIterator.java
+++ b/src/java.base/share/classes/java/text/BreakIterator.java
@@ -574,12 +574,13 @@
      * {@code get*Instance} methods of this class can return
      * localized instances.
      * 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.
      */
     public static synchronized Locale[] getAvailableLocales()
diff a/src/java.base/share/classes/java/text/Collator.java b/src/java.base/share/classes/java/text/Collator.java
--- a/src/java.base/share/classes/java/text/Collator.java
+++ b/src/java.base/share/classes/java/text/Collator.java
@@ -419,12 +419,13 @@
      * {@code getInstance} methods of this class can return
      * localized instances.
      * 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.
      */
     public static synchronized Locale[] getAvailableLocales() {
diff a/src/java.base/share/classes/java/text/DateFormat.java b/src/java.base/share/classes/java/text/DateFormat.java
--- a/src/java.base/share/classes/java/text/DateFormat.java
+++ b/src/java.base/share/classes/java/text/DateFormat.java
@@ -634,12 +634,13 @@
      * {@code get*Instance} methods of this class can return
      * localized instances.
      * 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.
      */
     public static Locale[] getAvailableLocales()
diff a/src/java.base/share/classes/java/text/DateFormatSymbols.java b/src/java.base/share/classes/java/text/DateFormatSymbols.java
--- a/src/java.base/share/classes/java/text/DateFormatSymbols.java
+++ b/src/java.base/share/classes/java/text/DateFormatSymbols.java
@@ -297,12 +297,13 @@
      * {@code getInstance} methods of this class can return
      * localized instances.
      * 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.
      * @since 1.6
      */
diff a/src/java.base/share/classes/java/text/DecimalFormatSymbols.java b/src/java.base/share/classes/java/text/DecimalFormatSymbols.java
--- a/src/java.base/share/classes/java/text/DecimalFormatSymbols.java
+++ b/src/java.base/share/classes/java/text/DecimalFormatSymbols.java
@@ -120,12 +120,13 @@
      * {@code getInstance} methods of this class can return
      * localized instances.
      * 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.
      * @since 1.6
      */
diff a/src/java.base/share/classes/java/text/NumberFormat.java b/src/java.base/share/classes/java/text/NumberFormat.java
--- a/src/java.base/share/classes/java/text/NumberFormat.java
+++ b/src/java.base/share/classes/java/text/NumberFormat.java
@@ -680,12 +680,13 @@
      * {@code get*Instance} methods of this class can return
      * localized instances.
      * 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.
      */
     public static Locale[] getAvailableLocales() {
diff a/src/java.base/share/classes/java/time/format/DecimalStyle.java b/src/java.base/share/classes/java/time/format/DecimalStyle.java
--- a/src/java.base/share/classes/java/time/format/DecimalStyle.java
+++ b/src/java.base/share/classes/java/time/format/DecimalStyle.java
@@ -113,11 +113,13 @@

     //-----------------------------------------------------------------------
     /**
      * Lists all the locales that are supported.
      * <p>
-     * The locale 'en_US' will always be present.
+     * At a minimum, the returned 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
      */
     public static Set<Locale> getAvailableLocales() {
         Locale[] l = DecimalFormatSymbols.getAvailableLocales();
diff a/src/java.base/share/classes/java/util/Calendar.java b/src/java.base/share/classes/java/util/Calendar.java
--- a/src/java.base/share/classes/java/util/Calendar.java
+++ b/src/java.base/share/classes/java/util/Calendar.java
@@ -1728,12 +1728,13 @@
     }

     /**
      * 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.
      */
     public static synchronized Locale[] getAvailableLocales()
diff a/src/java.base/share/classes/java/util/Locale.java b/src/java.base/share/classes/java/util/Locale.java
--- a/src/java.base/share/classes/java/util/Locale.java
+++ b/src/java.base/share/classes/java/util/Locale.java
@@ -1124,12 +1124,13 @@
     /**
      * Returns an array of all installed locales.
      * 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.
      */
     public static Locale[] getAvailableLocales() {