java.util

Class Locale.Builder

java.lang.Object

java.util.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 Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.

setLocale

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(java.lang.String), setRegion(java.lang.String) and setVariant(java.lang.String). All existing builder state is discarded.

Throws:

IllformedLocaleException - if locale is invalid.

NullPointerException - if locale is null.

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.

removeUnicodeLocaleAttribute

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(java.lang.String). This method has no effect if attribute hasn't already been added.

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.

clearExtensions

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(java.lang.String) and setUnicodeLocaleKeyword(java.lang.String, java.lang.String) are cleared.

setUnicodeLocaleKeyword

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

Throws:

IllformedLocaleException - if key or value are invalid.

clear

public Locale.Builder clear()

Clears all existing state from this builder.

build

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.