jtulach@1318
|
1 |
/*
|
jtulach@1318
|
2 |
* Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
|
jtulach@1318
|
3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
jtulach@1318
|
4 |
*
|
jtulach@1318
|
5 |
* This code is free software; you can redistribute it and/or modify it
|
jtulach@1318
|
6 |
* under the terms of the GNU General Public License version 2 only, as
|
jtulach@1318
|
7 |
* published by the Free Software Foundation. Oracle designates this
|
jtulach@1318
|
8 |
* particular file as subject to the "Classpath" exception as provided
|
jtulach@1318
|
9 |
* by Oracle in the LICENSE file that accompanied this code.
|
jtulach@1318
|
10 |
*
|
jtulach@1318
|
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT
|
jtulach@1318
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
jtulach@1318
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
jtulach@1318
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that
|
jtulach@1318
|
15 |
* accompanied this code).
|
jtulach@1318
|
16 |
*
|
jtulach@1318
|
17 |
* You should have received a copy of the GNU General Public License version
|
jtulach@1318
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation,
|
jtulach@1318
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
jtulach@1318
|
20 |
*
|
jtulach@1318
|
21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
jtulach@1318
|
22 |
* or visit www.oracle.com if you need additional information or have any
|
jtulach@1318
|
23 |
* questions.
|
jtulach@1318
|
24 |
*/
|
jtulach@1318
|
25 |
|
jtulach@1318
|
26 |
/*
|
jtulach@1318
|
27 |
* (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved
|
jtulach@1318
|
28 |
* (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved
|
jtulach@1318
|
29 |
*
|
jtulach@1318
|
30 |
* The original version of this source code and documentation
|
jtulach@1318
|
31 |
* is copyrighted and owned by Taligent, Inc., a wholly-owned
|
jtulach@1318
|
32 |
* subsidiary of IBM. These materials are provided under terms
|
jtulach@1318
|
33 |
* of a License Agreement between Taligent and Sun. This technology
|
jtulach@1318
|
34 |
* is protected by multiple US and International patents.
|
jtulach@1318
|
35 |
*
|
jtulach@1318
|
36 |
* This notice and attribution to Taligent may not be removed.
|
jtulach@1318
|
37 |
* Taligent is a registered trademark of Taligent, Inc.
|
jtulach@1318
|
38 |
*
|
jtulach@1318
|
39 |
*/
|
jtulach@1318
|
40 |
|
jtulach@1318
|
41 |
package java.util;
|
jtulach@1318
|
42 |
|
jtulach@1318
|
43 |
import java.io.IOException;
|
jtulach@1318
|
44 |
import java.io.ObjectInputStream;
|
jtulach@1318
|
45 |
import java.io.ObjectOutputStream;
|
jtulach@1318
|
46 |
import java.io.ObjectStreamField;
|
jtulach@1318
|
47 |
import java.io.Serializable;
|
jtulach@1318
|
48 |
|
jtulach@1318
|
49 |
/**
|
jtulach@1318
|
50 |
* A <code>Locale</code> object represents a specific geographical, political,
|
jtulach@1318
|
51 |
* or cultural region. An operation that requires a <code>Locale</code> to perform
|
jtulach@1318
|
52 |
* its task is called <em>locale-sensitive</em> and uses the <code>Locale</code>
|
jtulach@1318
|
53 |
* to tailor information for the user. For example, displaying a number
|
jtulach@1318
|
54 |
* is a locale-sensitive operation— the number should be formatted
|
jtulach@1318
|
55 |
* according to the customs and conventions of the user's native country,
|
jtulach@1318
|
56 |
* region, or culture.
|
jtulach@1318
|
57 |
*
|
jtulach@1318
|
58 |
* <p> The <code>Locale</code> class implements identifiers
|
jtulach@1318
|
59 |
* interchangeable with BCP 47 (IETF BCP 47, "Tags for Identifying
|
jtulach@1318
|
60 |
* Languages"), with support for the LDML (UTS#35, "Unicode Locale
|
jtulach@1318
|
61 |
* Data Markup Language") BCP 47-compatible extensions for locale data
|
jtulach@1318
|
62 |
* exchange.
|
jtulach@1318
|
63 |
*
|
jtulach@1318
|
64 |
* <p> A <code>Locale</code> object logically consists of the fields
|
jtulach@1318
|
65 |
* described below.
|
jtulach@1318
|
66 |
*
|
jtulach@1318
|
67 |
* <dl>
|
jtulach@1318
|
68 |
* <dt><a name="def_language"/><b>language</b></dt>
|
jtulach@1318
|
69 |
*
|
jtulach@1318
|
70 |
* <dd>ISO 639 alpha-2 or alpha-3 language code, or registered
|
jtulach@1318
|
71 |
* language subtags up to 8 alpha letters (for future enhancements).
|
jtulach@1318
|
72 |
* When a language has both an alpha-2 code and an alpha-3 code, the
|
jtulach@1318
|
73 |
* alpha-2 code must be used. You can find a full list of valid
|
jtulach@1318
|
74 |
* language codes in the IANA Language Subtag Registry (search for
|
jtulach@1318
|
75 |
* "Type: language"). The language field is case insensitive, but
|
jtulach@1318
|
76 |
* <code>Locale</code> always canonicalizes to lower case.</dd><br>
|
jtulach@1318
|
77 |
*
|
jtulach@1318
|
78 |
* <dd>Well-formed language values have the form
|
jtulach@1318
|
79 |
* <code>[a-zA-Z]{2,8}</code>. Note that this is not the the full
|
jtulach@1318
|
80 |
* BCP47 language production, since it excludes extlang. They are
|
jtulach@1318
|
81 |
* not needed since modern three-letter language codes replace
|
jtulach@1318
|
82 |
* them.</dd><br>
|
jtulach@1318
|
83 |
*
|
jtulach@1318
|
84 |
* <dd>Example: "en" (English), "ja" (Japanese), "kok" (Konkani)</dd><br>
|
jtulach@1318
|
85 |
*
|
jtulach@1318
|
86 |
* <dt><a name="def_script"/><b>script</b></dt>
|
jtulach@1318
|
87 |
*
|
jtulach@1318
|
88 |
* <dd>ISO 15924 alpha-4 script code. You can find a full list of
|
jtulach@1318
|
89 |
* valid script codes in the IANA Language Subtag Registry (search
|
jtulach@1318
|
90 |
* for "Type: script"). The script field is case insensitive, but
|
jtulach@1318
|
91 |
* <code>Locale</code> always canonicalizes to title case (the first
|
jtulach@1318
|
92 |
* letter is upper case and the rest of the letters are lower
|
jtulach@1318
|
93 |
* case).</dd><br>
|
jtulach@1318
|
94 |
*
|
jtulach@1318
|
95 |
* <dd>Well-formed script values have the form
|
jtulach@1318
|
96 |
* <code>[a-zA-Z]{4}</code></dd><br>
|
jtulach@1318
|
97 |
*
|
jtulach@1318
|
98 |
* <dd>Example: "Latn" (Latin), "Cyrl" (Cyrillic)</dd><br>
|
jtulach@1318
|
99 |
*
|
jtulach@1318
|
100 |
* <dt><a name="def_region"/><b>country (region)</b></dt>
|
jtulach@1318
|
101 |
*
|
jtulach@1318
|
102 |
* <dd>ISO 3166 alpha-2 country code or UN M.49 numeric-3 area code.
|
jtulach@1318
|
103 |
* You can find a full list of valid country and region codes in the
|
jtulach@1318
|
104 |
* IANA Language Subtag Registry (search for "Type: region"). The
|
jtulach@1318
|
105 |
* country (region) field is case insensitive, but
|
jtulach@1318
|
106 |
* <code>Locale</code> always canonicalizes to upper case.</dd><br>
|
jtulach@1318
|
107 |
*
|
jtulach@1318
|
108 |
* <dd>Well-formed country/region values have
|
jtulach@1318
|
109 |
* the form <code>[a-zA-Z]{2} | [0-9]{3}</code></dd><br>
|
jtulach@1318
|
110 |
*
|
jtulach@1318
|
111 |
* <dd>Example: "US" (United States), "FR" (France), "029"
|
jtulach@1318
|
112 |
* (Caribbean)</dd><br>
|
jtulach@1318
|
113 |
*
|
jtulach@1318
|
114 |
* <dt><a name="def_variant"/><b>variant</b></dt>
|
jtulach@1318
|
115 |
*
|
jtulach@1318
|
116 |
* <dd>Any arbitrary value used to indicate a variation of a
|
jtulach@1318
|
117 |
* <code>Locale</code>. Where there are two or more variant values
|
jtulach@1318
|
118 |
* each indicating its own semantics, these values should be ordered
|
jtulach@1318
|
119 |
* by importance, with most important first, separated by
|
jtulach@1318
|
120 |
* underscore('_'). The variant field is case sensitive.</dd><br>
|
jtulach@1318
|
121 |
*
|
jtulach@1318
|
122 |
* <dd>Note: IETF BCP 47 places syntactic restrictions on variant
|
jtulach@1318
|
123 |
* subtags. Also BCP 47 subtags are strictly used to indicate
|
jtulach@1318
|
124 |
* additional variations that define a language or its dialects that
|
jtulach@1318
|
125 |
* are not covered by any combinations of language, script and
|
jtulach@1318
|
126 |
* region subtags. You can find a full list of valid variant codes
|
jtulach@1318
|
127 |
* in the IANA Language Subtag Registry (search for "Type: variant").
|
jtulach@1318
|
128 |
*
|
jtulach@1318
|
129 |
* <p>However, the variant field in <code>Locale</code> has
|
jtulach@1318
|
130 |
* historically been used for any kind of variation, not just
|
jtulach@1318
|
131 |
* language variations. For example, some supported variants
|
jtulach@1318
|
132 |
* available in Java SE Runtime Environments indicate alternative
|
jtulach@1318
|
133 |
* cultural behaviors such as calendar type or number script. In
|
jtulach@1318
|
134 |
* BCP 47 this kind of information, which does not identify the
|
jtulach@1318
|
135 |
* language, is supported by extension subtags or private use
|
jtulach@1318
|
136 |
* subtags.</dd><br>
|
jtulach@1318
|
137 |
*
|
jtulach@1318
|
138 |
* <dd>Well-formed variant values have the form <code>SUBTAG
|
jtulach@1318
|
139 |
* (('_'|'-') SUBTAG)*</code> where <code>SUBTAG =
|
jtulach@1318
|
140 |
* [0-9][0-9a-zA-Z]{3} | [0-9a-zA-Z]{5,8}</code>. (Note: BCP 47 only
|
jtulach@1318
|
141 |
* uses hyphen ('-') as a delimiter, this is more lenient).</dd><br>
|
jtulach@1318
|
142 |
*
|
jtulach@1318
|
143 |
* <dd>Example: "polyton" (Polytonic Greek), "POSIX"</dd><br>
|
jtulach@1318
|
144 |
*
|
jtulach@1318
|
145 |
* <dt><a name="def_extensions"/><b>extensions</b></dt>
|
jtulach@1318
|
146 |
*
|
jtulach@1318
|
147 |
* <dd>A map from single character keys to string values, indicating
|
jtulach@1318
|
148 |
* extensions apart from language identification. The extensions in
|
jtulach@1318
|
149 |
* <code>Locale</code> implement the semantics and syntax of BCP 47
|
jtulach@1318
|
150 |
* extension subtags and private use subtags. The extensions are
|
jtulach@1318
|
151 |
* case insensitive, but <code>Locale</code> canonicalizes all
|
jtulach@1318
|
152 |
* extension keys and values to lower case. Note that extensions
|
jtulach@1318
|
153 |
* cannot have empty values.</dd><br>
|
jtulach@1318
|
154 |
*
|
jtulach@1318
|
155 |
* <dd>Well-formed keys are single characters from the set
|
jtulach@1318
|
156 |
* <code>[0-9a-zA-Z]</code>. Well-formed values have the form
|
jtulach@1318
|
157 |
* <code>SUBTAG ('-' SUBTAG)*</code> where for the key 'x'
|
jtulach@1318
|
158 |
* <code>SUBTAG = [0-9a-zA-Z]{1,8}</code> and for other keys
|
jtulach@1318
|
159 |
* <code>SUBTAG = [0-9a-zA-Z]{2,8}</code> (that is, 'x' allows
|
jtulach@1318
|
160 |
* single-character subtags).</dd><br>
|
jtulach@1318
|
161 |
*
|
jtulach@1318
|
162 |
* <dd>Example: key="u"/value="ca-japanese" (Japanese Calendar),
|
jtulach@1318
|
163 |
* key="x"/value="java-1-7"</dd>
|
jtulach@1318
|
164 |
* </dl>
|
jtulach@1318
|
165 |
*
|
jtulach@1318
|
166 |
* <b>Note:</b> Although BCP 47 requires field values to be registered
|
jtulach@1318
|
167 |
* in the IANA Language Subtag Registry, the <code>Locale</code> class
|
jtulach@1318
|
168 |
* does not provide any validation features. The <code>Builder</code>
|
jtulach@1318
|
169 |
* only checks if an individual field satisfies the syntactic
|
jtulach@1318
|
170 |
* requirement (is well-formed), but does not validate the value
|
jtulach@1318
|
171 |
* itself. See {@link Builder} for details.
|
jtulach@1318
|
172 |
*
|
jtulach@1318
|
173 |
* <h4><a name="def_locale_extension">Unicode locale/language extension</h4>
|
jtulach@1318
|
174 |
*
|
jtulach@1318
|
175 |
* <p>UTS#35, "Unicode Locale Data Markup Language" defines optional
|
jtulach@1318
|
176 |
* attributes and keywords to override or refine the default behavior
|
jtulach@1318
|
177 |
* associated with a locale. A keyword is represented by a pair of
|
jtulach@1318
|
178 |
* key and type. For example, "nu-thai" indicates that Thai local
|
jtulach@1318
|
179 |
* digits (value:"thai") should be used for formatting numbers
|
jtulach@1318
|
180 |
* (key:"nu").
|
jtulach@1318
|
181 |
*
|
jtulach@1318
|
182 |
* <p>The keywords are mapped to a BCP 47 extension value using the
|
jtulach@1318
|
183 |
* extension key 'u' ({@link #UNICODE_LOCALE_EXTENSION}). The above
|
jtulach@1318
|
184 |
* example, "nu-thai", becomes the extension "u-nu-thai".code
|
jtulach@1318
|
185 |
*
|
jtulach@1318
|
186 |
* <p>Thus, when a <code>Locale</code> object contains Unicode locale
|
jtulach@1318
|
187 |
* attributes and keywords,
|
jtulach@1318
|
188 |
* <code>getExtension(UNICODE_LOCALE_EXTENSION)</code> will return a
|
jtulach@1318
|
189 |
* String representing this information, for example, "nu-thai". The
|
jtulach@1318
|
190 |
* <code>Locale</code> class also provides {@link
|
jtulach@1318
|
191 |
* #getUnicodeLocaleAttributes}, {@link #getUnicodeLocaleKeys}, and
|
jtulach@1318
|
192 |
* {@link #getUnicodeLocaleType} which allow you to access Unicode
|
jtulach@1318
|
193 |
* locale attributes and key/type pairs directly. When represented as
|
jtulach@1318
|
194 |
* a string, the Unicode Locale Extension lists attributes
|
jtulach@1318
|
195 |
* alphabetically, followed by key/type sequences with keys listed
|
jtulach@1318
|
196 |
* alphabetically (the order of subtags comprising a key's type is
|
jtulach@1318
|
197 |
* fixed when the type is defined)
|
jtulach@1318
|
198 |
*
|
jtulach@1318
|
199 |
* <p>A well-formed locale key has the form
|
jtulach@1318
|
200 |
* <code>[0-9a-zA-Z]{2}</code>. A well-formed locale type has the
|
jtulach@1318
|
201 |
* form <code>"" | [0-9a-zA-Z]{3,8} ('-' [0-9a-zA-Z]{3,8})*</code> (it
|
jtulach@1318
|
202 |
* can be empty, or a series of subtags 3-8 alphanums in length). A
|
jtulach@1318
|
203 |
* well-formed locale attribute has the form
|
jtulach@1318
|
204 |
* <code>[0-9a-zA-Z]{3,8}</code> (it is a single subtag with the same
|
jtulach@1318
|
205 |
* form as a locale type subtag).
|
jtulach@1318
|
206 |
*
|
jtulach@1318
|
207 |
* <p>The Unicode locale extension specifies optional behavior in
|
jtulach@1318
|
208 |
* locale-sensitive services. Although the LDML specification defines
|
jtulach@1318
|
209 |
* various keys and values, actual locale-sensitive service
|
jtulach@1318
|
210 |
* implementations in a Java Runtime Environment might not support any
|
jtulach@1318
|
211 |
* particular Unicode locale attributes or key/type pairs.
|
jtulach@1318
|
212 |
*
|
jtulach@1318
|
213 |
* <h4>Creating a Locale</h4>
|
jtulach@1318
|
214 |
*
|
jtulach@1318
|
215 |
* <p>There are several different ways to create a <code>Locale</code>
|
jtulach@1318
|
216 |
* object.
|
jtulach@1318
|
217 |
*
|
jtulach@1318
|
218 |
* <h5>Builder</h5>
|
jtulach@1318
|
219 |
*
|
jtulach@1318
|
220 |
* <p>Using {@link Builder} you can construct a <code>Locale</code> object
|
jtulach@1318
|
221 |
* that conforms to BCP 47 syntax.
|
jtulach@1318
|
222 |
*
|
jtulach@1318
|
223 |
* <h5>Constructors</h5>
|
jtulach@1318
|
224 |
*
|
jtulach@1318
|
225 |
* <p>The <code>Locale</code> class provides three constructors:
|
jtulach@1318
|
226 |
* <blockquote>
|
jtulach@1318
|
227 |
* <pre>
|
jtulach@1318
|
228 |
* {@link #Locale(String language)}
|
jtulach@1318
|
229 |
* {@link #Locale(String language, String country)}
|
jtulach@1318
|
230 |
* {@link #Locale(String language, String country, String variant)}
|
jtulach@1318
|
231 |
* </pre>
|
jtulach@1318
|
232 |
* </blockquote>
|
jtulach@1318
|
233 |
* These constructors allow you to create a <code>Locale</code> object
|
jtulach@1318
|
234 |
* with language, country and variant, but you cannot specify
|
jtulach@1318
|
235 |
* script or extensions.
|
jtulach@1318
|
236 |
*
|
jtulach@1318
|
237 |
* <h5>Factory Methods</h5>
|
jtulach@1318
|
238 |
*
|
jtulach@1318
|
239 |
* <p>The method {@link #forLanguageTag} creates a <code>Locale</code>
|
jtulach@1318
|
240 |
* object for a well-formed BCP 47 language tag.
|
jtulach@1318
|
241 |
*
|
jtulach@1318
|
242 |
* <h5>Locale Constants</h5>
|
jtulach@1318
|
243 |
*
|
jtulach@1318
|
244 |
* <p>The <code>Locale</code> class provides a number of convenient constants
|
jtulach@1318
|
245 |
* that you can use to create <code>Locale</code> objects for commonly used
|
jtulach@1318
|
246 |
* locales. For example, the following creates a <code>Locale</code> object
|
jtulach@1318
|
247 |
* for the United States:
|
jtulach@1318
|
248 |
* <blockquote>
|
jtulach@1318
|
249 |
* <pre>
|
jtulach@1318
|
250 |
* Locale.US
|
jtulach@1318
|
251 |
* </pre>
|
jtulach@1318
|
252 |
* </blockquote>
|
jtulach@1318
|
253 |
*
|
jtulach@1318
|
254 |
* <h4>Use of Locale</h4>
|
jtulach@1318
|
255 |
*
|
jtulach@1318
|
256 |
* <p>Once you've created a <code>Locale</code> you can query it for information
|
jtulach@1318
|
257 |
* about itself. Use <code>getCountry</code> to get the country (or region)
|
jtulach@1318
|
258 |
* code and <code>getLanguage</code> to get the language code.
|
jtulach@1318
|
259 |
* You can use <code>getDisplayCountry</code> to get the
|
jtulach@1318
|
260 |
* name of the country suitable for displaying to the user. Similarly,
|
jtulach@1318
|
261 |
* you can use <code>getDisplayLanguage</code> to get the name of
|
jtulach@1318
|
262 |
* the language suitable for displaying to the user. Interestingly,
|
jtulach@1318
|
263 |
* the <code>getDisplayXXX</code> methods are themselves locale-sensitive
|
jtulach@1318
|
264 |
* and have two versions: one that uses the default locale and one
|
jtulach@1318
|
265 |
* that uses the locale specified as an argument.
|
jtulach@1318
|
266 |
*
|
jtulach@1318
|
267 |
* <p>The Java Platform provides a number of classes that perform locale-sensitive
|
jtulach@1318
|
268 |
* operations. For example, the <code>NumberFormat</code> class formats
|
jtulach@1318
|
269 |
* numbers, currency, and percentages in a locale-sensitive manner. Classes
|
jtulach@1318
|
270 |
* such as <code>NumberFormat</code> have several convenience methods
|
jtulach@1318
|
271 |
* for creating a default object of that type. For example, the
|
jtulach@1318
|
272 |
* <code>NumberFormat</code> class provides these three convenience methods
|
jtulach@1318
|
273 |
* for creating a default <code>NumberFormat</code> object:
|
jtulach@1318
|
274 |
* <blockquote>
|
jtulach@1318
|
275 |
* <pre>
|
jtulach@1318
|
276 |
* NumberFormat.getInstance()
|
jtulach@1318
|
277 |
* NumberFormat.getCurrencyInstance()
|
jtulach@1318
|
278 |
* NumberFormat.getPercentInstance()
|
jtulach@1318
|
279 |
* </pre>
|
jtulach@1318
|
280 |
* </blockquote>
|
jtulach@1318
|
281 |
* Each of these methods has two variants; one with an explicit locale
|
jtulach@1318
|
282 |
* and one without; the latter uses the default locale:
|
jtulach@1318
|
283 |
* <blockquote>
|
jtulach@1318
|
284 |
* <pre>
|
jtulach@1318
|
285 |
* NumberFormat.getInstance(myLocale)
|
jtulach@1318
|
286 |
* NumberFormat.getCurrencyInstance(myLocale)
|
jtulach@1318
|
287 |
* NumberFormat.getPercentInstance(myLocale)
|
jtulach@1318
|
288 |
* </pre>
|
jtulach@1318
|
289 |
* </blockquote>
|
jtulach@1318
|
290 |
* A <code>Locale</code> is the mechanism for identifying the kind of object
|
jtulach@1318
|
291 |
* (<code>NumberFormat</code>) that you would like to get. The locale is
|
jtulach@1318
|
292 |
* <STRONG>just</STRONG> a mechanism for identifying objects,
|
jtulach@1318
|
293 |
* <STRONG>not</STRONG> a container for the objects themselves.
|
jtulach@1318
|
294 |
*
|
jtulach@1318
|
295 |
* <h4>Compatibility</h4>
|
jtulach@1318
|
296 |
*
|
jtulach@1318
|
297 |
* <p>In order to maintain compatibility with existing usage, Locale's
|
jtulach@1318
|
298 |
* constructors retain their behavior prior to the Java Runtime
|
jtulach@1318
|
299 |
* Environment version 1.7. The same is largely true for the
|
jtulach@1318
|
300 |
* <code>toString</code> method. Thus Locale objects can continue to
|
jtulach@1318
|
301 |
* be used as they were. In particular, clients who parse the output
|
jtulach@1318
|
302 |
* of toString into language, country, and variant fields can continue
|
jtulach@1318
|
303 |
* to do so (although this is strongly discouraged), although the
|
jtulach@1318
|
304 |
* variant field will have additional information in it if script or
|
jtulach@1318
|
305 |
* extensions are present.
|
jtulach@1318
|
306 |
*
|
jtulach@1318
|
307 |
* <p>In addition, BCP 47 imposes syntax restrictions that are not
|
jtulach@1318
|
308 |
* imposed by Locale's constructors. This means that conversions
|
jtulach@1318
|
309 |
* between some Locales and BCP 47 language tags cannot be made without
|
jtulach@1318
|
310 |
* losing information. Thus <code>toLanguageTag</code> cannot
|
jtulach@1318
|
311 |
* represent the state of locales whose language, country, or variant
|
jtulach@1318
|
312 |
* do not conform to BCP 47.
|
jtulach@1318
|
313 |
*
|
jtulach@1318
|
314 |
* <p>Because of these issues, it is recommended that clients migrate
|
jtulach@1318
|
315 |
* away from constructing non-conforming locales and use the
|
jtulach@1318
|
316 |
* <code>forLanguageTag</code> and <code>Locale.Builder</code> APIs instead.
|
jtulach@1318
|
317 |
* Clients desiring a string representation of the complete locale can
|
jtulach@1318
|
318 |
* then always rely on <code>toLanguageTag</code> for this purpose.
|
jtulach@1318
|
319 |
*
|
jtulach@1318
|
320 |
* <h5><a name="special_cases_constructor"/>Special cases</h5>
|
jtulach@1318
|
321 |
*
|
jtulach@1318
|
322 |
* <p>For compatibility reasons, two
|
jtulach@1318
|
323 |
* non-conforming locales are treated as special cases. These are
|
jtulach@1318
|
324 |
* <b><tt>ja_JP_JP</tt></b> and <b><tt>th_TH_TH</tt></b>. These are ill-formed
|
jtulach@1318
|
325 |
* in BCP 47 since the variants are too short. To ease migration to BCP 47,
|
jtulach@1318
|
326 |
* these are treated specially during construction. These two cases (and only
|
jtulach@1318
|
327 |
* these) cause a constructor to generate an extension, all other values behave
|
jtulach@1318
|
328 |
* exactly as they did prior to Java 7.
|
jtulach@1318
|
329 |
*
|
jtulach@1318
|
330 |
* <p>Java has used <tt>ja_JP_JP</tt> to represent Japanese as used in
|
jtulach@1318
|
331 |
* Japan together with the Japanese Imperial calendar. This is now
|
jtulach@1318
|
332 |
* representable using a Unicode locale extension, by specifying the
|
jtulach@1318
|
333 |
* Unicode locale key <tt>ca</tt> (for "calendar") and type
|
jtulach@1318
|
334 |
* <tt>japanese</tt>. When the Locale constructor is called with the
|
jtulach@1318
|
335 |
* arguments "ja", "JP", "JP", the extension "u-ca-japanese" is
|
jtulach@1318
|
336 |
* automatically added.
|
jtulach@1318
|
337 |
*
|
jtulach@1318
|
338 |
* <p>Java has used <tt>th_TH_TH</tt> to represent Thai as used in
|
jtulach@1318
|
339 |
* Thailand together with Thai digits. This is also now representable using
|
jtulach@1318
|
340 |
* a Unicode locale extension, by specifying the Unicode locale key
|
jtulach@1318
|
341 |
* <tt>nu</tt> (for "number") and value <tt>thai</tt>. When the Locale
|
jtulach@1318
|
342 |
* constructor is called with the arguments "th", "TH", "TH", the
|
jtulach@1318
|
343 |
* extension "u-nu-thai" is automatically added.
|
jtulach@1318
|
344 |
*
|
jtulach@1318
|
345 |
* <h5>Serialization</h5>
|
jtulach@1318
|
346 |
*
|
jtulach@1318
|
347 |
* <p>During serialization, writeObject writes all fields to the output
|
jtulach@1318
|
348 |
* stream, including extensions.
|
jtulach@1318
|
349 |
*
|
jtulach@1318
|
350 |
* <p>During deserialization, readResolve adds extensions as described
|
jtulach@1318
|
351 |
* in <a href="#special_cases_constructor">Special Cases</a>, only
|
jtulach@1318
|
352 |
* for the two cases th_TH_TH and ja_JP_JP.
|
jtulach@1318
|
353 |
*
|
jtulach@1318
|
354 |
* <h5>Legacy language codes</h5>
|
jtulach@1318
|
355 |
*
|
jtulach@1318
|
356 |
* <p>Locale's constructor has always converted three language codes to
|
jtulach@1318
|
357 |
* their earlier, obsoleted forms: <tt>he</tt> maps to <tt>iw</tt>,
|
jtulach@1318
|
358 |
* <tt>yi</tt> maps to <tt>ji</tt>, and <tt>id</tt> maps to
|
jtulach@1318
|
359 |
* <tt>in</tt>. This continues to be the case, in order to not break
|
jtulach@1318
|
360 |
* backwards compatibility.
|
jtulach@1318
|
361 |
*
|
jtulach@1318
|
362 |
* <p>The APIs added in 1.7 map between the old and new language codes,
|
jtulach@1318
|
363 |
* maintaining the old codes internal to Locale (so that
|
jtulach@1318
|
364 |
* <code>getLanguage</code> and <code>toString</code> reflect the old
|
jtulach@1318
|
365 |
* code), but using the new codes in the BCP 47 language tag APIs (so
|
jtulach@1318
|
366 |
* that <code>toLanguageTag</code> reflects the new one). This
|
jtulach@1318
|
367 |
* preserves the equivalence between Locales no matter which code or
|
jtulach@1318
|
368 |
* API is used to construct them. Java's default resource bundle
|
jtulach@1318
|
369 |
* lookup mechanism also implements this mapping, so that resources
|
jtulach@1318
|
370 |
* can be named using either convention, see {@link ResourceBundle.Control}.
|
jtulach@1318
|
371 |
*
|
jtulach@1318
|
372 |
* <h5>Three-letter language/country(region) codes</h5>
|
jtulach@1318
|
373 |
*
|
jtulach@1318
|
374 |
* <p>The Locale constructors have always specified that the language
|
jtulach@1318
|
375 |
* and the country param be two characters in length, although in
|
jtulach@1318
|
376 |
* practice they have accepted any length. The specification has now
|
jtulach@1318
|
377 |
* been relaxed to allow language codes of two to eight characters and
|
jtulach@1318
|
378 |
* country (region) codes of two to three characters, and in
|
jtulach@1318
|
379 |
* particular, three-letter language codes and three-digit region
|
jtulach@1318
|
380 |
* codes as specified in the IANA Language Subtag Registry. For
|
jtulach@1318
|
381 |
* compatibility, the implementation still does not impose a length
|
jtulach@1318
|
382 |
* constraint.
|
jtulach@1318
|
383 |
*
|
jtulach@1318
|
384 |
* @see Builder
|
jtulach@1318
|
385 |
* @see ResourceBundle
|
jtulach@1318
|
386 |
* @see java.text.Format
|
jtulach@1318
|
387 |
* @see java.text.NumberFormat
|
jtulach@1318
|
388 |
* @see java.text.Collator
|
jtulach@1318
|
389 |
* @author Mark Davis
|
jtulach@1318
|
390 |
* @since 1.1
|
jtulach@1318
|
391 |
*/
|
jtulach@1318
|
392 |
public final class Locale implements Cloneable, Serializable {
|
jtulach@1318
|
393 |
|
jtulach@1318
|
394 |
/** Useful constant for language.
|
jtulach@1318
|
395 |
*/
|
jtulach@1318
|
396 |
static public final Locale ENGLISH = createConstant("en", "");
|
jtulach@1318
|
397 |
|
jtulach@1318
|
398 |
/** Useful constant for language.
|
jtulach@1318
|
399 |
*/
|
jtulach@1318
|
400 |
static public final Locale FRENCH = createConstant("fr", "");
|
jtulach@1318
|
401 |
|
jtulach@1318
|
402 |
/** Useful constant for language.
|
jtulach@1318
|
403 |
*/
|
jtulach@1318
|
404 |
static public final Locale GERMAN = createConstant("de", "");
|
jtulach@1318
|
405 |
|
jtulach@1318
|
406 |
/** Useful constant for language.
|
jtulach@1318
|
407 |
*/
|
jtulach@1318
|
408 |
static public final Locale ITALIAN = createConstant("it", "");
|
jtulach@1318
|
409 |
|
jtulach@1318
|
410 |
/** Useful constant for language.
|
jtulach@1318
|
411 |
*/
|
jtulach@1318
|
412 |
static public final Locale JAPANESE = createConstant("ja", "");
|
jtulach@1318
|
413 |
|
jtulach@1318
|
414 |
/** Useful constant for language.
|
jtulach@1318
|
415 |
*/
|
jtulach@1318
|
416 |
static public final Locale KOREAN = createConstant("ko", "");
|
jtulach@1318
|
417 |
|
jtulach@1318
|
418 |
/** Useful constant for language.
|
jtulach@1318
|
419 |
*/
|
jtulach@1318
|
420 |
static public final Locale CHINESE = createConstant("zh", "");
|
jtulach@1318
|
421 |
|
jtulach@1318
|
422 |
/** Useful constant for language.
|
jtulach@1318
|
423 |
*/
|
jtulach@1318
|
424 |
static public final Locale SIMPLIFIED_CHINESE = createConstant("zh", "CN");
|
jtulach@1318
|
425 |
|
jtulach@1318
|
426 |
/** Useful constant for language.
|
jtulach@1318
|
427 |
*/
|
jtulach@1318
|
428 |
static public final Locale TRADITIONAL_CHINESE = createConstant("zh", "TW");
|
jtulach@1318
|
429 |
|
jtulach@1318
|
430 |
/** Useful constant for country.
|
jtulach@1318
|
431 |
*/
|
jtulach@1318
|
432 |
static public final Locale FRANCE = createConstant("fr", "FR");
|
jtulach@1318
|
433 |
|
jtulach@1318
|
434 |
/** Useful constant for country.
|
jtulach@1318
|
435 |
*/
|
jtulach@1318
|
436 |
static public final Locale GERMANY = createConstant("de", "DE");
|
jtulach@1318
|
437 |
|
jtulach@1318
|
438 |
/** Useful constant for country.
|
jtulach@1318
|
439 |
*/
|
jtulach@1318
|
440 |
static public final Locale ITALY = createConstant("it", "IT");
|
jtulach@1318
|
441 |
|
jtulach@1318
|
442 |
/** Useful constant for country.
|
jtulach@1318
|
443 |
*/
|
jtulach@1318
|
444 |
static public final Locale JAPAN = createConstant("ja", "JP");
|
jtulach@1318
|
445 |
|
jtulach@1318
|
446 |
/** Useful constant for country.
|
jtulach@1318
|
447 |
*/
|
jtulach@1318
|
448 |
static public final Locale KOREA = createConstant("ko", "KR");
|
jtulach@1318
|
449 |
|
jtulach@1318
|
450 |
/** Useful constant for country.
|
jtulach@1318
|
451 |
*/
|
jtulach@1318
|
452 |
static public final Locale CHINA = SIMPLIFIED_CHINESE;
|
jtulach@1318
|
453 |
|
jtulach@1318
|
454 |
/** Useful constant for country.
|
jtulach@1318
|
455 |
*/
|
jtulach@1318
|
456 |
static public final Locale PRC = SIMPLIFIED_CHINESE;
|
jtulach@1318
|
457 |
|
jtulach@1318
|
458 |
/** Useful constant for country.
|
jtulach@1318
|
459 |
*/
|
jtulach@1318
|
460 |
static public final Locale TAIWAN = TRADITIONAL_CHINESE;
|
jtulach@1318
|
461 |
|
jtulach@1318
|
462 |
/** Useful constant for country.
|
jtulach@1318
|
463 |
*/
|
jtulach@1318
|
464 |
static public final Locale UK = createConstant("en", "GB");
|
jtulach@1318
|
465 |
|
jtulach@1318
|
466 |
/** Useful constant for country.
|
jtulach@1318
|
467 |
*/
|
jtulach@1318
|
468 |
static public final Locale US = createConstant("en", "US");
|
jtulach@1318
|
469 |
|
jtulach@1318
|
470 |
/** Useful constant for country.
|
jtulach@1318
|
471 |
*/
|
jtulach@1318
|
472 |
static public final Locale CANADA = createConstant("en", "CA");
|
jtulach@1318
|
473 |
|
jtulach@1318
|
474 |
/** Useful constant for country.
|
jtulach@1318
|
475 |
*/
|
jtulach@1318
|
476 |
static public final Locale CANADA_FRENCH = createConstant("fr", "CA");
|
jtulach@1318
|
477 |
|
jtulach@1318
|
478 |
/**
|
jtulach@1318
|
479 |
* Useful constant for the root locale. The root locale is the locale whose
|
jtulach@1318
|
480 |
* language, country, and variant are empty ("") strings. This is regarded
|
jtulach@1318
|
481 |
* as the base locale of all locales, and is used as the language/country
|
jtulach@1318
|
482 |
* neutral locale for the locale sensitive operations.
|
jtulach@1318
|
483 |
*
|
jtulach@1318
|
484 |
* @since 1.6
|
jtulach@1318
|
485 |
*/
|
jtulach@1318
|
486 |
static public final Locale ROOT = createConstant("", "");
|
jtulach@1318
|
487 |
|
jtulach@1318
|
488 |
/**
|
jtulach@1318
|
489 |
* The key for the private use extension ('x').
|
jtulach@1318
|
490 |
*
|
jtulach@1318
|
491 |
* @see #getExtension(char)
|
jtulach@1318
|
492 |
* @see Builder#setExtension(char, String)
|
jtulach@1318
|
493 |
* @since 1.7
|
jtulach@1318
|
494 |
*/
|
jtulach@1318
|
495 |
static public final char PRIVATE_USE_EXTENSION = 'x';
|
jtulach@1318
|
496 |
|
jtulach@1318
|
497 |
/**
|
jtulach@1318
|
498 |
* The key for Unicode locale extension ('u').
|
jtulach@1318
|
499 |
*
|
jtulach@1318
|
500 |
* @see #getExtension(char)
|
jtulach@1318
|
501 |
* @see Builder#setExtension(char, String)
|
jtulach@1318
|
502 |
* @since 1.7
|
jtulach@1318
|
503 |
*/
|
jtulach@1318
|
504 |
static public final char UNICODE_LOCALE_EXTENSION = 'u';
|
jtulach@1318
|
505 |
|
jtulach@1318
|
506 |
/** serialization ID
|
jtulach@1318
|
507 |
*/
|
jtulach@1318
|
508 |
static final long serialVersionUID = 9149081749638150636L;
|
jtulach@1318
|
509 |
|
jtulach@1318
|
510 |
/**
|
jtulach@1318
|
511 |
* Display types for retrieving localized names from the name providers.
|
jtulach@1318
|
512 |
*/
|
jtulach@1318
|
513 |
private static final int DISPLAY_LANGUAGE = 0;
|
jtulach@1318
|
514 |
private static final int DISPLAY_COUNTRY = 1;
|
jtulach@1318
|
515 |
private static final int DISPLAY_VARIANT = 2;
|
jtulach@1318
|
516 |
private static final int DISPLAY_SCRIPT = 3;
|
jaroslav@1320
|
517 |
private String language;
|
jaroslav@1320
|
518 |
private String country;
|
jaroslav@1320
|
519 |
private String variant;
|
jtulach@1318
|
520 |
|
jtulach@1318
|
521 |
|
jtulach@1318
|
522 |
/**
|
jtulach@1318
|
523 |
* Construct a locale from language, country and variant.
|
jtulach@1318
|
524 |
* This constructor normalizes the language value to lowercase and
|
jtulach@1318
|
525 |
* the country value to uppercase.
|
jtulach@1318
|
526 |
* <p>
|
jtulach@1318
|
527 |
* <b>Note:</b>
|
jtulach@1318
|
528 |
* <ul>
|
jtulach@1318
|
529 |
* <li>ISO 639 is not a stable standard; some of the language codes it defines
|
jtulach@1318
|
530 |
* (specifically "iw", "ji", and "in") have changed. This constructor accepts both the
|
jtulach@1318
|
531 |
* old codes ("iw", "ji", and "in") and the new codes ("he", "yi", and "id"), but all other
|
jtulach@1318
|
532 |
* API on Locale will return only the OLD codes.
|
jtulach@1318
|
533 |
* <li>For backward compatibility reasons, this constructor does not make
|
jtulach@1318
|
534 |
* any syntactic checks on the input.
|
jtulach@1318
|
535 |
* <li>The two cases ("ja", "JP", "JP") and ("th", "TH", "TH") are handled specially,
|
jtulach@1318
|
536 |
* see <a href="#special_cases_constructor">Special Cases</a> for more information.
|
jtulach@1318
|
537 |
* </ul>
|
jtulach@1318
|
538 |
*
|
jtulach@1318
|
539 |
* @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag
|
jtulach@1318
|
540 |
* up to 8 characters in length. See the <code>Locale</code> class description about
|
jtulach@1318
|
541 |
* valid language values.
|
jtulach@1318
|
542 |
* @param country An ISO 3166 alpha-2 country code or a UN M.49 numeric-3 area code.
|
jtulach@1318
|
543 |
* See the <code>Locale</code> class description about valid country values.
|
jtulach@1318
|
544 |
* @param variant Any arbitrary value used to indicate a variation of a <code>Locale</code>.
|
jtulach@1318
|
545 |
* See the <code>Locale</code> class description for the details.
|
jtulach@1318
|
546 |
* @exception NullPointerException thrown if any argument is null.
|
jtulach@1318
|
547 |
*/
|
jtulach@1318
|
548 |
public Locale(String language, String country, String variant) {
|
jtulach@1318
|
549 |
if (language== null || country == null || variant == null) {
|
jtulach@1318
|
550 |
throw new NullPointerException();
|
jtulach@1318
|
551 |
}
|
jaroslav@1320
|
552 |
this.language = language;
|
jaroslav@1320
|
553 |
this.country = country;
|
jaroslav@1320
|
554 |
this.variant = variant;
|
jtulach@1318
|
555 |
}
|
jtulach@1318
|
556 |
|
jtulach@1318
|
557 |
/**
|
jtulach@1318
|
558 |
* Construct a locale from language and country.
|
jtulach@1318
|
559 |
* This constructor normalizes the language value to lowercase and
|
jtulach@1318
|
560 |
* the country value to uppercase.
|
jtulach@1318
|
561 |
* <p>
|
jtulach@1318
|
562 |
* <b>Note:</b>
|
jtulach@1318
|
563 |
* <ul>
|
jtulach@1318
|
564 |
* <li>ISO 639 is not a stable standard; some of the language codes it defines
|
jtulach@1318
|
565 |
* (specifically "iw", "ji", and "in") have changed. This constructor accepts both the
|
jtulach@1318
|
566 |
* old codes ("iw", "ji", and "in") and the new codes ("he", "yi", and "id"), but all other
|
jtulach@1318
|
567 |
* API on Locale will return only the OLD codes.
|
jtulach@1318
|
568 |
* <li>For backward compatibility reasons, this constructor does not make
|
jtulach@1318
|
569 |
* any syntactic checks on the input.
|
jtulach@1318
|
570 |
* </ul>
|
jtulach@1318
|
571 |
*
|
jtulach@1318
|
572 |
* @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag
|
jtulach@1318
|
573 |
* up to 8 characters in length. See the <code>Locale</code> class description about
|
jtulach@1318
|
574 |
* valid language values.
|
jtulach@1318
|
575 |
* @param country An ISO 3166 alpha-2 country code or a UN M.49 numeric-3 area code.
|
jtulach@1318
|
576 |
* See the <code>Locale</code> class description about valid country values.
|
jtulach@1318
|
577 |
* @exception NullPointerException thrown if either argument is null.
|
jtulach@1318
|
578 |
*/
|
jtulach@1318
|
579 |
public Locale(String language, String country) {
|
jtulach@1318
|
580 |
this(language, country, "");
|
jtulach@1318
|
581 |
}
|
jtulach@1318
|
582 |
|
jtulach@1318
|
583 |
/**
|
jtulach@1318
|
584 |
* Construct a locale from a language code.
|
jtulach@1318
|
585 |
* This constructor normalizes the language value to lowercase.
|
jtulach@1318
|
586 |
* <p>
|
jtulach@1318
|
587 |
* <b>Note:</b>
|
jtulach@1318
|
588 |
* <ul>
|
jtulach@1318
|
589 |
* <li>ISO 639 is not a stable standard; some of the language codes it defines
|
jtulach@1318
|
590 |
* (specifically "iw", "ji", and "in") have changed. This constructor accepts both the
|
jtulach@1318
|
591 |
* old codes ("iw", "ji", and "in") and the new codes ("he", "yi", and "id"), but all other
|
jtulach@1318
|
592 |
* API on Locale will return only the OLD codes.
|
jtulach@1318
|
593 |
* <li>For backward compatibility reasons, this constructor does not make
|
jtulach@1318
|
594 |
* any syntactic checks on the input.
|
jtulach@1318
|
595 |
* </ul>
|
jtulach@1318
|
596 |
*
|
jtulach@1318
|
597 |
* @param language An ISO 639 alpha-2 or alpha-3 language code, or a language subtag
|
jtulach@1318
|
598 |
* up to 8 characters in length. See the <code>Locale</code> class description about
|
jtulach@1318
|
599 |
* valid language values.
|
jtulach@1318
|
600 |
* @exception NullPointerException thrown if argument is null.
|
jtulach@1318
|
601 |
* @since 1.4
|
jtulach@1318
|
602 |
*/
|
jtulach@1318
|
603 |
public Locale(String language) {
|
jtulach@1318
|
604 |
this(language, "", "");
|
jtulach@1318
|
605 |
}
|
jtulach@1318
|
606 |
|
jtulach@1318
|
607 |
/**
|
jtulach@1318
|
608 |
* This method must be called only for creating the Locale.*
|
jtulach@1318
|
609 |
* constants due to making shortcuts.
|
jtulach@1318
|
610 |
*/
|
jtulach@1318
|
611 |
private static Locale createConstant(String lang, String country) {
|
jaroslav@1320
|
612 |
return new Locale(lang, country);
|
jtulach@1318
|
613 |
}
|
jtulach@1318
|
614 |
|
jtulach@1318
|
615 |
/**
|
jtulach@1318
|
616 |
* Gets the current value of the default locale for this instance
|
jtulach@1318
|
617 |
* of the Java Virtual Machine.
|
jtulach@1318
|
618 |
* <p>
|
jtulach@1318
|
619 |
* The Java Virtual Machine sets the default locale during startup
|
jtulach@1318
|
620 |
* based on the host environment. It is used by many locale-sensitive
|
jtulach@1318
|
621 |
* methods if no locale is explicitly specified.
|
jtulach@1318
|
622 |
* It can be changed using the
|
jtulach@1318
|
623 |
* {@link #setDefault(java.util.Locale) setDefault} method.
|
jtulach@1318
|
624 |
*
|
jtulach@1318
|
625 |
* @return the default locale for this instance of the Java Virtual Machine
|
jtulach@1318
|
626 |
*/
|
jtulach@1318
|
627 |
public static Locale getDefault() {
|
jaroslav@1320
|
628 |
return Locale.US;
|
jtulach@1318
|
629 |
}
|
jtulach@1318
|
630 |
|
jtulach@1318
|
631 |
/**
|
jtulach@1318
|
632 |
* Sets the default locale for this instance of the Java Virtual Machine.
|
jtulach@1318
|
633 |
* This does not affect the host locale.
|
jtulach@1318
|
634 |
* <p>
|
jtulach@1318
|
635 |
* If there is a security manager, its <code>checkPermission</code>
|
jtulach@1318
|
636 |
* method is called with a <code>PropertyPermission("user.language", "write")</code>
|
jtulach@1318
|
637 |
* permission before the default locale is changed.
|
jtulach@1318
|
638 |
* <p>
|
jtulach@1318
|
639 |
* The Java Virtual Machine sets the default locale during startup
|
jtulach@1318
|
640 |
* based on the host environment. It is used by many locale-sensitive
|
jtulach@1318
|
641 |
* methods if no locale is explicitly specified.
|
jtulach@1318
|
642 |
* <p>
|
jtulach@1318
|
643 |
* Since changing the default locale may affect many different areas
|
jtulach@1318
|
644 |
* of functionality, this method should only be used if the caller
|
jtulach@1318
|
645 |
* is prepared to reinitialize locale-sensitive code running
|
jtulach@1318
|
646 |
* within the same Java Virtual Machine.
|
jtulach@1318
|
647 |
* <p>
|
jtulach@1318
|
648 |
* By setting the default locale with this method, all of the default
|
jtulach@1318
|
649 |
* locales for each Category are also set to the specified default locale.
|
jtulach@1318
|
650 |
*
|
jtulach@1318
|
651 |
* @throws SecurityException
|
jtulach@1318
|
652 |
* if a security manager exists and its
|
jtulach@1318
|
653 |
* <code>checkPermission</code> method doesn't allow the operation.
|
jtulach@1318
|
654 |
* @throws NullPointerException if <code>newLocale</code> is null
|
jtulach@1318
|
655 |
* @param newLocale the new default locale
|
jtulach@1318
|
656 |
* @see SecurityManager#checkPermission
|
jtulach@1318
|
657 |
* @see java.util.PropertyPermission
|
jtulach@1318
|
658 |
*/
|
jaroslav@1320
|
659 |
public static void setDefault(Locale newLocale) {
|
jaroslav@1320
|
660 |
throw new SecurityException();
|
jtulach@1318
|
661 |
}
|
jtulach@1318
|
662 |
|
jtulach@1318
|
663 |
/**
|
jtulach@1318
|
664 |
* Returns an array of all installed locales.
|
jtulach@1318
|
665 |
* The returned array represents the union of locales supported
|
jtulach@1318
|
666 |
* by the Java runtime environment and by installed
|
jtulach@1318
|
667 |
* {@link java.util.spi.LocaleServiceProvider LocaleServiceProvider}
|
jtulach@1318
|
668 |
* implementations. It must contain at least a <code>Locale</code>
|
jtulach@1318
|
669 |
* instance equal to {@link java.util.Locale#US Locale.US}.
|
jtulach@1318
|
670 |
*
|
jtulach@1318
|
671 |
* @return An array of installed locales.
|
jtulach@1318
|
672 |
*/
|
jtulach@1318
|
673 |
public static Locale[] getAvailableLocales() {
|
jaroslav@1320
|
674 |
return new Locale[] { Locale.US };
|
jtulach@1318
|
675 |
}
|
jtulach@1318
|
676 |
|
jtulach@1318
|
677 |
/**
|
jtulach@1318
|
678 |
* Returns the language code of this Locale.
|
jtulach@1318
|
679 |
*
|
jtulach@1318
|
680 |
* <p><b>Note:</b> ISO 639 is not a stable standard— some languages' codes have changed.
|
jtulach@1318
|
681 |
* Locale's constructor recognizes both the new and the old codes for the languages
|
jtulach@1318
|
682 |
* whose codes have changed, but this function always returns the old code. If you
|
jtulach@1318
|
683 |
* want to check for a specific language whose code has changed, don't do
|
jtulach@1318
|
684 |
* <pre>
|
jtulach@1318
|
685 |
* if (locale.getLanguage().equals("he")) // BAD!
|
jtulach@1318
|
686 |
* ...
|
jtulach@1318
|
687 |
* </pre>
|
jtulach@1318
|
688 |
* Instead, do
|
jtulach@1318
|
689 |
* <pre>
|
jtulach@1318
|
690 |
* if (locale.getLanguage().equals(new Locale("he").getLanguage()))
|
jtulach@1318
|
691 |
* ...
|
jtulach@1318
|
692 |
* </pre>
|
jtulach@1318
|
693 |
* @return The language code, or the empty string if none is defined.
|
jtulach@1318
|
694 |
* @see #getDisplayLanguage
|
jtulach@1318
|
695 |
*/
|
jtulach@1318
|
696 |
public String getLanguage() {
|
jaroslav@1320
|
697 |
return language;
|
jtulach@1318
|
698 |
}
|
jtulach@1318
|
699 |
|
jtulach@1318
|
700 |
/**
|
jtulach@1318
|
701 |
* Returns the script for this locale, which should
|
jtulach@1318
|
702 |
* either be the empty string or an ISO 15924 4-letter script
|
jtulach@1318
|
703 |
* code. The first letter is uppercase and the rest are
|
jtulach@1318
|
704 |
* lowercase, for example, 'Latn', 'Cyrl'.
|
jtulach@1318
|
705 |
*
|
jtulach@1318
|
706 |
* @return The script code, or the empty string if none is defined.
|
jtulach@1318
|
707 |
* @see #getDisplayScript
|
jtulach@1318
|
708 |
* @since 1.7
|
jtulach@1318
|
709 |
*/
|
jtulach@1318
|
710 |
public String getScript() {
|
jaroslav@1320
|
711 |
return "";
|
jtulach@1318
|
712 |
}
|
jtulach@1318
|
713 |
|
jtulach@1318
|
714 |
/**
|
jtulach@1318
|
715 |
* Returns the country/region code for this locale, which should
|
jtulach@1318
|
716 |
* either be the empty string, an uppercase ISO 3166 2-letter code,
|
jtulach@1318
|
717 |
* or a UN M.49 3-digit code.
|
jtulach@1318
|
718 |
*
|
jtulach@1318
|
719 |
* @return The country/region code, or the empty string if none is defined.
|
jtulach@1318
|
720 |
* @see #getDisplayCountry
|
jtulach@1318
|
721 |
*/
|
jtulach@1318
|
722 |
public String getCountry() {
|
jaroslav@1320
|
723 |
return country;
|
jtulach@1318
|
724 |
}
|
jtulach@1318
|
725 |
|
jtulach@1318
|
726 |
/**
|
jtulach@1318
|
727 |
* Returns the variant code for this locale.
|
jtulach@1318
|
728 |
*
|
jtulach@1318
|
729 |
* @return The variant code, or the empty string if none is defined.
|
jtulach@1318
|
730 |
* @see #getDisplayVariant
|
jtulach@1318
|
731 |
*/
|
jtulach@1318
|
732 |
public String getVariant() {
|
jaroslav@1320
|
733 |
return variant;
|
jaroslav@1320
|
734 |
}
|
jaroslav@1320
|
735 |
|
jaroslav@1320
|
736 |
String getRegion() {
|
jaroslav@1320
|
737 |
return getCountry();
|
jtulach@1318
|
738 |
}
|
jtulach@1318
|
739 |
|
jtulach@1318
|
740 |
/**
|
jtulach@1318
|
741 |
* Returns the extension (or private use) value associated with
|
jtulach@1318
|
742 |
* the specified key, or null if there is no extension
|
jtulach@1318
|
743 |
* associated with the key. To be well-formed, the key must be one
|
jtulach@1318
|
744 |
* of <code>[0-9A-Za-z]</code>. Keys are case-insensitive, so
|
jtulach@1318
|
745 |
* for example 'z' and 'Z' represent the same extension.
|
jtulach@1318
|
746 |
*
|
jtulach@1318
|
747 |
* @param key the extension key
|
jtulach@1318
|
748 |
* @return The extension, or null if this locale defines no
|
jtulach@1318
|
749 |
* extension for the specified key.
|
jtulach@1318
|
750 |
* @throws IllegalArgumentException if key is not well-formed
|
jtulach@1318
|
751 |
* @see #PRIVATE_USE_EXTENSION
|
jtulach@1318
|
752 |
* @see #UNICODE_LOCALE_EXTENSION
|
jtulach@1318
|
753 |
* @since 1.7
|
jtulach@1318
|
754 |
*/
|
jtulach@1318
|
755 |
public String getExtension(char key) {
|
jaroslav@1320
|
756 |
return null;
|
jtulach@1318
|
757 |
}
|
jtulach@1318
|
758 |
|
jtulach@1318
|
759 |
/**
|
jtulach@1318
|
760 |
* Returns the set of extension keys associated with this locale, or the
|
jtulach@1318
|
761 |
* empty set if it has no extensions. The returned set is unmodifiable.
|
jtulach@1318
|
762 |
* The keys will all be lower-case.
|
jtulach@1318
|
763 |
*
|
jtulach@1318
|
764 |
* @return The set of extension keys, or the empty set if this locale has
|
jtulach@1318
|
765 |
* no extensions.
|
jtulach@1318
|
766 |
* @since 1.7
|
jtulach@1318
|
767 |
*/
|
jtulach@1318
|
768 |
public Set<Character> getExtensionKeys() {
|
jaroslav@1320
|
769 |
return Collections.emptySet();
|
jtulach@1318
|
770 |
}
|
jtulach@1318
|
771 |
|
jtulach@1318
|
772 |
/**
|
jtulach@1318
|
773 |
* Returns the set of unicode locale attributes associated with
|
jtulach@1318
|
774 |
* this locale, or the empty set if it has no attributes. The
|
jtulach@1318
|
775 |
* returned set is unmodifiable.
|
jtulach@1318
|
776 |
*
|
jtulach@1318
|
777 |
* @return The set of attributes.
|
jtulach@1318
|
778 |
* @since 1.7
|
jtulach@1318
|
779 |
*/
|
jtulach@1318
|
780 |
public Set<String> getUnicodeLocaleAttributes() {
|
jaroslav@1320
|
781 |
return Collections.emptySet();
|
jtulach@1318
|
782 |
}
|
jtulach@1318
|
783 |
|
jtulach@1318
|
784 |
/**
|
jtulach@1318
|
785 |
* Returns the Unicode locale type associated with the specified Unicode locale key
|
jtulach@1318
|
786 |
* for this locale. Returns the empty string for keys that are defined with no type.
|
jtulach@1318
|
787 |
* Returns null if the key is not defined. Keys are case-insensitive. The key must
|
jtulach@1318
|
788 |
* be two alphanumeric characters ([0-9a-zA-Z]), or an IllegalArgumentException is
|
jtulach@1318
|
789 |
* thrown.
|
jtulach@1318
|
790 |
*
|
jtulach@1318
|
791 |
* @param key the Unicode locale key
|
jtulach@1318
|
792 |
* @return The Unicode locale type associated with the key, or null if the
|
jtulach@1318
|
793 |
* locale does not define the key.
|
jtulach@1318
|
794 |
* @throws IllegalArgumentException if the key is not well-formed
|
jtulach@1318
|
795 |
* @throws NullPointerException if <code>key</code> is null
|
jtulach@1318
|
796 |
* @since 1.7
|
jtulach@1318
|
797 |
*/
|
jtulach@1318
|
798 |
public String getUnicodeLocaleType(String key) {
|
jaroslav@1320
|
799 |
return null;
|
jtulach@1318
|
800 |
}
|
jtulach@1318
|
801 |
|
jtulach@1318
|
802 |
/**
|
jtulach@1318
|
803 |
* Returns the set of Unicode locale keys defined by this locale, or the empty set if
|
jtulach@1318
|
804 |
* this locale has none. The returned set is immutable. Keys are all lower case.
|
jtulach@1318
|
805 |
*
|
jtulach@1318
|
806 |
* @return The set of Unicode locale keys, or the empty set if this locale has
|
jtulach@1318
|
807 |
* no Unicode locale keywords.
|
jtulach@1318
|
808 |
* @since 1.7
|
jtulach@1318
|
809 |
*/
|
jtulach@1318
|
810 |
public Set<String> getUnicodeLocaleKeys() {
|
jaroslav@1320
|
811 |
return Collections.emptySet();
|
jtulach@1318
|
812 |
}
|
jtulach@1318
|
813 |
|
jtulach@1318
|
814 |
/**
|
jtulach@1318
|
815 |
* Returns a string representation of this <code>Locale</code>
|
jtulach@1318
|
816 |
* object, consisting of language, country, variant, script,
|
jtulach@1318
|
817 |
* and extensions as below:
|
jtulach@1318
|
818 |
* <p><blockquote>
|
jtulach@1318
|
819 |
* language + "_" + country + "_" + (variant + "_#" | "#") + script + "-" + extensions
|
jtulach@1318
|
820 |
* </blockquote>
|
jtulach@1318
|
821 |
*
|
jtulach@1318
|
822 |
* Language is always lower case, country is always upper case, script is always title
|
jtulach@1318
|
823 |
* case, and extensions are always lower case. Extensions and private use subtags
|
jtulach@1318
|
824 |
* will be in canonical order as explained in {@link #toLanguageTag}.
|
jtulach@1318
|
825 |
*
|
jtulach@1318
|
826 |
* <p>When the locale has neither script nor extensions, the result is the same as in
|
jtulach@1318
|
827 |
* Java 6 and prior.
|
jtulach@1318
|
828 |
*
|
jtulach@1318
|
829 |
* <p>If both the language and country fields are missing, this function will return
|
jtulach@1318
|
830 |
* the empty string, even if the variant, script, or extensions field is present (you
|
jtulach@1318
|
831 |
* can't have a locale with just a variant, the variant must accompany a well-formed
|
jtulach@1318
|
832 |
* language or country code).
|
jtulach@1318
|
833 |
*
|
jtulach@1318
|
834 |
* <p>If script or extensions are present and variant is missing, no underscore is
|
jtulach@1318
|
835 |
* added before the "#".
|
jtulach@1318
|
836 |
*
|
jtulach@1318
|
837 |
* <p>This behavior is designed to support debugging and to be compatible with
|
jtulach@1318
|
838 |
* previous uses of <code>toString</code> that expected language, country, and variant
|
jtulach@1318
|
839 |
* fields only. To represent a Locale as a String for interchange purposes, use
|
jtulach@1318
|
840 |
* {@link #toLanguageTag}.
|
jtulach@1318
|
841 |
*
|
jtulach@1318
|
842 |
* <p>Examples: <ul><tt>
|
jtulach@1318
|
843 |
* <li>en
|
jtulach@1318
|
844 |
* <li>de_DE
|
jtulach@1318
|
845 |
* <li>_GB
|
jtulach@1318
|
846 |
* <li>en_US_WIN
|
jtulach@1318
|
847 |
* <li>de__POSIX
|
jtulach@1318
|
848 |
* <li>zh_CN_#Hans
|
jtulach@1318
|
849 |
* <li>zh_TW_#Hant-x-java
|
jtulach@1318
|
850 |
* <li>th_TH_TH_#u-nu-thai</tt></ul>
|
jtulach@1318
|
851 |
*
|
jtulach@1318
|
852 |
* @return A string representation of the Locale, for debugging.
|
jtulach@1318
|
853 |
* @see #getDisplayName
|
jtulach@1318
|
854 |
* @see #toLanguageTag
|
jtulach@1318
|
855 |
*/
|
jtulach@1318
|
856 |
@Override
|
jtulach@1318
|
857 |
public final String toString() {
|
jaroslav@1320
|
858 |
Locale baseLocale = this;
|
jtulach@1318
|
859 |
boolean l = (baseLocale.getLanguage().length() != 0);
|
jtulach@1318
|
860 |
boolean s = (baseLocale.getScript().length() != 0);
|
jtulach@1318
|
861 |
boolean r = (baseLocale.getRegion().length() != 0);
|
jtulach@1318
|
862 |
boolean v = (baseLocale.getVariant().length() != 0);
|
jaroslav@1320
|
863 |
boolean e = false; //(localeExtensions != null && localeExtensions.getID().length() != 0);
|
jtulach@1318
|
864 |
|
jtulach@1318
|
865 |
StringBuilder result = new StringBuilder(baseLocale.getLanguage());
|
jtulach@1318
|
866 |
if (r || (l && (v || s || e))) {
|
jtulach@1318
|
867 |
result.append('_')
|
jtulach@1318
|
868 |
.append(baseLocale.getRegion()); // This may just append '_'
|
jtulach@1318
|
869 |
}
|
jtulach@1318
|
870 |
if (v && (l || r)) {
|
jtulach@1318
|
871 |
result.append('_')
|
jtulach@1318
|
872 |
.append(baseLocale.getVariant());
|
jtulach@1318
|
873 |
}
|
jtulach@1318
|
874 |
|
jtulach@1318
|
875 |
if (s && (l || r)) {
|
jtulach@1318
|
876 |
result.append("_#")
|
jtulach@1318
|
877 |
.append(baseLocale.getScript());
|
jtulach@1318
|
878 |
}
|
jtulach@1318
|
879 |
|
jtulach@1318
|
880 |
if (e && (l || r)) {
|
jtulach@1318
|
881 |
result.append('_');
|
jtulach@1318
|
882 |
if (!s) {
|
jtulach@1318
|
883 |
result.append('#');
|
jtulach@1318
|
884 |
}
|
jaroslav@1320
|
885 |
// result.append(localeExtensions.getID());
|
jtulach@1318
|
886 |
}
|
jtulach@1318
|
887 |
|
jtulach@1318
|
888 |
return result.toString();
|
jtulach@1318
|
889 |
}
|
jtulach@1318
|
890 |
|
jaroslav@1320
|
891 |
|
jtulach@1318
|
892 |
/**
|
jtulach@1318
|
893 |
* Overrides Cloneable.
|
jtulach@1318
|
894 |
*/
|
jtulach@1318
|
895 |
public Object clone()
|
jtulach@1318
|
896 |
{
|
jtulach@1318
|
897 |
try {
|
jtulach@1318
|
898 |
Locale that = (Locale)super.clone();
|
jtulach@1318
|
899 |
return that;
|
jtulach@1318
|
900 |
} catch (CloneNotSupportedException e) {
|
jtulach@1318
|
901 |
throw new InternalError();
|
jtulach@1318
|
902 |
}
|
jtulach@1318
|
903 |
}
|
jtulach@1318
|
904 |
|
jtulach@1318
|
905 |
/**
|
jtulach@1318
|
906 |
* Override hashCode.
|
jtulach@1318
|
907 |
* Since Locales are often used in hashtables, caches the value
|
jtulach@1318
|
908 |
* for speed.
|
jtulach@1318
|
909 |
*/
|
jtulach@1318
|
910 |
@Override
|
jtulach@1318
|
911 |
public int hashCode() {
|
jaroslav@1320
|
912 |
int hash = 3;
|
jaroslav@1320
|
913 |
hash = 43 * hash + Objects.hashCode(this.language);
|
jaroslav@1320
|
914 |
hash = 43 * hash + Objects.hashCode(this.country);
|
jaroslav@1320
|
915 |
hash = 43 * hash + Objects.hashCode(this.variant);
|
jaroslav@1320
|
916 |
return hash;
|
jtulach@1318
|
917 |
}
|
jtulach@1318
|
918 |
|
jtulach@1318
|
919 |
// Overrides
|
jtulach@1318
|
920 |
@Override
|
jtulach@1318
|
921 |
public boolean equals(Object obj) {
|
jaroslav@1320
|
922 |
if (obj == null) {
|
jtulach@1318
|
923 |
return false;
|
jtulach@1318
|
924 |
}
|
jaroslav@1320
|
925 |
if (getClass() != obj.getClass()) {
|
jaroslav@1320
|
926 |
return false;
|
jtulach@1318
|
927 |
}
|
jaroslav@1320
|
928 |
final Locale other = (Locale) obj;
|
jaroslav@1320
|
929 |
if (!Objects.equals(this.language, other.language)) {
|
jaroslav@1320
|
930 |
return false;
|
jaroslav@1320
|
931 |
}
|
jaroslav@1320
|
932 |
if (!Objects.equals(this.country, other.country)) {
|
jaroslav@1320
|
933 |
return false;
|
jaroslav@1320
|
934 |
}
|
jaroslav@1320
|
935 |
if (!Objects.equals(this.variant, other.variant)) {
|
jaroslav@1320
|
936 |
return false;
|
jaroslav@1320
|
937 |
}
|
jaroslav@1320
|
938 |
return true;
|
jtulach@1318
|
939 |
}
|
jtulach@1318
|
940 |
|
jtulach@1318
|
941 |
|
jtulach@1318
|
942 |
}
|