Класс Calendar.Builder

java.lang.Object

java.util.Calendar.Builder

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

public static class Calendar.Builder extends Object

Calendar.Builder используется для создания Calendar из различных параметров даты и времени.

Есть два способа задать для Calendar значение даты и времени. Первый — задать параметр момента времени как смещение в миллисекундах от эпохи. Второй — задать отдельные параметры полей, например YEAR, нужными значениями. Смешивать эти два способа нельзя. Попытка задать одновременно момент времени и отдельные поля приведёт к выбрасыванию IllegalStateException. Однако разрешено переопределять ранее заданные значения момента времени или параметров полей.

Если для определения даты и/или времени задано недостаточно параметров полей, при создании Calendar используются значения по умолчанию, специфичные для календаря. Например, если для григорианского календаря не задано значение YEAR, будет использоваться 1970 год. Если между параметрами полей возникают конфликты, применяются правила разрешения конфликтов. Поэтому порядок задания полей имеет значение.

Помимо параметров даты и времени можно задать параметры локали, часового пояса, определения недели и режима допуска.

Примеры

Ниже приведены примеры использования. В примерах кода предполагается, что константы Calendar статически импортированы.

Следующий код создаёт Calendar с датой 2012-12-31 (григорианский календарь), поскольку понедельник является первым днём недели при использовании параметров недели, совместимых с ISO 8601.

  Calendar cal = new Calendar.Builder().setCalendarType("iso8601")
                       .setWeekDate(2013, 1, MONDAY).build();

Следующий код создаёт японский Calendar с датой 1989-01-08 (григорианский календарь), если предположить, что значением ERA по умолчанию является Хэйсэй, начавшаяся в этот день.

  Calendar cal = new Calendar.Builder().setCalendarType("japanese")
                       .setFields(YEAR, 1, DAY_OF_YEAR, 1).build();

Начиная с:

1.8

См. также:

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

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

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

Модификатор и тип	Метод	Описание
`Calendar`	`build()`	Возвращает `Calendar`, созданный на основе параметров, заданных методами-сеттерами.
`Calendar.Builder`	`set(int field, int value)`	Задаёт параметру `field` указанное значение `value`.
`Calendar.Builder`	`setCalendarType(String type)`	Задаёт параметру типа календаря указанное значение `type`.
`Calendar.Builder`	`setDate(int year, int month, int dayOfMonth)`	Задаёт параметры полей даты значениями `year`, `month` и `dayOfMonth`.
`Calendar.Builder`	`setFields(int... fieldValuePairs)`	Задаёт параметры полей значениями из `fieldValuePairs` — пар поля и его значения.
`Calendar.Builder`	`setInstant(long instant)`	Задаёт параметру момента времени указанное значение `instant`, представляющее собой смещение в миллисекундах от эпохи.
`Calendar.Builder`	`setInstant(Date instant)`	Задаёт параметру момента времени значение `instant`, полученное из объекта `Date`.
`Calendar.Builder`	`setLenient(boolean lenient)`	Задаёт параметр режима допуска значением `lenient`.
`Calendar.Builder`	`setLocale(Locale locale)`	Задаёт параметру локали указанное значение `locale`.
`Calendar.Builder`	`setTimeOfDay(int hourOfDay, int minute, int second)`	Задаёт параметры полей времени суток значениями `hourOfDay`, `minute` и `second`.
`Calendar.Builder`	`setTimeOfDay(int hourOfDay, int minute, int second, int millis)`	Задаёт параметры полей времени суток значениями `hourOfDay`, `minute`, `second` и `millis`.
`Calendar.Builder`	`setTimeZone(TimeZone zone)`	Задаёт параметру часового пояса указанное значение `zone`.
`Calendar.Builder`	`setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)`	Задаёт параметры даты на основе недель значениями заданных компонентов даты: года недели, недели года и дня недели.
`Calendar.Builder`	`setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)`	Задаёт параметры определения недели значениями `firstDayOfWeek` и `minimalDaysInFirstWeek`, которые используются для определения первой недели года.

