com.ibm.icu.util
Class ULocale.Builder

java.lang.Object
  com.ibm.icu.util.ULocale.Builder

Enclosing class:

ULocale

public static final class ULocale.Builder
extends Object

Builder is used to build instances of ULocale from values configured by the setter. Unlike the ULocale constructors, the Builder checks if a value configured by a setter satisfies the syntactical requirements defined by the ULocale class. A ULocale 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 ULocale 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 ULocale object with the Builder.

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

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

See Also:

ULocale.toLanguageTag()

Status:

Draft ICU 4.2.

Constructor Summary

ULocale.Builder()
Constructs an empty Builder.

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

ULocale	build() Returns an instance of Locale created from the fields set on this builder.
ULocale.Builder	clear() Resets the builder to its initial, empty state.
ULocale.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
ULocale.Builder	setExtension(char key, String value) Sets the extension for the given key.
ULocale.Builder	setLanguage(String language) Sets the language.
ULocale.Builder	setLanguageTag(String languageTag) Resets the builder to match the provided IETF BCP 47 language tag.
ULocale.Builder	setLocale(ULocale locale) Resets the Builder to match the provided locale.
ULocale.Builder	setRegion(String region) Sets the region.
ULocale.Builder	setScript(String script) Sets the script.
ULocale.Builder	setUnicodeLocaleKeyword(String key, String type) Sets the Unicode locale keyword type for the given key.
ULocale.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

ULocale.Builder

public ULocale.Builder()

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

Status:

Draft ICU 4.2.

ULocale.Builder

public ULocale.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)

Status:

Draft ICU 4.4.

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.

Status:

Draft ICU 4.4.

setLocale

public ULocale.Builder setLocale(ULocale locale)

Resets the Builder to match the provided locale. The previous state of the builder is discarded. Fields that do not conform to the ULocale 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.

Status:

Draft ICU 4.2.

setLanguageTag

public ULocale.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:

ULocale.forLanguageTag(String)

Status:

Draft ICU 4.2.

setLanguage

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

Status:

Draft ICU 4.2.

setScript

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

Status:

Draft ICU 4.2.

setRegion

public ULocale.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 ULocale created by the Builder is always normalized to upper case.

Parameters:

region - the region

Returns:

this builder

Throws:

IllformedLocaleException - if region is ill-formed

Status:

Draft ICU 4.2.

setVariant

public ULocale.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. However, the ULocale class itself does not impose any syntactical restriction on variant. When a Builder is created by the constructor Builder(boolean isLenientVariant) with true, this method skips the syntax check.

Parameters:

variant - the variant

Returns:

this builder

Throws:

IllformedLocaleException - if variant is ill-formed

Status:

Draft ICU 4.2.

setExtension

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

See Also:

setUnicodeLocaleKeyword(String, String)

Status:

Draft ICU 4.2.

setUnicodeLocaleKeyword

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

See Also:

setExtension(char, String)

Status:

Draft ICU 4.4.

clear

public ULocale.Builder clear()

Resets the builder to its initial, empty state.

Returns:

this builder

Status:

Draft ICU 4.2.

clearExtensions

public ULocale.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)

Status:

Draft ICU 4.2.

build

public ULocale build()

Returns an instance of Locale created from the fields set on this builder.

Returns:

a new Locale

Status:

Draft ICU 4.4.