J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 2005-2006 Sun Microsystems, Inc. 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. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any 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. If neither |
| 90 | * the Java runtime environment itself nor an installed provider supports |
| 91 | * the requested locale, a fallback locale is constructed by replacing the |
| 92 | * first of the variant, country, or language strings of the locale that's |
| 93 | * not an empty string with an empty string, and the lookup process is |
| 94 | * restarted. In the case that the variant contains one or more '_'s, the |
| 95 | * fallback locale is constructed by replacing the variant with a new variant |
| 96 | * which eliminates the last '_' and the part following it. Even if a |
| 97 | * fallback occurs, methods that return requested objects or name are |
| 98 | * invoked with the original locale before the fallback.The Java runtime |
| 99 | * environment must support the root locale for all locale sensitive services |
| 100 | * in order to guarantee that this process terminates. |
| 101 | * <p> |
| 102 | * Providers of names (but not providers of other objects) are allowed to |
| 103 | * return null for some name requests even for locales that they claim to |
| 104 | * support by including them in their return value for |
| 105 | * <code>getAvailableLocales</code>. Similarly, the Java runtime |
| 106 | * environment itself may not have all names for all locales that it |
| 107 | * supports. This is because the sets of objects for which names are |
| 108 | * requested can be large and vary over time, so that it's not always |
| 109 | * feasible to cover them completely. If the Java runtime environment or a |
| 110 | * provider returns null instead of a name, the lookup will proceed as |
| 111 | * described above as if the locale was not supported. |
| 112 | * |
| 113 | * @since 1.6 |
| 114 | */ |
| 115 | public abstract class LocaleServiceProvider { |
| 116 | |
| 117 | /** |
| 118 | * Sole constructor. (For invocation by subclass constructors, typically |
| 119 | * implicit.) |
| 120 | */ |
| 121 | protected LocaleServiceProvider() { |
| 122 | } |
| 123 | |
| 124 | /** |
| 125 | * Returns an array of all locales for which this locale service provider |
| 126 | * can provide localized objects or names. |
| 127 | * |
| 128 | * @return An array of all locales for which this locale service provider |
| 129 | * can provide localized objects or names. |
| 130 | */ |
| 131 | public abstract Locale[] getAvailableLocales(); |
| 132 | } |