Class Locales

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.util.Locales

public final class Locales extends Static
Static methods working on Locale instances. While this class is documented as providing static methods, a few methods are actually non-static. Those methods need to be invoked on the ALL or SIS instance in order to specify the scope. Examples:
Since:
0.3
Version:
0.8
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Locales
    All locales available on the JavaVM.
    private static final short
    Bit mask for differentiating language codes from country codes in the ISO2 and ISO3 arrays.
    private static final short[]
    Mapping from 3-letters codes to 2-letters codes.
    private static final short[]
    Mapping from 3-letters codes to 2-letters codes.
    private static final short
    Bit mask for differentiating language codes from country codes in the ISO2 and ISO3 arrays.
    private static final Map<Locale,Locale>
    A read-only map for canonicalizing the locales.
    static final Locales
    Only locales available in the Apache SIS library.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Do not allow instantiation of this class, except for the constants defined in this class.
  • Method Summary

    Modifier and Type
    Method
    Description
    Returns the languages known to the JavaVM (ALL) or to the Apache SIS library (SIS).
    Returns the locales known to the JavaVM (ALL) or to the Apache SIS library (SIS).
    private static Locale[]
    getLanguages(Locale... locales)
    Returns the languages of the given locales, without duplicated values.
    static Locale
    parse(String code)
    Parses the given language code, optionally followed by country code and variant.
    static Locale
    parse(String code, int fromIndex)
    Parses the given language code and optional complements (country, variant), starting at the given index.
    private static String
    toISO2(String code, short type)
    Converts a 3-letters ISO code to a 2-letters one.
    private static short
    toNumber(String code, short n)
    Converts the given 1-, 2- or 3- letters alpha code to a 15 bits numbers.
    static Locale
    unique(Locale locale)
    Returns a unique instance of the given locale, if one is available.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • POOL

      private static final Map<Locale,Locale> POOL
      A read-only map for canonicalizing the locales. Filled on class initialization in order to avoid the need for synchronization.
    • LANGUAGE

      private static final short LANGUAGE
      Bit mask for differentiating language codes from country codes in the ISO2 and ISO3 arrays.
      See Also:
    • COUNTRY

      private static final short COUNTRY
      Bit mask for differentiating language codes from country codes in the ISO2 and ISO3 arrays.
      See Also:
    • ISO3

      private static final short[] ISO3
      Mapping from 3-letters codes to 2-letters codes. We use short type instead of String for compactness (conversions is done by toNumber(String, short)) and for avoiding references to String instances.
      Implementation note: Oracle JDK8 implementation computes the 3-letters codes on-the-fly instead of holding references to pre-existing strings. If we were holding string references here, we would prevent the garbage collector to collect the strings for all languages and countries. This would probably be a waste of resources.
    • ISO2

      private static final short[] ISO2
      Mapping from 3-letters codes to 2-letters codes. We use short type instead of String for compactness (conversions is done by toNumber(String, short)) and for avoiding references to String instances.
      Implementation note: Oracle JDK8 implementation computes the 3-letters codes on-the-fly instead of holding references to pre-existing strings. If we were holding string references here, we would prevent the garbage collector to collect the strings for all languages and countries. This would probably be a waste of resources.
    • ALL

      public static final Locales ALL
      All locales available on the JavaVM.
    • SIS

      public static final Locales SIS
      Only locales available in the Apache SIS library.
  • Constructor Details

    • Locales

      private Locales()
      Do not allow instantiation of this class, except for the constants defined in this class.
  • Method Details

    • getAvailableLanguages

      public Locale[] getAvailableLanguages()
      Returns the languages known to the JavaVM (ALL) or to the Apache SIS library (SIS). In the latter case, this method returns only the languages for which localized resources are provided in the org.apache.sis.util.resources package.
      Returns:
      the list of supported languages.
    • getAvailableLocales

      public Locale[] getAvailableLocales()
      Returns the locales known to the JavaVM (ALL) or to the Apache SIS library (SIS). In the latter case, this method returns only the locales for which localized resources are provided in the org.apache.sis.util.resources package.
      Returns:
      the list of supported locales.
    • getLanguages

      private static Locale[] getLanguages(Locale... locales)
      Returns the languages of the given locales, without duplicated values. The instances returned by this method have no country and no variant information.
      Parameters:
      locales - the locales from which to get the languages.
      Returns:
      the languages, without country or variant information.
    • parse

      public static Locale parse(String code) throws IllformedLocaleException
      Parses the given language code, optionally followed by country code and variant. The given string can be either the 2 letters or the 3 letters ISO 639 code. It can optionally be followed by the '_' character and the country code (again either as 2 or 3 letters), optionally followed by '_' and the variant.

      This method can be used when the caller wants the same Locale constants no matter if the language and country codes use 2 or 3 letters. This method tries to convert 3-letters codes to 2-letters code on a best effort basis.

      Parameters:
      code - the language code, optionally followed by country code and variant.
      Returns:
      the language for the given code (never null).
      Throws:
      IllformedLocaleException - if the given code is not valid.
      See Also:
    • parse

      public static Locale parse(String code, int fromIndex) throws IllformedLocaleException
      Parses the given language code and optional complements (country, variant), starting at the given index. All characters before fromIndex are ignored. Characters from fromIndex to the end of the string are parsed as documented in the parse(String) method. In particular, this method tries to convert 3-letters codes to 2-letters code on a best effort basis.
      Example: This method is useful when language codes are appended to a base property or resource name. For example, a dictionary may define the "remarks" property by values associated to the "remarks_en" and "remarks_fr" keys, for English and French locales respectively.
      Parameters:
      code - the language code, which may be followed by country code.
      fromIndex - index of the first character to parse.
      Returns:
      the language for the given code (never null).
      Throws:
      IllformedLocaleException - if the given code is not valid.
      See Also:
    • toISO2

      private static String toISO2(String code, short type)
      Converts a 3-letters ISO code to a 2-letters one. If the given code is not recognized, then this method returns code unmodified.
      Parameters:
      code - the 3-letters code.
      type - either LANGUAGE or COUNTRY.
      Returns:
      the 2-letters code, or null if none.
    • toNumber

      private static short toNumber(String code, short n)
      Converts the given 1-, 2- or 3- letters alpha code to a 15 bits numbers. Each letter uses 5 bits. If an invalid character is found, then this method returns 0.

      This method does not use the sign bit. Callers can use it for differentiating language codes from country codes, using the LANGUAGE or COUNTRY bit masks.

      Parameters:
      code - the 1-, 2- or 3- letters alpha code to convert.
      n - initial bit pattern, either LANGUAGE or COUNTRY.
      Returns:
      a number for the given code, or 0 if a non alpha characters were found.
    • unique

      public static Locale unique(Locale locale)
      Returns a unique instance of the given locale, if one is available. Otherwise returns the locale unchanged.
      Parameters:
      locale - the locale to canonicalize.
      Returns:
      a unique instance of the given locale, or locale if the given locale is not cached.