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   * An abstract class for service providers that
14   * provide localized names for the 
15   * {@link java.util.Locale Locale} class.
16   *
17   * @since        1.6
18   * @version      %W% %E%
19   */
20  public abstract class LocaleNameProvider extends LocaleServiceProvider {
21  
22      /**
23       * Sole constructor.  (For invocation by subclass constructors, typically
24       * implicit.)
25       */
26      protected LocaleNameProvider() {
27      }
28  
29      /**
30       * Returns a localized name for the given ISO 639 language code and the 
31       * given locale that is appropriate for display to the user.
32       * For example, if <code>languageCode</code> is "fr" and <code>locale</code>
33       * is en_US, getDisplayLanguage() will return "French"; if <code>languageCode</code>
34       * is "en" and <code>locale</code> is fr_FR, getDisplayLanguage() will return "anglais".
35       * If the name returned cannot be localized according to <code>locale</code>,
36       * (say, the provider does not have a Japanese name for Croatian),
37       * this method returns null.
38       * @param languageCode the ISO 639 language code string in the form of two
39       *     lower-case letters between 'a' (U+0061) and 'z' (U+007A)
40       * @param locale the desired locale
41       * @return the name of the given language code for the specified locale, or null if it's not 
42       *     available.
43       * @exception NullPointerException if <code>languageCode</code> or <code>locale</code> is null
44       * @exception IllegalArgumentException if <code>languageCode</code> is not in the form of
45       *     two lower-case letters, or <code>locale</code> isn't
46       *     one of the locales returned from 
47       *     {@link java.util.spi.LocaleServiceProvider#getAvailableLocales() 
48       *     getAvailableLocales()}.
49       * @see java.util.Locale#getDisplayLanguage(java.util.Locale)
50       */
51      public abstract String getDisplayLanguage(String languageCode, Locale locale);
52  
53      /**
54       * Returns a localized name for the given ISO 3166 country code and the 
55       * given locale that is appropriate for display to the user.
56       * For example, if <code>countryCode</code> is "FR" and <code>locale</code>
57       * is en_US, getDisplayCountry() will return "France"; if <code>countryCode</code> 
58       * is "US" and <code>locale</code> is fr_FR, getDisplayCountry() will return "Etats-Unis".
59       * If the name returned cannot be localized according to <code>locale</code>,
60       * (say, the provider does not have a Japanese name for Croatia),
61       * this method returns null.
62       * @param countryCode the ISO 3166 country code string in the form of two
63       *     upper-case letters between 'A' (U+0041) and 'Z' (U+005A)
64       * @param locale the desired locale
65       * @return the name of the given country code for the specified locale, or null if it's not
66       *     available.
67       * @exception NullPointerException if <code>countryCode</code> or <code>locale</code> is null
68       * @exception IllegalArgumentException if <code>countryCode</code> is not in the form of
69       *     two upper-case letters, or <code>locale</code> isn't
70       *     one of the locales returned from 
71       *     {@link java.util.spi.LocaleServiceProvider#getAvailableLocales() 
72       *     getAvailableLocales()}.
73       * @see java.util.Locale#getDisplayCountry(java.util.Locale)
74       */
75      public abstract String getDisplayCountry(String countryCode, Locale locale);
76  
77      /**
78       * Returns a localized name for the given variant code and the given locale that 
79       * is appropriate for display to the user.
80       * If the name returned cannot be localized according to <code>locale</code>,
81       * this method returns null.
82       * @param variant the variant string
83       * @param locale the desired locale
84       * @return the name of the given variant string for the specified locale, or null if it's not
85       *     available.
86       * @exception NullPointerException if <code>variant</code> or <code>locale</code> is null
87       * @exception IllegalArgumentException if <code>locale</code> isn't
88       *     one of the locales returned from 
89       *     {@link java.util.spi.LocaleServiceProvider#getAvailableLocales() 
90       *     getAvailableLocales()}.
91       * @see java.util.Locale#getDisplayVariant(java.util.Locale)
92       */
93      public abstract String getDisplayVariant(String variant, Locale locale);
94  }
95