LocaleNameProvider.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 * 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