Module java.base
Package java.util

# Class Locale.Builder

java.lang.Object
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 setters. Unlike the `Locale` constructors, the `Builder` checks if a value configured by a setter satisfies the syntax 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 syntactic restrictions on variant, while BCP 47 requires each variant subtag to be 5 to 8 alphanumerics or a single numeric followed by 3 alphanumerics. The method `setVariant` throws `IllformedLocaleException` for a variant that does not satisfy this restriction. If it is necessary to support such a variant, use a Locale constructor. However, 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.forLanguageTag(java.lang.String)`

## Constructor Summary

Constructors
Constructor
Description
`Builder()`
Constructs an empty Builder.

## Method Summary

Modifier and Type
Method
Description
`Locale.Builder`
`addUnicodeLocaleAttribute​(String attribute)`
Adds a unicode locale attribute, if not already present, otherwise has no effect.
`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.
`Locale.Builder`
`removeUnicodeLocaleAttribute​(String attribute)`
Removes a unicode locale attribute, if present, otherwise has no effect.
`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 declared in class java.lang.Object

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

## Constructor Details

### Builder

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

## Method Details

### setLocale

public Locale.Builder setLocale​(Locale locale)
Resets the `Builder` to match the provided `locale`. Existing state is discarded.

All fields of the locale must be well-formed, see `Locale`.

Locales with any ill-formed fields cause `IllformedLocaleException` to be thrown, except for the following three cases which are accepted for compatibility reasons:

- Locale("ja", "JP", "JP") is treated as "ja-JP-u-ca-japanese"
- Locale("th", "TH", "TH") is treated as "th-TH-u-nu-thai"
- Locale("no", "NO", "NY") is treated as "nn-NO"

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. Discards the existing state. Null and the empty string cause the builder to be reset, like `clear()`. Grandfathered tags (see `Locale.forLanguageTag(java.lang.String)`) are converted to their canonical form before being processed. Otherwise, the language tag must be well-formed (see `Locale`) or an exception is thrown (unlike `Locale.forLanguageTag`, which just discards ill-formed and following portions of the tag).

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

### setLanguage

public Locale.Builder setLanguage​(String language)
Sets the language. If `language` is the empty string or null, the language in this `Builder` is removed. Otherwise, the language must be well-formed or an exception is thrown.

The typical language value is a two or three-letter language code as defined in ISO639.

Parameters:
  `language` - the language
Returns:
  This builder.
Throws:
  `IllformedLocaleException` - if `language` is ill-formed

### setScript

public Locale.Builder setScript​(String script)
Sets the script. If `script` is null or the empty string, the script in this `Builder` is removed. Otherwise, the script must be well-formed or an exception is thrown.

The typical script value is a four-letter script code as defined by ISO 15924.

Parameters:
  `script` - the script
Returns:
  This builder.
Throws:
  `IllformedLocaleException` - if `script` is ill-formed

### setRegion

public Locale.Builder setRegion​(String region)
Sets the region. If region is null or the empty string, the region in this `Builder` is removed. Otherwise, the region must be well-formed or an exception is thrown.

The typical region value is a two-letter ISO 3166 code or a three-digit UN M.49 area code.

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

### setVariant

public Locale.Builder setVariant​(String variant)
Sets the variant. If variant is null or the empty string, the variant in this `Builder` is removed. Otherwise, it must consist of one or more well-formed subtags, or an exception is thrown.

Note: 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 does not impose any syntactic restriction on variant, and the variant value in `Locale` is case sensitive. To set such a variant, use a Locale constructor.

Parameters:
  `variant` - the variant
Returns:
  This builder.
Throws:
  `IllformedLocaleException` - if `variant` is ill-formed

### setExtension

public Locale.Builder setExtension​(char key, String value)
Sets the extension for the given key. If the value is null or the empty string, the extension is removed. Otherwise, the extension must be well-formed or an exception is thrown.

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.

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 subtags 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)`

### setUnicodeLocaleKeyword

public Locale.Builder setUnicodeLocaleKeyword​(String key, String type)
Sets the Unicode locale keyword type for the given key. If the type is null, the Unicode keyword is removed. Otherwise, the key must be non-null and both key and type must be well-formed or an exception is thrown.

Keys and types are converted to lower case.

Note:Setting the 'u' extension via `setExtension(char, java.lang.String)` 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` is null
See Also:
  `setExtension(char, String)`

### addUnicodeLocaleAttribute

public Locale.Builder addUnicodeLocaleAttribute​(String attribute)
Adds a unicode locale attribute, if not already present, otherwise has no effect. The attribute must not be null and must be well-formed or an exception is thrown.

Parameters:
  `attribute` - the attribute
Returns:
  This builder.
Throws:
  `NullPointerException` - if `attribute` is null
  `IllformedLocaleException` - if `attribute` is ill-formed
See Also:
  `setExtension(char, String)`

### removeUnicodeLocaleAttribute

public Locale.Builder removeUnicodeLocaleAttribute​(String attribute)
Removes a unicode locale attribute, if present, otherwise has no effect. The attribute must not be null and must be well-formed or an exception is thrown.

Attribute comparison for removal is case-insensitive.

Parameters:
  `attribute` - the attribute
Returns:
  This builder.
Throws:
  `NullPointerException` - if `attribute` is null
  `IllformedLocaleException` - if `attribute` is ill-formed
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.

This applies the conversions listed in `Locale.forLanguageTag(java.lang.String)` when constructing a Locale. (Grandfathered tags are handled in `setLanguageTag(java.lang.String)`.)

Returns:
  A Locale.