java.util
Class Locale.Builder

java.lang.Object
  extended by java.util.Locale.Builder
Enclosing class:
Locale

public static final class Locale.Builder
extends Object

Builder is used to build instances of Locale from values configured by the setter. Unlike the Locale constructors, the Builder checks if a value configured by a setter satisfies the syntactical requirements defined by the Locale class. A Locale object created by a Builder is well-formed and can be transformed to a well-formed IETF BCP 47 language tag without losing information.

Note: The Locale class does not provide any syntactical restrictions on variant, while BCP 47 requires each variant subtag to be 5 to 8 alphanumeric letters or a single numeric letter followed by 3 alphanumeric letters. By default, the setVariant method throws IllformedLocaleException for a variant that does not satisfy the syntax above. If it is necessary to support such a variant, you could use the constructor Builder(boolean isLenientVariant) passing true to skip the syntax validation for variant. However, you should keep in mind that a Locale object created this way might lose the variant information when transformed to a BCP 47 language tag.

The following example shows how to create a Locale object with the Builder.

     Locale aLocale = new Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();
 

Builders can be reused; clear() resets all fields to their default values.

Since:
1.7
See Also:
Locale.toLanguageTag()

Constructor Summary
Constructor and Description
Locale.Builder()
          Constructs an empty Builder.
Locale.Builder(boolean isLenientVariant)
          Constructs an empty Builder with an option whether to allow setVariant to accept a value that does not conform to the IETF BCP 47 variant subtag's syntax requirements.
 
Method Summary
Modifier and Type Method and Description
 Locale build()
          Returns an instance of Locale created from the fields set on this builder.
 Locale.Builder clear()
          Resets the builder to its initial, empty state.
 Locale.Builder clearExtensions()
          Resets the extensions to their initial, empty state.
 boolean isLenientVariant()
          Returns true if this Builder accepts a value that does not conform to the IETF BCP 47 variant subtag's syntax requirements in setVariant
 Locale.Builder setExtension(char key, String value)
          Sets the extension for the given key.
 Locale.Builder setLanguage(String language)
          Sets the language.
 Locale.Builder setLanguageTag(String languageTag)
          Resets the builder to match the provided IETF BCP 47 language tag.
 Locale.Builder setLocale(Locale locale)
          Resets the Builder to match the provided locale.
 Locale.Builder setRegion(String region)
          Sets the region.
 Locale.Builder setScript(String script)
          Sets the script.
 Locale.Builder setUnicodeLocaleKeyword(String key, String type)
          Sets the Unicode locale keyword type for the given key.
 Locale.Builder setVariant(String variant)
          Sets the variant.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Locale.Builder

public Locale.Builder()
Constructs an empty Builder. The default value of all fields, extensions, and private use information is the empty string.


Locale.Builder

public Locale.Builder(boolean isLenientVariant)
Constructs an empty Builder with an option whether to allow setVariant to accept a value that does not conform to the IETF BCP 47 variant subtag's syntax requirements.

Parameters:
isLenientVariant - When true, this Builder will accept an ill-formed variant.
See Also:
setVariant(String)
Method Detail

isLenientVariant

public boolean isLenientVariant()
Returns true if this Builder accepts a value that does not conform to the IETF BCP 47 variant subtag's syntax requirements in setVariant

Returns:
true if this Build accepts an ill-formed variant.

setLocale

public Locale.Builder setLocale(Locale locale)
Resets the Builder to match the provided locale. The previous state of the builder is discarded. Fields that do not conform to the Locale class specification, for example, a single letter language, are ill-formed.

Parameters:
locale - the locale
Returns:
this builder
Throws:
IllformedLocaleException - if locale has any ill-formed fields.
NullPointerException - if locale is null.

setLanguageTag

public Locale.Builder setLanguageTag(String languageTag)
Resets the builder to match the provided IETF BCP 47 language tag. The previous state of the builder is discarded.

Parameters:
languageTag - the language tag
Returns:
this builder
Throws:
IllformedLocaleException - if languageTag is ill-formed.
NullPointerException - if languageTag is null.
See Also:
Locale.forLanguageTag(String)

setLanguage

public Locale.Builder setLanguage(String language)
Sets the language. If language is the empty string, the language in this Builder will be removed. Typical language value is a two or three-letter language code as defined in ISO639. Well-formed values are any string of two to eight alpha letters. This method accepts upper case alpha letters [A-Z], but the language value in the Locale created by the Builder is always normalized to lower case letters.

