LocaleServiceProvider


1   /*
2    * @(#)LocaleServiceProvider.java   1.4 06/04/21
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN 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      @(#)LocaleServiceProvider.java 1.4 06/04/21
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags