Класс Locale.Builder

java.lang.Object

java.util.Locale.Builder

Внешний класс:: Locale

public static final class Locale.Builder extends Object

Builder используется для создания экземпляров Locale из значений, заданных с помощью методов-сеттеров. В отличие от конструкторов Locale или фабричных методов Locale.of(), Builder проверяет, соответствует ли значение, заданное методом-сеттером, синтаксическим требованиям, определённым классом Locale. Объект Locale, полученный из Builder, имеет корректный формат и может быть преобразован в корректно сформированный языковой тег IETF BCP 47 без потери информации.

Примечание по реализации:

Класс Locale не накладывает синтаксических ограничений на вариант, тогда как BCP 47 требует, чтобы каждый подtag варианта состоял из 5–8 буквенно-цифровых символов либо одной цифры, за которой следуют 3 буквенно-цифровых символа. Метод setVariant выбрасывает IllformedLocaleException для варианта, не соответствующего этому ограничению. Если необходимо поддерживать такой вариант, используйте Locale.of(String, String, String). Однако помните, что объект Locale, полученный таким способом, может потерять информацию о варианте при преобразовании в языковой тег BCP 47.

В следующем примере показано, как получить объект Locale с помощью Builder.

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

Построители можно использовать повторно; clear() сбрасывает все поля в значения по умолчанию.

Начиная с:

1.7

См. также:

Краткое описание конструкторов

Конструктор	Описание
`Builder()`	Создаёт пустой построитель.

Краткое описание методов

Модификатор и тип	Метод	Описание
`Locale.Builder`	`addUnicodeLocaleAttribute(String attribute)`	Добавляет атрибут локали Unicode, если он ещё не присутствует; в противном случае ничего не делает.
`Locale`	`build()`	Возвращает экземпляр `Locale`, созданный на основе полей, заданных в этом построителе.
`Locale.Builder`	`clear()`	Возвращает построитель в исходное пустое состояние.
`Locale.Builder`	`clearExtensions()`	Возвращает расширения в исходное пустое состояние.
`Locale.Builder`	`removeUnicodeLocaleAttribute(String attribute)`	Удаляет атрибут локали Unicode, если он присутствует; в противном случае ничего не делает.
`Locale.Builder`	`setExtension(char key, String value)`	Задаёт расширение для указанного ключа.
`Locale.Builder`	`setLanguage(String language)`	Задаёт язык.
`Locale.Builder`	`setLanguageTag(String languageTag)`	Сбрасывает состояние построителя, чтобы оно соответствовало предоставленному языковому тегу IETF BCP 47.
`Locale.Builder`	`setLocale(Locale locale)`	Сбрасывает `Builder`, чтобы оно соответствовало предоставленному `locale`.
`Locale.Builder`	`setRegion(String region)`	Задаёт регион.
`Locale.Builder`	`setScript(String script)`	Задаёт письменность.
`Locale.Builder`	`setUnicodeLocaleKeyword(String key, String type)`	Задаёт тип ключевого слова локали Unicode для указанного ключа.
`Locale.Builder`	`setVariant(String variant)`	Задаёт вариант.

Методы, объявленные в классе Object

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, равен ли этот объект какому-либо другому объекту.
`protected void`	`finalize()`	Устарело и будет удалено: этот элемент API может быть удалён в будущей версии. Финализация объявлена устаревшей и будет удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания, либо до истечения указанного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания, либо до истечения указанного промежутка реального времени.

Подробное описание конструкторов

Builder

public Builder()

Создаёт пустой построитель. Значением по умолчанию для всех полей, расширений и сведений о личном использовании является пустая строка.

Подробное описание методов

setLocale

public Locale.Builder setLocale(Locale locale)

Сбрасывает Builder, чтобы оно соответствовало предоставленному locale. Существующее состояние отбрасывается.

Все поля локали должны иметь корректный формат; см. Locale.

