com.ibm.icu.util
Class ULocale.Builder

java.lang.Object
  extended by com.ibm.icu.util.ULocale.Builder
Enclosing class:
ULocale

public static final class ULocale.Builder
extends Object

Builder is used to build instances of Locale from values configured by the setter.

Builder supports the 'langtag' production of RFC 4646. Language tags consist of the ASCII digits, upper and lower case letters, and hyphen (which appears only as a field separator). As a convenience, underscores are accepted and normalized to hyphen. Values with any other character are ill-formed. Since language tags are case-insensitive, they are normalized to lower case, case distinctions are not preserved by the builder.

Note that since this implements 'langtag' and not 'Language-Tag', grandfathered language tags are not supported by the builder. Clients should use ULocale.forLanguageTag(java.lang.String) instead.

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

See Also:
create(), clear()

Constructor Summary
ULocale.Builder()
          Constructs an empty Builder.
 
Method Summary
 ULocale.Builder clear()
          Resets the builder to its initial, default state.
 ULocale.Builder clearExtensions()
          Resets the extensions to their initial, default state.
 ULocale create()
          Returns an instance of locale created from the fields set on this builder.
 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 langtag)
          Resets the builder to match the provided language tag.
 ULocale.Builder setLDMLExtensionValue(String key, String value)
          Sets the LDML keyword value ('type') for the given key.
 ULocale.Builder setLocale(ULocale loc)
          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 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 values of all fields, extensions, and private use information are empty, the language is undefined.

Method Detail

setLocale

public ULocale.Builder setLocale(ULocale loc)
Resets the builder to match the provided locale. The previous state of the builder is discarded. Fields that do not conform to BCP47 syntax are ill-formed.

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

setLanguageTag

public ULocale.Builder setLanguageTag(String langtag)
Resets the builder to match the provided language tag. The previous state of the builder is discarded.

Parameters:
langtag - the language tag
Returns:
this builder
Throws:
IllformedLocaleException - if langtag is ill-formed.
See Also:
ULocale.forLanguageTag(String)

setLanguage

public ULocale.Builder setLanguage(String language)
Sets the language. If language is the empty string, the language is defaulted. Language should be a two or three-letter language code as defined in ISO639. Well-formed values are any string of two to eight ASCII letters.

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

setScript

public ULocale.Builder setScript(String script)
Sets the script. If script is the empty string, the script is defaulted. Scripts should be a four-letter script code as defined in ISO 15924. Well-formed values are any string of four ASCII letters.

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

setRegion

public ULocale.Builder setRegion(String region)
Sets the region. If region is the empty string, the region is defaulted. Regions should be a two-letter ISO 3166 code or a three-digit M. 49 code. Well-formed values are any two-letter or three-digit string.

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

setVariant

public ULocale.Builder setVariant(String variant)
Sets the variant. If variant is or the empty string, the variant is defaulted. Variants should be registered variants (see IANA Language Subtag Registry) for the prefix. Well-formed variants are any series of fields of either four characters starting with a digit, or five to eight alphanumeric characters, separated by hyphen or underscore.

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

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 the [0-9A-WY-Za-wy-z]. Well-formed values are any series of fields of two to eight alphanumeric characters, separated by hyphen or underscore.

note:The extension 'u' is used for LDML Keywords. Setting the 'u' extension replaces any existing LDML keywords with those defined in the extension. To be well-formed, a value for the 'u' extension must meet the additional constraint that the number of fields be even (fields represent key value pairs, where the value is mandatory), and that the keys and values be legal locale extension keys and values.

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:
setLDMLExtensionValue(java.lang.String, java.lang.String)

setLDMLExtensionValue

public ULocale.Builder setLDMLExtensionValue(String key,
                                             String value)
Sets the LDML keyword value ('type') for the given key. If the value is the empty string, the LDML keyword is removed. Well-formed keys are strings of two alphanumeric characters. Well-formed values are strings of three to eight alphanumeric characters.

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

Parameters:
key - the LDML extension key
value - the LDML extension value
Returns:
this builder
Throws:
IllformedLocaleException - if key or value is ill-formed
See Also:
setExtension(char, String)

clear

public ULocale.Builder clear()
Resets the builder to its initial, default state.

Returns:
this builder

clearExtensions

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

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

create

public ULocale create()
Returns an instance of locale created from the fields set on this builder.

Returns:
a new locale


Copyright (c) 2009 IBM Corporation and others.