1 /* 2 * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 /* 27 * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved 28 * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved 29 * 30 * The original version of this source code and documentation 31 * is copyrighted and owned by Taligent, Inc., a wholly-owned 32 * subsidiary of IBM. These materials are provided under terms 33 * of a License Agreement between Taligent and Sun. This technology 34 * is protected by multiple US and International patents. 35 * 36 * This notice and attribution to Taligent may not be removed. 37 * Taligent is a registered trademark of Taligent, Inc. 38 * 39 */ 40 41 package java.util; 42 43 import java.io.IOException; 44 import java.io.ObjectInputStream; 45 import java.io.ObjectOutputStream; 46 import java.io.ObjectStreamField; 47 import java.io.Serializable; 48 import java.security.AccessController; 49 import java.text.MessageFormat; 50 import java.util.spi.LocaleNameProvider; 51 52 import sun.security.action.GetPropertyAction; 53 import sun.util.locale.provider.LocaleServiceProviderPool; 54 import sun.util.locale.BaseLocale; 55 import sun.util.locale.InternalLocaleBuilder; 56 import sun.util.locale.LanguageTag; 57 import sun.util.locale.LocaleExtensions; 58 import sun.util.locale.LocaleMatcher; 59 import sun.util.locale.LocaleObjectCache; 60 import sun.util.locale.LocaleSyntaxException; 61 import sun.util.locale.LocaleUtils; 62 import sun.util.locale.ParseStatus; 63 import sun.util.locale.provider.LocaleProviderAdapter; 64 import sun.util.resources.OpenListResourceBundle; 65 66 /** 67 * A <code>Locale</code> object represents a specific geographical, political, 68 * or cultural region. An operation that requires a <code>Locale</code> to perform 69 * its task is called <em>locale-sensitive</em> and uses the <code>Locale</code> 70 * to tailor information for the user. For example, displaying a number 71 * is a locale-sensitive operation— the number should be formatted 72 * according to the customs and conventions of the user's native country, 73 * region, or culture. 74 * 75 * <p> The {@code Locale} class implements IETF BCP 47 which is composed of 76 * <a href="http://tools.ietf.org/html/rfc4647">RFC 4647 "Matching of Language 77 * Tags"</a> and <a href="http://tools.ietf.org/html/rfc5646">RFC 5646 "Tags 78 * for Identifying Languages"</a> with support for the LDML (UTS#35, "Unicode 79 * Locale Data Markup Language") BCP 47-compatible extensions for locale data 80 * exchange. 81 * 82 * <p> A <code>Locale</code> object logically consists of the fields 83 * described below. 84 * 85 * <dl> 86 * <dt><a name="def_language"/><b>language</b></dt> 87 * 88 * <dd>ISO 639 alpha-2 or alpha-3 language code, or registered 89 * language subtags up to 8 alpha letters (for future enhancements). 90 * When a language has both an alpha-2 code and an alpha-3 code, the 91 * alpha-2 code must be used. You can find a full list of valid 92 * language codes in the IANA Language Subtag Registry (search for 93 * "Type: language"). The language field is case insensitive, but 94 * <code>Locale</code> always canonicalizes to lower case.</dd><br> 95 * 96 * <dd>Well-formed language values have the form 97 * <code>[a-zA-Z]{2,8}</code>. Note that this is not the the full 98 * BCP47 language production, since it excludes extlang. They are 99 * not needed since modern three-letter language codes replace 100 * them.</dd><br> 101 * 102 * <dd>Example: "en" (English), "ja" (Japanese), "kok" (Konkani)</dd><br> 103 * 104 * <dt><a name="def_script"/><b>script</b></dt> 105 * 106 * <dd>ISO 15924 alpha-4 script code. You can find a full list of 107 * valid script codes in the IANA Language Subtag Registry (search 108 * for "Type: script"). The script field is case insensitive, but 109 * <code>Locale</code> always canonicalizes to title case (the first 110 * letter is upper case and the rest of the letters are lower 111 * case).</dd><br> 112 * 113 * <dd>Well-formed script values have the form 114 * <code>[a-zA-Z]{4}</code></dd><br> 115 * 116 * <dd>Example: "Latn" (Latin), "Cyrl" (Cyrillic)</dd><br> 117 * 118 * <dt><a name="def_region"/><b>country (region)</b></dt> 119 * 120 * <dd>ISO 3166 alpha-2 country code or UN M.49 numeric-3 area code. 121 * You can find a full list of valid country and region codes in the 122 * IANA Language Subtag Registry (search for "Type: region"). The 123 * country (region) field is case insensitive, but 124 * <code>Locale</code> always canonicalizes to upper case.</dd><br> 125 * 126 * <dd>Well-formed country/region values have 127 * the form <code>[a-zA-Z]{2} | [0-9]{3}</code></dd><br> 128 * 129 * <dd>Example: "US" (United States), "FR" (France), "029" 130 * (Caribbean)</dd><br> 131 * 132 * <dt><a name="def_variant"/><b>variant</b></dt> 133 * 134 * <dd>Any arbitrary value used to indicate a variation of a 135 * <code>Locale</code>. Where there are two or more variant values 136 * each indicating its own semantics, these values should be ordered 137 * by importance, with most important first, separated by 138 * underscore('_'). The variant field is case sensitive.</dd><br> 139 * 140 * <dd>Note: IETF BCP 47 places syntactic restrictions on variant 141 * subtags. Also BCP 47 subtags are strictly used to indicate 142 * additional variations that define a language or its dialects that 143 * are not covered by any combinations of language, script and 144 * region subtags. You can find a full list of valid variant codes 145 * in the IANA Language Subtag Registry (search for "Type: variant"). 146 * 147 * <p>However, the variant field in <code>Locale</code> has 148 * historically been used for any kind of variation, not just 149 * language variations. For example, some supported variants 150 * available in Java SE Runtime Environments indicate alternative 151 * cultural behaviors such as calendar type or number script. In 152 * BCP 47 this kind of information, which does not identify the 153 * language, is supported by extension subtags or private use 154 * subtags.</dd><br> 155 * 156 * <dd>Well-formed variant values have the form <code>SUBTAG 157 * (('_'|'-') SUBTAG)*</code> where <code>SUBTAG = 158 * [0-9][0-9a-zA-Z]{3} | [0-9a-zA-Z]{5,8}</code>. (Note: BCP 47 only 159 * uses hyphen ('-') as a delimiter, this is more lenient).</dd><br> 160 * 161 * <dd>Example: "polyton" (Polytonic Greek), "POSIX"</dd><br> 162 * 163 * <dt><a name="def_extensions"/><b>extensions</b></dt> 164 * 165 * <dd>A map from single character keys to string values, indicating 166 * extensions apart from language identification. The extensions in 167 * <code>Locale</code> implement the semantics and syntax of BCP 47 168 * extension subtags and private use subtags. The extensions are 169 * case insensitive, but <code>Locale</code> canonicalizes all 170 * extension keys and values to lower case. Note that extensions 171 * cannot have empty values.</dd><br> 172 * 173 * <dd>Well-formed keys are single characters from the set 174 * <code>[0-9a-zA-Z]</code>. Well-formed values have the form 175 * <code>SUBTAG ('-' SUBTAG)*</code> where for the key 'x' 176 * <code>SUBTAG = [0-9a-zA-Z]{1,8}</code> and for other keys 177 * <code>SUBTAG = [0-9a-zA-Z]{2,8}</code> (that is, 'x' allows 178 * single-character subtags).</dd><br> 179 * 180 * <dd>Example: key="u"/value="ca-japanese" (Japanese Calendar), 181 * key="x"/value="java-1-7"</dd> 182 * </dl> 183 * 184 * <b>Note:</b> Although BCP 47 requires field values to be registered 185 * in the IANA Language Subtag Registry, the <code>Locale</code> class 186 * does not provide any validation features. The <code>Builder</code> 187 * only checks if an individual field satisfies the syntactic 188 * requirement (is well-formed), but does not validate the value 189 * itself. See {@link Builder} for details. 190 * 191 * <h4><a name="def_locale_extension">Unicode locale/language extension</h4> 192 * 193 * <p>UTS#35, "Unicode Locale Data Markup Language" defines optional 194 * attributes and keywords to override or refine the default behavior 195 * associated with a locale. A keyword is represented by a pair of 196 * key and type. For example, "nu-thai" indicates that Thai local 197 * digits (value:"thai") should be used for formatting numbers 198 * (key:"nu"). 199 * 200 * <p>The keywords are mapped to a BCP 47 extension value using the 201 * extension key 'u' ({@link #UNICODE_LOCALE_EXTENSION}). The above 202 * example, "nu-thai", becomes the extension "u-nu-thai".code 203 * 204 * <p>Thus, when a <code>Locale</code> object contains Unicode locale 205 * attributes and keywords, 206 * <code>getExtension(UNICODE_LOCALE_EXTENSION)</code> will return a 207 * String representing this information, for example, "nu-thai". The 208 * <code>Locale</code> class also provides {@link 209 * #getUnicodeLocaleAttributes}, {@link #getUnicodeLocaleKeys}, and 210 * {@link #getUnicodeLocaleType} which allow you to access Unicode 211 * locale attributes and key/type pairs directly. When represented as 212 * a string, the Unicode Locale Extension lists attributes 213 * alphabetically, followed by key/type sequences with keys listed 214 * alphabetically (the order of subtags comprising a key's type is 215 * fixed when the type is defined) 216 * 217 * <p>A well-formed locale key has the form 218 * <code>[0-9a-zA-Z]{2}</code>. A well-formed locale type has the 219 * form <code>"" | [0-9a-zA-Z]{3,8} ('-' [0-9a-zA-Z]{3,8})*</code> (it 220 * can be empty, or a series of subtags 3-8 alphanums in length). A 221 * well-formed locale attribute has the form 222 * <code>[0-9a-zA-Z]{3,8}</code> (it is a single subtag with the same 223 * form as a locale type subtag). 224 * 225 * <p>The Unicode locale extension specifies optional behavior in 226 * locale-sensitive services. Although the LDML specification defines 227 * various keys and values, actual locale-sensitive service 228 * implementations in a Java Runtime Environment might not support any 229 * particular Unicode locale attributes or key/type pairs. 230 * 231 * <h4>Creating a Locale</h4> 232 * 233 * <p>There are several different ways to create a <code>Locale</code> 234 * object. 235 * 236 * <h5>Builder</h5> 237 * 238 * <p>Using {@link Builder} you can construct a <code>Locale</code> object 239 * that conforms to BCP 47 syntax. 240 * 241 * <h5>Constructors</h5> 242 * 243 * <p>The <code>Locale</code> class provides three constructors: 244 * <blockquote> 245 * <pre> 246 * {@link #Locale(String language)} 247 * {@link #Locale(String language, String country)} 248 * {@link #Locale(String language, String country, String variant)} 249 * </pre> 250 * </blockquote> 251 * These constructors allow you to create a <code>Locale</code> object 252 * with language, country and variant, but you cannot specify 253 * script or extensions. 254 * 255 * <h5>Factory Methods</h5> 256 * 257 * <p>The method {@link #forLanguageTag} creates a <code>Locale</code> 258 * object for a well-formed BCP 47 language tag. 259 * 260 * <h5>Locale Constants</h5> 261 * 262 * <p>The <code>Locale</code> class provides a number of convenient constants 263 * that you can use to create <code>Locale</code> objects for commonly used 264 * locales. For example, the following creates a <code>Locale</code> object 265 * for the United States: 266 * <blockquote> 267 * <pre> 268 * Locale.US 269 * </pre> 270 * </blockquote> 271 * 272 * <h4><a name="LocaleMatching">Locale Matching</a></h4> 273 * 274 * <p>If an application or a system is internationalized and provides localized 275 * resources for multiple locales, it sometimes needs to find one or more 276 * locales (or language tags) which meet each user's specific preferences. Note 277 * that a term "language tag" is used interchangeably with "locale" in this 278 * locale matching documentation. 279 * 280 * <p>In order to do matching a user's preferred locales to a set of language 281 * tags, <a href="http://tools.ietf.org/html/rfc4647">RFC 4647 Matching of 282 * Language Tags</a> defines two mechanisms: filtering and lookup. 283 * <em>Filtering</em> is used to get all matching locales, whereas 284 * <em>lookup</em> is to choose the best matching locale. 285 * Matching is done case-insensitively. These matching mechanisms are described 286 * in the following sections. 287 * 288 * <p>A user's preference is called a <em>Language Priority List</em> and is 289 * expressed as a list of language ranges. There are syntactically two types of 290 * language ranges: basic and extended. See 291 * {@link Locale.LanguageRange Locale.LanguageRange} for details. 292 * 293 * <h5>Filtering</h5> 294 * 295 * <p>The filtering operation returns all matching language tags. It is defined 296 * in RFC 4647 as follows: 297 * "In filtering, each language range represents the least specific language 298 * tag (that is, the language tag with fewest number of subtags) that is an 299 * acceptable match. All of the language tags in the matching set of tags will 300 * have an equal or greater number of subtags than the language range. Every 301 * non-wildcard subtag in the language range will appear in every one of the 302 * matching language tags." 303 * 304 * <p>There are two types of filtering: filtering for basic language ranges 305 * (called "basic filtering") and filtering for extended language ranges 306 * (called "extended filtering"). They may return different results by what 307 * kind of language ranges are included in the given Language Priority List. 308 * {@link Locale.FilteringMode} is a parameter to specify how filtering should 309 * be done. 310 * 311 * <h5>Lookup</h5> 312 * 313 * <p>The lookup operation returns the best matching language tags. It is 314 * defined in RFC 4647 as follows: 315 * "By contrast with filtering, each language range represents the most 316 * specific tag that is an acceptable match. The first matching tag found, 317 * according to the user's priority, is considered the closest match and is the 318 * item returned." 319 * 320 * <p>For example, if a Language Priority List consists of two language ranges, 321 * {@code "zh-Hant-TW"} and {@code "en-US"}, in prioritized order, lookup 322 * method progressively searches the language tags below in order to find the 323 * best matching language tag. 324 * <blockquote> 325 * <pre> 326 * 1. zh-Hant-TW 327 * 2. zh-Hant 328 * 3. zh 329 * 4. en-US 330 * 5. en 331 * </pre> 332 * </blockquote> 333 * If there is a language tag which matches completely to a language range 334 * above, the language tag is returned. 335 * 336 * <p>{@code "*"} is the special language range, and it is ignored in lookup. 337 * 338 * <p>If multiple language tags match as a result of the subtag {@code '*'} 339 * included in a language range, the first matching language tag returned by 340 * an {@link Iterator} over a {@link Collection} of language tags is treated as 341 * the best matching one. 342 * 343 * <h4>Use of Locale</h4> 344 * 345 * <p>Once you've created a <code>Locale</code> you can query it for information 346 * about itself. Use <code>getCountry</code> to get the country (or region) 347 * code and <code>getLanguage</code> to get the language code. 348 * You can use <code>getDisplayCountry</code> to get the 349 * name of the country suitable for displaying to the user. Similarly, 350 * you can use <code>getDisplayLanguage</code> to get the name of 351 * the language suitable for displaying to the user. Interestingly, 352 * the <code>getDisplayXXX</code> methods are themselves locale-sensitive 353 * and have two versions: one that uses the default locale and one 354 * that uses the locale specified as an argument. 355 * 356 * <p>The Java Platform provides a number of classes that perform locale-sensitive 357 * operations. For example, the <code>NumberFormat</code> class formats 358 * numbers, currency, and percentages in a locale-sensitive manner. Classes 359 * such as <code>NumberFormat</code> have several convenience methods 360 * for creating a default object of that type. For example, the 361 * <code>NumberFormat</code> class provides these three convenience methods 362 * for creating a default <code>NumberFormat</code> object: 363 * <blockquote> 364 * <pre> 365 * NumberFormat.getInstance() 366 * NumberFormat.getCurrencyInstance() 367 * NumberFormat.getPercentInstance() 368 * </pre> 369 * </blockquote> 370 * Each of these methods has two variants; one with an explicit locale 371 * and one without; the latter uses the default locale: 372 * <blockquote> 373 * <pre> 374 * NumberFormat.getInstance(myLocale) 375 * NumberFormat.getCurrencyInstance(myLocale) 376 * NumberFormat.getPercentInstance(myLocale) 377 * </pre> 378 * </blockquote> 379 * A <code>Locale</code> is the mechanism for identifying the kind of object 380 * (<code>NumberFormat</code>) that you would like to get. The locale is 381 * <STRONG>just</STRONG> a mechanism for identifying objects, 382 * <STRONG>not</STRONG> a container for the objects themselves. 383 * 384 * <h4>Compatibility</h4> 385 * 386 * <p>In order to maintain compatibility with existing usage, Locale's 387 * constructors retain their behavior prior to the Java Runtime 388 * Environment version 1.7. The same is largely true for the 389 * <code>toString</code> method. Thus Locale objects can continue to 390 * be used as they were. In particular, clients who parse the output 391 * of toString into language, country, and variant fields can continue 392 * to do so (although this is strongly discouraged), although the 393 * variant field will have additional information in it if script or 394 * extensions are present. 395 * 396 * <p>In addition, BCP 47 imposes syntax restrictions that are not 397 * imposed by Locale's constructors. This means that conversions 398 * between some Locales and BCP 47 language tags cannot be made without 399 * losing information. Thus <code>toLanguageTag</code> cannot 400 * represent the state of locales whose language, country, or variant 401 * do not conform to BCP 47. 402 * 403 * <p>Because of these issues, it is recommended that clients migrate 404 * away from constructing non-conforming locales and use the 405 * <code>forLanguageTag</code> and <code>Locale.Builder</code> APIs instead. 406 * Clients desiring a string representation of the complete locale can 407 * then always rely on <code>toLanguageTag</code> for this purpose. 408 * 409 * <h5><a name="special_cases_constructor"/>Special cases</h5> 410 * 411 * <p>For compatibility reasons, two 412 * non-conforming locales are treated as special cases. These are 413 * <b><tt>ja_JP_JP</tt></b> and <b><tt>th_TH_TH</tt></b>. These are ill-formed 414 * in BCP 47 since the variants are too short. To ease migration to BCP 47, 415 * these are treated specially during construction. These two cases (and only 416 * these) cause a constructor to generate an extension, all other values behave 417 * exactly as they did prior to Java 7. 418 * 419 * <p>Java has used <tt>ja_JP_JP</tt> to represent Japanese as used in 420 * Japan together with the Japanese Imperial calendar. This is now 421 * representable using a Unicode locale extension, by specifying the 422 * Unicode locale key <tt>ca</tt> (for "calendar") and type 423 * <tt>japanese</tt>. When the Locale constructor is called with the 424 * arguments "ja", "JP", "JP", the extension "u-ca-japanese" is 425 * automatically added. 426 * 427 * <p>Java has used <tt>th_TH_TH</tt> to represent Thai as used in 428 * Thailand together with Thai digits. This is also now representable using 429 * a Unicode locale extension, by specifying the Unicode locale key 430 * <tt>nu</tt> (for "number") and value <tt>thai</tt>. When the Locale 431 * constructor is called with the arguments "th", "TH", "TH", the 432 * extension "u-nu-thai" is automatically added. 433 * 434 * <h5>Serialization</h5> 435 * 436 * <p>During serialization, writeObject writes all fields to the output 437 * stream, including extensions. 438 * 439 * <p>During deserialization, readResolve adds extensions as described 440 * in <a href="#special_cases_constructor">Special Cases</a>, only 441 * for the two cases th_TH_TH and ja_JP_JP. 442 * 443 * <h5>Legacy language codes</h5> 444 * 445 * <p>Locale's constructor has always converted three language codes to 446 * their earlier, obsoleted forms: <tt>he</tt> maps to <tt>iw</tt>, 447 * <tt>yi</tt> maps to <tt>ji</tt>, and <tt>id</tt> maps to 448 * <tt>in</tt>. This continues to be the case, in order to not break 449 * backwards compatibility. 450 * 451 * <p>The APIs added in 1.7 map between the old and new language codes, 452 * maintaining the old codes internal to Locale (so that 453 * <code>getLanguage</code> and <code>toString</code> reflect the old 454 * code), but using the new codes in the BCP 47 language tag APIs (so 455 * that <code>toLanguageTag</code> reflects the new one). This 456 * preserves the equivalence between Locales no matter which code or 457 * API is used to construct them. Java's default resource bundle 458 * lookup mechanism also implements this mapping, so that resources 459 * can be named using either convention, see {@link ResourceBundle.Control}. 460 * 461 * <h5>Three-letter language/country(region) codes</h5> 462 * 463 * <p>The Locale constructors have always specified that the language 464 * and the country param be two characters in length, although in 465 * practice they have accepted any length. The specification has now 466 * been relaxed to allow language codes of two to eight characters and 467 * country (region) codes of two to three characters, and in 468 * particular, three-letter language codes and three-digit region 469 * codes as specified in the IANA Language Subtag Registry. For 470 * compatibility, the implementation still does not impose a length 471 * constraint. 472 * 473 * @see Builder 474 * @see ResourceBundle 475 * @see java.text.Format 476 * @see java.text.NumberFormat 477 * @see java.text.Collator 478 * @author Mark Davis 479 * @since 1.1 480 */ 481 public final class Locale implements Cloneable, Serializable { 482 483 static private final Cache LOCALECACHE = new Cache(); 484 485 /** Useful constant for language. 486 */ 487 static public final Locale ENGLISH = createConstant("en", ""); 488 489 /** Useful constant for language. 490 */ 491 static public final Locale FRENCH = createConstant("fr", ""); 492 493 /** Useful constant for language. 494 */ 495 static public final Locale GERMAN = createConstant("de", ""); 496 497 /** Useful constant for language. 498 */ 499 static public final Locale ITALIAN = createConstant("it", ""); 500 501 /** Useful constant for language. 502 */ 503 static public final Locale JAPANESE = createConstant("ja", ""); 504 505 /** Useful constant for language. 506 */ 507 static public final Locale KOREAN = createConstant("ko", ""); 508 509 /** Useful constant for language. 510 */ 511 static public final Locale CHINESE = createConstant("zh", ""); 512 513 /** Useful constant for language. 514 */ 515 static public final Locale SIMPLIFIED_CHINESE = createConstant("zh", "CN"); 516 517 /** Useful constant for language. 518 */ 519 static public final Locale TRADITIONAL_CHINESE = createConstant("zh", "TW"); 520 521 /** Useful constant for country. 522 */ 523 static public final Locale FRANCE = createConstant("fr", "FR"); 524 525 /** Useful constant for country. 526 */ 527 static public final Locale GERMANY = createConstant("de", "DE"); 528 529 /** Useful constant for country. 530 */ 531 static public final Locale ITALY = createConstant("it", "IT"); 532 533 /** Useful constant for country. 534 */ 535 static public final Locale JAPAN = createConstant("ja", "JP"); 536 537 /** Useful constant for country. 538 */ 539 static public final Locale KOREA = createConstant("ko", "KR"); 540 541 /** Useful constant for country. 542 */ 543 static public final Locale CHINA = SIMPLIFIED_CHINESE; 544 545 /** Useful constant for country. 546 */ 547 static public final Locale PRC = SIMPLIFIED_CHINESE; 548 549 /** Useful constant for country. 550 */ 551 static public final Locale TAIWAN = TRADITIONAL_CHINESE; 552 553 /** Useful constant for country. 554 */ 555 static public final Locale UK = createConstant("en", "GB"); 556 557 /** Useful constant for country. 558 */ 559 static public final Locale US = createConstant("en", "US"); 560 561 /** Useful constant for country. 562 */ 563 static public final Locale CANADA = createConstant("en", "CA"); 564 565 /** Useful constant for country. 566 */ 567 static public final Locale CANADA_FRENCH = createConstant("fr", "CA"); 568 569 /** 570 * Useful constant for the root locale. The root locale is the locale whose 571 * language, country, and variant are empty ("") strings. This is regarded 572 * as the base locale of all locales, and is used as the language/country 573 * neutral locale for the locale sensitive operations. 574 * 575 * @since 1.6 576 */ 577 static public final Locale ROOT = createConstant("", ""); 578 579 /** 580 * The key for the private use extension ('x'). 581 * 582 * @see #getExtension(char) 583 * @see Builder#setExtension(char, String) 584 * @since 1.7 585 */ 586 static public final char PRIVATE_USE_EXTENSION = 'x'; 587 588 /** 589 * The key for Unicode locale extension ('u'). 590 * 591 * @see #getExtension(char) 592 * @see Builder#setExtension(char, String) 593 * @since 1.7 594 */ 595 static public final char UNICODE_LOCALE_EXTENSION = 'u'; 596 597 /** serialization ID 598 */ 599 static final long serialVersionUID = 9149081749638150636L; 600 601 /** 602 * Display types for retrieving localized names from the name providers. 603 */ 604 private static final int DISPLAY_LANGUAGE = 0; 605 private static final int DISPLAY_COUNTRY = 1; 606 private static final int DISPLAY_VARIANT = 2; 607 private static final int DISPLAY_SCRIPT = 3; 608 609 /** 610 * Private constructor used by getInstance method 611 */ 612 private Locale(BaseLocale baseLocale, LocaleExtensions extensions) { 613 this.baseLocale = baseLocale; 614 this.localeExtensions = extensions; 615 } 616 617 /** 618 * Construct a locale from language, country and variant. 619 * This constructor normalizes the language value to lowercase and 620 * the country value to uppercase. 621 * <p> 622 * <b>Note:</b> 623 * <ul> 624 * <li>ISO 639 is not a stable standard; some of the language codes it defines 625 * (specifically "iw", "ji", and "in") have changed. This constructor accepts both the 626 * old codes ("iw", "ji", and "in") and the new codes ("he", "yi", and "id"), but all other 627 * API on Locale will return only the OLD codes. 628 * <li>For backward compatibility reasons, this constructor does not make 629 * any syntactic checks on the input. 630 * <li>The two cases ("ja", "JP", "JP") and ("th", "TH", "TH") are handled specially, 631 * see <a href="#special_cases_constructor">Special Cases</a> for more information. 632 * </ul> 633 * 634 * @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag 635 * up to 8 characters in length. See the <code>Locale</code> class description about 636 * valid language values. 637 * @param country An ISO 3166 alpha-2 country code or a UN M.49 numeric-3 area code. 638 * See the <code>Locale</code> class description about valid country values. 639 * @param variant Any arbitrary value used to indicate a variation of a <code>Locale</code>. 640 * See the <code>Locale</code> class description for the details. 641 * @exception NullPointerException thrown if any argument is null. 642 */ 643 public Locale(String language, String country, String variant) { 644 if (language== null || country == null || variant == null) { 645 throw new NullPointerException(); 646 } 647 baseLocale = BaseLocale.getInstance(convertOldISOCodes(language), "", country, variant); 648 localeExtensions = getCompatibilityExtensions(language, "", country, variant); 649 } 650 651 /** 652 * Construct a locale from language and country. 653 * This constructor normalizes the language value to lowercase and 654 * the country value to uppercase. 655 * <p> 656 * <b>Note:</b> 657 * <ul> 658 * <li>ISO 639 is not a stable standard; some of the language codes it defines 659 * (specifically "iw", "ji", and "in") have changed. This constructor accepts both the 660 * old codes ("iw", "ji", and "in") and the new codes ("he", "yi", and "id"), but all other 661 * API on Locale will return only the OLD codes. 662 * <li>For backward compatibility reasons, this constructor does not make 663 * any syntactic checks on the input. 664 * </ul> 665 * 666 * @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag 667 * up to 8 characters in length. See the <code>Locale</code> class description about 668 * valid language values. 669 * @param country An ISO 3166 alpha-2 country code or a UN M.49 numeric-3 area code. 670 * See the <code>Locale</code> class description about valid country values. 671 * @exception NullPointerException thrown if either argument is null. 672 */ 673 public Locale(String language, String country) { 674 this(language, country, ""); 675 } 676 677 /** 678 * Construct a locale from a language code. 679 * This constructor normalizes the language value to lowercase. 680 * <p> 681 * <b>Note:</b> 682 * <ul> 683 * <li>ISO 639 is not a stable standard; some of the language codes it defines 684 * (specifically "iw", "ji", and "in") have changed. This constructor accepts both the 685 * old codes ("iw", "ji", and "in") and the new codes ("he", "yi", and "id"), but all other 686 * API on Locale will return only the OLD codes. 687 * <li>For backward compatibility reasons, this constructor does not make 688 * any syntactic checks on the input. 689 * </ul> 690 * 691 * @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag 692 * up to 8 characters in length. See the <code>Locale</code> class description about 693 * valid language values. 694 * @exception NullPointerException thrown if argument is null. 695 * @since 1.4 696 */ 697 public Locale(String language) { 698 this(language, "", ""); 699 } 700 701 /** 702 * This method must be called only for creating the Locale.* 703 * constants due to making shortcuts. 704 */ 705 private static Locale createConstant(String lang, String country) { 706 BaseLocale base = BaseLocale.createInstance(lang, country); 707 return getInstance(base, null); 708 } 709 710 /** 711 * Returns a <code>Locale</code> constructed from the given 712 * <code>language</code>, <code>country</code> and 713 * <code>variant</code>. If the same <code>Locale</code> instance 714 * is available in the cache, then that instance is 715 * returned. Otherwise, a new <code>Locale</code> instance is 716 * created and cached. 717 * 718 * @param language lowercase 2 to 8 language code. 719 * @param country uppercase two-letter ISO-3166 code and numric-3 UN M.49 area code. 720 * @param variant vendor and browser specific code. See class description. 721 * @return the <code>Locale</code> instance requested 722 * @exception NullPointerException if any argument is null. 723 */ 724 static Locale getInstance(String language, String country, String variant) { 725 return getInstance(language, "", country, variant, null); 726 } 727 728 static Locale getInstance(String language, String script, String country, 729 String variant, LocaleExtensions extensions) { 730 if (language== null || script == null || country == null || variant == null) { 731 throw new NullPointerException(); 732 } 733 734 if (extensions == null) { 735 extensions = getCompatibilityExtensions(language, script, country, variant); 736 } 737 738 BaseLocale baseloc = BaseLocale.getInstance(language, script, country, variant); 739 return getInstance(baseloc, extensions); 740 } 741 742 static Locale getInstance(BaseLocale baseloc, LocaleExtensions extensions) { 743 LocaleKey key = new LocaleKey(baseloc, extensions); 744 return LOCALECACHE.get(key); 745 } 746 747 private static class Cache extends LocaleObjectCache<LocaleKey, Locale> { 748 private Cache() { 749 } 750 751 @Override 752 protected Locale createObject(LocaleKey key) { 753 return new Locale(key.base, key.exts); 754 } 755 } 756 757 private static final class LocaleKey { 758 private final BaseLocale base; 759 private final LocaleExtensions exts; 760 private final int hash; 761 762 private LocaleKey(BaseLocale baseLocale, LocaleExtensions extensions) { 763 base = baseLocale; 764 exts = extensions; 765 766 // Calculate the hash value here because it's always used. 767 int h = base.hashCode(); 768 if (exts != null) { 769 h ^= exts.hashCode(); 770 } 771 hash = h; 772 } 773 774 @Override 775 public boolean equals(Object obj) { 776 if (this == obj) { 777 return true; 778 } 779 if (!(obj instanceof LocaleKey)) { 780 return false; 781 } 782 LocaleKey other = (LocaleKey)obj; 783 if (hash != other.hash || !base.equals(other.base)) { 784 return false; 785 } 786 if (exts == null) { 787 return other.exts == null; 788 } 789 return exts.equals(other.exts); 790 } 791 792 @Override 793 public int hashCode() { 794 return hash; 795 } 796 } 797 798 /** 799 * Gets the current value of the default locale for this instance 800 * of the Java Virtual Machine. 801 * <p> 802 * The Java Virtual Machine sets the default locale during startup 803 * based on the host environment. It is used by many locale-sensitive 804 * methods if no locale is explicitly specified. 805 * It can be changed using the 806 * {@link #setDefault(java.util.Locale) setDefault} method. 807 * 808 * @return the default locale for this instance of the Java Virtual Machine 809 */ 810 public static Locale getDefault() { 811 // do not synchronize this method - see 4071298 812 return defaultLocale; 813 } 814 815 /** 816 * Gets the current value of the default locale for the specified Category 817 * for this instance of the Java Virtual Machine. 818 * <p> 819 * The Java Virtual Machine sets the default locale during startup based 820 * on the host environment. It is used by many locale-sensitive methods 821 * if no locale is explicitly specified. It can be changed using the 822 * setDefault(Locale.Category, Locale) method. 823 * 824 * @param category - the specified category to get the default locale 825 * @throws NullPointerException - if category is null 826 * @return the default locale for the specified Category for this instance 827 * of the Java Virtual Machine 828 * @see #setDefault(Locale.Category, Locale) 829 * @since 1.7 830 */ 831 public static Locale getDefault(Locale.Category category) { 832 // do not synchronize this method - see 4071298 833 switch (category) { 834 case DISPLAY: 835 if (defaultDisplayLocale == null) { 836 synchronized(Locale.class) { 837 if (defaultDisplayLocale == null) { 838 defaultDisplayLocale = initDefault(category); 839 } 840 } 841 } 842 return defaultDisplayLocale; 843 case FORMAT: 844 if (defaultFormatLocale == null) { 845 synchronized(Locale.class) { 846 if (defaultFormatLocale == null) { 847 defaultFormatLocale = initDefault(category); 848 } 849 } 850 } 851 return defaultFormatLocale; 852 default: 853 assert false: "Unknown Category"; 854 } 855 return getDefault(); 856 } 857 858 private static Locale initDefault() { 859 String language, region, script, country, variant; 860 language = AccessController.doPrivileged( 861 new GetPropertyAction("user.language", "en")); 862 // for compatibility, check for old user.region property 863 region = AccessController.doPrivileged( 864 new GetPropertyAction("user.region")); 865 if (region != null) { 866 // region can be of form country, country_variant, or _variant 867 int i = region.indexOf('_'); 868 if (i >= 0) { 869 country = region.substring(0, i); 870 variant = region.substring(i + 1); 871 } else { 872 country = region; 873 variant = ""; 874 } 875 script = ""; 876 } else { 877 script = AccessController.doPrivileged( 878 new GetPropertyAction("user.script", "")); 879 country = AccessController.doPrivileged( 880 new GetPropertyAction("user.country", "")); 881 variant = AccessController.doPrivileged( 882 new GetPropertyAction("user.variant", "")); 883 } 884 885 return getInstance(language, script, country, variant, null); 886 } 887 888 private static Locale initDefault(Locale.Category category) { 889 return getInstance( 890 AccessController.doPrivileged( 891 new GetPropertyAction(category.languageKey, defaultLocale.getLanguage())), 892 AccessController.doPrivileged( 893 new GetPropertyAction(category.scriptKey, defaultLocale.getScript())), 894 AccessController.doPrivileged( 895 new GetPropertyAction(category.countryKey, defaultLocale.getCountry())), 896 AccessController.doPrivileged( 897 new GetPropertyAction(category.variantKey, defaultLocale.getVariant())), 898 null); 899 } 900 901 /** 902 * Sets the default locale for this instance of the Java Virtual Machine. 903 * This does not affect the host locale. 904 * <p> 905 * If there is a security manager, its <code>checkPermission</code> 906 * method is called with a <code>PropertyPermission("user.language", "write")</code> 907 * permission before the default locale is changed. 908 * <p> 909 * The Java Virtual Machine sets the default locale during startup 910 * based on the host environment. It is used by many locale-sensitive 911 * methods if no locale is explicitly specified. 912 * <p> 913 * Since changing the default locale may affect many different areas 914 * of functionality, this method should only be used if the caller 915 * is prepared to reinitialize locale-sensitive code running 916 * within the same Java Virtual Machine. 917 * <p> 918 * By setting the default locale with this method, all of the default 919 * locales for each Category are also set to the specified default locale. 920 * 921 * @throws SecurityException 922 * if a security manager exists and its 923 * <code>checkPermission</code> method doesn't allow the operation. 924 * @throws NullPointerException if <code>newLocale</code> is null 925 * @param newLocale the new default locale 926 * @see SecurityManager#checkPermission 927 * @see java.util.PropertyPermission 928 */ 929 public static synchronized void setDefault(Locale newLocale) { 930 setDefault(Category.DISPLAY, newLocale); 931 setDefault(Category.FORMAT, newLocale); 932 defaultLocale = newLocale; 933 } 934 935 /** 936 * Sets the default locale for the specified Category for this instance 937 * of the Java Virtual Machine. This does not affect the host locale. 938 * <p> 939 * If there is a security manager, its checkPermission method is called 940 * with a PropertyPermission("user.language", "write") permission before 941 * the default locale is changed. 942 * <p> 943 * The Java Virtual Machine sets the default locale during startup based 944 * on the host environment. It is used by many locale-sensitive methods 945 * if no locale is explicitly specified. 946 * <p> 947 * Since changing the default locale may affect many different areas of 948 * functionality, this method should only be used if the caller is 949 * prepared to reinitialize locale-sensitive code running within the 950 * same Java Virtual Machine. 951 * <p> 952 * 953 * @param category - the specified category to set the default locale 954 * @param newLocale - the new default locale 955 * @throws SecurityException - if a security manager exists and its 956 * checkPermission method doesn't allow the operation. 957 * @throws NullPointerException - if category and/or newLocale is null 958 * @see SecurityManager#checkPermission(java.security.Permission) 959 * @see PropertyPermission 960 * @see #getDefault(Locale.Category) 961 * @since 1.7 962 */ 963 public static synchronized void setDefault(Locale.Category category, 964 Locale newLocale) { 965 if (category == null) 966 throw new NullPointerException("Category cannot be NULL"); 967 if (newLocale == null) 968 throw new NullPointerException("Can't set default locale to NULL"); 969 970 SecurityManager sm = System.getSecurityManager(); 971 if (sm != null) sm.checkPermission(new PropertyPermission 972 ("user.language", "write")); 973 switch (category) { 974 case DISPLAY: 975 defaultDisplayLocale = newLocale; 976 break; 977 case FORMAT: 978 defaultFormatLocale = newLocale; 979 break; 980 default: 981 assert false: "Unknown Category"; 982 } 983 } 984 985 /** 986 * Returns an array of all installed locales. 987 * The returned array represents the union of locales supported 988 * by the Java runtime environment and by installed 989 * {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider} 990 * implementations. It must contain at least a <code>Locale</code> 991 * instance equal to {@link java.util.Locale#US Locale.US}. 992 * 993 * @return An array of installed locales. 994 */ 995 public static Locale[] getAvailableLocales() { 996 return LocaleServiceProviderPool.getAllAvailableLocales(); 997 } 998 999 /** 1000 * Returns a list of all 2-letter country codes defined in ISO 3166. 1001 * Can be used to create Locales. 1002 * <p> 1003 * <b>Note:</b> The <code>Locale</code> class also supports other codes for 1004 * country (region), such as 3-letter numeric UN M.49 area codes. 1005 * Therefore, the list returned by this method does not contain ALL valid 1006 * codes that can be used to create Locales. 1007 */ 1008 public static String[] getISOCountries() { 1009 if (isoCountries == null) { 1010 isoCountries = getISO2Table(LocaleISOData.isoCountryTable); 1011 } 1012 String[] result = new String[isoCountries.length]; 1013 System.arraycopy(isoCountries, 0, result, 0, isoCountries.length); 1014 return result; 1015 } 1016 1017 /** 1018 * Returns a list of all 2-letter language codes defined in ISO 639. 1019 * Can be used to create Locales. 1020 * <p> 1021 * <b>Note:</b> 1022 * <ul> 1023 * <li>ISO 639 is not a stable standard— some languages' codes have changed. 1024 * The list this function returns includes both the new and the old codes for the 1025 * languages whose codes have changed. 1026 * <li>The <code>Locale</code> class also supports language codes up to 1027 * 8 characters in length. Therefore, the list returned by this method does 1028 * not contain ALL valid codes that can be used to create Locales. 1029 * </ul> 1030 */ 1031 public static String[] getISOLanguages() { 1032 if (isoLanguages == null) { 1033 isoLanguages = getISO2Table(LocaleISOData.isoLanguageTable); 1034 } 1035 String[] result = new String[isoLanguages.length]; 1036 System.arraycopy(isoLanguages, 0, result, 0, isoLanguages.length); 1037 return result; 1038 } 1039 1040 private static String[] getISO2Table(String table) { 1041 int len = table.length() / 5; 1042 String[] isoTable = new String[len]; 1043 for (int i = 0, j = 0; i < len; i++, j += 5) { 1044 isoTable[i] = table.substring(j, j + 2); 1045 } 1046 return isoTable; 1047 } 1048 1049 /** 1050 * Returns the language code of this Locale. 1051 * 1052 * <p><b>Note:</b> ISO 639 is not a stable standard— some languages' codes have changed. 1053 * Locale's constructor recognizes both the new and the old codes for the languages 1054 * whose codes have changed, but this function always returns the old code. If you 1055 * want to check for a specific language whose code has changed, don't do 1056 * <pre> 1057 * if (locale.getLanguage().equals("he")) // BAD! 1058 * ... 1059 * </pre> 1060 * Instead, do 1061 * <pre> 1062 * if (locale.getLanguage().equals(new Locale("he").getLanguage())) 1063 * ... 1064 * </pre> 1065 * @return The language code, or the empty string if none is defined. 1066 * @see #getDisplayLanguage 1067 */ 1068 public String getLanguage() { 1069 return baseLocale.getLanguage(); 1070 } 1071 1072 /** 1073 * Returns the script for this locale, which should 1074 * either be the empty string or an ISO 15924 4-letter script 1075 * code. The first letter is uppercase and the rest are 1076 * lowercase, for example, 'Latn', 'Cyrl'. 1077 * 1078 * @return The script code, or the empty string if none is defined. 1079 * @see #getDisplayScript 1080 * @since 1.7 1081 */ 1082 public String getScript() { 1083 return baseLocale.getScript(); 1084 } 1085 1086 /** 1087 * Returns the country/region code for this locale, which should 1088 * either be the empty string, an uppercase ISO 3166 2-letter code, 1089 * or a UN M.49 3-digit code. 1090 * 1091 * @return The country/region code, or the empty string if none is defined. 1092 * @see #getDisplayCountry 1093 */ 1094 public String getCountry() { 1095 return baseLocale.getRegion(); 1096 } 1097 1098 /** 1099 * Returns the variant code for this locale. 1100 * 1101 * @return The variant code, or the empty string if none is defined. 1102 * @see #getDisplayVariant 1103 */ 1104 public String getVariant() { 1105 return baseLocale.getVariant(); 1106 } 1107 1108 /** 1109 * Returns {@code true} if this {@code Locale} has any <a href="#def_extensions"> 1110 * extensions</a>. 1111 * 1112 * @return {@code true} if this {@code Locale} has any extensions 1113 * @since 1.8 1114 */ 1115 public boolean hasExtensions() { 1116 return localeExtensions != null; 1117 } 1118 1119 /** 1120 * Returns a copy of this {@code Locale} with no <a href="#def_extensions"> 1121 * extensions</a>. If this {@code Locale} has no extensions, this {@code Locale} 1122 * is returned. 1123 * 1124 * @return a copy of this {@code Locale} with no extensions, or {@code this} 1125 * if {@code this} has no extensions 1126 * @since 1.8 1127 */ 1128 public Locale stripExtensions() { 1129 return hasExtensions() ? Locale.getInstance(baseLocale, null) : this; 1130 } 1131 1132 /** 1133 * Returns the extension (or private use) value associated with 1134 * the specified key, or null if there is no extension 1135 * associated with the key. To be well-formed, the key must be one 1136 * of <code>[0-9A-Za-z]</code>. Keys are case-insensitive, so 1137 * for example 'z' and 'Z' represent the same extension. 1138 * 1139 * @param key the extension key 1140 * @return The extension, or null if this locale defines no 1141 * extension for the specified key. 1142 * @throws IllegalArgumentException if key is not well-formed 1143 * @see #PRIVATE_USE_EXTENSION 1144 * @see #UNICODE_LOCALE_EXTENSION 1145 * @since 1.7 1146 */ 1147 public String getExtension(char key) { 1148 if (!LocaleExtensions.isValidKey(key)) { 1149 throw new IllegalArgumentException("Ill-formed extension key: " + key); 1150 } 1151 return hasExtensions() ? localeExtensions.getExtensionValue(key) : null; 1152 } 1153 1154 /** 1155 * Returns the set of extension keys associated with this locale, or the 1156 * empty set if it has no extensions. The returned set is unmodifiable. 1157 * The keys will all be lower-case. 1158 * 1159 * @return The set of extension keys, or the empty set if this locale has 1160 * no extensions. 1161 * @since 1.7 1162 */ 1163 public Set<Character> getExtensionKeys() { 1164 if (!hasExtensions()) { 1165 return Collections.emptySet(); 1166 } 1167 return localeExtensions.getKeys(); 1168 } 1169 1170 /** 1171 * Returns the set of unicode locale attributes associated with 1172 * this locale, or the empty set if it has no attributes. The 1173 * returned set is unmodifiable. 1174 * 1175 * @return The set of attributes. 1176 * @since 1.7 1177 */ 1178 public Set<String> getUnicodeLocaleAttributes() { 1179 if (!hasExtensions()) { 1180 return Collections.emptySet(); 1181 } 1182 return localeExtensions.getUnicodeLocaleAttributes(); 1183 } 1184 1185 /** 1186 * Returns the Unicode locale type associated with the specified Unicode locale key 1187 * for this locale. Returns the empty string for keys that are defined with no type. 1188 * Returns null if the key is not defined. Keys are case-insensitive. The key must 1189 * be two alphanumeric characters ([0-9a-zA-Z]), or an IllegalArgumentException is 1190 * thrown. 1191 * 1192 * @param key the Unicode locale key 1193 * @return The Unicode locale type associated with the key, or null if the 1194 * locale does not define the key. 1195 * @throws IllegalArgumentException if the key is not well-formed 1196 * @throws NullPointerException if <code>key</code> is null 1197 * @since 1.7 1198 */ 1199 public String getUnicodeLocaleType(String key) { 1200 if (!isUnicodeExtensionKey(key)) { 1201 throw new IllegalArgumentException("Ill-formed Unicode locale key: " + key); 1202 } 1203 return hasExtensions() ? localeExtensions.getUnicodeLocaleType(key) : null; 1204 } 1205 1206 /** 1207 * Returns the set of Unicode locale keys defined by this locale, or the empty set if 1208 * this locale has none. The returned set is immutable. Keys are all lower case. 1209 * 1210 * @return The set of Unicode locale keys, or the empty set if this locale has 1211 * no Unicode locale keywords. 1212 * @since 1.7 1213 */ 1214 public Set<String> getUnicodeLocaleKeys() { 1215 if (localeExtensions == null) { 1216 return Collections.emptySet(); 1217 } 1218 return localeExtensions.getUnicodeLocaleKeys(); 1219 } 1220 1221 /** 1222 * Package locale method returning the Locale's BaseLocale, 1223 * used by ResourceBundle 1224 * @return base locale of this Locale 1225 */ 1226 BaseLocale getBaseLocale() { 1227 return baseLocale; 1228 } 1229 1230 /** 1231 * Package private method returning the Locale's LocaleExtensions, 1232 * used by ResourceBundle. 1233 * @return locale exnteions of this Locale, 1234 * or {@code null} if no extensions are defined 1235 */ 1236 LocaleExtensions getLocaleExtensions() { 1237 return localeExtensions; 1238 } 1239 1240 /** 1241 * Returns a string representation of this <code>Locale</code> 1242 * object, consisting of language, country, variant, script, 1243 * and extensions as below: 1244 * <p><blockquote> 1245 * language + "_" + country + "_" + (variant + "_#" | "#") + script + "-" + extensions 1246 * </blockquote> 1247 * 1248 * Language is always lower case, country is always upper case, script is always title 1249 * case, and extensions are always lower case. Extensions and private use subtags 1250 * will be in canonical order as explained in {@link #toLanguageTag}. 1251 * 1252 * <p>When the locale has neither script nor extensions, the result is the same as in 1253 * Java 6 and prior. 1254 * 1255 * <p>If both the language and country fields are missing, this function will return 1256 * the empty string, even if the variant, script, or extensions field is present (you 1257 * can't have a locale with just a variant, the variant must accompany a well-formed 1258 * language or country code). 1259 * 1260 * <p>If script or extensions are present and variant is missing, no underscore is 1261 * added before the "#". 1262 * 1263 * <p>This behavior is designed to support debugging and to be compatible with 1264 * previous uses of <code>toString</code> that expected language, country, and variant 1265 * fields only. To represent a Locale as a String for interchange purposes, use 1266 * {@link #toLanguageTag}. 1267 * 1268 * <p>Examples: <ul><tt> 1269 * <li>en 1270 * <li>de_DE 1271 * <li>_GB 1272 * <li>en_US_WIN 1273 * <li>de__POSIX 1274 * <li>zh_CN_#Hans 1275 * <li>zh_TW_#Hant-x-java 1276 * <li>th_TH_TH_#u-nu-thai</tt></ul> 1277 * 1278 * @return A string representation of the Locale, for debugging. 1279 * @see #getDisplayName 1280 * @see #toLanguageTag 1281 */ 1282 @Override 1283 public final String toString() { 1284 boolean l = (baseLocale.getLanguage().length() != 0); 1285 boolean s = (baseLocale.getScript().length() != 0); 1286 boolean r = (baseLocale.getRegion().length() != 0); 1287 boolean v = (baseLocale.getVariant().length() != 0); 1288 boolean e = (localeExtensions != null && localeExtensions.getID().length() != 0); 1289 1290 StringBuilder result = new StringBuilder(baseLocale.getLanguage()); 1291 if (r || (l && (v || s || e))) { 1292 result.append('_') 1293 .append(baseLocale.getRegion()); // This may just append '_' 1294 } 1295 if (v && (l || r)) { 1296 result.append('_') 1297 .append(baseLocale.getVariant()); 1298 } 1299 1300 if (s && (l || r)) { 1301 result.append("_#") 1302 .append(baseLocale.getScript()); 1303 } 1304 1305 if (e && (l || r)) { 1306 result.append('_'); 1307 if (!s) { 1308 result.append('#'); 1309 } 1310 result.append(localeExtensions.getID()); 1311 } 1312 1313 return result.toString(); 1314 } 1315 1316 /** 1317 * Returns a well-formed IETF BCP 47 language tag representing 1318 * this locale. 1319 * 1320 * <p>If this <code>Locale</code> has a language, country, or 1321 * variant that does not satisfy the IETF BCP 47 language tag 1322 * syntax requirements, this method handles these fields as 1323 * described below: 1324 * 1325 * <p><b>Language:</b> If language is empty, or not <a 1326 * href="#def_language" >well-formed</a> (for example "a" or 1327 * "e2"), it will be emitted as "und" (Undetermined). 1328 * 1329 * <p><b>Country:</b> If country is not <a 1330 * href="#def_region">well-formed</a> (for example "12" or "USA"), 1331 * it will be omitted. 1332 * 1333 * <p><b>Variant:</b> If variant <b>is</b> <a 1334 * href="#def_variant">well-formed</a>, each sub-segment 1335 * (delimited by '-' or '_') is emitted as a subtag. Otherwise: 1336 * <ul> 1337 * 1338 * <li>if all sub-segments match <code>[0-9a-zA-Z]{1,8}</code> 1339 * (for example "WIN" or "Oracle_JDK_Standard_Edition"), the first 1340 * ill-formed sub-segment and all following will be appended to 1341 * the private use subtag. The first appended subtag will be 1342 * "lvariant", followed by the sub-segments in order, separated by 1343 * hyphen. For example, "x-lvariant-WIN", 1344 * "Oracle-x-lvariant-JDK-Standard-Edition". 1345 * 1346 * <li>if any sub-segment does not match 1347 * <code>[0-9a-zA-Z]{1,8}</code>, the variant will be truncated 1348 * and the problematic sub-segment and all following sub-segments 1349 * will be omitted. If the remainder is non-empty, it will be 1350 * emitted as a private use subtag as above (even if the remainder 1351 * turns out to be well-formed). For example, 1352 * "Solaris_isjustthecoolestthing" is emitted as 1353 * "x-lvariant-Solaris", not as "solaris".</li></ul> 1354 * 1355 * <p><b>Special Conversions:</b> Java supports some old locale 1356 * representations, including deprecated ISO language codes, 1357 * for compatibility. This method performs the following 1358 * conversions: 1359 * <ul> 1360 * 1361 * <li>Deprecated ISO language codes "iw", "ji", and "in" are 1362 * converted to "he", "yi", and "id", respectively. 1363 * 1364 * <li>A locale with language "no", country "NO", and variant 1365 * "NY", representing Norwegian Nynorsk (Norway), is converted 1366 * to a language tag "nn-NO".</li></ul> 1367 * 1368 * <p><b>Note:</b> Although the language tag created by this 1369 * method is well-formed (satisfies the syntax requirements 1370 * defined by the IETF BCP 47 specification), it is not 1371 * necessarily a valid BCP 47 language tag. For example, 1372 * <pre> 1373 * new Locale("xx", "YY").toLanguageTag();</pre> 1374 * 1375 * will return "xx-YY", but the language subtag "xx" and the 1376 * region subtag "YY" are invalid because they are not registered 1377 * in the IANA Language Subtag Registry. 1378 * 1379 * @return a BCP47 language tag representing the locale 1380 * @see #forLanguageTag(String) 1381 * @since 1.7 1382 */ 1383 public String toLanguageTag() { 1384 if (languageTag != null) { 1385 return languageTag; 1386 } 1387 1388 LanguageTag tag = LanguageTag.parseLocale(baseLocale, localeExtensions); 1389 StringBuilder buf = new StringBuilder(); 1390 1391 String subtag = tag.getLanguage(); 1392 if (subtag.length() > 0) { 1393 buf.append(LanguageTag.canonicalizeLanguage(subtag)); 1394 } 1395 1396 subtag = tag.getScript(); 1397 if (subtag.length() > 0) { 1398 buf.append(LanguageTag.SEP); 1399 buf.append(LanguageTag.canonicalizeScript(subtag)); 1400 } 1401 1402 subtag = tag.getRegion(); 1403 if (subtag.length() > 0) { 1404 buf.append(LanguageTag.SEP); 1405 buf.append(LanguageTag.canonicalizeRegion(subtag)); 1406 } 1407 1408 List<String>subtags = tag.getVariants(); 1409 for (String s : subtags) { 1410 buf.append(LanguageTag.SEP); 1411 // preserve casing 1412 buf.append(s); 1413 } 1414 1415 subtags = tag.getExtensions(); 1416 for (String s : subtags) { 1417 buf.append(LanguageTag.SEP); 1418 buf.append(LanguageTag.canonicalizeExtension(s)); 1419 } 1420 1421 subtag = tag.getPrivateuse(); 1422 if (subtag.length() > 0) { 1423 if (buf.length() > 0) { 1424 buf.append(LanguageTag.SEP); 1425 } 1426 buf.append(LanguageTag.PRIVATEUSE).append(LanguageTag.SEP); 1427 // preserve casing 1428 buf.append(subtag); 1429 } 1430 1431 String langTag = buf.toString(); 1432 synchronized (this) { 1433 if (languageTag == null) { 1434 languageTag = langTag; 1435 } 1436 } 1437 return languageTag; 1438 } 1439 1440 /** 1441 * Returns a locale for the specified IETF BCP 47 language tag string. 1442 * 1443 * <p>If the specified language tag contains any ill-formed subtags, 1444 * the first such subtag and all following subtags are ignored. Compare 1445 * to {@link Locale.Builder#setLanguageTag} which throws an exception 1446 * in this case. 1447 * 1448 * <p>The following <b>conversions</b> are performed:<ul> 1449 * 1450 * <li>The language code "und" is mapped to language "". 1451 * 1452 * <li>The language codes "he", "yi", and "id" are mapped to "iw", 1453 * "ji", and "in" respectively. (This is the same canonicalization 1454 * that's done in Locale's constructors.) 1455 * 1456 * <li>The portion of a private use subtag prefixed by "lvariant", 1457 * if any, is removed and appended to the variant field in the 1458 * result locale (without case normalization). If it is then 1459 * empty, the private use subtag is discarded: 1460 * 1461 * <pre> 1462 * Locale loc; 1463 * loc = Locale.forLanguageTag("en-US-x-lvariant-POSIX"); 1464 * loc.getVariant(); // returns "POSIX" 1465 * loc.getExtension('x'); // returns null 1466 * 1467 * loc = Locale.forLanguageTag("de-POSIX-x-URP-lvariant-Abc-Def"); 1468 * loc.getVariant(); // returns "POSIX_Abc_Def" 1469 * loc.getExtension('x'); // returns "urp" 1470 * </pre> 1471 * 1472 * <li>When the languageTag argument contains an extlang subtag, 1473 * the first such subtag is used as the language, and the primary 1474 * language subtag and other extlang subtags are ignored: 1475 * 1476 * <pre> 1477 * Locale.forLanguageTag("ar-aao").getLanguage(); // returns "aao" 1478 * Locale.forLanguageTag("en-abc-def-us").toString(); // returns "abc_US" 1479 * </pre> 1480 * 1481 * <li>Case is normalized except for variant tags, which are left 1482 * unchanged. Language is normalized to lower case, script to 1483 * title case, country to upper case, and extensions to lower 1484 * case. 1485 * 1486 * <li>If, after processing, the locale would exactly match either 1487 * ja_JP_JP or th_TH_TH with no extensions, the appropriate 1488 * extensions are added as though the constructor had been called: 1489 * 1490 * <pre> 1491 * Locale.forLanguageTag("ja-JP-x-lvariant-JP").toLanguageTag(); 1492 * // returns "ja-JP-u-ca-japanese-x-lvariant-JP" 1493 * Locale.forLanguageTag("th-TH-x-lvariant-TH").toLanguageTag(); 1494 * // returns "th-TH-u-nu-thai-x-lvariant-TH" 1495 * <pre></ul> 1496 * 1497 * <p>This implements the 'Language-Tag' production of BCP47, and 1498 * so supports grandfathered (regular and irregular) as well as 1499 * private use language tags. Stand alone private use tags are 1500 * represented as empty language and extension 'x-whatever', 1501 * and grandfathered tags are converted to their canonical replacements 1502 * where they exist. 1503 * 1504 * <p>Grandfathered tags with canonical replacements are as follows: 1505 * 1506 * <table> 1507 * <tbody align="center"> 1508 * <tr><th>grandfathered tag</th><th> </th><th>modern replacement</th></tr> 1509 * <tr><td>art-lojban</td><td> </td><td>jbo</td></tr> 1510 * <tr><td>i-ami</td><td> </td><td>ami</td></tr> 1511 * <tr><td>i-bnn</td><td> </td><td>bnn</td></tr> 1512 * <tr><td>i-hak</td><td> </td><td>hak</td></tr> 1513 * <tr><td>i-klingon</td><td> </td><td>tlh</td></tr> 1514 * <tr><td>i-lux</td><td> </td><td>lb</td></tr> 1515 * <tr><td>i-navajo</td><td> </td><td>nv</td></tr> 1516 * <tr><td>i-pwn</td><td> </td><td>pwn</td></tr> 1517 * <tr><td>i-tao</td><td> </td><td>tao</td></tr> 1518 * <tr><td>i-tay</td><td> </td><td>tay</td></tr> 1519 * <tr><td>i-tsu</td><td> </td><td>tsu</td></tr> 1520 * <tr><td>no-bok</td><td> </td><td>nb</td></tr> 1521 * <tr><td>no-nyn</td><td> </td><td>nn</td></tr> 1522 * <tr><td>sgn-BE-FR</td><td> </td><td>sfb</td></tr> 1523 * <tr><td>sgn-BE-NL</td><td> </td><td>vgt</td></tr> 1524 * <tr><td>sgn-CH-DE</td><td> </td><td>sgg</td></tr> 1525 * <tr><td>zh-guoyu</td><td> </td><td>cmn</td></tr> 1526 * <tr><td>zh-hakka</td><td> </td><td>hak</td></tr> 1527 * <tr><td>zh-min-nan</td><td> </td><td>nan</td></tr> 1528 * <tr><td>zh-xiang</td><td> </td><td>hsn</td></tr> 1529 * </tbody> 1530 * </table> 1531 * 1532 * <p>Grandfathered tags with no modern replacement will be 1533 * converted as follows: 1534 * 1535 * <table> 1536 * <tbody align="center"> 1537 * <tr><th>grandfathered tag</th><th> </th><th>converts to</th></tr> 1538 * <tr><td>cel-gaulish</td><td> </td><td>xtg-x-cel-gaulish</td></tr> 1539 * <tr><td>en-GB-oed</td><td> </td><td>en-GB-x-oed</td></tr> 1540 * <tr><td>i-default</td><td> </td><td>en-x-i-default</td></tr> 1541 * <tr><td>i-enochian</td><td> </td><td>und-x-i-enochian</td></tr> 1542 * <tr><td>i-mingo</td><td> </td><td>see-x-i-mingo</td></tr> 1543 * <tr><td>zh-min</td><td> </td><td>nan-x-zh-min</td></tr> 1544 * </tbody> 1545 * </table> 1546 * 1547 * <p>For a list of all grandfathered tags, see the 1548 * IANA Language Subtag Registry (search for "Type: grandfathered"). 1549 * 1550 * <p><b>Note</b>: there is no guarantee that <code>toLanguageTag</code> 1551 * and <code>forLanguageTag</code> will round-trip. 1552 * 1553 * @param languageTag the language tag 1554 * @return The locale that best represents the language tag. 1555 * @throws NullPointerException if <code>languageTag</code> is <code>null</code> 1556 * @see #toLanguageTag() 1557 * @see java.util.Locale.Builder#setLanguageTag(String) 1558 * @since 1.7 1559 */ 1560 public static Locale forLanguageTag(String languageTag) { 1561 LanguageTag tag = LanguageTag.parse(languageTag, null); 1562 InternalLocaleBuilder bldr = new InternalLocaleBuilder(); 1563 bldr.setLanguageTag(tag); 1564 BaseLocale base = bldr.getBaseLocale(); 1565 LocaleExtensions exts = bldr.getLocaleExtensions(); 1566 if (exts == null && base.getVariant().length() > 0) { 1567 exts = getCompatibilityExtensions(base.getLanguage(), base.getScript(), 1568 base.getRegion(), base.getVariant()); 1569 } 1570 return getInstance(base, exts); 1571 } 1572 1573 /** 1574 * Returns a three-letter abbreviation of this locale's language. 1575 * If the language matches an ISO 639-1 two-letter code, the 1576 * corresponding ISO 639-2/T three-letter lowercase code is 1577 * returned. The ISO 639-2 language codes can be found on-line, 1578 * see "Codes for the Representation of Names of Languages Part 2: 1579 * Alpha-3 Code". If the locale specifies a three-letter 1580 * language, the language is returned as is. If the locale does 1581 * not specify a language the empty string is returned. 1582 * 1583 * @return A three-letter abbreviation of this locale's language. 1584 * @exception MissingResourceException Throws MissingResourceException if 1585 * three-letter language abbreviation is not available for this locale. 1586 */ 1587 public String getISO3Language() throws MissingResourceException { 1588 String lang = baseLocale.getLanguage(); 1589 if (lang.length() == 3) { 1590 return lang; 1591 } 1592 1593 String language3 = getISO3Code(lang, LocaleISOData.isoLanguageTable); 1594 if (language3 == null) { 1595 throw new MissingResourceException("Couldn't find 3-letter language code for " 1596 + lang, "FormatData_" + toString(), "ShortLanguage"); 1597 } 1598 return language3; 1599 } 1600 1601 /** 1602 * Returns a three-letter abbreviation for this locale's country. 1603 * If the country matches an ISO 3166-1 alpha-2 code, the 1604 * corresponding ISO 3166-1 alpha-3 uppercase code is returned. 1605 * If the locale doesn't specify a country, this will be the empty 1606 * string. 1607 * 1608 * <p>The ISO 3166-1 codes can be found on-line. 1609 * 1610 * @return A three-letter abbreviation of this locale's country. 1611 * @exception MissingResourceException Throws MissingResourceException if the 1612 * three-letter country abbreviation is not available for this locale. 1613 */ 1614 public String getISO3Country() throws MissingResourceException { 1615 String country3 = getISO3Code(baseLocale.getRegion(), LocaleISOData.isoCountryTable); 1616 if (country3 == null) { 1617 throw new MissingResourceException("Couldn't find 3-letter country code for " 1618 + baseLocale.getRegion(), "FormatData_" + toString(), "ShortCountry"); 1619 } 1620 return country3; 1621 } 1622 1623 private static String getISO3Code(String iso2Code, String table) { 1624 int codeLength = iso2Code.length(); 1625 if (codeLength == 0) { 1626 return ""; 1627 } 1628 1629 int tableLength = table.length(); 1630 int index = tableLength; 1631 if (codeLength == 2) { 1632 char c1 = iso2Code.charAt(0); 1633 char c2 = iso2Code.charAt(1); 1634 for (index = 0; index < tableLength; index += 5) { 1635 if (table.charAt(index) == c1 1636 && table.charAt(index + 1) == c2) { 1637 break; 1638 } 1639 } 1640 } 1641 return index < tableLength ? table.substring(index + 2, index + 5) : null; 1642 } 1643 1644 /** 1645 * Returns a name for the locale's language that is appropriate for display to the 1646 * user. 1647 * If possible, the name returned will be localized for the default locale. 1648 * For example, if the locale is fr_FR and the default locale 1649 * is en_US, getDisplayLanguage() will return "French"; if the locale is en_US and 1650 * the default locale is fr_FR, getDisplayLanguage() will return "anglais". 1651 * If the name returned cannot be localized for the default locale, 1652 * (say, we don't have a Japanese name for Croatian), 1653 * this function falls back on the English name, and uses the ISO code as a last-resort 1654 * value. If the locale doesn't specify a language, this function returns the empty string. 1655 */ 1656 public final String getDisplayLanguage() { 1657 return getDisplayLanguage(getDefault(Category.DISPLAY)); 1658 } 1659 1660 /** 1661 * Returns a name for the locale's language that is appropriate for display to the 1662 * user. 1663 * If possible, the name returned will be localized according to inLocale. 1664 * For example, if the locale is fr_FR and inLocale 1665 * is en_US, getDisplayLanguage() will return "French"; if the locale is en_US and 1666 * inLocale is fr_FR, getDisplayLanguage() will return "anglais". 1667 * If the name returned cannot be localized according to inLocale, 1668 * (say, we don't have a Japanese name for Croatian), 1669 * this function falls back on the English name, and finally 1670 * on the ISO code as a last-resort value. If the locale doesn't specify a language, 1671 * this function returns the empty string. 1672 * 1673 * @exception NullPointerException if <code>inLocale</code> is <code>null</code> 1674 */ 1675 public String getDisplayLanguage(Locale inLocale) { 1676 return getDisplayString(baseLocale.getLanguage(), inLocale, DISPLAY_LANGUAGE); 1677 } 1678 1679 /** 1680 * Returns a name for the the locale's script that is appropriate for display to 1681 * the user. If possible, the name will be localized for the default locale. Returns 1682 * the empty string if this locale doesn't specify a script code. 1683 * 1684 * @return the display name of the script code for the current default locale 1685 * @since 1.7 1686 */ 1687 public String getDisplayScript() { 1688 return getDisplayScript(getDefault(Category.DISPLAY)); 1689 } 1690 1691 /** 1692 * Returns a name for the locale's script that is appropriate 1693 * for display to the user. If possible, the name will be 1694 * localized for the given locale. Returns the empty string if 1695 * this locale doesn't specify a script code. 1696 * 1697 * @return the display name of the script code for the current default locale 1698 * @throws NullPointerException if <code>inLocale</code> is <code>null</code> 1699 * @since 1.7 1700 */ 1701 public String getDisplayScript(Locale inLocale) { 1702 return getDisplayString(baseLocale.getScript(), inLocale, DISPLAY_SCRIPT); 1703 } 1704 1705 /** 1706 * Returns a name for the locale's country that is appropriate for display to the 1707 * user. 1708 * If possible, the name returned will be localized for the default locale. 1709 * For example, if the locale is fr_FR and the default locale 1710 * is en_US, getDisplayCountry() will return "France"; if the locale is en_US and 1711 * the default locale is fr_FR, getDisplayCountry() will return "Etats-Unis". 1712 * If the name returned cannot be localized for the default locale, 1713 * (say, we don't have a Japanese name for Croatia), 1714 * this function falls back on the English name, and uses the ISO code as a last-resort 1715 * value. If the locale doesn't specify a country, this function returns the empty string. 1716 */ 1717 public final String getDisplayCountry() { 1718 return getDisplayCountry(getDefault(Category.DISPLAY)); 1719 } 1720 1721 /** 1722 * Returns a name for the locale's country that is appropriate for display to the 1723 * user. 1724 * If possible, the name returned will be localized according to inLocale. 1725 * For example, if the locale is fr_FR and inLocale 1726 * is en_US, getDisplayCountry() will return "France"; if the locale is en_US and 1727 * inLocale is fr_FR, getDisplayCountry() will return "Etats-Unis". 1728 * If the name returned cannot be localized according to inLocale. 1729 * (say, we don't have a Japanese name for Croatia), 1730 * this function falls back on the English name, and finally 1731 * on the ISO code as a last-resort value. If the locale doesn't specify a country, 1732 * this function returns the empty string. 1733 * 1734 * @exception NullPointerException if <code>inLocale</code> is <code>null</code> 1735 */ 1736 public String getDisplayCountry(Locale inLocale) { 1737 return getDisplayString(baseLocale.getRegion(), inLocale, DISPLAY_COUNTRY); 1738 } 1739 1740 private String getDisplayString(String code, Locale inLocale, int type) { 1741 if (code.length() == 0) { 1742 return ""; 1743 } 1744 1745 if (inLocale == null) { 1746 throw new NullPointerException(); 1747 } 1748 1749 LocaleServiceProviderPool pool = 1750 LocaleServiceProviderPool.getPool(LocaleNameProvider.class); 1751 String key = (type == DISPLAY_VARIANT ? "%%"+code : code); 1752 String result = pool.getLocalizedObject( 1753 LocaleNameGetter.INSTANCE, 1754 inLocale, key, type, code); 1755 if (result != null) { 1756 return result; 1757 } 1758 1759 return code; 1760 } 1761 1762 /** 1763 * Returns a name for the locale's variant code that is appropriate for display to the 1764 * user. If possible, the name will be localized for the default locale. If the locale 1765 * doesn't specify a variant code, this function returns the empty string. 1766 */ 1767 public final String getDisplayVariant() { 1768 return getDisplayVariant(getDefault(Category.DISPLAY)); 1769 } 1770 1771 /** 1772 * Returns a name for the locale's variant code that is appropriate for display to the 1773 * user. If possible, the name will be localized for inLocale. If the locale 1774 * doesn't specify a variant code, this function returns the empty string. 1775 * 1776 * @exception NullPointerException if <code>inLocale</code> is <code>null</code> 1777 */ 1778 public String getDisplayVariant(Locale inLocale) { 1779 if (baseLocale.getVariant().length() == 0) 1780 return ""; 1781 1782 OpenListResourceBundle bundle = LocaleProviderAdapter.forJRE().getLocaleData().getLocaleNames(inLocale); 1783 1784 String names[] = getDisplayVariantArray(bundle, inLocale); 1785 1786 // Get the localized patterns for formatting a list, and use 1787 // them to format the list. 1788 String listPattern = null; 1789 String listCompositionPattern = null; 1790 try { 1791 listPattern = bundle.getString("ListPattern"); 1792 listCompositionPattern = bundle.getString("ListCompositionPattern"); 1793 } catch (MissingResourceException e) { 1794 } 1795 return formatList(names, listPattern, listCompositionPattern); 1796 } 1797 1798 /** 1799 * Returns a name for the locale that is appropriate for display to the 1800 * user. This will be the values returned by getDisplayLanguage(), 1801 * getDisplayScript(), getDisplayCountry(), and getDisplayVariant() assembled 1802 * into a single string. The the non-empty values are used in order, 1803 * with the second and subsequent names in parentheses. For example: 1804 * <blockquote> 1805 * language (script, country, variant)<br> 1806 * language (country)<br> 1807 * language (variant)<br> 1808 * script (country)<br> 1809 * country<br> 1810 * </blockquote> 1811 * depending on which fields are specified in the locale. If the 1812 * language, sacript, country, and variant fields are all empty, 1813 * this function returns the empty string. 1814 */ 1815 public final String getDisplayName() { 1816 return getDisplayName(getDefault(Category.DISPLAY)); 1817 } 1818 1819 /** 1820 * Returns a name for the locale that is appropriate for display 1821 * to the user. This will be the values returned by 1822 * getDisplayLanguage(), getDisplayScript(),getDisplayCountry(), 1823 * and getDisplayVariant() assembled into a single string. 1824 * The non-empty values are used in order, 1825 * with the second and subsequent names in parentheses. For example: 1826 * <blockquote> 1827 * language (script, country, variant)<br> 1828 * language (country)<br> 1829 * language (variant)<br> 1830 * script (country)<br> 1831 * country<br> 1832 * </blockquote> 1833 * depending on which fields are specified in the locale. If the 1834 * language, script, country, and variant fields are all empty, 1835 * this function returns the empty string. 1836 * 1837 * @throws NullPointerException if <code>inLocale</code> is <code>null</code> 1838 */ 1839 public String getDisplayName(Locale inLocale) { 1840 OpenListResourceBundle bundle = LocaleProviderAdapter.forJRE().getLocaleData().getLocaleNames(inLocale); 1841 1842 String languageName = getDisplayLanguage(inLocale); 1843 String scriptName = getDisplayScript(inLocale); 1844 String countryName = getDisplayCountry(inLocale); 1845 String[] variantNames = getDisplayVariantArray(bundle, inLocale); 1846 1847 // Get the localized patterns for formatting a display name. 1848 String displayNamePattern = null; 1849 String listPattern = null; 1850 String listCompositionPattern = null; 1851 try { 1852 displayNamePattern = bundle.getString("DisplayNamePattern"); 1853 listPattern = bundle.getString("ListPattern"); 1854 listCompositionPattern = bundle.getString("ListCompositionPattern"); 1855 } catch (MissingResourceException e) { 1856 } 1857 1858 // The display name consists of a main name, followed by qualifiers. 1859 // Typically, the format is "MainName (Qualifier, Qualifier)" but this 1860 // depends on what pattern is stored in the display locale. 1861 String mainName = null; 1862 String[] qualifierNames = null; 1863 1864 // The main name is the language, or if there is no language, the script, 1865 // then if no script, the country. If there is no language/script/country 1866 // (an anomalous situation) then the display name is simply the variant's 1867 // display name. 1868 if (languageName.length() == 0 && scriptName.length() == 0 && countryName.length() == 0) { 1869 if (variantNames.length == 0) { 1870 return ""; 1871 } else { 1872 return formatList(variantNames, listPattern, listCompositionPattern); 1873 } 1874 } 1875 ArrayList<String> names = new ArrayList<>(4); 1876 if (languageName.length() != 0) { 1877 names.add(languageName); 1878 } 1879 if (scriptName.length() != 0) { 1880 names.add(scriptName); 1881 } 1882 if (countryName.length() != 0) { 1883 names.add(countryName); 1884 } 1885 if (variantNames.length != 0) { 1886 names.addAll(Arrays.asList(variantNames)); 1887 } 1888 1889 // The first one in the main name 1890 mainName = names.get(0); 1891 1892 // Others are qualifiers 1893 int numNames = names.size(); 1894 qualifierNames = (numNames > 1) ? 1895 names.subList(1, numNames).toArray(new String[numNames - 1]) : new String[0]; 1896 1897 // Create an array whose first element is the number of remaining 1898 // elements. This serves as a selector into a ChoiceFormat pattern from 1899 // the resource. The second and third elements are the main name and 1900 // the qualifier; if there are no qualifiers, the third element is 1901 // unused by the format pattern. 1902 Object[] displayNames = { 1903 new Integer(qualifierNames.length != 0 ? 2 : 1), 1904 mainName, 1905 // We could also just call formatList() and have it handle the empty 1906 // list case, but this is more efficient, and we want it to be 1907 // efficient since all the language-only locales will not have any 1908 // qualifiers. 1909 qualifierNames.length != 0 ? formatList(qualifierNames, listPattern, listCompositionPattern) : null 1910 }; 1911 1912 if (displayNamePattern != null) { 1913 return new MessageFormat(displayNamePattern).format(displayNames); 1914 } 1915 else { 1916 // If we cannot get the message format pattern, then we use a simple 1917 // hard-coded pattern. This should not occur in practice unless the 1918 // installation is missing some core files (FormatData etc.). 1919 StringBuilder result = new StringBuilder(); 1920 result.append((String)displayNames[1]); 1921 if (displayNames.length > 2) { 1922 result.append(" ("); 1923 result.append((String)displayNames[2]); 1924 result.append(')'); 1925 } 1926 return result.toString(); 1927 } 1928 } 1929 1930 /** 1931 * Overrides Cloneable. 1932 */ 1933 @Override 1934 public Object clone() 1935 { 1936 try { 1937 Locale that = (Locale)super.clone(); 1938 return that; 1939 } catch (CloneNotSupportedException e) { 1940 throw new InternalError(e); 1941 } 1942 } 1943 1944 /** 1945 * Override hashCode. 1946 * Since Locales are often used in hashtables, caches the value 1947 * for speed. 1948 */ 1949 @Override 1950 public int hashCode() { 1951 int hc = hashCodeValue; 1952 if (hc == 0) { 1953 hc = baseLocale.hashCode(); 1954 if (localeExtensions != null) { 1955 hc ^= localeExtensions.hashCode(); 1956 } 1957 hashCodeValue = hc; 1958 } 1959 return hc; 1960 } 1961 1962 // Overrides 1963 1964 /** 1965 * Returns true if this Locale is equal to another object. A Locale is 1966 * deemed equal to another Locale with identical language, script, country, 1967 * variant and extensions, and unequal to all other objects. 1968 * 1969 * @return true if this Locale is equal to the specified object. 1970 */ 1971 @Override 1972 public boolean equals(Object obj) { 1973 if (this == obj) // quick check 1974 return true; 1975 if (!(obj instanceof Locale)) 1976 return false; 1977 BaseLocale otherBase = ((Locale)obj).baseLocale; 1978 if (!baseLocale.equals(otherBase)) { 1979 return false; 1980 } 1981 if (localeExtensions == null) { 1982 return ((Locale)obj).localeExtensions == null; 1983 } 1984 return localeExtensions.equals(((Locale)obj).localeExtensions); 1985 } 1986 1987 // ================= privates ===================================== 1988 1989 private transient BaseLocale baseLocale; 1990 private transient LocaleExtensions localeExtensions; 1991 1992 /** 1993 * Calculated hashcode 1994 */ 1995 private transient volatile int hashCodeValue = 0; 1996 1997 private volatile static Locale defaultLocale = initDefault(); 1998 private volatile static Locale defaultDisplayLocale = null; 1999 private volatile static Locale defaultFormatLocale = null; 2000 2001 private transient volatile String languageTag; 2002 2003 /** 2004 * Return an array of the display names of the variant. 2005 * @param bundle the ResourceBundle to use to get the display names 2006 * @return an array of display names, possible of zero length. 2007 */ 2008 private String[] getDisplayVariantArray(OpenListResourceBundle bundle, Locale inLocale) { 2009 // Split the variant name into tokens separated by '_'. 2010 StringTokenizer tokenizer = new StringTokenizer(baseLocale.getVariant(), "_"); 2011 String[] names = new String[tokenizer.countTokens()]; 2012 2013 // For each variant token, lookup the display name. If 2014 // not found, use the variant name itself. 2015 for (int i=0; i<names.length; ++i) { 2016 names[i] = getDisplayString(tokenizer.nextToken(), 2017 inLocale, DISPLAY_VARIANT); 2018 } 2019 2020 return names; 2021 } 2022 2023 /** 2024 * Format a list using given pattern strings. 2025 * If either of the patterns is null, then a the list is 2026 * formatted by concatenation with the delimiter ','. 2027 * @param stringList the list of strings to be formatted. 2028 * @param listPattern should create a MessageFormat taking 0-3 arguments 2029 * and formatting them into a list. 2030 * @param listCompositionPattern should take 2 arguments 2031 * and is used by composeList. 2032 * @return a string representing the list. 2033 */ 2034 private static String formatList(String[] stringList, String listPattern, String listCompositionPattern) { 2035 // If we have no list patterns, compose the list in a simple, 2036 // non-localized way. 2037 if (listPattern == null || listCompositionPattern == null) { 2038 StringBuilder result = new StringBuilder(); 2039 for (int i = 0; i < stringList.length; ++i) { 2040 if (i > 0) { 2041 result.append(','); 2042 } 2043 result.append(stringList[i]); 2044 } 2045 return result.toString(); 2046 } 2047 2048 // Compose the list down to three elements if necessary 2049 if (stringList.length > 3) { 2050 MessageFormat format = new MessageFormat(listCompositionPattern); 2051 stringList = composeList(format, stringList); 2052 } 2053 2054 // Rebuild the argument list with the list length as the first element 2055 Object[] args = new Object[stringList.length + 1]; 2056 System.arraycopy(stringList, 0, args, 1, stringList.length); 2057 args[0] = new Integer(stringList.length); 2058 2059 // Format it using the pattern in the resource 2060 MessageFormat format = new MessageFormat(listPattern); 2061 return format.format(args); 2062 } 2063 2064 /** 2065 * Given a list of strings, return a list shortened to three elements. 2066 * Shorten it by applying the given format to the first two elements 2067 * recursively. 2068 * @param format a format which takes two arguments 2069 * @param list a list of strings 2070 * @return if the list is three elements or shorter, the same list; 2071 * otherwise, a new list of three elements. 2072 */ 2073 private static String[] composeList(MessageFormat format, String[] list) { 2074 if (list.length <= 3) return list; 2075 2076 // Use the given format to compose the first two elements into one 2077 String[] listItems = { list[0], list[1] }; 2078 String newItem = format.format(listItems); 2079 2080 // Form a new list one element shorter 2081 String[] newList = new String[list.length-1]; 2082 System.arraycopy(list, 2, newList, 1, newList.length-1); 2083 newList[0] = newItem; 2084 2085 // Recurse 2086 return composeList(format, newList); 2087 } 2088 2089 // Duplicate of sun.util.locale.UnicodeLocaleExtension.isKey in order to 2090 // avoid its class loading. 2091 private static boolean isUnicodeExtensionKey(String s) { 2092 // 2alphanum 2093 return (s.length() == 2) && LocaleUtils.isAlphaNumericString(s); 2094 } 2095 2096 /** 2097 * @serialField language String 2098 * language subtag in lower case. (See <a href="java/util/Locale.html#getLanguage()">getLanguage()</a>) 2099 * @serialField country String 2100 * country subtag in upper case. (See <a href="java/util/Locale.html#getCountry()">getCountry()</a>) 2101 * @serialField variant String 2102 * variant subtags separated by LOWLINE characters. (See <a href="java/util/Locale.html#getVariant()">getVariant()</a>) 2103 * @serialField hashcode int 2104 * deprecated, for forward compatibility only 2105 * @serialField script String 2106 * script subtag in title case (See <a href="java/util/Locale.html#getScript()">getScript()</a>) 2107 * @serialField extensions String 2108 * canonical representation of extensions, that is, 2109 * BCP47 extensions in alphabetical order followed by 2110 * BCP47 private use subtags, all in lower case letters 2111 * separated by HYPHEN-MINUS characters. 2112 * (See <a href="java/util/Locale.html#getExtensionKeys()">getExtensionKeys()</a>, 2113 * <a href="java/util/Locale.html#getExtension(char)">getExtension(char)</a>) 2114 */ 2115 private static final ObjectStreamField[] serialPersistentFields = { 2116 new ObjectStreamField("language", String.class), 2117 new ObjectStreamField("country", String.class), 2118 new ObjectStreamField("variant", String.class), 2119 new ObjectStreamField("hashcode", int.class), 2120 new ObjectStreamField("script", String.class), 2121 new ObjectStreamField("extensions", String.class), 2122 }; 2123 2124 /** 2125 * Serializes this <code>Locale</code> to the specified <code>ObjectOutputStream</code>. 2126 * @param out the <code>ObjectOutputStream</code> to write 2127 * @throws IOException 2128 * @since 1.7 2129 */ 2130 private void writeObject(ObjectOutputStream out) throws IOException { 2131 ObjectOutputStream.PutField fields = out.putFields(); 2132 fields.put("language", baseLocale.getLanguage()); 2133 fields.put("script", baseLocale.getScript()); 2134 fields.put("country", baseLocale.getRegion()); 2135 fields.put("variant", baseLocale.getVariant()); 2136 fields.put("extensions", localeExtensions == null ? "" : localeExtensions.getID()); 2137 fields.put("hashcode", -1); // place holder just for backward support 2138 out.writeFields(); 2139 } 2140 2141 /** 2142 * Deserializes this <code>Locale</code>. 2143 * @param in the <code>ObjectInputStream</code> to read 2144 * @throws IOException 2145 * @throws ClassNotFoundException 2146 * @throws IllformdLocaleException 2147 * @since 1.7 2148 */ 2149 private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException { 2150 ObjectInputStream.GetField fields = in.readFields(); 2151 String language = (String)fields.get("language", ""); 2152 String script = (String)fields.get("script", ""); 2153 String country = (String)fields.get("country", ""); 2154 String variant = (String)fields.get("variant", ""); 2155 String extStr = (String)fields.get("extensions", ""); 2156 baseLocale = BaseLocale.getInstance(convertOldISOCodes(language), script, country, variant); 2157 if (extStr.length() > 0) { 2158 try { 2159 InternalLocaleBuilder bldr = new InternalLocaleBuilder(); 2160 bldr.setExtensions(extStr); 2161 localeExtensions = bldr.getLocaleExtensions(); 2162 } catch (LocaleSyntaxException e) { 2163 throw new IllformedLocaleException(e.getMessage()); 2164 } 2165 } else { 2166 localeExtensions = null; 2167 } 2168 } 2169 2170 /** 2171 * Returns a cached <code>Locale</code> instance equivalent to 2172 * the deserialized <code>Locale</code>. When serialized 2173 * language, country and variant fields read from the object data stream 2174 * are exactly "ja", "JP", "JP" or "th", "TH", "TH" and script/extensions 2175 * fields are empty, this method supplies <code>UNICODE_LOCALE_EXTENSION</code> 2176 * "ca"/"japanese" (calendar type is "japanese") or "nu"/"thai" (number script 2177 * type is "thai"). See <a href="Locale.html#special_cases_constructor"/>Special Cases</a> 2178 * for more information. 2179 * 2180 * @return an instance of <code>Locale</code> equivalent to 2181 * the deserialized <code>Locale</code>. 2182 * @throws java.io.ObjectStreamException 2183 */ 2184 private Object readResolve() throws java.io.ObjectStreamException { 2185 return getInstance(baseLocale.getLanguage(), baseLocale.getScript(), 2186 baseLocale.getRegion(), baseLocale.getVariant(), localeExtensions); 2187 } 2188 2189 private static volatile String[] isoLanguages = null; 2190 2191 private static volatile String[] isoCountries = null; 2192 2193 private static String convertOldISOCodes(String language) { 2194 // we accept both the old and the new ISO codes for the languages whose ISO 2195 // codes have changed, but we always store the OLD code, for backward compatibility 2196 language = LocaleUtils.toLowerString(language).intern(); 2197 if (language == "he") { 2198 return "iw"; 2199 } else if (language == "yi") { 2200 return "ji"; 2201 } else if (language == "id") { 2202 return "in"; 2203 } else { 2204 return language; 2205 } 2206 } 2207 2208 private static LocaleExtensions getCompatibilityExtensions(String language, 2209 String script, 2210 String country, 2211 String variant) { 2212 LocaleExtensions extensions = null; 2213 // Special cases for backward compatibility support 2214 if (LocaleUtils.caseIgnoreMatch(language, "ja") 2215 && script.length() == 0 2216 && LocaleUtils.caseIgnoreMatch(country, "jp") 2217 && "JP".equals(variant)) { 2218 // ja_JP_JP -> u-ca-japanese (calendar = japanese) 2219 extensions = LocaleExtensions.CALENDAR_JAPANESE; 2220 } else if (LocaleUtils.caseIgnoreMatch(language, "th") 2221 && script.length() == 0 2222 && LocaleUtils.caseIgnoreMatch(country, "th") 2223 && "TH".equals(variant)) { 2224 // th_TH_TH -> u-nu-thai (numbersystem = thai) 2225 extensions = LocaleExtensions.NUMBER_THAI; 2226 } 2227 return extensions; 2228 } 2229 2230 /** 2231 * Obtains a localized locale names from a LocaleNameProvider 2232 * implementation. 2233 */ 2234 private static class LocaleNameGetter 2235 implements LocaleServiceProviderPool.LocalizedObjectGetter<LocaleNameProvider, String> { 2236 private static final LocaleNameGetter INSTANCE = new LocaleNameGetter(); 2237 2238 @Override 2239 public String getObject(LocaleNameProvider localeNameProvider, 2240 Locale locale, 2241 String key, 2242 Object... params) { 2243 assert params.length == 2; 2244 int type = (Integer)params[0]; 2245 String code = (String)params[1]; 2246 2247 switch(type) { 2248 case DISPLAY_LANGUAGE: 2249 return localeNameProvider.getDisplayLanguage(code, locale); 2250 case DISPLAY_COUNTRY: 2251 return localeNameProvider.getDisplayCountry(code, locale); 2252 case DISPLAY_VARIANT: 2253 return localeNameProvider.getDisplayVariant(code, locale); 2254 case DISPLAY_SCRIPT: 2255 return localeNameProvider.getDisplayScript(code, locale); 2256 default: 2257 assert false; // shouldn't happen 2258 } 2259 2260 return null; 2261 } 2262 } 2263 2264 /** 2265 * Enum for locale categories. These locale categories are used to get/set 2266 * the default locale for the specific functionality represented by the 2267 * category. 2268 * 2269 * @see #getDefault(Locale.Category) 2270 * @see #setDefault(Locale.Category, Locale) 2271 * @since 1.7 2272 */ 2273 public enum Category { 2274 2275 /** 2276 * Category used to represent the default locale for 2277 * displaying user interfaces. 2278 */ 2279 DISPLAY("user.language.display", 2280 "user.script.display", 2281 "user.country.display", 2282 "user.variant.display"), 2283 2284 /** 2285 * Category used to represent the default locale for 2286 * formatting dates, numbers, and/or currencies. 2287 */ 2288 FORMAT("user.language.format", 2289 "user.script.format", 2290 "user.country.format", 2291 "user.variant.format"); 2292 2293 Category(String languageKey, String scriptKey, String countryKey, String variantKey) { 2294 this.languageKey = languageKey; 2295 this.scriptKey = scriptKey; 2296 this.countryKey = countryKey; 2297 this.variantKey = variantKey; 2298 } 2299 2300 final String languageKey; 2301 final String scriptKey; 2302 final String countryKey; 2303 final String variantKey; 2304 } 2305 2306 /** 2307 * <code>Builder</code> is used to build instances of <code>Locale</code> 2308 * from values configured by the setters. Unlike the <code>Locale</code> 2309 * constructors, the <code>Builder</code> checks if a value configured by a 2310 * setter satisfies the syntax requirements defined by the <code>Locale</code> 2311 * class. A <code>Locale</code> object created by a <code>Builder</code> is 2312 * well-formed and can be transformed to a well-formed IETF BCP 47 language tag 2313 * without losing information. 2314 * 2315 * <p><b>Note:</b> The <code>Locale</code> class does not provide any 2316 * syntactic restrictions on variant, while BCP 47 requires each variant 2317 * subtag to be 5 to 8 alphanumerics or a single numeric followed by 3 2318 * alphanumerics. The method <code>setVariant</code> throws 2319 * <code>IllformedLocaleException</code> for a variant that does not satisfy 2320 * this restriction. If it is necessary to support such a variant, use a 2321 * Locale constructor. However, keep in mind that a <code>Locale</code> 2322 * object created this way might lose the variant information when 2323 * transformed to a BCP 47 language tag. 2324 * 2325 * <p>The following example shows how to create a <code>Locale</code> object 2326 * with the <code>Builder</code>. 2327 * <blockquote> 2328 * <pre> 2329 * Locale aLocale = new Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build(); 2330 * </pre> 2331 * </blockquote> 2332 * 2333 * <p>Builders can be reused; <code>clear()</code> resets all 2334 * fields to their default values. 2335 * 2336 * @see Locale#forLanguageTag 2337 * @since 1.7 2338 */ 2339 public static final class Builder { 2340 private final InternalLocaleBuilder localeBuilder; 2341 2342 /** 2343 * Constructs an empty Builder. The default value of all 2344 * fields, extensions, and private use information is the 2345 * empty string. 2346 */ 2347 public Builder() { 2348 localeBuilder = new InternalLocaleBuilder(); 2349 } 2350 2351 /** 2352 * Resets the <code>Builder</code> to match the provided 2353 * <code>locale</code>. Existing state is discarded. 2354 * 2355 * <p>All fields of the locale must be well-formed, see {@link Locale}. 2356 * 2357 * <p>Locales with any ill-formed fields cause 2358 * <code>IllformedLocaleException</code> to be thrown, except for the 2359 * following three cases which are accepted for compatibility 2360 * reasons:<ul> 2361 * <li>Locale("ja", "JP", "JP") is treated as "ja-JP-u-ca-japanese" 2362 * <li>Locale("th", "TH", "TH") is treated as "th-TH-u-nu-thai" 2363 * <li>Locale("no", "NO", "NY") is treated as "nn-NO"</ul> 2364 * 2365 * @param locale the locale 2366 * @return This builder. 2367 * @throws IllformedLocaleException if <code>locale</code> has 2368 * any ill-formed fields. 2369 * @throws NullPointerException if <code>locale</code> is null. 2370 */ 2371 public Builder setLocale(Locale locale) { 2372 try { 2373 localeBuilder.setLocale(locale.baseLocale, locale.localeExtensions); 2374 } catch (LocaleSyntaxException e) { 2375 throw new IllformedLocaleException(e.getMessage(), e.getErrorIndex()); 2376 } 2377 return this; 2378 } 2379 2380 /** 2381 * Resets the Builder to match the provided IETF BCP 47 2382 * language tag. Discards the existing state. Null and the 2383 * empty string cause the builder to be reset, like {@link 2384 * #clear}. Grandfathered tags (see {@link 2385 * Locale#forLanguageTag}) are converted to their canonical 2386 * form before being processed. Otherwise, the language tag 2387 * must be well-formed (see {@link Locale}) or an exception is 2388 * thrown (unlike <code>Locale.forLanguageTag</code>, which 2389 * just discards ill-formed and following portions of the 2390 * tag). 2391 * 2392 * @param languageTag the language tag 2393 * @return This builder. 2394 * @throws IllformedLocaleException if <code>languageTag</code> is ill-formed 2395 * @see Locale#forLanguageTag(String) 2396 */ 2397 public Builder setLanguageTag(String languageTag) { 2398 ParseStatus sts = new ParseStatus(); 2399 LanguageTag tag = LanguageTag.parse(languageTag, sts); 2400 if (sts.isError()) { 2401 throw new IllformedLocaleException(sts.getErrorMessage(), sts.getErrorIndex()); 2402 } 2403 localeBuilder.setLanguageTag(tag); 2404 return this; 2405 } 2406 2407 /** 2408 * Sets the language. If <code>language</code> is the empty string or 2409 * null, the language in this <code>Builder</code> is removed. Otherwise, 2410 * the language must be <a href="./Locale.html#def_language">well-formed</a> 2411 * or an exception is thrown. 2412 * 2413 * <p>The typical language value is a two or three-letter language 2414 * code as defined in ISO639. 2415 * 2416 * @param language the language 2417 * @return This builder. 2418 * @throws IllformedLocaleException if <code>language</code> is ill-formed 2419 */ 2420 public Builder setLanguage(String language) { 2421 try { 2422 localeBuilder.setLanguage(language); 2423 } catch (LocaleSyntaxException e) { 2424 throw new IllformedLocaleException(e.getMessage(), e.getErrorIndex()); 2425 } 2426 return this; 2427 } 2428 2429 /** 2430 * Sets the script. If <code>script</code> is null or the empty string, 2431 * the script in this <code>Builder</code> is removed. 2432 * Otherwise, the script must be <a href="./Locale.html#def_script">well-formed</a> or an 2433 * exception is thrown. 2434 * 2435 * <p>The typical script value is a four-letter script code as defined by ISO 15924. 2436 * 2437 * @param script the script 2438 * @return This builder. 2439 * @throws IllformedLocaleException if <code>script</code> is ill-formed 2440 */ 2441 public Builder setScript(String script) { 2442 try { 2443 localeBuilder.setScript(script); 2444 } catch (LocaleSyntaxException e) { 2445 throw new IllformedLocaleException(e.getMessage(), e.getErrorIndex()); 2446 } 2447 return this; 2448 } 2449 2450 /** 2451 * Sets the region. If region is null or the empty string, the region 2452 * in this <code>Builder</code> is removed. Otherwise, 2453 * the region must be <a href="./Locale.html#def_region">well-formed</a> or an 2454 * exception is thrown. 2455 * 2456 * <p>The typical region value is a two-letter ISO 3166 code or a 2457 * three-digit UN M.49 area code. 2458 * 2459 * <p>The country value in the <code>Locale</code> created by the 2460 * <code>Builder</code> is always normalized to upper case. 2461 * 2462 * @param region the region 2463 * @return This builder. 2464 * @throws IllformedLocaleException if <code>region</code> is ill-formed 2465 */ 2466 public Builder setRegion(String region) { 2467 try { 2468 localeBuilder.setRegion(region); 2469 } catch (LocaleSyntaxException e) { 2470 throw new IllformedLocaleException(e.getMessage(), e.getErrorIndex()); 2471 } 2472 return this; 2473 } 2474 2475 /** 2476 * Sets the variant. If variant is null or the empty string, the 2477 * variant in this <code>Builder</code> is removed. Otherwise, it 2478 * must consist of one or more <a href="./Locale.html#def_variant">well-formed</a> 2479 * subtags, or an exception is thrown. 2480 * 2481 * <p><b>Note:</b> This method checks if <code>variant</code> 2482 * satisfies the IETF BCP 47 variant subtag's syntax requirements, 2483 * and normalizes the value to lowercase letters. However, 2484 * the <code>Locale</code> class does not impose any syntactic 2485 * restriction on variant, and the variant value in 2486 * <code>Locale</code> is case sensitive. To set such a variant, 2487 * use a Locale constructor. 2488 * 2489 * @param variant the variant 2490 * @return This builder. 2491 * @throws IllformedLocaleException if <code>variant</code> is ill-formed 2492 */ 2493 public Builder setVariant(String variant) { 2494 try { 2495 localeBuilder.setVariant(variant); 2496 } catch (LocaleSyntaxException e) { 2497 throw new IllformedLocaleException(e.getMessage(), e.getErrorIndex()); 2498 } 2499 return this; 2500 } 2501 2502 /** 2503 * Sets the extension for the given key. If the value is null or the 2504 * empty string, the extension is removed. Otherwise, the extension 2505 * must be <a href="./Locale.html#def_extensions">well-formed</a> or an exception 2506 * is thrown. 2507 * 2508 * <p><b>Note:</b> The key {@link Locale#UNICODE_LOCALE_EXTENSION 2509 * UNICODE_LOCALE_EXTENSION} ('u') is used for the Unicode locale extension. 2510 * Setting a value for this key replaces any existing Unicode locale key/type 2511 * pairs with those defined in the extension. 2512 * 2513 * <p><b>Note:</b> The key {@link Locale#PRIVATE_USE_EXTENSION 2514 * PRIVATE_USE_EXTENSION} ('x') is used for the private use code. To be 2515 * well-formed, the value for this key needs only to have subtags of one to 2516 * eight alphanumeric characters, not two to eight as in the general case. 2517 * 2518 * @param key the extension key 2519 * @param value the extension value 2520 * @return This builder. 2521 * @throws IllformedLocaleException if <code>key</code> is illegal 2522 * or <code>value</code> is ill-formed 2523 * @see #setUnicodeLocaleKeyword(String, String) 2524 */ 2525 public Builder setExtension(char key, String value) { 2526 try { 2527 localeBuilder.setExtension(key, value); 2528 } catch (LocaleSyntaxException e) { 2529 throw new IllformedLocaleException(e.getMessage(), e.getErrorIndex()); 2530 } 2531 return this; 2532 } 2533 2534 /** 2535 * Sets the Unicode locale keyword type for the given key. If the type 2536 * is null, the Unicode keyword is removed. Otherwise, the key must be 2537 * non-null and both key and type must be <a 2538 * href="./Locale.html#def_locale_extension">well-formed</a> or an exception 2539 * is thrown. 2540 * 2541 * <p>Keys and types are converted to lower case. 2542 * 2543 * <p><b>Note</b>:Setting the 'u' extension via {@link #setExtension} 2544 * replaces all Unicode locale keywords with those defined in the 2545 * extension. 2546 * 2547 * @param key the Unicode locale key 2548 * @param type the Unicode locale type 2549 * @return This builder. 2550 * @throws IllformedLocaleException if <code>key</code> or <code>type</code> 2551 * is ill-formed 2552 * @throws NullPointerException if <code>key</code> is null 2553 * @see #setExtension(char, String) 2554 */ 2555 public Builder setUnicodeLocaleKeyword(String key, String type) { 2556 try { 2557 localeBuilder.setUnicodeLocaleKeyword(key, type); 2558 } catch (LocaleSyntaxException e) { 2559 throw new IllformedLocaleException(e.getMessage(), e.getErrorIndex()); 2560 } 2561 return this; 2562 } 2563 2564 /** 2565 * Adds a unicode locale attribute, if not already present, otherwise 2566 * has no effect. The attribute must not be null and must be <a 2567 * href="./Locale.html#def_locale_extension">well-formed</a> or an exception 2568 * is thrown. 2569 * 2570 * @param attribute the attribute 2571 * @return This builder. 2572 * @throws NullPointerException if <code>attribute</code> is null 2573 * @throws IllformedLocaleException if <code>attribute</code> is ill-formed 2574 * @see #setExtension(char, String) 2575 */ 2576 public Builder addUnicodeLocaleAttribute(String attribute) { 2577 try { 2578 localeBuilder.addUnicodeLocaleAttribute(attribute); 2579 } catch (LocaleSyntaxException e) { 2580 throw new IllformedLocaleException(e.getMessage(), e.getErrorIndex()); 2581 } 2582 return this; 2583 } 2584 2585 /** 2586 * Removes a unicode locale attribute, if present, otherwise has no 2587 * effect. The attribute must not be null and must be <a 2588 * href="./Locale.html#def_locale_extension">well-formed</a> or an exception 2589 * is thrown. 2590 * 2591 * <p>Attribute comparision for removal is case-insensitive. 2592 * 2593 * @param attribute the attribute 2594 * @return This builder. 2595 * @throws NullPointerException if <code>attribute</code> is null 2596 * @throws IllformedLocaleException if <code>attribute</code> is ill-formed 2597 * @see #setExtension(char, String) 2598 */ 2599 public Builder removeUnicodeLocaleAttribute(String attribute) { 2600 try { 2601 localeBuilder.removeUnicodeLocaleAttribute(attribute); 2602 } catch (LocaleSyntaxException e) { 2603 throw new IllformedLocaleException(e.getMessage(), e.getErrorIndex()); 2604 } 2605 return this; 2606 } 2607 2608 /** 2609 * Resets the builder to its initial, empty state. 2610 * 2611 * @return This builder. 2612 */ 2613 public Builder clear() { 2614 localeBuilder.clear(); 2615 return this; 2616 } 2617 2618 /** 2619 * Resets the extensions to their initial, empty state. 2620 * Language, script, region and variant are unchanged. 2621 * 2622 * @return This builder. 2623 * @see #setExtension(char, String) 2624 */ 2625 public Builder clearExtensions() { 2626 localeBuilder.clearExtensions(); 2627 return this; 2628 } 2629 2630 /** 2631 * Returns an instance of <code>Locale</code> created from the fields set 2632 * on this builder. 2633 * 2634 * <p>This applies the conversions listed in {@link Locale#forLanguageTag} 2635 * when constructing a Locale. (Grandfathered tags are handled in 2636 * {@link #setLanguageTag}.) 2637 * 2638 * @return A Locale. 2639 */ 2640 public Locale build() { 2641 BaseLocale baseloc = localeBuilder.getBaseLocale(); 2642 LocaleExtensions extensions = localeBuilder.getLocaleExtensions(); 2643 if (extensions == null && baseloc.getVariant().length() > 0) { 2644 extensions = getCompatibilityExtensions(baseloc.getLanguage(), baseloc.getScript(), 2645 baseloc.getRegion(), baseloc.getVariant()); 2646 } 2647 return Locale.getInstance(baseloc, extensions); 2648 } 2649 } 2650 2651 /** 2652 * This enum provides constants to select a filtering mode for locale 2653 * matching. Refer to <a href="http://tools.ietf.org/html/rfc4647">RFC 4647 2654 * Matching of Language Tags</a> for details. 2655 * 2656 * <p>As an example, think of two Language Priority Lists each of which 2657 * includes only one language range and a set of following language tags: 2658 * 2659 * <pre> 2660 * de (German) 2661 * de-DE (German, Germany) 2662 * de-Deva (German, in Devanagari script) 2663 * de-Deva-DE (German, in Devanagari script, Germany) 2664 * de-DE-1996 (German, Germany, orthography of 1996) 2665 * de-Latn-DE (German, in Latin script, Germany) 2666 * de-Latn-DE-1996 (German, in Latin script, Germany, orthography of 1996) 2667 * </pre> 2668 * 2669 * The filtering method will behave as follows: 2670 * 2671 * <table cellpadding=2> 2672 * <tr> 2673 * <th>Filtering Mode</th> 2674 * <th>Language Priority List: {@code "de-DE"}</th> 2675 * <th>Language Priority List: {@code "de-*-DE"}</th> 2676 * </tr> 2677 * <tr> 2678 * <td valign=top> 2679 * {@link FilteringMode#AUTOSELECT_FILTERING AUTOSELECT_FILTERING} 2680 * </td> 2681 * <td valign=top> 2682 * Performs <em>basic</em> filtering and returns {@code "de-DE"} and 2683 * {@code "de-DE-1996"}. 2684 * </td> 2685 * <td valign=top> 2686 * Performs <em>extended</em> filtering and returns {@code "de-DE"}, 2687 * {@code "de-Deva-DE"}, {@code "de-DE-1996"}, {@code "de-Latn-DE"}, and 2688 * {@code "de-Latn-DE-1996"}. 2689 * </td> 2690 * </tr> 2691 * <tr> 2692 * <td valign=top> 2693 * {@link FilteringMode#EXTENDED_FILTERING EXTENDED_FILTERING} 2694 * </td> 2695 * <td valign=top> 2696 * Performs <em>extended</em> filtering and returns {@code "de-DE"}, 2697 * {@code "de-Deva-DE"}, {@code "de-DE-1996"}, {@code "de-Latn-DE"}, and 2698 * {@code "de-Latn-DE-1996"}. 2699 * </td> 2700 * <td valign=top>Same as above.</td> 2701 * </tr> 2702 * <tr> 2703 * <td valign=top> 2704 * {@link FilteringMode#IGNORE_EXTENDED_RANGES IGNORE_EXTENDED_RANGES} 2705 * </td> 2706 * <td valign=top> 2707 * Performs <em>basic</em> filtering and returns {@code "de-DE"} and 2708 * {@code "de-DE-1996"}. 2709 * </td> 2710 * <td valign=top> 2711 * Performs <em>basic</em> filtering and returns {@code null} because 2712 * nothing matches. 2713 * </td> 2714 * </tr> 2715 * <tr> 2716 * <td valign=top> 2717 * {@link FilteringMode#MAP_EXTENDED_RANGES MAP_EXTENDED_RANGES} 2718 * </td> 2719 * <td valign=top>Same as above.</td> 2720 * <td valign=top> 2721 * Performs <em>basic</em> filtering and returns {@code "de-DE"} and 2722 * {@code "de-DE-1996"} because {@code "de-*-DE"} is mapped to 2723 * {@code "de-DE"}. 2724 * </td> 2725 * </tr> 2726 * <tr> 2727 * <td valign=top> 2728 * {@link FilteringMode#REJECT_EXTENDED_RANGES REJECT_EXTENDED_RANGES} 2729 * </td> 2730 * <td valign=top>Same as above.</td> 2731 * <td valign=top> 2732 * Throws {@link IllegalArgumentException} because {@code "de-*-DE"} is 2733 * not a valid basic language range. 2734 * </td> 2735 * </tr> 2736 * </table> 2737 * 2738 * @see #filter(List, Collection, FilteringMode) 2739 * @see #filterTags(List, Collection, FilteringMode) 2740 * 2741 * @since 1.8 2742 */ 2743 public static enum FilteringMode { 2744 /** 2745 * Specifies automatic filtering mode based on the given Language 2746 * Priority List consisting of language ranges. If all of the ranges 2747 * are basic, basic filtering is selected. Otherwise, extended 2748 * filtering is selected. 2749 */ 2750 AUTOSELECT_FILTERING, 2751 2752 /** 2753 * Specifies extended filtering. 2754 */ 2755 EXTENDED_FILTERING, 2756 2757 /** 2758 * Specifies basic filtering: Note that any extended language ranges 2759 * included in the given Language Priority List are ignored. 2760 */ 2761 IGNORE_EXTENDED_RANGES, 2762 2763 /** 2764 * Specifies basic filtering: If any extended language ranges are 2765 * included in the given Language Priority List, they are mapped to the 2766 * basic language range. Specifically, a language range starting with a 2767 * subtag {@code "*"} is treated as a language range {@code "*"}. For 2768 * example, {@code "*-US"} is treated as {@code "*"}. If {@code "*"} is 2769 * not the first subtag, {@code "*"} and extra {@code "-"} are removed. 2770 * For example, {@code "ja-*-JP"} is mapped to {@code "ja-JP"}. 2771 */ 2772 MAP_EXTENDED_RANGES, 2773 2774 /** 2775 * Specifies basic filtering: If any extended language ranges are 2776 * included in the given Language Priority List, the list is rejected 2777 * and the filtering method throws {@link IllegalArgumentException}. 2778 */ 2779 REJECT_EXTENDED_RANGES 2780 }; 2781 2782 /** 2783 * This class expresses a <em>Language Range</em> defined in 2784 * <a href="http://tools.ietf.org/html/rfc4647">RFC 4647 Matching of 2785 * Language Tags</a>. A language range is an identifier which is used to 2786 * select language tag(s) meeting specific requirements by using the 2787 * mechanisms described in <a href="Locale.html#LocaleMatching">Locale 2788 * Matching</a>. A list which represents a user's preferences and consists 2789 * of language ranges is called a <em>Language Priority List</em>. 2790 * 2791 * <p>There are two types of language ranges: basic and extended. In RFC 2792 * 4647, the syntax of language ranges is expressed in 2793 * <a href="http://tools.ietf.org/html/rfc4234">ABNF</a> as follows: 2794 * <blockquote> 2795 * <pre> 2796 * basic-language-range = (1*8ALPHA *("-" 1*8alphanum)) / "*" 2797 * extended-language-range = (1*8ALPHA / "*") 2798 * *("-" (1*8alphanum / "*")) 2799 * alphanum = ALPHA / DIGIT 2800 * </pre> 2801 * </blockquote> 2802 * For example, {@code "en"} (English), {@code "ja-JP"} (Japanese, Japan), 2803 * {@code "*"} (special language range which matches any language tag) are 2804 * basic language ranges, whereas {@code "*-CH"} (any languages, 2805 * Switzerland), {@code "es-*"} (Spanish, any regions), and 2806 * {@code "zh-Hant-*"} (Traditional Chinese, any regions) are extended 2807 * language ranges. 2808 * 2809 * @see #filter 2810 * @see #filterTags 2811 * @see #lookup 2812 * @see #lookupTag 2813 * 2814 * @since 1.8 2815 */ 2816 public static final class LanguageRange { 2817 2818 /** 2819 * A constant holding the maximum value of weight, 1.0, which indicates 2820 * that the language range is a good fit for the user. 2821 */ 2822 public static final double MAX_WEIGHT = 1.0; 2823 2824 /** 2825 * A constant holding the minimum value of weight, 0.0, which indicates 2826 * that the language range is not a good fit for the user. 2827 */ 2828 public static final double MIN_WEIGHT = 0.0; 2829 2830 private final String range; 2831 private final double weight; 2832 2833 private volatile int hash = 0; 2834 2835 /** 2836 * Constructs a {@code LanguageRange} using the given {@code range}. 2837 * Note that no validation is done against the IANA Language Subtag 2838 * Registry at time of construction. 2839 * 2840 * <p>This is equivalent to {@code LanguageRange(range, MAX_WEIGHT)}. 2841 * 2842 * @param range a language range 2843 * @throws NullPointerException if the given {@code range} is 2844 * {@code null} 2845 */ 2846 public LanguageRange(String range) { 2847 this(range, MAX_WEIGHT); 2848 } 2849 2850 /** 2851 * Constructs a {@code LanguageRange} using the given {@code range} and 2852 * {@code weight}. Note that no validation is done against the IANA 2853 * Language Subtag Registry at time of construction. 2854 * 2855 * @param range a language range 2856 * @param weight a weight value between {@code MIN_WEIGHT} and 2857 * {@code MAX_WEIGHT} 2858 * @throws NullPointerException if the given {@code range} is 2859 * {@code null} 2860 * @throws IllegalArgumentException if the given {@code weight} is less 2861 * than {@code MIN_WEIGHT} or greater than {@code MAX_WEIGHT} 2862 */ 2863 public LanguageRange(String range, double weight) { 2864 if (range == null) { 2865 throw new NullPointerException(); 2866 } 2867 if (weight < MIN_WEIGHT || weight > MAX_WEIGHT) { 2868 throw new IllegalArgumentException("weight=" + weight); 2869 } 2870 2871 range = range.toLowerCase(); 2872 2873 // Do syntax check. 2874 boolean isIllFormed = false; 2875 String[] subtags = range.split("-"); 2876 if (isSubtagIllFormed(subtags[0], true) 2877 || range.endsWith("-")) { 2878 isIllFormed = true; 2879 } else { 2880 for (int i = 1; i < subtags.length; i++) { 2881 if (isSubtagIllFormed(subtags[i], false)) { 2882 isIllFormed = true; 2883 } 2884 break; 2885 } 2886 } 2887 if (isIllFormed) { 2888 throw new IllegalArgumentException("range=" + range); 2889 } 2890 2891 this.range = range; 2892 this.weight = weight; 2893 } 2894 2895 private static boolean isSubtagIllFormed(String subtag, 2896 boolean isFirstSubtag) { 2897 if (subtag.equals("") || subtag.length() > 8) { 2898 return true; 2899 } else if (subtag.equals("*")) { 2900 return false; 2901 } 2902 char[] charArray = subtag.toCharArray(); 2903 if (isFirstSubtag) { // ALPHA 2904 for (char c : charArray) { 2905 if (c < 'a' || c > 'z') { 2906 return true; 2907 } 2908 } 2909 } else { // ALPHA / DIGIT 2910 for (char c : charArray) { 2911 if (c < '0' || (c > '9' && c < 'a') || c > 'z') { 2912 return true; 2913 } 2914 } 2915 } 2916 return false; 2917 } 2918 2919 /** 2920 * Returns the language range of this {@code LanguageRange}. 2921 * 2922 * @return the language range. 2923 */ 2924 public String getRange() { 2925 return range; 2926 } 2927 2928 /** 2929 * Returns the weight of this {@code LanguageRange}. 2930 * 2931 * @return the weight value. 2932 */ 2933 public double getWeight() { 2934 return weight; 2935 } 2936 2937 /** 2938 * Parses the given {@code ranges} to generate a Language Priority List. 2939 * 2940 * <p>This method performs a syntactic check for each language range in 2941 * the given {@code ranges} but doesn't do validation using the IANA 2942 * Language Subtag Registry. 2943 * 2944 * <p>The {@code ranges} to be given can take one of the following 2945 * forms: 2946 * 2947 * <pre> 2948 * "Accept-Language: ja,en;q=0.4" (weighted list with Accept-Language prefix) 2949 * "ja,en;q=0.4" (weighted list) 2950 * "ja,en" (prioritized list) 2951 * </pre> 2952 * 2953 * In a weighted list, each language range is given a weight value. 2954 * The weight value is identical to the "quality value" in 2955 * <a href="http://tools.ietf.org/html/rfc2616">RFC 2616</a>, and it 2956 * expresses how much the user prefers the language. A weight value is 2957 * specified after a corresponding language range followed by 2958 * {@code ";q="}, and the default weight value is {@code MAX_WEIGHT} 2959 * when it is omitted. 2960 * 2961 * <p>Unlike a weighted list, language ranges in a prioritized list 2962 * are sorted in the descending order based on its priority. The first 2963 * language range has the highest priority and meets the user's 2964 * preference most. 2965 * 2966 * <p>In either case, language ranges are sorted in descending order in 2967 * the Language Priority List based on priority or weight. If a 2968 * language range appears in the given {@code ranges} more than once, 2969 * only the first one is included on the Language Priority List. 2970 * 2971 * <p>The returned list consists of language ranges from the given 2972 * {@code ranges} and their equivalents found in the IANA Language 2973 * Subtag Registry. For example, if the given {@code ranges} is 2974 * {@code "Accept-Language: iw,en-us;q=0.7,en;q=0.3"}, the elements in 2975 * the list to be returned are: 2976 * 2977 * <pre> 2978 * <b>Range</b> <b>Weight</b> 2979 * "iw" (older tag for Hebrew) 1.0 2980 * "he" (new preferred code for Hebrew) 1.0 2981 * "en-us" (English, United States) 0.7 2982 * "en" (English) 0.3 2983 * </pre> 2984 * 2985 * Two language ranges, {@code "iw"} and {@code "he"}, have the same 2986 * highest priority in the list. By adding {@code "he"} to the user's 2987 * Language Priority List, locale-matching method can find Hebrew as a 2988 * matching locale (or language tag) even if the application or system 2989 * offers only {@code "he"} as a supported locale (or language tag). 2990 * 2991 * @param ranges a list of comma-separated language ranges or a list of 2992 * language ranges in the form of the "Accept-Language" header 2993 * defined in <a href="http://tools.ietf.org/html/rfc2616">RFC 2994 * 2616</a> 2995 * @return a Language Priority List consisting of language ranges 2996 * included in the given {@code ranges} and their equivalent 2997 * language ranges if available. The list is modifiable. 2998 * @throws NullPointerException if {@code ranges} is null 2999 * @throws IllegalArgumentException if a language range or a weight 3000 * found in the given {@code ranges} is ill-formed 3001 */ 3002 public static List<LanguageRange> parse(String ranges) { 3003 return LocaleMatcher.parse(ranges); 3004 } 3005 3006 /** 3007 * Parses the given {@code ranges} to generate a Language Priority 3008 * List, and then customizes the list using the given {@code map}. 3009 * This method is equivalent to 3010 * {@code mapEquivalents(parse(ranges), map)}. 3011 * 3012 * @param ranges a list of comma-separated language ranges or a list 3013 * of language ranges in the form of the "Accept-Language" header 3014 * defined in <a href="http://tools.ietf.org/html/rfc2616">RFC 3015 * 2616</a> 3016 * @param map a map containing information to customize language ranges 3017 * @return a Language Priority List with customization. The list is 3018 * @throws NullPointerException if {@code ranges} is null 3019 * @throws IllegalArgumentException if a language range or a weight 3020 * found in the given {@code ranges} is ill-formed 3021 * @see #parse(String) 3022 * @see #mapEquivalents 3023 */ 3024 public static List<LanguageRange> parse(String ranges, 3025 Map<String, List<String>> map) { 3026 return mapEquivalents(parse(ranges), map); 3027 } 3028 3029 /** 3030 * Generates a new customized Language Priority List using the given 3031 * {@code priorityList} and {@code map}. If the given {@code map} is 3032 * empty, this method returns a copy of the given {@code priorityList}. 3033 * 3034 * <p>In the map, a key represents a language range whereas a value is 3035 * a list of equivalents of it. {@code '*'} cannot be used in the map. 3036 * Each equivalent language range has the same weight value as its 3037 * original language range. 3038 * 3039 * <pre> 3040 * An example of map: 3041 * <b>Key</b> <b>Value</b> 3042 * "zh" (Chinese) "zh", 3043 * "zh-Hans"(Simplified Chinese) 3044 * "zh-HK" (Chinese, Hong Kong) "zh-HK" 3045 * "zh-TW" (Chinese, Taiwan) "zh-TW" 3046 * </pre> 3047 * 3048 * The customization is performed after modification using the IANA 3049 * Language Subtag Registry. 3050 * 3051 * <p>For example, if a user's Language Priority List consists of five 3052 * language ranges ({@code "zh"}, {@code "zh-CN"}, {@code "en"}, 3053 * {@code "zh-TW"}, and {@code "zh-HK"}), the newly generated Language 3054 * Priority List which is customized using the above map example will 3055 * consists of {@code "zh"}, {@code "zh-Hans"}, {@code "zh-CN"}, 3056 * {@code "zh-Hans-CN"}, {@code "en"}, {@code "zh-TW"}, and 3057 * {@code "zh-HK"}. 3058 * 3059 * <p>{@code "zh-HK"} and {@code "zh-TW"} aren't converted to 3060 * {@code "zh-Hans-HK"} nor {@code "zh-Hans-TW"} even if they are 3061 * included in the Language Priority List. In this example, mapping 3062 * is used to clearly distinguish Simplified Chinese and Traditional 3063 * Chinese. 3064 * 3065 * <p>If the {@code "zh"}-to-{@code "zh"} mapping isn't included in the 3066 * map, a simple replacement will be performed and the customized list 3067 * won't include {@code "zh"} and {@code "zh-CN"}. 3068 * 3069 * @param priorityList user's Language Priority List 3070 * @param map a map containing information to customize language ranges 3071 * @return a new Language Priority List with customization. The list is 3072 * modifiable. 3073 * @throws NullPointerException if {@code priorityList} is {@code null} 3074 * @see #parse(String, Map) 3075 */ 3076 public static List<LanguageRange> mapEquivalents( 3077 List<LanguageRange>priorityList, 3078 Map<String, List<String>> map) { 3079 return LocaleMatcher.mapEquivalents(priorityList, map); 3080 } 3081 3082 /** 3083 * Returns a hash code value for the object. 3084 * 3085 * @return a hash code value for this object. 3086 */ 3087 @Override 3088 public int hashCode() { 3089 if (hash == 0) { 3090 int result = 17; 3091 result = 37*result + range.hashCode(); 3092 long bitsWeight = Double.doubleToLongBits(weight); 3093 result = 37*result + (int)(bitsWeight ^ (bitsWeight >>> 32)); 3094 hash = result; 3095 } 3096 return hash; 3097 } 3098 3099 /** 3100 * Compares this object to the specified object. The result is true if 3101 * and only if the argument is not {@code null} and is a 3102 * {@code LanguageRange} object that contains the same {@code range} 3103 * and {@code weight} values as this object. 3104 * 3105 * @param obj the object to compare with 3106 * @return {@code true} if this object's {@code range} and 3107 * {@code weight} are the same as the {@code obj}'s; {@code false} 3108 * otherwise. 3109 */ 3110 @Override 3111 public boolean equals(Object obj) { 3112 if (this == obj) { 3113 return true; 3114 } 3115 if (!(obj instanceof LanguageRange)) { 3116 return false; 3117 } 3118 LanguageRange other = (LanguageRange)obj; 3119 return hash == other.hash 3120 && range.equals(other.range) 3121 && weight == other.weight; 3122 } 3123 } 3124 3125 /** 3126 * Returns a list of matching {@code Locale} instances using the filtering 3127 * mechanism defined in RFC 4647. 3128 * 3129 * @param priorityList user's Language Priority List in which each language 3130 * tag is sorted in descending order based on priority or weight 3131 * @param locales {@code Locale} instances used for matching 3132 * @param mode filtering mode 3133 * @return a list of {@code Locale} instances for matching language tags 3134 * sorted in descending order based on priority or weight, or an empty 3135 * list if nothing matches. The list is modifiable. 3136 * @throws NullPointerException if {@code priorityList} or {@code locales} 3137 * is {@code null} 3138 * @throws IllegalArgumentException if one or more extended language ranges 3139 * are included in the given list when 3140 * {@link FilteringMode#REJECT_EXTENDED_RANGES} is specified 3141 * 3142 * @since 1.8 3143 */ 3144 public static List<Locale> filter(List<LanguageRange> priorityList, 3145 Collection<Locale> locales, 3146 FilteringMode mode) { 3147 return LocaleMatcher.filter(priorityList, locales, mode); 3148 } 3149 3150 /** 3151 * Returns a list of matching {@code Locale} instances using the filtering 3152 * mechanism defined in RFC 4647. This is equivalent to 3153 * {@link #filter(List, Collection, FilteringMode)} when {@code mode} is 3154 * {@link FilteringMode#AUTOSELECT_FILTERING}. 3155 * 3156 * @param priorityList user's Language Priority List in which each language 3157 * tag is sorted in descending order based on priority or weight 3158 * @param locales {@code Locale} instances used for matching 3159 * @return a list of {@code Locale} instances for matching language tags 3160 * sorted in descending order based on priority or weight, or an empty 3161 * list if nothing matches. The list is modifiable. 3162 * @throws NullPointerException if {@code priorityList} or {@code locales} 3163 * is {@code null} 3164 * 3165 * @since 1.8 3166 */ 3167 public static List<Locale> filter(List<LanguageRange> priorityList, 3168 Collection<Locale> locales) { 3169 return filter(priorityList, locales, FilteringMode.AUTOSELECT_FILTERING); 3170 } 3171 3172 /** 3173 * Returns a list of matching languages tags using the basic filtering 3174 * mechanism defined in RFC 4647. 3175 * 3176 * @param priorityList user's Language Priority List in which each language 3177 * tag is sorted in descending order based on priority or weight 3178 * @param tags language tags 3179 * @param mode filtering mode 3180 * @return a list of matching language tags sorted in descending order 3181 * based on priority or weight, or an empty list if nothing matches. 3182 * The list is modifiable. 3183 * @throws NullPointerException if {@code priorityList} or {@code tags} is 3184 * {@code null} 3185 * @throws IllegalArgumentException if one or more extended language ranges 3186 * are included in the given list when 3187 * {@link FilteringMode#REJECT_EXTENDED_RANGES} is specified 3188 * 3189 * @since 1.8 3190 */ 3191 public static List<String> filterTags(List<LanguageRange> priorityList, 3192 Collection<String> tags, 3193 FilteringMode mode) { 3194 return LocaleMatcher.filterTags(priorityList, tags, mode); 3195 } 3196 3197 /** 3198 * Returns a list of matching languages tags using the basic filtering 3199 * mechanism defined in RFC 4647. This is equivalent to 3200 * {@link #filterTags(List, Collection, FilteringMode)} when {@code mode} 3201 * is {@link FilteringMode#AUTOSELECT_FILTERING}. 3202 * 3203 * @param priorityList user's Language Priority List in which each language 3204 * tag is sorted in descending order based on priority or weight 3205 * @param tags language tags 3206 * @return a list of matching language tags sorted in descending order 3207 * based on priority or weight, or an empty list if nothing matches. 3208 * The list is modifiable. 3209 * @throws NullPointerException if {@code priorityList} or {@code tags} is 3210 * {@code null} 3211 * 3212 * @since 1.8 3213 */ 3214 public static List<String> filterTags(List<LanguageRange> priorityList, 3215 Collection<String> tags) { 3216 return filterTags(priorityList, tags, FilteringMode.AUTOSELECT_FILTERING); 3217 } 3218 3219 /** 3220 * Returns a {@code Locale} instance for the best-matching language 3221 * tag using the lookup mechanism defined in RFC 4647. 3222 * 3223 * @param priorityList user's Language Priority List in which each language 3224 * tag is sorted in descending order based on priority or weight 3225 * @param locales {@code Locale} instances used for matching 3226 * @return the best matching <code>Locale</code> instance chosen based on 3227 * priority or weight, or {@code null} if nothing matches. 3228 * @throws NullPointerException if {@code priorityList} or {@code tags} is 3229 * {@code null} 3230 * 3231 * @since 1.8 3232 */ 3233 public static Locale lookup(List<LanguageRange> priorityList, 3234 Collection<Locale> locales) { 3235 return LocaleMatcher.lookup(priorityList, locales); 3236 } 3237 3238 /** 3239 * Returns the best-matching language tag using the lookup mechanism 3240 * defined in RFC 4647. 3241 * 3242 * @param priorityList user's Language Priority List in which each language 3243 * tag is sorted in descending order based on priority or weight 3244 * @param tags language tangs used for matching 3245 * @return the best matching language tag chosen based on priority or 3246 * weight, or {@code null} if nothing matches. 3247 * @throws NullPointerException if {@code priorityList} or {@code tags} is 3248 * {@code null} 3249 * 3250 * @since 1.8 3251 */ 3252 public static String lookupTag(List<LanguageRange> priorityList, 3253 Collection<String> tags) { 3254 return LocaleMatcher.lookupTag(priorityList, tags); 3255 } 3256 3257 }