From 078401134a97a13a96e12aa23e3481c59f3669ed Mon Sep 17 00:00:00 2001 From: Justin Lu Date: Fri, 18 Oct 2024 17:41:36 +0000 Subject: [PATCH] 8340488: Clarify LocaleServiceProvider deployment on application module path Reviewed-by: naoto --- .../java/util/spi/LocaleServiceProvider.java | 43 +++++++++++++------ 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/src/java.base/share/classes/java/util/spi/LocaleServiceProvider.java b/src/java.base/share/classes/java/util/spi/LocaleServiceProvider.java index 6ec8b2a149a..2dd13324ec8 100644 --- a/src/java.base/share/classes/java/util/spi/LocaleServiceProvider.java +++ b/src/java.base/share/classes/java/util/spi/LocaleServiceProvider.java @@ -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. * *

Packaging of Locale Sensitive Service Provider Implementations

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

For a locale sensitive service provider deployed in a module, the provides + * directive must be specified in the module declaration. The provides + * directive specifies both the service and the service provider. + * + *

For example, an implementation of the {@link java.text.spi.DateFormatProvider + * DateFormatProvider} class deployed as a module might specify the following directive: + * 

{@code
+ *     provides java.text.spi.DateFormatProvider with com.example.ExternalDateFormatProvider;
+ * }
+ * + *

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

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