Summary

Clarify the description of java.locale.providers system property

Problem

The system property java.locale.providers specifies the user's preferred loading order of the locale sensitive services, described in java.util.spi.LocaleServiceProvider class. The current description is not clear on the possible values of the property, especially whether they are normative Java SE specs or implementation specific.

Solution

Clarify the class description for java.locale.providers system property, making a clear distinction on the mandated spec or implementation note.

Specification

Modify the third paragraph in Invocation of Locale Sensitive Services section of the java.util.spi.LocaleServiceProvider class description as follows:

   * <p>
-  * The search order of locale sensitive services can
-  * be configured by using the {@systemProperty java.locale.providers} system property.
-  * This system property declares the user's preferred order for looking up
-  * the locale sensitive services separated by a comma. As this property value is
-  * read and cached only at the initialization of this class, users should specify the
-  * property on the java launcher command line. Setting it at runtime with
-  * {@link System#setProperty(String, String)} is discouraged and it may not affect
-  * the order.
-  * JDK Reference Implementation provides the following four
-  * locale providers:
+  * Since an implementation of the JDK may provide multiple sets of locale sensitive
+  * service implementations, their search order can be configured using the
+  * {@systemProperty java.locale.providers} system property. This system property
+  * declares the user's preferred order for looking up the sets of locale sensitive
+  * services separated by a comma. Each string entity represents an arbitrary name of
+  * the set provided by the JDK implementation except "{@code SPI}", with which the
+  * application provided implementations of {@code LocaleServiceProvider} are
+  * represented. Applications which require their implementations of
+  * {@code LocaleServiceProvider} must explicitly specify "{@code SPI}" in the system
+  * property, in order for the Java runtime to load them from the classpath. If
+  * multiple implementations of the same subclass of {@code LocaleServiceProvider}
+  * are found on the classpath, it depends on the JDK with regard to which one is loaded.
+  * As this system property value is read and cached only at the initialization
+  * of this class, users should specify the property on the java launcher command
+  * line. Setting it at runtime with {@link System#setProperty(String, String)}
+  * is discouraged and it may not affect the order.
+  * @implNote The JDK provides the following four sets of locale sensitive services:
   * <ul>
-  * <li> "CLDR": A provider based on Unicode Consortium's
+  * <li> "{@code CLDR}": The set of locale sensitive services based on Unicode Consortium's
   * <a href="http://cldr.unicode.org/">CLDR Project</a>.
-  * <li> "COMPAT": represents the locale sensitive services that is compatible
-  * with the prior JDK releases up to JDK 8 (same as JDK 8's "JRE"). This
-  * provider is deprecated and will be removed in the future release of JDK.
-  * <li> "SPI": represents the locale sensitive services implementing the subclasses of
-  * this {@code LocaleServiceProvider} class.
-  * <li> "HOST": A provider that reflects the user's custom settings in the
-  * underlying operating system. This provider may not be available, depending
-  * on the JDK Reference Implementation.
-  * <li> "JRE": represents a synonym to "COMPAT". This name
+  * <li> "{@code COMPAT}": The set of locale sensitive services that is compatible
+  * with the prior JDK releases up to JDK 8 (same as JDK 8's "{@code JRE}"). This
+  * set is deprecated and will be removed in the future release of JDK.
+  * <li> "{@code SPI}": The set of application provided locale sensitive services implementing
+  * the subclasses of this {@code LocaleServiceProvider} class on the classpath.
+  * <li> "{@code HOST}": The Set of locale sensitive services that reflects the user's custom
+  * settings in the underlying operating system.
+  * <li> "{@code JRE}": represents a synonym to "{@code COMPAT}". This name
   * is deprecated and will be removed in the future release of JDK.
   * </ul>
   * <p>
-  * For example, if the following is specified in the property:
+  * For example, if the following is specified in the system property:
   * <pre>
   * java.locale.providers=SPI,CLDR,COMPAT
   * </pre>
-  * the locale sensitive services in the SPI providers are looked up first. If the
-  * desired locale sensitive service is not available, then the runtime looks for CLDR,
-  * COMPAT in that order.
+  * the locale sensitive services in the "{@code SPI}" set are looked up first. If the
+  * desired locale sensitive service is not available, then the runtime looks for the one
+  * in {@code CLDR}, {@code COMPAT} in that order.
   * <p>
-  * The default order for looking up the preferred locale providers is "CLDR,COMPAT",
-  * so specifying "CLDR,COMPAT" is identical to the default behavior. Applications which
-  * require implementations of the locale sensitive services must explicitly specify
-  * "SPI" in order for the Java runtime to load them from the classpath.
+  * The default order for looking up the preferred sets of locale providers is
+  * "{@code CLDR,COMPAT}", so specifying  "{@code CLDR,COMPAT}" is identical to the
+  * default behavior.
   *