Если какое-либо поле локали имеет некорректный формат, выбрасывается IllformedLocaleException, за исключением следующих трёх случаев, принимаемых для обеспечения совместимости:

Locale("ja", "JP", "JP") интерпретируется как "ja-JP-u-ca-japanese"
Locale("th", "TH", "TH") интерпретируется как "th-TH-u-nu-thai"
Locale("no", "NO", "NY") интерпретируется как "nn-NO"

Параметры:: locale — локаль
Возвращает:: Этот построитель.
Выбрасывает:: IllformedLocaleException — если locale содержит поля с некорректным форматом.; NullPointerException — если locale равно null.

setLanguageTag

public Locale.Builder setLanguageTag(String languageTag)

Сбрасывает состояние построителя, чтобы оно соответствовало предоставленному языковому тегу IETF BCP 47. Существующее состояние отбрасывается. Значение null и пустая строка сбрасывают построитель, как и clear(). Устаревшие теги (см. Locale.forLanguageTag(String)) перед обработкой преобразуются в каноническую форму. В остальных случаях языковой тег должен иметь корректный формат (см. Locale), иначе выбрасывается исключение (в отличие от Locale.forLanguageTag, который просто отбрасывает некорректную часть тега и следующие за ней части).

Повторяющиеся варианты принимаются и включаются построителем. Однако повторяющиеся одиночные ключи расширений и связанные с ними типы принимаются, но игнорируются. Такое же поведение применяется к повторяющимся ключам локали и атрибутам в расширении U. Обратите внимание, что последующие подtags после повторяющегося элемента не игнорируются.

Полный список преобразований, выполняемых для languageTag, см. в разделе converions.

Параметры:

languageTag — языковой тег

Возвращает:

Этот построитель.

Выбрасывает:

IllformedLocaleException — если languageTag имеет некорректный формат

См. также:

setLanguage

public Locale.Builder setLanguage(String language)

Задаёт язык. Если language — пустая строка или null, язык в этом Builder удаляется. В противном случае язык должен иметь корректный формат, иначе выбрасывается исключение.

Обычно в качестве значения языка используется двух- или трёхбуквенный код языка, определённый стандартом ISO 639.

Параметры:: language — язык
Возвращает:: Этот построитель.
Выбрасывает:: IllformedLocaleException — если language имеет некорректный формат

setScript

public Locale.Builder setScript(String script)

Задаёт письменность. Если script равно null или пустой строке, письменность в этом Builder удаляется. В противном случае письменность должна иметь корректный формат, иначе выбрасывается исключение.

Обычно в качестве значения письменности используется четырёхбуквенный код письменности, определённый стандартом ISO 15924.

Параметры:: script — письменность
Возвращает:: Этот построитель.
Выбрасывает:: IllformedLocaleException — если script имеет некорректный формат

setRegion

public Locale.Builder setRegion(String region)

Задаёт регион. Если регион равен null или пустой строке, регион в этом Builder удаляется. В противном случае регион должен иметь корректный формат, иначе выбрасывается исключение.

Обычно в качестве значения региона используется двухбуквенный код ISO 3166 или трёхзначный код территории ООН M.49.

Значение страны в Locale, полученном из Builder, всегда приводится к верхнему регистру.

Параметры:: region — регион
Возвращает:: Этот построитель.
Выбрасывает:: IllformedLocaleException — если region имеет некорректный формат

setVariant

public Locale.Builder setVariant(String variant)

Задаёт вариант. Если вариант равен null или пустой строке, вариант в этом Builder удаляется. В противном случае он должен состоять из одного или нескольких корректно сформированных подtag, иначе выбрасывается исключение. Повторяющиеся варианты принимаются и включаются построителем.

Примечание: Этот метод проверяет, соответствует ли variant синтаксическим требованиям IETF BCP 47 к подtag варианта, и приводит значение к нижнему регистру. Однако класс Locale не накладывает синтаксических ограничений на вариант, а значение варианта в Locale чувствительно к регистру. Чтобы задать такой вариант, используйте Locale.of(String, String, String).

