1 /*
   2  * Copyright (c) 2005, 2006, 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
  23  * questions.
  24  */
  25 
  26 package java.util.spi;
  27 
  28 import java.util.Locale;
  29 
  30 /**
  31  * <p>
  32  * This is the super class of all the locale sensitive service provider
  33  * interfaces (SPIs).
  34  * <p>
  35  * Locale sensitive  service provider interfaces are interfaces that
  36  * correspond to locale sensitive classes in the <code>java.text</code>
  37  * and <code>java.util</code> packages. The interfaces enable the
  38  * construction of locale sensitive objects and the retrieval of
  39  * localized names for these packages. Locale sensitive factory methods
  40  * and methods for name retrieval in the <code>java.text</code> and
  41  * <code>java.util</code> packages use implementations of the provider
  42  * interfaces to offer support for locales beyond the set of locales
  43  * supported by the Java runtime environment itself.
  44  * <p>
  45  * <h4>Packaging of Locale Sensitive Service Provider Implementations</h4>
  46  * Implementations of these locale sensitive services are packaged using the
  47  * <a href="../../../../technotes/guides/extensions/index.html">Java Extension Mechanism</a>
  48  * as installed extensions.  A provider identifies itself with a
  49  * provider-configuration file in the resource directory META-INF/services,
  50  * using the fully qualified provider interface class name as the file name.
  51  * The file should contain a list of fully-qualified concrete provider class names,
  52  * one per line. A line is terminated by any one of a line feed ('\n'), a carriage
  53  * return ('\r'), or a carriage return followed immediately by a line feed. Space
  54  * and tab characters surrounding each name, as well as blank lines, are ignored.
  55  * The comment character is '#' ('\u0023'); on each line all characters following
  56  * the first comment character are ignored. The file must be encoded in UTF-8.
  57  * <p>
  58  * If a particular concrete provider class is named in more than one configuration
  59  * file, or is named in the same configuration file more than once, then the
  60  * duplicates will be ignored. The configuration file naming a particular provider
  61  * need not be in the same jar file or other distribution unit as the provider itself.
  62  * The provider must be accessible from the same class loader that was initially
  63  * queried to locate the configuration file; this is not necessarily the class loader
  64  * that loaded the file.
  65  * <p>
  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 }
--- EOF ---