001 /* Locale.java -- i18n locales
002 Copyright (C) 1998, 1999, 2001, 2002, 2005, 2006 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.util;
040
041 import gnu.classpath.SystemProperties;
042 import gnu.java.locale.LocaleHelper;
043
044 import java.io.IOException;
045 import java.io.ObjectInputStream;
046 import java.io.ObjectOutputStream;
047 import java.io.Serializable;
048
049 import java.util.spi.LocaleNameProvider;
050
051 /**
052 * Locales represent a specific country and culture. Classes which can be
053 * passed a Locale object tailor their information for a given locale. For
054 * instance, currency number formatting is handled differently for the USA
055 * and France.
056 *
057 * <p>Locales are made up of a language code, a country code, and an optional
058 * set of variant strings. Language codes are represented by
059 * <a href="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">
060 * ISO 639:1988</a> w/ additions from ISO 639/RA Newsletter No. 1/1989
061 * and a decision of the Advisory Committee of ISO/TC39 on August 8, 1997.
062 *
063 * <p>Country codes are represented by
064 * <a href="http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html">
065 * ISO 3166</a>. Variant strings are vendor and browser specific. Standard
066 * variant strings include "POSIX" for POSIX, "WIN" for MS-Windows, and
067 * "MAC" for Macintosh. When there is more than one variant string, they must
068 * be separated by an underscore (U+005F).
069 *
070 * <p>The default locale is determined by the values of the system properties
071 * user.language, user.country (or user.region), and user.variant, defaulting
072 * to "en_US". Note that the locale does NOT contain the conversion and
073 * formatting capabilities (for that, use ResourceBundle and java.text).
074 * Rather, it is an immutable tag object for identifying a given locale, which
075 * is referenced by these other classes when they must make locale-dependent
076 * decisions.
077 *
078 * @see ResourceBundle
079 * @see java.text.Format
080 * @see java.text.NumberFormat
081 * @see java.text.Collator
082 * @author Jochen Hoenicke
083 * @author Paul Fisher
084 * @author Eric Blake (ebb9@email.byu.edu)
085 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
086 * @since 1.1
087 * @status updated to 1.4
088 */
089 public final class Locale implements Serializable, Cloneable
090 {
091 /** Locale which represents the English language. */
092 public static final Locale ENGLISH = getLocale("en");
093
094 /** Locale which represents the French language. */
095 public static final Locale FRENCH = getLocale("fr");
096
097 /** Locale which represents the German language. */
098 public static final Locale GERMAN = getLocale("de");
099
100 /** Locale which represents the Italian language. */
101 public static final Locale ITALIAN = getLocale("it");
102
103 /** Locale which represents the Japanese language. */
104 public static final Locale JAPANESE = getLocale("ja");
105
106 /** Locale which represents the Korean language. */
107 public static final Locale KOREAN = getLocale("ko");
108
109 /** Locale which represents the Chinese language. */
110 public static final Locale CHINESE = getLocale("zh");
111
112 /** Locale which represents the Chinese language as used in China. */
113 public static final Locale SIMPLIFIED_CHINESE = getLocale("zh", "CN");
114
115 /**
116 * Locale which represents the Chinese language as used in Taiwan.
117 * Same as TAIWAN Locale.
118 */
119 public static final Locale TRADITIONAL_CHINESE = getLocale("zh", "TW");
120
121 /** Locale which represents France. */
122 public static final Locale FRANCE = getLocale("fr", "FR");
123
124 /** Locale which represents Germany. */
125 public static final Locale GERMANY = getLocale("de", "DE");
126
127 /** Locale which represents Italy. */
128 public static final Locale ITALY = getLocale("it", "IT");
129
130 /** Locale which represents Japan. */
131 public static final Locale JAPAN = getLocale("ja", "JP");
132
133 /** Locale which represents Korea. */
134 public static final Locale KOREA = getLocale("ko", "KR");
135
136 /**
137 * Locale which represents China.
138 * Same as SIMPLIFIED_CHINESE Locale.
139 */
140 public static final Locale CHINA = SIMPLIFIED_CHINESE;
141
142 /**
143 * Locale which represents the People's Republic of China.
144 * Same as CHINA Locale.
145 */
146 public static final Locale PRC = CHINA;
147
148 /**
149 * Locale which represents Taiwan.
150 * Same as TRADITIONAL_CHINESE Locale.
151 */
152 public static final Locale TAIWAN = TRADITIONAL_CHINESE;
153
154 /** Locale which represents the United Kingdom. */
155 public static final Locale UK = getLocale("en", "GB");
156
157 /** Locale which represents the United States. */
158 public static final Locale US = getLocale("en", "US");
159
160 /** Locale which represents the English speaking portion of Canada. */
161 public static final Locale CANADA = getLocale("en", "CA");
162
163 /** Locale which represents the French speaking portion of Canada. */
164 public static final Locale CANADA_FRENCH = getLocale("fr", "CA");
165
166 /** The root locale, used as the base case in lookups by
167 * locale-sensitive operations.
168 */
169 public static final Locale ROOT = new Locale("","","");
170
171 /**
172 * Compatible with JDK 1.1+.
173 */
174 private static final long serialVersionUID = 9149081749638150636L;
175
176 /**
177 * The language code, as returned by getLanguage().
178 *
179 * @serial the languange, possibly ""
180 */
181 private String language;
182
183 /**
184 * The country code, as returned by getCountry().
185 *
186 * @serial the country, possibly ""
187 */
188 private String country;
189
190 /**
191 * The variant code, as returned by getVariant().
192 *
193 * @serial the variant, possibly ""
194 */
195 private String variant;
196
197 /**
198 * This is the cached hashcode. When writing to stream, we write -1.
199 *
200 * @serial should be -1 in serial streams
201 */
202 private int hashcode;
203
204 /**
205 * Array storing all available locales.
206 */
207 private static transient Locale[] availableLocales;
208
209 /**
210 * Locale cache. Only created locale objects are stored.
211 * Contains all supported locales when getAvailableLocales()
212 * got called.
213 */
214 private static transient HashMap localeMap;
215
216 /**
217 * The default locale. Except for during bootstrapping, this should never be
218 * null. Note the logic in the main constructor, to detect when
219 * bootstrapping has completed.
220 */
221 private static Locale defaultLocale;
222
223 static {
224 String language = SystemProperties.getProperty("user.language", "en");
225 String country = SystemProperties.getProperty("user.country", "US");
226 String region = SystemProperties.getProperty("user.region", null);
227 String variant = SystemProperties.getProperty("user.variant", "");
228
229 defaultLocale = getLocale(language,
230 (region != null) ? region : country,
231 variant);
232 }
233
234 /**
235 * Array storing all the available two-letter ISO639 languages.
236 */
237 private static transient String[] languageCache;
238
239 /**
240 * Array storing all the available two-letter ISO3166 country codes.
241 */
242 private static transient String[] countryCache;
243
244 /**
245 * Retrieves the locale with the specified language from the cache.
246 *
247 * @param language the language of the locale to retrieve.
248 * @return the locale.
249 */
250 private static Locale getLocale(String language)
251 {
252 return getLocale(language, "", "");
253 }
254
255 /**
256 * Retrieves the locale with the specified language and country
257 * from the cache.
258 *
259 * @param language the language of the locale to retrieve.
260 * @param country the country of the locale to retrieve.
261 * @return the locale.
262 */
263 private static Locale getLocale(String language, String country)
264 {
265 return getLocale(language, country, "");
266 }
267
268 /**
269 * Retrieves the locale with the specified language, country
270 * and variant from the cache.
271 *
272 * @param language the language of the locale to retrieve.
273 * @param country the country of the locale to retrieve.
274 * @param variant the variant of the locale to retrieve.
275 * @return the locale.
276 */
277 private static Locale getLocale(String language, String country, String variant)
278 {
279 if (localeMap == null)
280 localeMap = new HashMap(256);
281
282 String name = language + "_" + country + "_" + variant;
283 Locale locale = (Locale) localeMap.get(name);
284
285 if (locale == null)
286 {
287 locale = new Locale(language, country, variant);
288 localeMap.put(name, locale);
289 }
290
291 return locale;
292 }
293
294 /**
295 * Convert new iso639 codes to the old ones.
296 *
297 * @param language the language to check
298 * @return the appropriate code
299 */
300 private String convertLanguage(String language)
301 {
302 if (language.equals(""))
303 return language;
304 language = language.toLowerCase();
305 int index = "he,id,yi".indexOf(language);
306 if (index != -1)
307 return "iw,in,ji".substring(index, index + 2);
308 return language;
309 }
310
311 /**
312 * Creates a new locale for the given language and country.
313 *
314 * @param language lowercase two-letter ISO-639 A2 language code
315 * @param country uppercase two-letter ISO-3166 A2 contry code
316 * @param variant vendor and browser specific
317 * @throws NullPointerException if any argument is null
318 */
319 public Locale(String language, String country, String variant)
320 {
321 // During bootstrap, we already know the strings being passed in are
322 // the correct capitalization, and not null. We can't call
323 // String.toUpperCase during this time, since that depends on the
324 // default locale.
325 if (defaultLocale != null)
326 {
327 language = convertLanguage(language).intern();
328 country = country.toUpperCase().intern();
329 variant = variant.intern();
330 }
331 this.language = language;
332 this.country = country;
333 this.variant = variant;
334 hashcode = language.hashCode() ^ country.hashCode() ^ variant.hashCode();
335 }
336
337 /**
338 * Creates a new locale for the given language and country.
339 *
340 * @param language lowercase two-letter ISO-639 A2 language code
341 * @param country uppercase two-letter ISO-3166 A2 country code
342 * @throws NullPointerException if either argument is null
343 */
344 public Locale(String language, String country)
345 {
346 this(language, country, "");
347 }
348
349 /**
350 * Creates a new locale for a language.
351 *
352 * @param language lowercase two-letter ISO-639 A2 language code
353 * @throws NullPointerException if either argument is null
354 * @since 1.4
355 */
356 public Locale(String language)
357 {
358 this(language, "", "");
359 }
360
361 /**
362 * Returns the default Locale. The default locale is generally once set
363 * on start up and then never changed. Normally you should use this locale
364 * for everywhere you need a locale. The initial setting matches the
365 * default locale, the user has chosen.
366 *
367 * @return the default locale for this virtual machine
368 */
369 public static Locale getDefault()
370 {
371 return defaultLocale;
372 }
373
374 /**
375 * Changes the default locale. Normally only called on program start up.
376 * Note that this doesn't change the locale for other programs. This has
377 * a security check,
378 * <code>PropertyPermission("user.language", "write")</code>, because of
379 * its potential impact to running code.
380 *
381 * @param newLocale the new default locale
382 * @throws NullPointerException if newLocale is null
383 * @throws SecurityException if permission is denied
384 */
385 public static void setDefault(Locale newLocale)
386 {
387 if (newLocale == null)
388 throw new NullPointerException();
389 SecurityManager sm = System.getSecurityManager();
390 if (sm != null)
391 sm.checkPermission(new PropertyPermission("user.language", "write"));
392 defaultLocale = newLocale;
393 }
394
395 /**
396 * Returns the list of available locales.
397 *
398 * @return the installed locales
399 */
400 public static synchronized Locale[] getAvailableLocales()
401 {
402 if (availableLocales == null)
403 {
404 int len = LocaleHelper.getLocaleCount();
405 availableLocales = new Locale[len];
406
407 for (int i = 0; i < len; i++)
408 {
409 String language;
410 String country = "";
411 String variant = "";
412 String name = LocaleHelper.getLocaleName(i);
413
414 language = name.substring(0, 2);
415
416 if (name.length() > 2)
417 country = name.substring(3);
418
419 int index = country.indexOf("_");
420 if (index > 0)
421 {
422 variant = country.substring(index + 1);
423 country = country.substring(0, index - 1);
424 }
425
426 availableLocales[i] = getLocale(language, country, variant);
427 }
428 }
429
430 return (Locale[]) availableLocales.clone();
431 }
432
433 /**
434 * Returns a list of all 2-letter uppercase country codes as defined
435 * in ISO 3166.
436 *
437 * @return a list of acceptable country codes
438 */
439 public static String[] getISOCountries()
440 {
441 if (countryCache == null)
442 {
443 countryCache = getISOStrings("territories");
444 }
445
446 return (String[]) countryCache.clone();
447 }
448
449 /**
450 * Returns a list of all 2-letter lowercase language codes as defined
451 * in ISO 639 (both old and new variant).
452 *
453 * @return a list of acceptable language codes
454 */
455 public static String[] getISOLanguages()
456 {
457 if (languageCache == null)
458 {
459 languageCache = getISOStrings("languages");
460 }
461 return (String[]) languageCache.clone();
462 }
463
464 /**
465 * Returns the set of keys from the specified resource hashtable, filtered
466 * so that only two letter strings are returned.
467 *
468 * @param tableName the name of the table from which to retrieve the keys.
469 * @return an array of two-letter strings.
470 */
471 private static String[] getISOStrings(String tableName)
472 {
473 int count = 0;
474 ResourceBundle bundle =
475 ResourceBundle.getBundle("gnu.java.locale.LocaleInformation");
476 Enumeration e = bundle.getKeys();
477 ArrayList tempList = new ArrayList();
478
479 while (e.hasMoreElements())
480 {
481 String key = (String) e.nextElement();
482
483 if (key.startsWith(tableName + "."))
484 {
485 String str = key.substring(tableName.length() + 1);
486
487 if (str.length() == 2
488 && Character.isLetter(str.charAt(0))
489 && Character.isLetter(str.charAt(1)))
490 {
491 tempList.add(str);
492 ++count;
493 }
494 }
495 }
496
497 String[] strings = new String[count];
498
499 for (int a = 0; a < count; ++a)
500 strings[a] = (String) tempList.get(a);
501
502 return strings;
503 }
504
505 /**
506 * Returns the language code of this locale. Some language codes have changed
507 * as ISO 639 has evolved; this returns the old name, even if you built
508 * the locale with the new one.
509 *
510 * @return language code portion of this locale, or an empty String
511 */
512 public String getLanguage()
513 {
514 return language;
515 }
516
517 /**
518 * Returns the country code of this locale.
519 *
520 * @return country code portion of this locale, or an empty String
521 */
522 public String getCountry()
523 {
524 return country;
525 }
526
527 /**
528 * Returns the variant code of this locale.
529 *
530 * @return the variant code portion of this locale, or an empty String
531 */
532 public String getVariant()
533 {
534 return variant;
535 }
536
537 /**
538 * Gets the string representation of the current locale. This consists of
539 * the language, the country, and the variant, separated by an underscore.
540 * The variant is listed only if there is a language or country. Examples:
541 * "en", "de_DE", "_GB", "en_US_WIN", "de__POSIX", "fr__MAC".
542 *
543 * @return the string representation of this Locale
544 * @see #getDisplayName()
545 */
546 public String toString()
547 {
548 if (language.length() == 0 && country.length() == 0)
549 return "";
550 else if (country.length() == 0 && variant.length() == 0)
551 return language;
552 StringBuffer result = new StringBuffer(language);
553 result.append('_').append(country);
554 if (variant.length() != 0)
555 result.append('_').append(variant);
556 return result.toString();
557 }
558
559 /**
560 * Returns the three-letter ISO language abbrevation of this locale.
561 *
562 * @throws MissingResourceException if the three-letter code is not known
563 */
564 public String getISO3Language()
565 {
566 // We know all strings are interned so we can use '==' for better performance.
567 if (language == "")
568 return "";
569 int index
570 = ("aa,ab,af,am,ar,as,ay,az,ba,be,bg,bh,bi,bn,bo,br,ca,co,cs,cy,da,"
571 + "de,dz,el,en,eo,es,et,eu,fa,fi,fj,fo,fr,fy,ga,gd,gl,gn,gu,ha,iw,"
572 + "hi,hr,hu,hy,ia,in,ie,ik,in,is,it,iu,iw,ja,ji,jw,ka,kk,kl,km,kn,"
573 + "ko,ks,ku,ky,la,ln,lo,lt,lv,mg,mi,mk,ml,mn,mo,mr,ms,mt,my,na,ne,"
574 + "nl,no,oc,om,or,pa,pl,ps,pt,qu,rm,rn,ro,ru,rw,sa,sd,sg,sh,si,sk,"
575 + "sl,sm,sn,so,sq,sr,ss,st,su,sv,sw,ta,te,tg,th,ti,tk,tl,tn,to,tr,"
576 + "ts,tt,tw,ug,uk,ur,uz,vi,vo,wo,xh,ji,yo,za,zh,zu")
577 .indexOf(language);
578
579 if (index % 3 != 0 || language.length() != 2)
580 throw new MissingResourceException
581 ("Can't find ISO3 language for " + language,
582 "java.util.Locale", language);
583
584 // Don't read this aloud. These are the three letter language codes.
585 return
586 ("aarabkaframharaasmaymazebakbelbulbihbisbenbodbrecatcoscescymdandeu"
587 + "dzoellengepospaesteusfasfinfijfaofrafrygaigdhglggrngujhauhebhinhrv"
588 + "hunhyeinaindileipkindislitaikuhebjpnyidjawkatkazkalkhmkankorkaskur"
589 + "kirlatlinlaolitlavmlgmrimkdmalmonmolmarmsamltmyanaunepnldnorociorm"
590 + "oripanpolpusporquerohrunronruskinsansndsagsrpsinslkslvsmosnasomsqi"
591 + "srpsswsotsunsweswatamteltgkthatirtuktgltsntonturtsotattwiuigukrurd"
592 + "uzbvievolwolxhoyidyorzhazhozul")
593 .substring(index, index + 3);
594 }
595
596 /**
597 * Returns the three-letter ISO country abbrevation of the locale.
598 *
599 * @throws MissingResourceException if the three-letter code is not known
600 */
601 public String getISO3Country()
602 {
603 // We know all strings are interned so we can use '==' for better performance.
604 if (country == "")
605 return "";
606 int index
607 = ("AD,AE,AF,AG,AI,AL,AM,AN,AO,AQ,AR,AS,AT,AU,AW,AZ,BA,BB,BD,BE,BF,"
608 + "BG,BH,BI,BJ,BM,BN,BO,BR,BS,BT,BV,BW,BY,BZ,CA,CC,CF,CG,CH,CI,CK,"
609 + "CL,CM,CN,CO,CR,CU,CV,CX,CY,CZ,DE,DJ,DK,DM,DO,DZ,EC,EE,EG,EH,ER,"
610 + "ES,ET,FI,FJ,FK,FM,FO,FR,FX,GA,GB,GD,GE,GF,GH,GI,GL,GM,GN,GP,GQ,"
611 + "GR,GS,GT,GU,GW,GY,HK,HM,HN,HR,HT,HU,ID,IE,IL,IN,IO,IQ,IR,IS,IT,"
612 + "JM,JO,JP,KE,KG,KH,KI,KM,KN,KP,KR,KW,KY,KZ,LA,LB,LC,LI,LK,LR,LS,"
613 + "LT,LU,LV,LY,MA,MC,MD,MG,MH,MK,ML,MM,MN,MO,MP,MQ,MR,MS,MT,MU,MV,"
614 + "MW,MX,MY,MZ,NA,NC,NE,NF,NG,NI,NL,NO,NP,NR,NU,NZ,OM,PA,PE,PF,PG,"
615 + "PH,PK,PL,PM,PN,PR,PT,PW,PY,QA,RE,RO,RU,RW,SA,SB,SC,SD,SE,SG,SH,"
616 + "SI,SJ,SK,SL,SM,SN,SO,SR,ST,SV,SY,SZ,TC,TD,TF,TG,TH,TJ,TK,TM,TN,"
617 + "TO,TP,TR,TT,TV,TW,TZ,UA,UG,UM,US,UY,UZ,VA,VC,VE,VG,VI,VN,VU,WF,"
618 + "WS,YE,YT,YU,ZA,ZM,ZR,ZW")
619 .indexOf(country);
620
621 if (index % 3 != 0 || country.length() != 2)
622 throw new MissingResourceException
623 ("Can't find ISO3 country for " + country,
624 "java.util.Locale", country);
625
626 // Don't read this aloud. These are the three letter country codes.
627 return
628 ("ANDAREAFGATGAIAALBARMANTAGOATAARGASMAUTAUSABWAZEBIHBRBBGDBELBFABGR"
629 + "BHRBDIBENBMUBRNBOLBRABHSBTNBVTBWABLRBLZCANCCKCAFCOGCHECIVCOKCHLCMR"
630 + "CHNCOLCRICUBCPVCXRCYPCZEDEUDJIDNKDMADOMDZAECUESTEGYESHERIESPETHFIN"
631 + "FJIFLKFSMFROFRAFXXGABGBRGRDGEOGUFGHAGIBGRLGMBGINGLPGNQGRCSGSGTMGUM"
632 + "GNBGUYHKGHMDHNDHRVHTIHUNIDNIRLISRINDIOTIRQIRNISLITAJAMJORJPNKENKGZ"
633 + "KHMKIRCOMKNAPRKKORKWTCYMKAZLAOLBNLCALIELKALBRLSOLTULUXLVALBYMARMCO"
634 + "MDAMDGMHLMKDMLIMMRMNGMACMNPMTQMRTMSRMLTMUSMDVMWIMEXMYSMOZNAMNCLNER"
635 + "NFKNGANICNLDNORNPLNRUNIUNZLOMNPANPERPYFPNGPHLPAKPOLSPMPCNPRIPRTPLW"
636 + "PRYQATREUROMRUSRWASAUSLBSYCSDNSWESGPSHNSVNSJMSVKSLESMRSENSOMSURSTP"
637 + "SLVSYRSWZTCATCDATFTGOTHATJKTKLTKMTUNTONTMPTURTTOTUVTWNTZAUKRUGAUMI"
638 + "USAURYUZBVATVCTVENVGBVIRVNMVUTWLFWSMYEMMYTYUGZAFZMBZARZWE")
639 .substring(index, index + 3);
640 }
641
642 /**
643 * Gets the country name suitable for display to the user, formatted
644 * for the default locale. This has the same effect as
645 * <pre>
646 * getDisplayLanguage(Locale.getDefault());
647 * </pre>
648 *
649 * @return the language name of this locale localized to the default locale,
650 * with the ISO code as backup
651 */
652 public String getDisplayLanguage()
653 {
654 return getDisplayLanguage(defaultLocale);
655 }
656
657 /**
658 * <p>
659 * Gets the name of the language specified by this locale, in a form suitable
660 * for display to the user. If possible, the display name will be localized
661 * to the specified locale. For example, if the locale instance is
662 * <code>Locale.GERMANY</code>, and the specified locale is <code>Locale.UK</code>,
663 * the result would be 'German'. Using the German locale would instead give
664 * 'Deutsch'. If the display name can not be localized to the supplied
665 * locale, it will fall back on other output in the following order:
666 * </p>
667 * <ul>
668 * <li>the display name in the default locale</li>
669 * <li>the display name in English</li>
670 * <li>the ISO code</li>
671 * </ul>
672 * <p>
673 * If the language is unspecified by this locale, then the empty string is
674 * returned.
675 * </p>
676 *
677 * @param inLocale the locale to use for formatting the display string.
678 * @return the language name of this locale localized to the given locale,
679 * with the default locale, English and the ISO code as backups.
680 * @throws NullPointerException if the supplied locale is null.
681 */
682 public String getDisplayLanguage(Locale inLocale)
683 {
684 if (language.isEmpty())
685 return "";
686 try
687 {
688 ResourceBundle res =
689 ResourceBundle.getBundle("gnu.java.locale.LocaleInformation",
690 inLocale,
691 ClassLoader.getSystemClassLoader());
692
693 return res.getString("languages." + language);
694 }
695 catch (MissingResourceException e)
696 {
697 /* This means runtime support for the locale
698 * is not available, so we check providers. */
699 }
700 for (LocaleNameProvider p :
701 ServiceLoader.load(LocaleNameProvider.class))
702 {
703 for (Locale loc : p.getAvailableLocales())
704 {
705 if (loc.equals(inLocale))
706 {
707 String locLang = p.getDisplayLanguage(language,
708 inLocale);
709 if (locLang != null)
710 return locLang;
711 break;
712 }
713 }
714 }
715 if (inLocale.equals(Locale.ROOT)) // Base case
716 return language;
717 return getDisplayLanguage(LocaleHelper.getFallbackLocale(inLocale));
718 }
719
720 /**
721 * Returns the country name of this locale localized to the
722 * default locale. If the localized is not found, the ISO code
723 * is returned. This has the same effect as
724 * <pre>
725 * getDisplayCountry(Locale.getDefault());
726 * </pre>
727 *
728 * @return the country name of this locale localized to the given locale,
729 * with the ISO code as backup
730 */
731 public String getDisplayCountry()
732 {
733 return getDisplayCountry(defaultLocale);
734 }
735
736 /**
737 * <p>
738 * Gets the name of the country specified by this locale, in a form suitable
739 * for display to the user. If possible, the display name will be localized
740 * to the specified locale. For example, if the locale instance is
741 * <code>Locale.GERMANY</code>, and the specified locale is <code>Locale.UK</code>,
742 * the result would be 'Germany'. Using the German locale would instead give
743 * 'Deutschland'. If the display name can not be localized to the supplied
744 * locale, it will fall back on other output in the following order:
745 * </p>
746 * <ul>
747 * <li>the display name in the default locale</li>
748 * <li>the display name in English</li>
749 * <li>the ISO code</li>
750 * </ul>
751 * <p>
752 * If the country is unspecified by this locale, then the empty string is
753 * returned.
754 * </p>
755 *
756 * @param inLocale the locale to use for formatting the display string.
757 * @return the country name of this locale localized to the given locale,
758 * with the default locale, English and the ISO code as backups.
759 * @throws NullPointerException if the supplied locale is null.
760 */
761 public String getDisplayCountry(Locale inLocale)
762 {
763 if (country.isEmpty())
764 return "";
765 try
766 {
767 ResourceBundle res =
768 ResourceBundle.getBundle("gnu.java.locale.LocaleInformation",
769 inLocale,
770 ClassLoader.getSystemClassLoader());
771
772 return res.getString("territories." + country);
773 }
774 catch (MissingResourceException e)
775 {
776 /* This means runtime support for the locale
777 * is not available, so we check providers. */
778 }
779 for (LocaleNameProvider p :
780 ServiceLoader.load(LocaleNameProvider.class))
781 {
782 for (Locale loc : p.getAvailableLocales())
783 {
784 if (loc.equals(inLocale))
785 {
786 String locCountry = p.getDisplayCountry(country,
787 inLocale);
788 if (locCountry != null)
789 return locCountry;
790 break;
791 }
792 }
793 }
794 if (inLocale.equals(Locale.ROOT)) // Base case
795 return country;
796 return getDisplayCountry(LocaleHelper.getFallbackLocale(inLocale));
797 }
798
799 /**
800 * Returns the variant name of this locale localized to the
801 * default locale. If the localized is not found, the variant code
802 * itself is returned. This has the same effect as
803 * <pre>
804 * getDisplayVariant(Locale.getDefault());
805 * </pre>
806 *
807 * @return the variant code of this locale localized to the given locale,
808 * with the ISO code as backup
809 */
810 public String getDisplayVariant()
811 {
812 return getDisplayVariant(defaultLocale);
813 }
814
815
816 /**
817 * <p>
818 * Gets the name of the variant specified by this locale, in a form suitable
819 * for display to the user. If possible, the display name will be localized
820 * to the specified locale. For example, if the locale instance is a revised
821 * variant, and the specified locale is <code>Locale.UK</code>, the result
822 * would be 'REVISED'. Using the German locale would instead give
823 * 'Revidiert'. If the display name can not be localized to the supplied
824 * locale, it will fall back on other output in the following order:
825 * </p>
826 * <ul>
827 * <li>the display name in the default locale</li>
828 * <li>the display name in English</li>
829 * <li>the ISO code</li>
830 * </ul>
831 * <p>
832 * If the variant is unspecified by this locale, then the empty string is
833 * returned.
834 * </p>
835 *
836 * @param inLocale the locale to use for formatting the display string.
837 * @return the variant name of this locale localized to the given locale,
838 * with the default locale, English and the ISO code as backups.
839 * @throws NullPointerException if the supplied locale is null.
840 */
841 public String getDisplayVariant(Locale inLocale)
842 {
843 if (variant.isEmpty())
844 return "";
845 try
846 {
847 ResourceBundle res =
848 ResourceBundle.getBundle("gnu.java.locale.LocaleInformation",
849 inLocale,
850 ClassLoader.getSystemClassLoader());
851
852 return res.getString("variants." + variant);
853 }
854 catch (MissingResourceException e)
855 {
856 /* This means runtime support for the locale
857 * is not available, so we check providers. */
858 }
859 for (LocaleNameProvider p :
860 ServiceLoader.load(LocaleNameProvider.class))
861 {
862 for (Locale loc : p.getAvailableLocales())
863 {
864 if (loc.equals(inLocale))
865 {
866 String locVar = p.getDisplayVariant(variant,
867 inLocale);
868 if (locVar != null)
869 return locVar;
870 break;
871 }
872 }
873 }
874 if (inLocale.equals(Locale.ROOT)) // Base case
875 return country;
876 return getDisplayVariant(LocaleHelper.getFallbackLocale(inLocale));
877 }
878
879 /**
880 * Gets all local components suitable for display to the user, formatted
881 * for the default locale. For the language component, getDisplayLanguage
882 * is called. For the country component, getDisplayCountry is called.
883 * For the variant set component, getDisplayVariant is called.
884 *
885 * <p>The returned String will be one of the following forms:<br>
886 * <pre>
887 * language (country, variant)
888 * language (country)
889 * language (variant)
890 * country (variant)
891 * language
892 * country
893 * variant
894 * </pre>
895 *
896 * @return String version of this locale, suitable for display to the user
897 */
898 public String getDisplayName()
899 {
900 return getDisplayName(defaultLocale);
901 }
902
903 /**
904 * Gets all local components suitable for display to the user, formatted
905 * for a specified locale. For the language component,
906 * getDisplayLanguage(Locale) is called. For the country component,
907 * getDisplayCountry(Locale) is called. For the variant set component,
908 * getDisplayVariant(Locale) is called.
909 *
910 * <p>The returned String will be one of the following forms:<br>
911 * <pre>
912 * language (country, variant)
913 * language (country)
914 * language (variant)
915 * country (variant)
916 * language
917 * country
918 * variant
919 * </pre>
920 *
921 * @param locale locale to use for formatting
922 * @return String version of this locale, suitable for display to the user
923 */
924 public String getDisplayName(Locale locale)
925 {
926 StringBuffer result = new StringBuffer();
927 int count = 0;
928 String[] delimiters = {"", " (", ","};
929 if (language.length() != 0)
930 {
931 result.append(delimiters[count++]);
932 result.append(getDisplayLanguage(locale));
933 }
934 if (country.length() != 0)
935 {
936 result.append(delimiters[count++]);
937 result.append(getDisplayCountry(locale));
938 }
939 if (variant.length() != 0)
940 {
941 result.append(delimiters[count++]);
942 result.append(getDisplayVariant(locale));
943 }
944 if (count > 1)
945 result.append(")");
946 return result.toString();
947 }
948
949 /**
950 * Does the same as <code>Object.clone()</code> but does not throw
951 * a <code>CloneNotSupportedException</code>. Why anyone would
952 * use this method is a secret to me, since this class is immutable.
953 *
954 * @return the clone
955 */
956 public Object clone()
957 {
958 // This class is final, so no need to use native super.clone().
959 return new Locale(language, country, variant);
960 }
961
962 /**
963 * Return the hash code for this locale. The hashcode is the logical
964 * xor of the hash codes of the language, the country and the variant.
965 * The hash code is precomputed, since <code>Locale</code>s are often
966 * used in hash tables.
967 *
968 * @return the hashcode
969 */
970 public int hashCode()
971 {
972 return hashcode;
973 }
974
975 /**
976 * Compares two locales. To be equal, obj must be a Locale with the same
977 * language, country, and variant code.
978 *
979 * @param obj the other locale
980 * @return true if obj is equal to this
981 */
982 public boolean equals(Object obj)
983 {
984 if (this == obj)
985 return true;
986 if (! (obj instanceof Locale))
987 return false;
988 Locale l = (Locale) obj;
989
990 return (language == l.language
991 && country == l.country
992 && variant == l.variant);
993 }
994
995 /**
996 * Write the locale to an object stream.
997 *
998 * @param s the stream to write to
999 * @throws IOException if the write fails
1000 * @serialData The first three fields are Strings representing language,
1001 * country, and variant. The fourth field is a placeholder for
1002 * the cached hashcode, but this is always written as -1, and
1003 * recomputed when reading it back.
1004 */
1005 private void writeObject(ObjectOutputStream s)
1006 throws IOException
1007 {
1008 ObjectOutputStream.PutField fields = s.putFields();
1009 fields.put("hashcode", -1);
1010 s.defaultWriteObject();
1011 }
1012
1013 /**
1014 * Reads a locale from the input stream.
1015 *
1016 * @param s the stream to read from
1017 * @throws IOException if reading fails
1018 * @throws ClassNotFoundException if reading fails
1019 * @serialData the hashCode is always invalid and must be recomputed
1020 */
1021 private void readObject(ObjectInputStream s)
1022 throws IOException, ClassNotFoundException
1023 {
1024 s.defaultReadObject();
1025 language = language.intern();
1026 country = country.intern();
1027 variant = variant.intern();
1028 hashcode = language.hashCode() ^ country.hashCode() ^ variant.hashCode();
1029 }
1030 } // class Locale