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 }