Параметры:

variant — вариант

Возвращает:

Этот построитель.

Выбрасывает:

IllformedLocaleException — если variant имеет некорректный формат

См. также:

setExtension

public Locale.Builder setExtension(char key, String value)

Задаёт расширение для указанного ключа. Если значение равно null или пустой строке, расширение удаляется. В противном случае расширение должно иметь корректный формат, иначе выбрасывается исключение.

Примечание: Ключ UNICODE_LOCALE_EXTENSION ('u') используется для расширения локали Unicode. Задание значения для этого ключа заменяет все существующие пары ключ/тип локали Unicode парами, определёнными в расширении. Повторяющиеся атрибуты локали, а также ключи локали и связанные с ними типы принимаются, но игнорируются.

Примечание: Ключ PRIVATE_USE_EXTENSION ('x') используется для кода личного использования. Чтобы значение для этого ключа имело корректный формат, его подtags должны состоять из одного–восьми буквенно-цифровых символов, а не из двух–восьми, как в общем случае.

Параметры:

key — ключ расширения

value — значение расширения

Возвращает:

Этот построитель.

Выбрасывает:

IllformedLocaleException — если key недопустим или value имеет некорректный формат

См. также:

setUnicodeLocaleKeyword

public Locale.Builder setUnicodeLocaleKeyword(String key, String type)

Задаёт тип ключевого слова локали Unicode для указанного ключа. Если тип равен null, ключевое слово Unicode удаляется. В противном случае ключ не должен быть равен null, а ключ и тип должны иметь корректный формат, иначе выбрасывается исключение.

Ключи и типы преобразуются в нижний регистр.

Примечание: Задание расширения 'u' с помощью setExtension(char, String) заменяет все ключевые слова локали Unicode ключевыми словами, определёнными в расширении.

Параметры:

key — ключ локали Unicode

type — тип локали Unicode

Возвращает:

Этот построитель.

Выбрасывает:

IllformedLocaleException — если key или type имеет некорректный формат

NullPointerException — если key равно null

См. также:

addUnicodeLocaleAttribute

public Locale.Builder addUnicodeLocaleAttribute(String attribute)

Добавляет атрибут локали Unicode, если он ещё не присутствует; в противном случае ничего не делает. Атрибут не должен быть равен null и должен иметь корректный формат, иначе выбрасывается исключение.

Параметры:

attribute — атрибут

Возвращает:

Этот построитель.

Выбрасывает:

NullPointerException — если attribute равно null

IllformedLocaleException — если attribute имеет некорректный формат

См. также:

removeUnicodeLocaleAttribute

public Locale.Builder removeUnicodeLocaleAttribute(String attribute)

Удаляет атрибут локали Unicode, если он присутствует; в противном случае ничего не делает. Атрибут не должен быть равен null и должен иметь корректный формат, иначе выбрасывается исключение.

При удалении атрибуты сравниваются без учёта регистра.

Параметры:

attribute — атрибут

Возвращает:

Этот построитель.

Выбрасывает:

NullPointerException — если attribute равно null

IllformedLocaleException — если attribute имеет некорректный формат

См. также:

clear

public Locale.Builder clear()

Возвращает построитель в исходное пустое состояние.

Возвращает:: Этот построитель.

clearExtensions

public Locale.Builder clearExtensions()

Возвращает расширения в исходное пустое состояние. Язык, письменность, регион и вариант не изменяются.

Возвращает:

Этот построитель.

См. также:

build

public Locale build()

Возвращает экземпляр Locale, созданный на основе полей, заданных в этом построителе.

При создании Locale применяются преобразования, перечисленные в разделе Locale.forLanguageTag(String). (Обработка устаревших тегов выполняется в setLanguageTag(String).)

Возвращает:: Locale.

© 1993, 2025, 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.