src/share/classes/java/util/spi/LocaleServiceProvider.java
Print this page
rev 5696 : 6336885: RFE: Locale Data Deployment Enhancements
4609153: Provide locale data for Indic locales
5104387: Support for gl_ES locale (galician language)
6337471: desktop/system locale preferences support
7056139: (cal) SPI support for locale-dependent Calendar parameters
7058206: Provide CalendarData SPI for week params and display field value names
7073852: Support multiple scripts for digits and decimal symbols per locale
7079560: [Fmt-Da] Context dependent month names support in SimpleDateFormat
7171324: getAvailableLocales() of locale sensitive services should return the actual availability of locales
7151414: (cal) Support calendar type identification
7168528: LocaleServiceProvider needs to be aware of Locale extensions
7171372: (cal) locale's default Calendar should be created if unknown calendar is specified
Summary: JEP 127: Improve Locale Data Packaging and Adopt Unicode CLDR Data (part 1 w/o packaging changes. by Naoto Sato and Masayoshi Okutsu)
*** 1,7 ****
/*
! * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
--- 1,7 ----
/*
! * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
*** 81,106 ****
* Locale sensitive factory methods and methods for name retrieval in the
* <code>java.text</code> and <code>java.util</code> 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 <code>getAvailableLocales()</code> 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.
* 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 <code>ResourceBunlde</code> by default (see
* {@link java.util.ResourceBundle.Control#getCandidateLocales 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 extensions. The Java runtime environment must
! * support the root locale for all locale sensitive services in order to
! * guarantee that this process terminates.
* <p>
* 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
* <code>getAvailableLocales</code>. Similarly, the Java runtime
--- 81,108 ----
* Locale sensitive factory methods and methods for name retrieval in the
* <code>java.text</code> and <code>java.util</code> 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 {@link #isSupportedLocale(Locale) 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 <a href="../Locale.html#def_extensions">
! * locale's extensions</a> are ignored by default. (If 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.
* The algorithm used for creating a list of candidate locales is same as
* the one used by <code>ResourceBunlde</code> by default (see
* {@link java.util.ResourceBundle.Control#getCandidateLocales 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 {@code Locale} extensions. The Java runtime
! * environment must support the root locale for all locale sensitive services in
! * order to guarantee that this process terminates.
* <p>
* 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
* <code>getAvailableLocales</code>. Similarly, the Java runtime
*** 108,117 ****
--- 110,135 ----
* 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.
+ * <p>
+ * Starting from JDK8, 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. It is only read at
+ * the Java runtime startup, so the later call to System.setProperty() won't
+ * affect the order.
+ * <p>
+ * For example, if the following is specified in the property:
+ * <pre>
+ * java.locale.providers=SPI,JRE
+ * </pre>
+ * where "SPI" represents the locale sensitive services implemented in the
+ * installed SPI providers, and "JRE" represents the locale sensitive services
+ * in the Java Runtime Environment, the locale sensitive services in the SPI
+ * providers are looked up first.
*
* @since 1.6
*/
public abstract class LocaleServiceProvider {
*** 122,138 ****
protected LocaleServiceProvider() {
}
/**
* Returns an array of all locales for which this locale service provider
! * can provide localized objects or names.
! * <p>
! * <b>Note:</b> Extensions in a <code>Locale</code> are ignored during
! * service provider lookup. So the array returned by this method should
! * not include two or more <code>Locale</code> objects only differing in
! * their extensions.
*
* @return An array of all locales for which this locale service provider
* can provide localized objects or names.
*/
public abstract Locale[] getAvailableLocales();
}
--- 140,193 ----
protected LocaleServiceProvider() {
}
/**
* Returns an array of all locales for which this locale service provider
! * can provide localized objects or names. This information is used to
! * compose {@code getAvailableLocales()} values of the locale-dependent
! * services, such as {@code DateFormat.getAvailableLocales()}.
*
+ * <p>The array returned by this method should not include two or more
+ * {@code Locale} objects only differing in their extensions.
+ *
* @return An array of all locales for which this locale service provider
* can provide localized objects or names.
*/
public abstract Locale[] getAvailableLocales();
+
+ /**
+ * Returns {@code true} if the given {@code locale} is supported by
+ * this locale service provider. The given {@code locale} may contain
+ * <a href="../Locale.html#def_extensions">extensions<a/> that should be
+ * taken into account for the support determination.
+ *
+ * <p>The default implementation returns {@code true} if the given {@code locale}
+ * is equal to any of the available {@code Locale}s returned by
+ * {@link #getAvailableLocales()} with ignoring any extensions in both the
+ * given {@code locale} and the available locales. Concrete locale service
+ * provider implementations should override this method if those
+ * implementations are {@code Locale} extensions-aware. For example,
+ * {@code DecimalFormatSymbolsProvider} implementations will need to check
+ * extensions in the given {@code locale} to see if any numbering system is
+ * specified and can be supported. However, {@code CollatorProvider}
+ * implementations may not be affected by any particular numbering systems,
+ * and in that case, extensions for numbering systems should be ignored.
+ *
+ * @param locale a {@code Locale} to be tested
+ * @return {@code true} if the given {@code locale} is supported by this
+ * provider; {@code false} otherwise.
+ * @throws NullPointerException
+ * if the given {@code locale} is {@code null}
+ * @see Locale#hasExtensions()
+ * @see Locale#stripExtensions()
+ * @since 1.8
+ */
+ public boolean isSupportedLocale(Locale locale) {
+ locale = locale.stripExtensions(); // throws NPE if locale == null
+ for (Locale available : getAvailableLocales()) {
+ if (locale.equals(available.stripExtensions())) {
+ return true;
+ }
+ }
+ return false;
+ }
}