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.
       *