Методы, объявленные в классе 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()`	Заставляет текущий поток ожидать пробуждения, обычно вследствие вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно вследствие вызова notify или interrupt, либо до истечения заданного времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно вследствие вызова notify или interrupt, либо до истечения заданного времени.

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

Builder

public Builder()

Создаёт Calendar.Builder.

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

setInstant

public Calendar.Builder setInstant(long instant)

Задаёт параметру момента времени указанное значение instant, представляющее собой смещение в миллисекундах от эпохи.

Параметры:

instant — смещение в миллисекундах от эпохи

Возвращает:

этот Calendar.Builder

Исключения:

IllegalStateException — если уже заданы какие-либо параметры полей

См. также:

setInstant

public Calendar.Builder setInstant(Date instant)

Задаёт параметру момента времени значение instant, полученное из объекта Date. Этот метод эквивалентен вызову setInstant(instant.getTime()).

Параметры:

instant — объект Date, представляющий смещение в миллисекундах от эпохи

Возвращает:

этот Calendar.Builder

Исключения:

NullPointerException — если instant имеет значение null

IllegalStateException — если уже заданы какие-либо параметры полей

См. также:

set

public Calendar.Builder set(int field, int value)

Задаёт параметру field указанное значение value. field — это индекс в Calendar.fields, например DAY_OF_MONTH. В этом методе проверка допустимости значения поля не выполняется. Выходящие за диапазон значения нормализуются в режиме допуска или распознаются как недопустимые в строгом режиме при создании Calendar.

Параметры:

field — индекс поля Calendar

value — значение поля

Возвращает:

этот Calendar.Builder

Исключения:

IllegalArgumentException — если field недопустимо

IllegalStateException — если значение момента времени уже задано или поля задавались слишком много раз (примерно Integer.MAX_VALUE раз).

См. также:

setFields

public Calendar.Builder setFields(int... fieldValuePairs)

Задаёт параметры полей значениями из fieldValuePairs — пар поля и его значения. Например,

  setFields(Calendar.YEAR, 2013,
            Calendar.MONTH, Calendar.DECEMBER,
            Calendar.DAY_OF_MONTH, 23);

эквивалентен последовательности следующих вызовов set:

  set(Calendar.YEAR, 2013)
  .set(Calendar.MONTH, Calendar.DECEMBER)
  .set(Calendar.DAY_OF_MONTH, 23);

Параметры:: fieldValuePairs — пары «поле — значение»
Возвращает:: этот Calendar.Builder
Исключения:: NullPointerException — если fieldValuePairs имеет значение null; IllegalArgumentException — если какое-либо поле недопустимо или fieldValuePairs.length является нечётным числом.; IllegalStateException — если значение момента времени задано или поля задавались слишком много раз (примерно Integer.MAX_VALUE раз).

setDate

public Calendar.Builder setDate(int year, int month, int dayOfMonth)

Задаёт параметры полей даты значениями year, month и dayOfMonth. Этот метод эквивалентен вызову:

  setFields(Calendar.YEAR, year,
            Calendar.MONTH, month,
            Calendar.DAY_OF_MONTH, dayOfMonth);

Параметры:: year — значение YEAR; month — значение MONTH (нумерация месяцев начинается с 0).; dayOfMonth — значение DAY_OF_MONTH
Возвращает:: этот Calendar.Builder

setTimeOfDay

public Calendar.Builder setTimeOfDay(int hourOfDay, int minute, int second)

Задаёт параметры полей времени суток значениями hourOfDay, minute и second. Этот метод эквивалентен вызову:

  setTimeOfDay(hourOfDay, minute, second, 0);

Параметры:: hourOfDay — значение HOUR_OF_DAY (24-часовой формат); minute — значение MINUTE; second — значение SECOND
Возвращает:: этот Calendar.Builder

setTimeOfDay

public Calendar.Builder setTimeOfDay(int hourOfDay, int minute, int second, int millis)

Задаёт параметры полей времени суток значениями hourOfDay, minute, second и millis. Этот метод эквивалентен вызову:

  setFields(Calendar.HOUR_OF_DAY, hourOfDay,
            Calendar.MINUTE, minute,
            Calendar.SECOND, second,
            Calendar.MILLISECOND, millis);

Параметры:: hourOfDay — значение HOUR_OF_DAY (24-часовой формат); minute — значение MINUTE; second — значение SECOND; millis — значение MILLISECOND
Возвращает:: этот Calendar.Builder

setWeekDate

public Calendar.Builder setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)

Задаёт параметры даты на основе недель значениями заданных компонентов даты: года недели, недели года и дня недели.

Если указанный календарь не поддерживает даты на основе недель, метод build выбросит исключение IllegalArgumentException.

Параметры:

weekYear — год недели

weekOfYear — номер недели на основе weekYear

dayOfWeek — значение дня недели: одна из констант поля DAY_OF_WEEK: SUNDAY, ..., SATURDAY.

Возвращает:

этот Calendar.Builder

См. также:

setTimeZone

public Calendar.Builder setTimeZone(TimeZone zone)

Задаёт параметру часового пояса указанное значение zone. Если для этого Calendar.Builder параметр часового пояса не задан, в методе build будет использоваться часовой пояс TimeZone по умолчанию.

Параметры:

zone — TimeZone

Возвращает:

этот Calendar.Builder

Исключения:

NullPointerException — если zone имеет значение null

См. также:

setLenient

public Calendar.Builder setLenient(boolean lenient)

Задаёт параметру режима допуска значение lenient. Если для этого Calendar.Builder параметр допуска не задан, в методе build будет использоваться режим допуска.

Параметры:

lenient — true для режима допуска; false для строгого режима

Возвращает:

этот Calendar.Builder

См. также:

setCalendarType

public Calendar.Builder setCalendarType(String type)

Задаёт параметру типа календаря указанное значение type. Тип календаря, заданный этим методом, имеет приоритет над любым явным или неявным типом календаря, определяемым параметром локали.

Помимо доступных типов календаря, возвращаемых методом Calendar.getAvailableCalendarTypes, с этим методом можно использовать "gregorian" и "iso8601" в качестве псевдонимов "gregory".

Параметры:

type — тип календаря

Возвращает:

этот Calendar.Builder

Исключения:

NullPointerException — если type имеет значение null

IllegalArgumentException — если type неизвестно

IllegalStateException — если тип календаря уже задан

См. также:

setLocale

public Calendar.Builder setLocale(Locale locale)

Задаёт параметру локали указанное значение locale. Если для этого Calendar.Builder локаль не задана, будет использоваться Locale по умолчанию для Locale.Category.FORMAT.

Если явный тип календаря не задан вызовом метода setCalendarType, значение Locale используется для определения типа создаваемого Calendar.

Если параметры определения недели явно не заданы вызовом метода setWeekDefinition, используются значения по умолчанию для Locale.

Параметры:

locale — Locale

Возвращает:

этот Calendar.Builder

Исключения:

NullPointerException — если locale имеет значение null

См. также:

setWeekDefinition

public Calendar.Builder setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)

Задаёт параметры определения недели значениями firstDayOfWeek и minimalDaysInFirstWeek, которые используются для определения первой недели года. Параметры, заданные этим методом, имеют приоритет над значениями по умолчанию, определяемыми локалью.

Параметры:

firstDayOfWeek — первый день недели: одно из значений от Calendar.SUNDAY до Calendar.SATURDAY

minimalDaysInFirstWeek — минимальное число дней в первой неделе (1..7)

Возвращает:

этот Calendar.Builder

Исключения:

IllegalArgumentException — если firstDayOfWeek или minimalDaysInFirstWeek недопустимо

См. также:

build

public Calendar build()

Возвращает Calendar, созданный на основе параметров, заданных методами-сеттерами. Тип создаваемого Calendar определяется методом setCalendarType или параметром локали. Если явный тип календаря не задан, создаётся календарь, используемый по умолчанию для данной локали.

Если тип календаря — "iso8601", дата перехода на григорианский календарь дата перехода на григорианский календарь объекта GregorianCalendar устанавливается в Date(Long.MIN_VALUE), чтобы календарь был пролептическим григорианским календарём. Параметры определения недели также устанавливаются в соответствии со стандартом ISO 8601. Обратите внимание, что метод getCalendarType объекта GregorianCalendar, созданного с помощью "iso8601", возвращает "gregory".

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

Если локаль содержит часовой пояс в виде расширения Unicode "tz", а часовой пояс не задан явно, используется часовой пояс из локали.

Выходящие за диапазон значения полей нормализуются в режиме допуска или распознаются как недопустимые в строгом режиме.

Возвращает:

Calendar, созданный с параметрами этого


        Calendar.Builder

Исключения:

IllegalArgumentException — если тип календаря неизвестен, если в строгом режиме заданы недопустимые значения полей или если для типа календаря, не поддерживающего даты на основе недель, задана дата на основе недели.

См. также:

© 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.