Класс 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 год. При наличии конфликтов между параметрами полей применяются правила разрешения конфликтов. Поэтому порядок задания полей имеет значение.

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

Примеры

Ниже приведены примеры использования. Предполагается, что константы 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 значение, указанное в `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

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

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. В этом методе проверка допустимости значения поля не выполняется. Все значения вне допустимого диапазона либо нормализуются в режиме lenient, либо распознаются как недопустимые в строгом режиме при создании 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 значение, указанное в lenient. Если для этого Calendar.Builder параметр режима lenient не задан, в методе build будет использоваться режим lenient.

Параметры:

lenient — true для режима lenient; 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» (расширение локали), а часовой пояс явно не задан, используется часовой пояс из локали.

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

Возвращает:

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.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Calendar.Builder.html