org.apache.commons.lang

Class LocaleUtils

public class LocaleUtils extends Object

Operations to assist when working with a Locale.

This class tries to handle null input gracefully. An exception will not be thrown for a null input. Each method documents its behaviour in more detail.

Since: 2.2

Version: $Id: LocaleUtils.java 534277 2007-05-01 23:50:01Z bayard $

Author: Stephen Colebourne

Constructor Summary
LocaleUtils()

LocaleUtils instances should NOT be constructed in standard programming.

Method Summary
static ListavailableLocaleList()

Obtains an unmodifiable list of installed locales.

This method is a wrapper around Locale#getAvailableLocales().

static SetavailableLocaleSet()

Obtains an unmodifiable set of installed locales.

This method is a wrapper around Locale#getAvailableLocales().

static ListcountriesByLanguage(String languageCode)

Obtains the list of countries supported for a given language.

This method takes a language code and searches to find the countries available for that language.

static booleanisAvailableLocale(Locale locale)

Checks if the locale specified is in the list of available locales.

static ListlanguagesByCountry(String countryCode)

Obtains the list of languages supported for a given country.

This method takes a country code and searches to find the languages available for that country.

static ListlocaleLookupList(Locale locale)

Obtains the list of locales to search through when performing a locale search.

 localeLookupList(Locale("fr","CA","xxx"))
   = [Locale("fr","CA","xxx"), Locale("fr","CA"), Locale("fr")]
 
static ListlocaleLookupList(Locale locale, Locale defaultLocale)

Obtains the list of locales to search through when performing a locale search.

 localeLookupList(Locale("fr", "CA", "xxx"), Locale("en"))
   = [Locale("fr","CA","xxx"), Locale("fr","CA"), Locale("fr"), Locale("en"]
 

The result list begins with the most specific locale, then the next more general and so on, finishing with the default locale.

static LocaletoLocale(String str)

Converts a String to a Locale.

This method takes the string format of a locale and creates the locale object from it.

   LocaleUtils.toLocale("en")         = new Locale("en", "")
   LocaleUtils.toLocale("en_GB")      = new Locale("en", "GB")
   LocaleUtils.toLocale("en_GB_xxx")  = new Locale("en", "GB", "xxx")   (#)
 

(#) The behaviour of the JDK variant constructor changed between JDK1.3 and JDK1.4.

Constructor Detail

LocaleUtils

public LocaleUtils()

LocaleUtils instances should NOT be constructed in standard programming. Instead, the class should be used as LocaleUtils.toLocale("en_GB");.

This constructor is public to permit tools that require a JavaBean instance to operate.

Method Detail

availableLocaleList

public static List availableLocaleList()

Obtains an unmodifiable list of installed locales.

This method is a wrapper around Locale#getAvailableLocales(). It is more efficient, as the JDK method must create a new array each time it is called.

Returns: the unmodifiable list of available locales

availableLocaleSet

public static Set availableLocaleSet()

Obtains an unmodifiable set of installed locales.

This method is a wrapper around Locale#getAvailableLocales(). It is more efficient, as the JDK method must create a new array each time it is called.

Returns: the unmodifiable set of available locales

countriesByLanguage

public static List countriesByLanguage(String languageCode)

Obtains the list of countries supported for a given language.

This method takes a language code and searches to find the countries available for that language. Variant locales are removed.

Parameters: languageCode the 2 letter language code, null returns empty

Returns: an unmodifiable List of Locale objects, never null

isAvailableLocale

public static boolean isAvailableLocale(Locale locale)

Checks if the locale specified is in the list of available locales.

Parameters: locale the Locale object to check if it is available

Returns: true if the locale is a known locale

languagesByCountry

public static List languagesByCountry(String countryCode)

Obtains the list of languages supported for a given country.

This method takes a country code and searches to find the languages available for that country. Variant locales are removed.

Parameters: countryCode the 2 letter country code, null returns empty

Returns: an unmodifiable List of Locale objects, never null

localeLookupList

public static List localeLookupList(Locale locale)

Obtains the list of locales to search through when performing a locale search.

 localeLookupList(Locale("fr","CA","xxx"))
   = [Locale("fr","CA","xxx"), Locale("fr","CA"), Locale("fr")]
 

Parameters: locale the locale to start from

Returns: the unmodifiable list of Locale objects, 0 being locale, never null

localeLookupList

public static List localeLookupList(Locale locale, Locale defaultLocale)

Obtains the list of locales to search through when performing a locale search.

 localeLookupList(Locale("fr", "CA", "xxx"), Locale("en"))
   = [Locale("fr","CA","xxx"), Locale("fr","CA"), Locale("fr"), Locale("en"]
 

The result list begins with the most specific locale, then the next more general and so on, finishing with the default locale. The list will never contain the same locale twice.

Parameters: locale the locale to start from, null returns empty list defaultLocale the default locale to use if no other is found

Returns: the unmodifiable list of Locale objects, 0 being locale, never null

toLocale

public static Locale toLocale(String str)

Converts a String to a Locale.

This method takes the string format of a locale and creates the locale object from it.

   LocaleUtils.toLocale("en")         = new Locale("en", "")
   LocaleUtils.toLocale("en_GB")      = new Locale("en", "GB")
   LocaleUtils.toLocale("en_GB_xxx")  = new Locale("en", "GB", "xxx")   (#)
 

(#) The behaviour of the JDK variant constructor changed between JDK1.3 and JDK1.4. In JDK1.3, the constructor upper cases the variant, in JDK1.4, it doesn't. Thus, the result from getVariant() may vary depending on your JDK.

This method validates the input strictly. The language code must be lowercase. The country code must be uppercase. The separator must be an underscore. The length must be correct.

Parameters: str the locale String to convert, null returns null

Returns: a Locale, null if null input

Throws: IllegalArgumentException if the string is an invalid format

Copyright © 2001-2010 - Apache Software Foundation