View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3;
18  
19  import java.util.ArrayList;
20  import java.util.Arrays;
21  import java.util.Collections;
22  import java.util.Comparator;
23  import java.util.LinkedHashSet;
24  import java.util.List;
25  import java.util.Locale;
26  import java.util.Set;
27  import java.util.concurrent.ConcurrentHashMap;
28  import java.util.concurrent.ConcurrentMap;
29  import java.util.function.Predicate;
30  import java.util.stream.Collectors;
31  
32  /**
33   * Operations to assist when working with a {@link Locale}.
34   *
35   * <p>This class tries to handle {@code null} input gracefully.
36   * An exception will not be thrown for a {@code null} input.
37   * Each method documents its behavior in more detail.</p>
38   *
39   * @since 2.2
40   */
41  public class LocaleUtils {
42  
43      /**
44       * Avoids synchronization, inits on demand.
45       */
46      private static final class SyncAvoid {
47  
48          /** Private unmodifiable and sorted list of available locales. */
49          private static final List<Locale> AVAILABLE_LOCALE_ULIST;
50  
51          /** Private unmodifiable set of available locales. */
52          private static final Set<Locale> AVAILABLE_LOCALE_USET;
53  
54          static {
55              AVAILABLE_LOCALE_ULIST = Collections
56                      .unmodifiableList(Arrays.asList(ArraySorter.sort(Locale.getAvailableLocales(), Comparator.comparing(Locale::toString))));
57              AVAILABLE_LOCALE_USET = Collections.unmodifiableSet(new LinkedHashSet<>(AVAILABLE_LOCALE_ULIST));
58          }
59      }
60  
61      /**
62       * The underscore character {@code '}{@value}{@code '}.
63       */
64      private static final char UNDERSCORE = '_';
65  
66      /**
67       * The undetermined language {@value}.
68       * <p>
69       * If a language is empty, or not <em>well-formed</am> (for example "a" or "e2"), {@link Locale#toLanguageTag()} will return {@code "und"} (Undetermined).
70       * </p>
71       *
72       * @see Locale#toLanguageTag()
73       */
74      private static final String UNDETERMINED = "und";
75  
76      /**
77       * The dash character {@code '}{@value}{@code '}.
78       */
79      private static final char DASH = '-';
80  
81      /**
82       * Concurrent map of language locales by country.
83       */
84      private static final ConcurrentMap<String, List<Locale>> cLanguagesByCountry = new ConcurrentHashMap<>();
85  
86      /**
87       * Concurrent map of country locales by language.
88       */
89      private static final ConcurrentMap<String, List<Locale>> cCountriesByLanguage = new ConcurrentHashMap<>();
90  
91      /**
92       * Obtains an unmodifiable and sorted list of installed locales.
93       *
94       * <p>This method is a wrapper around {@link Locale#getAvailableLocales()}.
95       * It is more efficient, as the JDK method must create a new array each
96       * time it is called.</p>
97       *
98       * @return the unmodifiable and sorted list of available locales
99       */
100     public static List<Locale> availableLocaleList() {
101         return SyncAvoid.AVAILABLE_LOCALE_ULIST;
102     }
103 
104     private static List<Locale> availableLocaleList(final Predicate<Locale> predicate) {
105         return availableLocaleList().stream().filter(predicate).collect(Collectors.toList());
106     }
107 
108     /**
109      * Obtains an unmodifiable set of installed locales.
110      *
111      * <p>This method is a wrapper around {@link Locale#getAvailableLocales()}.
112      * It is more efficient, as the JDK method must create a new array each
113      * time it is called.</p>
114      *
115      * @return the unmodifiable set of available locales
116      */
117     public static Set<Locale> availableLocaleSet() {
118         return SyncAvoid.AVAILABLE_LOCALE_USET;
119     }
120 
121     /**
122      * Obtains the list of countries supported for a given language.
123      *
124      * <p>This method takes a language code and searches to find the
125      * countries available for that language. Variant locales are removed.</p>
126      *
127      * @param languageCode  the 2 letter language code, null returns empty
128      * @return an unmodifiable List of Locale objects, not null
129      */
130     public static List<Locale> countriesByLanguage(final String languageCode) {
131         if (languageCode == null) {
132             return Collections.emptyList();
133         }
134         return cCountriesByLanguage.computeIfAbsent(languageCode, lc -> Collections.unmodifiableList(
135             availableLocaleList(locale -> languageCode.equals(locale.getLanguage()) && !locale.getCountry().isEmpty() && locale.getVariant().isEmpty())));
136     }
137 
138     /**
139      * Checks if the locale specified is in the set of available locales.
140      *
141      * @param locale the Locale object to check if it is available
142      * @return true if the locale is a known locale
143      */
144     public static boolean isAvailableLocale(final Locale locale) {
145         return availableLocaleSet().contains(locale);
146     }
147 
148     /**
149      * Tests whether the given String is a ISO 3166 alpha-2 country code.
150      *
151      * @param str the String to check
152      * @return true, is the given String is a ISO 3166 compliant country code.
153      */
154     private static boolean isISO3166CountryCode(final String str) {
155         return StringUtils.isAllUpperCase(str) && str.length() == 2;
156     }
157 
158     /**
159      * Tests whether the given String is a ISO 639 compliant language code.
160      *
161      * @param str the String to check.
162      * @return true, if the given String is a ISO 639 compliant language code.
163      */
164     private static boolean isISO639LanguageCode(final String str) {
165         return StringUtils.isAllLowerCase(str) && (str.length() == 2 || str.length() == 3);
166     }
167 
168     /**
169      * Tests whether a Locale's language is undetermined.
170      * <p>
171      * A Locale's language tag is undetermined if it's value is {@code "und"}. If a language is empty, or not well-formed (for example, "a" or "e2"), it will be
172      * equal to {@code "und"}.
173      * </p>
174      *
175      * @param locale the locale to test.
176      * @return whether a Locale's language is undetermined.
177      * @see Locale#toLanguageTag()
178      * @since 3.14.0
179      */
180     public static boolean isLanguageUndetermined(final Locale locale) {
181         return locale == null || UNDETERMINED.equals(locale.toLanguageTag());
182     }
183 
184     /**
185      * TestsNo whether the given String is a UN M.49 numeric area code.
186      *
187      * @param str the String to check
188      * @return true, is the given String is a UN M.49 numeric area code.
189      */
190     private static boolean isNumericAreaCode(final String str) {
191         return StringUtils.isNumeric(str) && str.length() == 3;
192     }
193 
194     /**
195      * Obtains the list of languages supported for a given country.
196      *
197      * <p>This method takes a country code and searches to find the
198      * languages available for that country. Variant locales are removed.</p>
199      *
200      * @param countryCode  the 2-letter country code, null returns empty
201      * @return an unmodifiable List of Locale objects, not null
202      */
203     public static List<Locale> languagesByCountry(final String countryCode) {
204         if (countryCode == null) {
205             return Collections.emptyList();
206         }
207         return cLanguagesByCountry.computeIfAbsent(countryCode,
208             k -> Collections.unmodifiableList(availableLocaleList(locale -> countryCode.equals(locale.getCountry()) && locale.getVariant().isEmpty())));
209     }
210 
211     /**
212      * Obtains the list of locales to search through when performing
213      * a locale search.
214      *
215      * <pre>
216      * localeLookupList(Locale("fr", "CA", "xxx"))
217      *   = [Locale("fr", "CA", "xxx"), Locale("fr", "CA"), Locale("fr")]
218      * </pre>
219      *
220      * @param locale  the locale to start from
221      * @return the unmodifiable list of Locale objects, 0 being locale, not null
222      */
223     public static List<Locale> localeLookupList(final Locale locale) {
224         return localeLookupList(locale, locale);
225     }
226 
227     /**
228      * Obtains the list of locales to search through when performing
229      * a locale search.
230      *
231      * <pre>
232      * localeLookupList(Locale("fr", "CA", "xxx"), Locale("en"))
233      *   = [Locale("fr", "CA", "xxx"), Locale("fr", "CA"), Locale("fr"), Locale("en"]
234      * </pre>
235      *
236      * <p>The result list begins with the most specific locale, then the
237      * next more general and so on, finishing with the default locale.
238      * The list will never contain the same locale twice.</p>
239      *
240      * @param locale  the locale to start from, null returns empty list
241      * @param defaultLocale  the default locale to use if no other is found
242      * @return the unmodifiable list of Locale objects, 0 being locale, not null
243      */
244     public static List<Locale> localeLookupList(final Locale locale, final Locale defaultLocale) {
245         final List<Locale> list = new ArrayList<>(4);
246         if (locale != null) {
247             list.add(locale);
248             if (!locale.getVariant().isEmpty()) {
249                 list.add(new Locale(locale.getLanguage(), locale.getCountry()));
250             }
251             if (!locale.getCountry().isEmpty()) {
252                 list.add(new Locale(locale.getLanguage(), StringUtils.EMPTY));
253             }
254             if (!list.contains(defaultLocale)) {
255                 list.add(defaultLocale);
256             }
257         }
258         return Collections.unmodifiableList(list);
259     }
260 
261     /**
262      * Tries to parse a Locale from the given String.
263      * <p>
264      * See {@link Locale} for the format.
265      * </p>
266      *
267      * @param str the String to parse as a Locale.
268      * @return a Locale parsed from the given String.
269      * @throws IllegalArgumentException if the given String cannot be parsed.
270      * @see Locale
271      */
272     private static Locale parseLocale(final String str) {
273         if (isISO639LanguageCode(str)) {
274             return new Locale(str);
275         }
276         final int limit = 3;
277         final char separator = str.indexOf(UNDERSCORE) != -1 ? UNDERSCORE : DASH;
278         final String[] segments = str.split(String.valueOf(separator), 3);
279         final String language = segments[0];
280         if (segments.length == 2) {
281             final String country = segments[1];
282             if (isISO639LanguageCode(language) && isISO3166CountryCode(country) || isNumericAreaCode(country)) {
283                 return new Locale(language, country);
284             }
285         } else if (segments.length == limit) {
286             final String country = segments[1];
287             final String variant = segments[2];
288             if (isISO639LanguageCode(language) &&
289                     (country.isEmpty() || isISO3166CountryCode(country) || isNumericAreaCode(country)) &&
290                     !variant.isEmpty()) {
291                 return new Locale(language, country, variant);
292             }
293         }
294         throw new IllegalArgumentException("Invalid locale format: " + str);
295     }
296 
297     /**
298      * Returns the given locale if non-{@code null}, otherwise {@link Locale#getDefault()}.
299      *
300      * @param locale a locale or {@code null}.
301      * @return the given locale if non-{@code null}, otherwise {@link Locale#getDefault()}.
302      * @since 3.12.0
303      */
304     public static Locale toLocale(final Locale locale) {
305         return locale != null ? locale : Locale.getDefault();
306     }
307 
308     /**
309      * Converts a String to a Locale.
310      *
311      * <p>This method takes the string format of a locale and creates the
312      * locale object from it.</p>
313      *
314      * <pre>
315      *   LocaleUtils.toLocale("")           = new Locale("", "")
316      *   LocaleUtils.toLocale("en")         = new Locale("en", "")
317      *   LocaleUtils.toLocale("en_GB")      = new Locale("en", "GB")
318      *   LocaleUtils.toLocale("en-GB")      = new Locale("en", "GB")
319      *   LocaleUtils.toLocale("en_001")     = new Locale("en", "001")
320      *   LocaleUtils.toLocale("en_GB_xxx")  = new Locale("en", "GB", "xxx")   (#)
321      * </pre>
322      *
323      * <p>(#) The behavior of the JDK variant constructor changed between JDK1.3 and JDK1.4.
324      * In JDK1.3, the constructor upper cases the variant, in JDK1.4, it doesn't.
325      * Thus, the result from getVariant() may vary depending on your JDK.</p>
326      *
327      * <p>This method validates the input strictly.
328      * The language code must be lowercase.
329      * The country code must be uppercase.
330      * The separator must be an underscore or a dash.
331      * The length must be correct.
332      * </p>
333      *
334      * @param str  the locale String to convert, null returns null
335      * @return a Locale, null if null input
336      * @throws IllegalArgumentException if the string is an invalid format
337      * @see Locale#forLanguageTag(String)
338      */
339     public static Locale toLocale(final String str) {
340         if (str == null) {
341             // TODO Should this return the default locale?
342             return null;
343         }
344         if (str.isEmpty()) { // LANG-941 - JDK 8 introduced an empty locale where all fields are blank
345             return new Locale(StringUtils.EMPTY, StringUtils.EMPTY);
346         }
347         if (str.contains("#")) { // LANG-879 - Cannot handle Java 7 script & extensions
348             throw new IllegalArgumentException("Invalid locale format: " + str);
349         }
350         final int len = str.length();
351         if (len < 2) {
352             throw new IllegalArgumentException("Invalid locale format: " + str);
353         }
354         final char ch0 = str.charAt(0);
355         if (ch0 == UNDERSCORE || ch0 == DASH) {
356             if (len < 3) {
357                 throw new IllegalArgumentException("Invalid locale format: " + str);
358             }
359             final char ch1 = str.charAt(1);
360             final char ch2 = str.charAt(2);
361             if (!Character.isUpperCase(ch1) || !Character.isUpperCase(ch2)) {
362                 throw new IllegalArgumentException("Invalid locale format: " + str);
363             }
364             if (len == 3) {
365                 return new Locale(StringUtils.EMPTY, str.substring(1, 3));
366             }
367             if (len < 5) {
368                 throw new IllegalArgumentException("Invalid locale format: " + str);
369             }
370             if (str.charAt(3) != ch0) {
371                 throw new IllegalArgumentException("Invalid locale format: " + str);
372             }
373             return new Locale(StringUtils.EMPTY, str.substring(1, 3), str.substring(4));
374         }
375 
376         return parseLocale(str);
377     }
378 
379     /**
380      * {@link LocaleUtils} instances should NOT be constructed in standard programming.
381      * Instead, the class should be used as {@code LocaleUtils.toLocale("en_GB");}.
382      *
383      * <p>This constructor is public to permit tools that require a JavaBean instance
384      * to operate.</p>
385      *
386      * @deprecated TODO Make private in 4.0.
387      */
388     @Deprecated
389     public LocaleUtils() {
390         // empty
391     }
392 
393 }