8340488: Clarify LocaleServiceProvider deployment on application module path

Reviewed-by: naoto
This commit is contained in:
Justin Lu 2024-10-18 17:41:36 +00:00
parent 4dcc7f3f26
commit 078401134a

@ -41,19 +41,36 @@ import java.util.Locale;
* 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 @@ import java.util.Locale;
* 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.