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