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 or Locale.of()
factory methods, the Builder
checks if a value configured by a setter satisfies the syntax requirements defined by the Locale
class. A Locale
object obtained from a Builder
is well-formed and can be transformed to a well-formed IETF BCP 47 language tag without losing information.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 Locale.of(String, String, String)
. However, keep in mind that a Locale
object obtained this way might lose the variant information when transformed to a BCP 47 language tag. The following example shows how to obtain a Locale
object using a Builder
.
Locale aLocale = new Locale.Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();
Builders can be reused; clear()
resets all fields to their default values.
Constructor | Description |
---|---|
Builder() |
Constructs an empty Builder. |
Modifier and Type | Method | Description |
---|---|---|
Locale.Builder |
addUnicodeLocaleAttribute |
Adds a unicode locale attribute, if not already present, otherwise has no effect. |
Locale |
build() |
Returns an instance of Locale obtained 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 |
Removes a unicode locale attribute, if present, otherwise has no effect. |
Locale.Builder |
setExtension |
Sets the extension for the given key. |
Locale.Builder |
setLanguage |
Sets the language. |
Locale.Builder |
setLanguageTag |
Resets the Builder to match the provided IETF BCP 47 language tag. |
Locale.Builder |
setLocale |
Resets the Builder to match the provided locale . |
Locale.Builder |
setRegion |
Sets the region. |
Locale.Builder |
setScript |
Sets the script. |
Locale.Builder |
setUnicodeLocaleKeyword |
Sets the Unicode locale keyword type for the given key. |
Locale.Builder |
setVariant |
Sets the variant. |
public Builder()
public Locale.Builder setLocale(Locale locale)
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
- the localeIllformedLocaleException
- if locale
has any ill-formed fields.NullPointerException
- if locale
is null.public Locale.Builder setLanguageTag(String languageTag)
clear()
. Legacy 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).languageTag
- the language tagIllformedLocaleException
- if languageTag
is ill-formedpublic Locale.Builder setLanguage(String language)
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.
language
- the languageIllformedLocaleException
- if language
is ill-formedpublic Locale.Builder setScript(String script)
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.
script
- the scriptIllformedLocaleException
- if script
is ill-formedpublic Locale.Builder setRegion(String region)
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
obtained from a Builder
is always normalized to upper case.
region
- the regionIllformedLocaleException
- if region
is ill-formedpublic Locale.Builder setVariant(String variant)
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 Locale.of(String, String, String)
.
variant
- the variantIllformedLocaleException
- if variant
is ill-formedpublic Locale.Builder setExtension(char key, String value)
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.
key
- the extension keyvalue
- the extension valueIllformedLocaleException
- if key
is illegal or value
is ill-formedpublic Locale.Builder setUnicodeLocaleKeyword(String key, String type)
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.
key
- the Unicode locale keytype
- the Unicode locale typeIllformedLocaleException
- if key
or type
is ill-formedNullPointerException
- if key
is nullpublic Locale.Builder addUnicodeLocaleAttribute(String attribute)
attribute
- the attributeNullPointerException
- if attribute
is nullIllformedLocaleException
- if attribute
is ill-formedpublic Locale.Builder removeUnicodeLocaleAttribute(String attribute)
Attribute comparison for removal is case-insensitive.
attribute
- the attributeNullPointerException
- if attribute
is nullIllformedLocaleException
- if attribute
is ill-formedpublic Locale.Builder clear()
public Locale.Builder clearExtensions()
public Locale build()
Locale
obtained from the fields set on this builder. This applies the conversions listed in Locale.forLanguageTag(java.lang.String)
when constructing a Locale. (Legacy tags are handled in setLanguageTag(java.lang.String)
.)
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Locale.Builder.html