Класс Calendar.Builder

public static class Calendar.Builder
extends Object

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

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

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

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

Примеры

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

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

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

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

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

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

Builder

public Builder()

Создаёт Calendar.Builder.

Методы

setInstant

public Calendar.Builder setInstant(long instant)

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

Параметры:

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

Возвращает:

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

Возвращает:

этот 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 - значение поля

Возвращает:

этот Calendar.Builder

Исключения:

IllegalArgumentException - если field некорректно

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

См. также:

Calendar.set(int, int)

setFields

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

Устанавливает параметры поля на их значения, заданные fieldValuePairs - парами поля и его значения. Например,

setFeilds(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 (номерация месяцев нулевая).

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)

Параметры:

weekYear - год недели

weekOfYear - номер недели, основанный на weekYear

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

Возвращает:

этот Calendar.Builder

См. также:

Calendar.setWeekDate(int, int, int), Calendar.isWeekDateSupported()

setTimeZone

public Calendar.Builder setTimeZone(TimeZone zone)

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

Параметры:

zone - TimeZone

Возвращает:

этот Calendar.Builder

Исключения:

NullPointerException - если zone null

См. также:

Calendar.setTimeZone(TimeZone)

setLenient

public Calendar.Builder setLenient(boolean lenient)

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

Параметры:

lenient - true для режима «поблажки»; false для режима «без поблажек»

Возвращает:

этот Calendar.Builder

См. также:

Calendar.setLenient(boolean)

setCalendarType

public Calendar.Builder setCalendarType(String type)

Параметры:

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

Возвращает:

этот Calendar.Builder

Исключения:

NullPointerException - если type null

IllegalArgumentException - если тип календаря неизвестен

IllegalStateException - если другой тип календаря уже задан

См. также:

Calendar.getCalendarType(), Calendar.getAvailableCalendarTypes()

setLocale

public Calendar.Builder setLocale(Locale locale)

Параметры:

locale - Locale

Возвращает:

этот Calendar.Builder

Исключения:

NullPointerException - если locale null

См. также:

Calendar.getInstance(Locale)

setWeekDefinition

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

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

Параметры:

firstDayOfWeek - первый день недели; один из Calendar.SUNDAY по Calendar.SATURDAY

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

Возвращает:

this Calendar.Builder

Выбрасывает:

IllegalArgumentException - если firstDayOfWeek или minimalDaysInFirstWeek неверны

См. также:

Calendar.getFirstDayOfWeek(), Calendar.getMinimalDaysInFirstWeek()

build

public Calendar build()

Возвращает:

календарь, построенный с параметрами этого Calendar.Builder

Выбрасывает:

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

См. также:

Calendar.getInstance(TimeZone, Locale), Locale.getDefault(Locale.Category), TimeZone.getDefault()