LocaleServiceProvider.java |
1 /* 2 * %W% %E% 3 * 4 * Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved. 5 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. 6 */ 7 8 package java.util.spi; 9 10 import java.util.Locale; 11 12 /** 13 * <p> 14 * This is the super class of all the locale sensitive service provider 15 * interfaces (SPIs). 16 * <p> 17 * Locale sensitive service provider interfaces are interfaces that 18 * correspond to locale sensitive classes in the <code>java.text</code> 19 * and <code>java.util</code> packages. The interfaces enable the 20 * construction of locale sensitive objects and the retrieval of 21 * localized names for these packages. Locale sensitive factory methods 22 * and methods for name retrieval in the <code>java.text</code> and 23 * <code>java.util</code> packages use implementations of the provider 24 * interfaces to offer support for locales beyond the set of locales 25 * supported by the Java runtime environment itself. 26 * <p> 27 * <h4>Packaging of Locale Sensitive Service Provider Implementations</h4> 28 * Implementations of these locale sensitive services are packaged using the 29 * <a href="../../../../technotes/guides/extensions/index.html">Java Extension Mechanism</a> 30 * as installed extensions. A provider identifies itself with a 31 * provider-configuration file in the resource directory META-INF/services, 32 * using the fully qualified provider interface class name as the file name. 33 * The file should contain a list of fully-qualified concrete provider class names, 34 * one per line. A line is terminated by any one of a line feed ('\n'), a carriage 35 * return ('\r'), or a carriage return followed immediately by a line feed. Space 36 * and tab characters surrounding each name, as well as blank lines, are ignored. 37 * The comment character is '#' ('#'); on each line all characters following 38 * the first comment character are ignored. The file must be encoded in UTF-8. 39 * <p> 40 * If a particular concrete provider class is named in more than one configuration 41 * file, or is named in the same configuration file more than once, then the 42 * duplicates will be ignored. The configuration file naming a particular provider 43 * need not be in the same jar file or other distribution unit as the provider itself. 44 * The provider must be accessible from the same class loader that was initially 45 * queried to locate the configuration file; this is not necessarily the class loader 46 * that loaded the file. 47 * <p> 48 * For example, an implementation of the 49 * {@link java.text.spi.DateFormatProvider DateFormatProvider} class should 50 * take the form of a jar file which contains the file: 51 * <pre> 52 * META-INF/services/java.text.spi.DateFormatProvider 53 * </pre> 54 * And the file <code>java.text.spi.DateFormatProvider</code> should have 55 * a line such as: 56 * <pre> 57 * <code>com.foo.DateFormatProviderImpl</code> 58 * </pre> 59 * which is the fully qualified class name of the class implementing 60 * <code>DateFormatProvider</code>. 61 * <h4>Invocation of Locale Sensitive Services</h4> 62 * <p> 63 * Locale sensitive factory methods and methods for name retrieval in the 64 * <code>java.text</code> and <code>java.util</code> packages invoke 65 * service provider methods when needed to support the requested locale. 66 * The methods first check whether the Java runtime environment itself 67 * supports the requested locale, and use its support if available. 68 * Otherwise, they call the <code>getAvailableLocales()</code> methods of 69 * installed providers for the appropriate interface to find one that 70 * supports the requested locale. If such a provider is found, its other 71 * methods are called to obtain the requested object or name. If neither 72 * the Java runtime environment itself nor an installed provider supports 73 * the requested locale, a fallback locale is constructed by replacing the 74 * first of the variant, country, or language strings of the locale that's 75 * not an empty string with an empty string, and the lookup process is 76 * restarted. In the case that the variant contains one or more '_'s, the 77 * fallback locale is constructed by replacing the variant with a new variant 78 * which eliminates the last '_' and the part following it. Even if a 79 * fallback occurs, methods that return requested objects or name are 80 * invoked with the original locale before the fallback.The Java runtime 81 * environment must support the root locale for all locale sensitive services 82 * in order to guarantee that this process terminates. 83 * <p> 84 * Providers of names (but not providers of other objects) are allowed to 85 * return null for some name requests even for locales that they claim to 86 * support by including them in their return value for 87 * <code>getAvailableLocales</code>. Similarly, the Java runtime 88 * environment itself may not have all names for all locales that it 89 * supports. This is because the sets of objects for which names are 90 * requested can be large and vary over time, so that it's not always 91 * feasible to cover them completely. If the Java runtime environment or a 92 * provider returns null instead of a name, the lookup will proceed as 93 * described above as if the locale was not supported. 94 * 95 * @since 1.6 96 * @version %W% %E% 97 */ 98 public abstract class LocaleServiceProvider { 99 100 /** 101 * Sole constructor. (For invocation by subclass constructors, typically 102 * implicit.) 103 */ 104 protected LocaleServiceProvider() { 105 } 106 107 /** 108 * Returns an array of all locales for which this locale service provider 109 * can provide localized objects or names. 110 * 111 * @return An array of all locales for which this locale service provider 112 * can provide localized objects or names. 113 */ 114 public abstract Locale[] getAvailableLocales(); 115 } 116