Класс 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

Конструкторы

Builder

public Builder()

Создаёт Calendar.Builder.

Методы

setInstant

public Calendar.Builder setInstant(long instant)

Устанавливает параметр 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. В этом методе валидация значения поля не выполняется. Любые значения вне диапазона либо нормализуются в режиме допуска, либо распознаются как недопустимое значение при построении Calendar.

Параметры:
field — индекс поля в Calendar
value — значение поля
Возвращает:
this Calendar.Builder
Исключения:
IllegalArgumentException — если field недопустимо
IllegalStateException — если значение instant уже установлено или поля были установлены слишком много раз (приблизительно 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 — если какое-либо из полей недопустимо или fieldValuePairs.length является нечётным числом.
IllegalStateException — если значение instant уже установлено или поля были установлены слишком много раз (приблизительно 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 будет использован по умолчанию TimeZone.

Параметры:
zone — TimeZone
Возвращает:
this Calendar.Builder
Исключения:
NullPointerException — если zone является null
См. также:
Calendar.setTimeZone(TimeZone)

setLenient

public Calendar.Builder setLenient(boolean lenient)

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

Параметры:
lenient — true для режима допуска; false для режима без допуска
Возвращает:
this Calendar.Builder
См. также:
Calendar.setLenient(boolean)

setCalendarType

public Calendar.Builder setCalendarType(String type)

Устанавливает параметр типа календаря в заданное значение type. Тип календаря, заданный этим методом, имеет приоритет над любым явным или неявным типом календаря, заданным локалью locale.

Помимо доступных типов календаря, возвращаемых методом 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.Category.FORMAT.

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

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

Параметры:
locale — Locale
Возвращает:
this Calendar.Builder
Исключения:
NullPointerException — если locale является null
См. также:
Calendar.getInstance(Locale)

setWeekDefinition

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

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

Параметры:
firstDayOfWeek - первый день недели; один из Calendar.SUNDAY до Calendar.SATURDAY
minimalDaysInFirstWeek - минимальное количество дней в первой неделе (1..7)
Возвращает:
это Calendar.Builder
Выбрасывает:
IllegalArgumentException - если firstDayOfWeek или minimalDaysInFirstWeek некорректны
См. также:
Calendar.getFirstDayOfWeek(), Calendar.getMinimalDaysInFirstWeek()

build

public Calendar build()

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

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

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

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

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

Возвращает:
Calendar, созданный с параметрами этого Calendar.Builder
Выбрасывает:
IllegalArgumentException - если тип календаря неизвестен, или если заданы некорректные значения полей в режиме non-lenient, или если для календаря, не поддерживающего даты недели, задана дата недели.
См. также:
Calendar.getInstance(TimeZone, Locale), Locale.getDefault(Locale.Category), TimeZone.getDefault()

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

Spec-Zone .ru
спецификации, руководства, описания, API