BreakIteratorProvider
, CalendarDataProvider
, CalendarNameProvider
, CollatorProvider
, CurrencyNameProvider
, DateFormatProvider
, DateFormatSymbolsProvider
, DecimalFormatSymbolsProvider
, LocaleNameProvider
, NumberFormatProvider
, TimeZoneNameProvider
public abstract class LocaleServiceProvider extends Object
This is the super class of all the locale sensitive service provider interfaces (SPIs).
Locale sensitive service provider interfaces are interfaces that correspond to locale sensitive classes in the java.text
and java.util
packages. The interfaces enable the construction of locale sensitive objects and the retrieval of localized names for these packages. Locale sensitive factory methods and methods for name retrieval in the java.text
and 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.
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 duplicates will be ignored. The configuration file naming a particular provider need not be in the same jar file or other distribution unit as the provider itself. The provider must be accessible from the same class loader that was initially queried to locate the configuration file; this is not necessarily the class loader that loaded the file.
For example, an implementation of the DateFormatProvider
class should take the form of a jar file which contains the file:
META-INF/services/java.text.spi.DateFormatProviderAnd the file
java.text.spi.DateFormatProvider
should have a line such as:
com.foo.DateFormatProviderImpl
which is the fully qualified class name of the class implementing DateFormatProvider
. Locale sensitive factory methods and methods for name retrieval in the java.text
and java.util
packages invoke service provider methods when needed to support the requested locale. The methods first check whether the Java runtime environment itself supports the requested locale, and use its support if available. Otherwise, they call the isSupportedLocale
methods of installed providers for the appropriate interface to find one that 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 locale's extensions are ignored by default. (If locale's extensions should also be checked, the 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. The algorithm used for creating a list of candidate locales is same as the one used by ResourceBundle
by default (see getCandidateLocales
for the details). Even if a locale is resolved from the candidate list, methods that return requested objects or names are invoked with the original requested locale including Locale
extensions. The Java runtime environment must support the root locale for all locale sensitive services in order to guarantee that this process terminates.
Providers of names (but not providers of other objects) are allowed to return null for some name requests even for locales that they claim to support by including them in their return value for getAvailableLocales
. Similarly, the Java runtime environment itself may not have all names for all locales that it supports. This is because the sets of objects for which names are requested can be large and vary over time, so that it's not always feasible to cover them completely. If the Java runtime environment or a provider returns null instead of a name, the lookup will proceed as described above as if the locale was not supported.
The search order of locale sensitive services can be configured by using the 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 System.setProperty(String, String)
is discouraged and it may not affect the order. JDK Reference Implementation provides the following four locale providers:
LocaleServiceProvider
class. For example, if the following is specified in the property:
java.locale.providers=SPI,CLDR,COMPATthe 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 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.
Modifier | Constructor | Description |
---|---|---|
protected |
Initializes a new locale service provider. |
Modifier and Type | Method | Description |
---|---|---|
abstract Locale[] |
getAvailableLocales() |
Returns an array of all locales for which this locale service provider can provide localized objects or names. |
boolean |
isSupportedLocale |
Returns true if the given locale is supported by this locale service provider. |
protected LocaleServiceProvider()
SecurityException
- If a security manager has been installed and it denies RuntimePermission("localeServiceProvider")
public abstract Locale[] getAvailableLocales()
getAvailableLocales()
values of the locale-dependent services, such as DateFormat.getAvailableLocales()
. The array returned by this method should not include two or more Locale
objects only differing in their extensions.
public boolean isSupportedLocale(Locale locale)
true
if the given locale
is supported by this locale service provider. The given locale
may contain extensions that should be taken into account for the support determination. The default implementation returns true
if the given locale
is equal to any of the available Locale
s returned by getAvailableLocales()
with ignoring any extensions in both the given locale
and the available locales. Concrete locale service provider implementations should override this method if those implementations are Locale
extensions-aware. For example, DecimalFormatSymbolsProvider
implementations will need to check extensions in the given locale
to see if any numbering system is specified and can be supported. However, CollatorProvider
implementations may not be affected by any particular numbering systems, and in that case, extensions for numbering systems should be ignored.
locale
- a Locale
to be testedtrue
if the given locale
is supported by this provider; false
otherwise.NullPointerException
- if the given locale
is null
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/spi/LocaleServiceProvider.html