Locale.Builder - JRE Emulation | JRE Emulation
public static final class

Locale.Builder

extends Object
java.lang.Object
   ↳ java.util.Locale.Builder

Class Overview

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.

Summary

Public Constructors
Locale.Builder()
Public Methods
Locale.Builder addUnicodeLocaleAttribute(String attribute)
Adds the specified attribute to the list of attributes in the unicode locale extension.
Locale build()
Constructs a locale from the existing state of the builder.
Locale.Builder clear()
Clears all existing state from this builder.
Locale.Builder clearExtensions()
Clears all extensions from this builder.
Locale.Builder removeUnicodeLocaleAttribute(String attribute)
Removes an attribute from the list of attributes in the unicode locale extension.
Locale.Builder setExtension(char key, String value)
Sets the extension identified by key to value.
Locale.Builder setLanguage(String language)
Sets the locale language.
Locale.Builder setLanguageTag(String languageTag)
Set the state of this builder to the parsed contents of the BCP-47 language tag languageTag.
Locale.Builder setLocale(Locale locale)
Sets the state of the builder to the Locale represented by locale.
Locale.Builder setRegion(String region)
Sets the locale region.
Locale.Builder setScript(String script)
Sets the locale script.
Locale.Builder setUnicodeLocaleKeyword(String key, String type)
Adds a key / type pair to the list of unicode locale extension keys.
Locale.Builder setVariant(String variant)
Sets the locale variant.
Inherited Methods
[Expand]
From class java.lang.Object

Public Constructors

public Locale.Builder ()

Public Methods

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 getExtension(char) with the UNICODE_LOCALE_EXTENSION key.

Throws
IllformedLocaleException if attribute is invalid.
NullPointerException if attribute is null.

public Locale build ()

Constructs a locale from the existing state of the builder. Note that this method is guaranteed to succeed since field validity checks are performed at the point of setting them.

public Locale.Builder clear ()

Clears all existing state from this builder.

public Locale.Builder clearExtensions ()

Clears all extensions from this builder. Note that this also implicitly clears all state related to the unicode locale extension; all attributes and keywords set by addUnicodeLocaleAttribute(String) and setUnicodeLocaleKeyword(String, String) are cleared.

public Locale.Builder removeUnicodeLocaleAttribute (String attribute)

Removes an attribute from the list of attributes in the unicode locale extension. attribute must be valid as per the rules specified in addUnicodeLocaleAttribute(String). This method has no effect if attribute hasn't already been added.

Throws
IllformedLocaleException if attribute is invalid.
NullPointerException if attribute is null.

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', 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', 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.

    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.

    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 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.

    public Locale.Builder setLocale (Locale locale)

    Sets the state of the builder to the Locale represented by locale. Note that the locale's language, region and variant are validated as per the rules specified in setLanguage(String), setRegion(String) and setVariant(String). All existing builder state is discarded.

    Throws
    IllformedLocaleException if locale is invalid.
    NullPointerException if locale is null.

    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.

    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.

    public Locale.Builder setUnicodeLocaleKeyword (String key, String type)

    Adds a key / type pair to the list of unicode locale extension keys. key must be 2 characters in length, and each character must be in the range [a-zA-Z0-9]. {#code type} can either be empty, or a series of one or more subtags separated by a separator ("-" or "_"). Each subtag must be between 3 and 8 characters in length and each character in the subtag must be in the range [a-zA-Z0-9]. Note that the type is normalized to lower case, and all separators are normalized to "-". All added attributes and keywords are combined to form a complete unicode locale extension on Locale objects built by this builder, and accessible via getExtension(char) with the UNICODE_LOCALE_EXTENSION key.

    Throws
    IllformedLocaleException if key or value are invalid.

    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.