Parameters:
language - the language
Returns:
this builder
Throws:
IllformedLocaleException - if language is ill-formed
NullPointerException - if language is null.

setScript

public Locale.Builder setScript(String script)
Sets the script. If script is the empty string, the script in this Builder is removed. Typical script value is a four-letter script code as defined by ISO 15924. Well-formed values are any string of four alpha letters. This method accepts both upper and lower case alpha letters [a-zA-Z], but the script value in the Locale created by the Builder is always normalized to title case (the first letter is upper case and the rest of letters are lower case).

Parameters:
script - the script
Returns:
this builder
Throws:
IllformedLocaleException - if script is ill-formed
NullPointerException - if script is null.

setRegion

public Locale.Builder setRegion(String region)
Sets the region. If region is the empty string, the region in this Builder is removed. Typical region value is a two-letter ISO 3166 code or a three-digit UN M.49 area code. Well-formed values are any two-letter or three-digit string. This method accepts lower case letters [a-z], but the country value in the Locale created by the Builder is always normalized to upper case.

Parameters:
region - the region
Returns:
this builder
Throws:
IllformedLocaleException - if region is ill-formed
NullPointerException - if region is null.

setVariant

public Locale.Builder setVariant(String variant)
Sets the variant. If variant is the empty string, the variant in this Builder is removed.

Note: By default, this method checks if variant satisfies the IETF BCP 47 variant subtag's syntax requirements, and normalizes the value to lowercase letters. However, the Locale class itself does not impose any syntactical restriction on variant. Also, the variant value in Locale is case sensitive. When a Builder is created by the constructor Builder(boolean isLenientVariant) with true, this method skips the syntax check, and leaves the value unchanged.

Parameters:
variant - the variant
Returns:
this builder
Throws:
IllformedLocaleException - if variant is ill-formed
NullPointerException - if variant is null.

setExtension

public Locale.Builder setExtension(char key,
                                   String value)
Sets the extension for the given key. If the value is the empty string, the extension is removed. Legal keys are characters in the ranges [0-9A-Za-z]. Keys are case-insensitive, so for example 'z' and 'Z' represent the same extension. In general, well-formed values are any series of fields of two to eight alphanumeric characters, separated by hyphen or underscore.

Note: The key UNICODE_LOCALE_EXTENSION ('u') is used for the Unicode locale extension. Setting a value for this key replaces any existing Unicode locale key/type pairs with those defined in the extension. To be well-formed, a value for this extension must meet the additional constraints that each locale key is two alphanumeric characters, followed by at least one locale type subtag represented by three to eight alphanumeric characters, and that the keys and types be legal Unicode locale keys and values.

Note: The key PRIVATE_USE_EXTENSION ('x') is used for the private use code. To be well-formed, the value for this key needs only to have fields of one to eight alphanumeric characters, not two to eight as in the general case.

Parameters:
key - the extension key
value - the extension value
Returns:
this builder
Throws:
IllformedLocaleException - if key is illegal or value is ill-formed
NullPointerException - if value is null.
See Also:
setUnicodeLocaleKeyword(String, String)

setUnicodeLocaleKeyword

public Locale.Builder setUnicodeLocaleKeyword(String key,
                                              String type)
Sets the Unicode locale keyword type for the given key. If the value is the empty string, the Unicode keyword is removed. Well-formed keys are strings of two alphanumeric characters. Well-formed types are one or more subtags where each of them is three to eight alphanumeric characters.

Note:Setting the 'u' extension replaces all Unicode locale keywords with those defined in the extension.

Parameters:
key - the Unicode locale key
type - the Unicode locale type
Returns:
this builder
Throws:
IllformedLocaleException - if key or type is ill-formed
NullPointerException - if key or value is null.
See Also:
setExtension(char, String)

clear

public Locale.Builder clear()
Resets the builder to its initial, empty state.

Returns:
this builder

clearExtensions

public Locale.Builder clearExtensions()
Resets the extensions to their initial, empty state. Language, script, region and variant are unchanged.

Returns:
this builder
See Also:
setExtension(char, String)

build

public Locale build()
Returns an instance of Locale created from the fields set on this builder.

Returns:
a new Locale