Spec-Zone.ru › OpenJDK 21

Класс 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 — Heisei, которое началось в этот день. 

   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 — миллисекундное смещение от эпохи.
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 — для определения первой недели года.

Методы, объявленные в классе 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 - если значение поля недопустимо
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 null
IllegalArgumentException - если какое-либо из полей является недопустимым или количество полей нечётное.
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 - номер недели в году, основанный на weekYear
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 будет использован стандартный часовой пояс.
Параметры:
zone - объект TimeZone
Возвращает:
this Calendar.Builder
Исключения:
NullPointerException - если zone null
См. также:
  • Calendar.setTimeZone(TimeZone)

setLenient

public Calendar.Builder setLenient(boolean lenient)
Устанавливает параметр lenient в заданное значение lenient. Если параметр lenient не задан для данного Calendar.Builder, в методе build будет использован режим lenient.
Параметры:
lenient - значение true для lenient, false для non-lenient
Возвращает:
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 null
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".

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

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

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

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

© 1993, 2023, 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/21/docs/api/java.base/java/util/Calendar.Builder.html

Spec-Zone.ru

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