Класс 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()`	Создаёт пустой 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)`	Сбрасывает Builder, приводя его в соответствие с указанным языковым тегом 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

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

Builder

public Builder()

Создаёт пустой 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)

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

Полный список преобразований, выполняемых для 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)

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

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

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

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

setVariant

public Locale.Builder setVariant(String variant)

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

Примечание: Этот метод проверяет, соответствует ли 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.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Locale.Builder.html