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 /*
   2  * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


  66  * For example, an implementation of the
  67  * {@link java.text.spi.DateFormatProvider DateFormatProvider} class should
  68  * take the form of a jar file which contains the file:
  69  * <pre>
  70  * META-INF/services/java.text.spi.DateFormatProvider
  71  * </pre>
  72  * And the file <code>java.text.spi.DateFormatProvider</code> should have
  73  * a line such as:
  74  * <pre>
  75  * <code>com.foo.DateFormatProviderImpl</code>
  76  * </pre>
  77  * which is the fully qualified class name of the class implementing
  78  * <code>DateFormatProvider</code>.
  79  * <h4>Invocation of Locale Sensitive Services</h4>
  80  * <p>
  81  * Locale sensitive factory methods and methods for name retrieval in the
  82  * <code>java.text</code> and <code>java.util</code> packages invoke
  83  * service provider methods when needed to support the requested locale.
  84  * The methods first check whether the Java runtime environment itself
  85  * supports the requested locale, and use its support if available.
  86  * Otherwise, they call the <code>getAvailableLocales()</code> methods of
  87  * installed providers for the appropriate interface to find one that
  88  * supports the requested locale. If such a provider is found, its other
  89  * methods are called to obtain the requested object or name.  When checking
  90  * whether a locale is supported, the locale's extensions are ignored.


  91  * If neither the Java runtime environment itself nor an installed provider
  92  * supports the requested locale, the methods go through a list of candidate
  93  * locales and repeat the availability check for each until a match is found.
  94  * The algorithm used for creating a list of candidate locales is same as
  95  * the one used by <code>ResourceBunlde</code> by default (see
  96  * {@link java.util.ResourceBundle.Control#getCandidateLocales getCandidateLocales}
  97  * for the details).  Even if a locale is resolved from the candidate list,
  98  * methods that return requested objects or names are invoked with the original
  99  * requested locale including extensions.  The Java runtime environment must
 100  * support the root locale for all locale sensitive services in order to
 101  * guarantee that this process terminates.
 102  * <p>
 103  * Providers of names (but not providers of other objects) are allowed to
 104  * return null for some name requests even for locales that they claim to
 105  * support by including them in their return value for
 106  * <code>getAvailableLocales</code>. Similarly, the Java runtime
 107  * environment itself may not have all names for all locales that it
 108  * supports. This is because the sets of objects for which names are
 109  * requested can be large and vary over time, so that it's not always
 110  * feasible to cover them completely. If the Java runtime environment or a
 111  * provider returns null instead of a name, the lookup will proceed as
 112  * described above as if the locale was not supported.
















 113  *
 114  * @since        1.6
 115  */
 116 public abstract class LocaleServiceProvider {
 117 
 118     /**
 119      * Sole constructor.  (For invocation by subclass constructors, typically
 120      * implicit.)
 121      */
 122     protected LocaleServiceProvider() {
 123     }
 124 
 125     /**
 126      * Returns an array of all locales for which this locale service provider
 127      * can provide localized objects or names.
 128      * <p>
 129      * <b>Note:</b> Extensions in a <code>Locale</code> are ignored during
 130      * service provider lookup.  So the array returned by this method should
 131      * not include two or more <code>Locale</code> objects only differing in
 132      * their extensions.
 133      *



 134      * @return An array of all locales for which this locale service provider
 135      * can provide localized objects or names.
 136      */
 137     public abstract Locale[] getAvailableLocales();





































 138 }
   1 /*
   2  * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


  66  * For example, an implementation of the
  67  * {@link java.text.spi.DateFormatProvider DateFormatProvider} class should
  68  * take the form of a jar file which contains the file:
  69  * <pre>
  70  * META-INF/services/java.text.spi.DateFormatProvider
  71  * </pre>
  72  * And the file <code>java.text.spi.DateFormatProvider</code> should have
  73  * a line such as:
  74  * <pre>
  75  * <code>com.foo.DateFormatProviderImpl</code>
  76  * </pre>
  77  * which is the fully qualified class name of the class implementing
  78  * <code>DateFormatProvider</code>.
  79  * <h4>Invocation of Locale Sensitive Services</h4>
  80  * <p>
  81  * Locale sensitive factory methods and methods for name retrieval in the
  82  * <code>java.text</code> and <code>java.util</code> packages invoke
  83  * service provider methods when needed to support the requested locale.
  84  * The methods first check whether the Java runtime environment itself
  85  * supports the requested locale, and use its support if available.
  86  * Otherwise, they call the {@link #isSupportedLocale(Locale) isSupportedLocale}
  87  * methods of installed providers for the appropriate interface to find one that
  88  * supports the requested locale. If such a provider is found, its other
  89  * methods are called to obtain the requested object or name.  When checking
  90  * whether a locale is supported, the <a href="../Locale.html#def_extensions">
  91  * locale's extensions</a> are ignored by default. (If locale's extensions should
  92  * also be checked, the {@code isSupportedLocale} method must be overridden.)
  93  * If neither the Java runtime environment itself nor an installed provider
  94  * supports the requested locale, the methods go through a list of candidate
  95  * locales and repeat the availability check for each until a match is found.
  96  * The algorithm used for creating a list of candidate locales is same as
  97  * the one used by <code>ResourceBunlde</code> by default (see
  98  * {@link java.util.ResourceBundle.Control#getCandidateLocales getCandidateLocales}
  99  * for the details).  Even if a locale is resolved from the candidate list,
 100  * methods that return requested objects or names are invoked with the original
 101  * requested locale including {@code Locale} extensions. The Java runtime
 102  * environment must support the root locale for all locale sensitive services in
 103  * order to guarantee that this process terminates.
 104  * <p>
 105  * Providers of names (but not providers of other objects) are allowed to
 106  * return null for some name requests even for locales that they claim to
 107  * support by including them in their return value for
 108  * <code>getAvailableLocales</code>. Similarly, the Java runtime
 109  * environment itself may not have all names for all locales that it
 110  * supports. This is because the sets of objects for which names are
 111  * requested can be large and vary over time, so that it's not always
 112  * feasible to cover them completely. If the Java runtime environment or a
 113  * provider returns null instead of a name, the lookup will proceed as
 114  * described above as if the locale was not supported.
 115  * <p>
 116  * Starting from JDK8, the search order of locale sensitive services can
 117  * be configured by using the "java.locale.providers" system property.
 118  * This system property declares the user's preferred order for looking up
 119  * the locale sensitive services separated by a comma. It is only read at
 120  * the Java runtime startup, so the later call to System.setProperty() won't
 121  * affect the order.
 122  * <p>
 123  * For example, if the following is specified in the property:
 124  * <pre>
 125  * java.locale.providers=SPI,JRE
 126  * </pre>
 127  * where "SPI" represents the locale sensitive services implemented in the
 128  * installed SPI providers, and "JRE" represents the locale sensitive services
 129  * in the Java Runtime Environment, the locale sensitive services in the SPI
 130  * providers are looked up first.
 131  *
 132  * @since        1.6
 133  */
 134 public abstract class LocaleServiceProvider {
 135 
 136     /**
 137      * Sole constructor.  (For invocation by subclass constructors, typically
 138      * implicit.)
 139      */
 140     protected LocaleServiceProvider() {
 141     }
 142 
 143     /**
 144      * Returns an array of all locales for which this locale service provider
 145      * can provide localized objects or names. This information is used to
 146      * compose {@code getAvailableLocales()} values of the locale-dependent
 147      * services, such as {@code DateFormat.getAvailableLocales()}.



 148      *
 149      * <p>The array returned by this method should not include two or more
 150      * {@code Locale} objects only differing in their extensions.
 151      *
 152      * @return An array of all locales for which this locale service provider
 153      * can provide localized objects or names.
 154      */
 155     public abstract Locale[] getAvailableLocales();
 156 
 157     /**
 158      * Returns {@code true} if the given {@code locale} is supported by
 159      * this locale service provider. The given {@code locale} may contain
 160      * <a href="../Locale.html#def_extensions">extensions<a/> that should be
 161      * taken into account for the support determination.
 162      *
 163      * <p>The default implementation returns {@code true} if the given {@code locale}
 164      * is equal to any of the available {@code Locale}s returned by
 165      * {@link #getAvailableLocales()} with ignoring any extensions in both the
 166      * given {@code locale} and the available locales. Concrete locale service
 167      * provider implementations should override this method if those
 168      * implementations are {@code Locale} extensions-aware. For example,
 169      * {@code DecimalFormatSymbolsProvider} implementations will need to check
 170      * extensions in the given {@code locale} to see if any numbering system is
 171      * specified and can be supported. However, {@code CollatorProvider}
 172      * implementations may not be affected by any particular numbering systems,
 173      * and in that case, extensions for numbering systems should be ignored.
 174      *
 175      * @param locale a {@code Locale} to be tested
 176      * @return {@code true} if the given {@code locale} is supported by this
 177      *         provider; {@code false} otherwise.
 178      * @throws NullPointerException
 179      *         if the given {@code locale} is {@code null}
 180      * @see Locale#hasExtensions()
 181      * @see Locale#stripExtensions()
 182      * @since 1.8
 183      */
 184     public boolean isSupportedLocale(Locale locale) {
 185         locale = locale.stripExtensions(); // throws NPE if locale == null
 186         for (Locale available : getAvailableLocales()) {
 187             if (locale.equals(available.stripExtensions())) {
 188                 return true;
 189 }
 190         }
 191         return false;
 192     }
 193 }