Package java.util

Class Locale.Builder

  • Enclosing class:
    Locale
    public static final class Locale.Builder
extends Object
    A class that helps construct Locale instances. Unlike the public Locale constructors, the methods of this class perform much stricter checks on their input. Validity checks on the language, country, variant and extension values are carried out as per the BCP-47 specification. In addition, we treat the Unicode locale extension specially and provide methods to manipulate the structured state (keywords and attributes) specified therein.
    Since:
    1.7

    • Constructor Detail

      • Builder

        public Builder()

    • Method Detail

      • setLanguage

        public Locale.Builder setLanguage​(String language)
        Sets the locale language. If language is null or empty, the previous value is cleared. As per BCP-47, the language must be between 2 and 3 ASCII characters in length and must only contain characters in the range [a-zA-Z]. This value is usually an ISO-639-2 alpha-2 or alpha-3 code, though no explicit checks are carried out that it's a valid code in that namespace. Values are normalized to lower case. Note that we don't support BCP-47 "extlang" languages because they were only ever used to substitute for a lack of 3 letter language codes.
        Throws:
        IllformedLocaleException - if the language was invalid.

      • setLanguageTag

        public Locale.Builder setLanguageTag​(String languageTag)
        Set the state of this builder to the parsed contents of the BCP-47 language tag languageTag. This method is equivalent to a call to clear() if languageTag is null or empty. NOTE: In contrast to Locale.forLanguageTag(String), which simply ignores malformed input, this method will throw an exception if its input is malformed.
        Throws:
        IllformedLocaleException - if languageTag is not a well formed BCP-47 tag.

      • setRegion

        public Locale.Builder setRegion​(String region)
        Sets the locale region. If region is null or empty, the previous value is cleared. As per BCP-47, the region must either be a 2 character ISO-3166-1 code (each character in the range [a-zA-Z]) OR a 3 digit UN M.49 code. Values are normalized to upper case.
        Throws:
        IllformedLocaleException - if region is invalid.

      • setVariant

        public Locale.Builder setVariant​(String variant)
        Sets the locale variant. If variant is null or empty, the previous value is cleared. The input string my consist of one or more variants separated by valid separators ('-' or '_'). As per BCP-47, each variant must be between 5 and 8 alphanumeric characters in length (each character in the range [a-zA-Z0-9]) but can be exactly 4 characters in length if the first character is a digit. Note that this is a much stricter interpretation of variant than the public Locale constructors. The latter allowed free form variants. Variants are case sensitive and all separators are normalized to '_'.
        Throws:
        IllformedLocaleException - if variant is invalid.

      • setScript

        public Locale.Builder setScript​(String script)
        Sets the locale script. If script is null or empty, the previous value is cleared. As per BCP-47, the script must be 4 characters in length, and each character in the range [a-zA-Z]. A script usually represents a valid ISO 15924 script code, though no other registry or validity checks are performed. Scripts are normalized to title cased values.
        Throws:
        IllformedLocaleException - if script is invalid.

      • addUnicodeLocaleAttribute

        public Locale.Builder addUnicodeLocaleAttribute​(String attribute)
        Adds the specified attribute to the list of attributes in the unicode locale extension. Attributes must be between 3 and 8 characters in length, and each character must be in the range [a-zA-Z0-9]. Attributes are normalized to lower case values. All added attributes and keywords are combined to form a complete unicode locale extension on Locale objects built by this builder, and accessible via Locale.getExtension(char) with the Locale.UNICODE_LOCALE_EXTENSION key.
        Throws:
        IllformedLocaleException - if attribute is invalid.
        NullPointerException - if attribute is null.

      • setExtension

        public Locale.Builder setExtension​(char key,
                                   String value)
        Sets the extension identified by key to value. key must be in the range [a-zA-Z0-9]. If value is null or empty, the extension is removed. In the general case, value must be a series of subtags separated by ("-" or "_"). Each subtag must be between 2 and 8 characters in length, and each character in the subtag must be in the range [a-zA-Z0-9].

        There are two special cases :

        • The unicode locale extension (key == 'u', Locale.UNICODE_LOCALE_EXTENSION) : Setting the unicode locale extension results in all existing keyword and attribute state being replaced by the parsed result of value. For example, builder.setExtension('u', "baaaz-baaar-fo-baar-ba-baaz") is equivalent to: 
                       builder.addUnicodeLocaleAttribute("baaaz");
             builder.addUnicodeLocaleAttribute("baaar");
             builder.setUnicodeLocaleKeyword("fo", "baar");
             builder.setUnicodeLocaleKeyword("ba", "baaa");
          The private use extension (key == 'x', Locale.PRIVATE_USE_EXTENSION) : Each subtag in a private use extension can be between 1 and 8 characters in length (in contrast to a minimum length of 2 for all other extensions).
Throws:
IllformedLocaleException - if value is invalid.