8340488: Clarify LocaleServiceProvider deployment on application module path

Reviewed-by: naoto

Author: Justin Lu

src/java.base/share/classes/java/util/spi/LocaleServiceProvider.java

@@ -41,19 +41,36 @@
  * and methods for name retrieval in the {@code java.text} and
  * {@code java.util} packages use implementations of the provider
  * interfaces to offer support for locales beyond the set of locales
- * supported by the Java runtime environment itself.
+ * supported by the Java runtime environment itself. Locale sensitive service
+ * providers are deployed on the application module path or the application class
+ * path. In order to be looked up, providers must be visible to the {@link
+ * ClassLoader#getSystemClassLoader() system class loader}.
+ * See {@link java.util.ServiceLoader##developing-service-providers Deploying
+ * Service Providers} for further detail on deploying a locale sensitive service
+ * provider as a module or on the class path.
  *
  * <h2>Packaging of Locale Sensitive Service Provider Implementations</h2>
- * Implementations of these locale sensitive services can be made available
- * by adding them to the application's class path. A provider identifies itself with a
- * provider-configuration file in the resource directory META-INF/services,
- * using the fully qualified provider interface class name as the file name.
- * The file should contain a list of fully-qualified concrete provider class names,
- * one per line. A line is terminated by any one of a line feed ('\n'), a carriage
- * return ('\r'), or a carriage return followed immediately by a line feed. Space
- * and tab characters surrounding each name, as well as blank lines, are ignored.
- * The comment character is '#' ('\u0023'); on each line all characters following
- * the first comment character are ignored. The file must be encoded in UTF-8.
+ *
+ * <p> For a locale sensitive service provider deployed in a module, the <i>provides</i>
+ * directive must be specified in the module declaration. The <i>provides</i>
+ * directive specifies both the service and the service provider.
+ *
+ * <p> For example, an implementation of the {@link java.text.spi.DateFormatProvider
+ * DateFormatProvider} class deployed as a module might specify the following directive:
+ * <pre>{@code
+ *     provides java.text.spi.DateFormatProvider with com.example.ExternalDateFormatProvider;
+ * }</pre>
+ *
+ * <p> For a Locale Service Provider deployed on the class path, the provider
+ * identifies itself with a provider-configuration file in the resource directory
+ * META-INF/services. The file name should be the fully fully qualified provider
+ * interface class name. The file should contain a list of fully-qualified concrete
+ * provider class names, one per line. A line is terminated by any one of a line
+ * feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately
+ * by a line feed. Space and tab characters surrounding each name, as well as
+ * blank lines, are ignored. The comment character is '#' ('\u0023'); on each line
+ * all characters following the first comment character are ignored. The file must
+ * be encoded in UTF-8.
  * <p>
  * If a particular concrete provider class is named in more than one configuration
  * file, or is named in the same configuration file more than once, then the
@@ -88,8 +105,8 @@
  * supports the requested locale. If such a provider is found, its other
  * methods are called to obtain the requested object or name.  When checking
  * whether a locale is supported, the {@linkplain Locale##def_extensions
- * locale's extensions} are ignored by default. (If locale's extensions should
- * also be checked, the {@code isSupportedLocale} method must be overridden.)
+ * locale's extensions} are ignored by default. (If a locale's extensions should
+ * also be checked, the {@code isSupportedLocale} method must be overridden).
  * If neither the Java runtime environment itself nor an installed provider
  * supports the requested locale, the methods go through a list of candidate
  * locales and repeat the availability check for each until a match is found.