Spec-Zone.ru › OpenJDK 24

Класс Calendar.Builder

java.lang.Object
java.util.Calendar.Builder
Вложенный класс:
Calendar
public static class Calendar.Builder extends Object
Calendar.Builder используется для создания экземпляра Calendar на основе различных параметров даты и времени.

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

Если для определения даты и/или времени предоставлено недостаточно параметров полей, при построении экземпляра 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
См. также:
  • Calendar.getInstance(TimeZone, Locale)
  • Calendar.fields

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

Конструктор Описание
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 заданному значению instant, которое представляет собой миллисекундное смещение от эпохи.
Calendar.Builder setInstant(Date instant)
Устанавливает параметр instant значению instant, заданному объектом Date.
Calendar.Builder setLenient(boolean lenient)
Устанавливает параметр lenient заданному значению lenient.
Calendar.Builder setLocale(Locale 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)
Устанавливает параметр time zone заданному значению zone.
Calendar.Builder setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)
Устанавливает параметры даты, основанной на неделе, значениям с заданными спецификаторами даты — номер года, номер недели и день недели.
Calendar.Builder setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)
Устанавливает параметры определения недели значениям, заданным firstDayOfWeek и minimalDaysInFirstWeek, которые используются для определения первой недели года.

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

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

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

Конструктор

public Builder()
Создаёт экземпляр Calendar.Builder.

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

setInstant

public Calendar.Builder setInstant(long instant)
Устанавливает параметр момента времени на заданное instant значение, являющееся миллисекундным смещением от эпохи.
Параметры:
instant - миллисекундное смещение от эпохи
Возвращает:
this Calendar.Builder
Исключения:
IllegalStateException - если любой из параметров поля уже установлен
См. также:
  • Calendar.setTime(Date)
  • Calendar.setTimeInMillis(long)
  • Calendar.time

setInstant

public Calendar.Builder setInstant(Date instant)
Устанавливает параметр момента времени на значение, заданное instant объектом Date. Этот метод эквивалентен вызову setInstant(instant.getTime()).
Параметры:
instant - объект Date, представляющий миллисекундное смещение от эпохи
Возвращает:
this Calendar.Builder
Исключения:
NullPointerException - если instant является null
IllegalStateException - если любой из параметров поля уже установлен
См. также:
  • Calendar.setTime(Date)
  • Calendar.setTimeInMillis(long)
  • Calendar.time

set

public Calendar.Builder set(int field, int value)
Устанавливает параметр field на заданное value значение. field — это индекс к Calendar.fields, например, DAY_OF_MONTH. В этом методе не выполняется валидация значений поля. Любые значения вне диапазона либо нормализуются в режиме lenient, либо распознаются как недопустимые значения в режиме non-lenient при создании Calendar.
Параметры:
field - индекс к полям Calendar
value - значение поля
Возвращает:
this Calendar.Builder
Исключения:
IllegalArgumentException - если field некорректно
IllegalStateException - если значение момента времени уже установлено или поля были установлены слишком много раз (примерно Integer.MAX_VALUE).
См. также:
  • Calendar.set(int, int)

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 - пары поле-значение
Возвращает:
this Calendar.Builder
Исключения:
NullPointerException - если fieldValuePairs некорректно
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
Возвращает:
this 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
Возвращает:
this 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
Возвращает:
this Calendar.Builder

setWeekDate

public Calendar.Builder setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)
Устанавливает параметры даты, основанной на неделе, на значения, указанные с помощью спецификаторов даты - год по неделям, номер недели по году и день недели.

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

Параметры:
weekYear - год по неделям
weekOfYear - номер недели по году
dayOfWeek - значение дня недели: одно из констант для поля DAY_OF_WEEK: SUNDAY, ..., SATURDAY.
Возвращает:
this Calendar.Builder
См. также:
  • Calendar.setWeekDate(int, int, int)
  • Calendar.isWeekDateSupported()

setTimeZone

public Calendar.Builder setTimeZone(TimeZone zone)
Устанавливает параметр часового пояса на заданный zone. Если для данного Calendar.Builder не задан параметр часового пояса, в методе build будет использован по умолчанию TimeZone.
Параметры:
zone - TimeZone
Возвращает:
this Calendar.Builder
Исключения:
NullPointerException - если zone некорректно
См. также:
  • Calendar.setTimeZone(TimeZone)

setLenient

public Calendar.Builder setLenient(boolean lenient)
Устанавливает параметр lenient mode на значение, заданное lenient. Если для данного Calendar.Builder не задан параметр lenient mode, в методе build будет использован режим lenient.
Параметры:
lenient - значение true для lenient mode; false для non-lenient mode
Возвращает:
this Calendar.Builder
См. также:
  • Calendar.setLenient(boolean)

setCalendarType

public Calendar.Builder setCalendarType(String type)
Устанавливает параметр типа календаря на заданный type. Тип календаря, заданный этим методом, имеет приоритет над любым явным или неявным типом календаря, заданным локалью.

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

Параметры:
type - тип календаря
Возвращает:
this Calendar.Builder
Исключения:
NullPointerException - если type некорректно
IllegalArgumentException - если тип календаря неизвестен
IllegalStateException - если другой тип календаря уже установлен
См. также:
  • Calendar.getCalendarType()
  • Calendar.getAvailableCalendarTypes()

setLocale

public Calendar.Builder setLocale(Locale locale)
Устанавливает параметр локали на заданную locale. Если для данной Calendar.Builder не задана локаль, используется по умолчанию Locale для Locale.Category.FORMAT.

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

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

Parameters:
locale - Locale
Returns:
this Calendar.Builder
Throws:
NullPointerException - если locale является null
See Also:
  • Calendar.getInstance(Locale)

setWeekDefinition

public Calendar.Builder setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)
Устанавливает параметры определения недели в значения, заданные firstDayOfWeek и minimalDaysInFirstWeek, которые используются для определения первой недели года. Параметры, заданные этим методом, имеют приоритет над значениями по умолчанию, заданными локалью locale.
Parameters:
firstDayOfWeek - первый день недели; одно из значений от Calendar.SUNDAY до Calendar.SATURDAY
minimalDaysInFirstWeek - минимальное количество дней в первой неделе (1..7)
Returns:
this Calendar.Builder
Throws:
IllegalArgumentException - если firstDayOfWeek или minimalDaysInFirstWeek имеют недопустимые значения
See Also:
  • Calendar.getFirstDayOfWeek()
  • Calendar.getMinimalDaysInFirstWeek()

build

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

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

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

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

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

Returns:
Calendar, созданный с параметрами этого Calendar.Builder
Throws:
IllegalArgumentException - если тип календаря неизвестен, или если заданы недопустимые значения полей в режиме non-lenient, или если для типа календаря задан дата недели, которая не поддерживается.
See Also:
  • Calendar.getInstance(TimeZone, Locale)
  • Locale.getDefault(Locale.Category)
  • TimeZone.getDefault()

© 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/Calendar.Builder.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API