Spec-Zone.ru › OpenJDK 17

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

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

setCalendarType

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

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

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

УстановитьЛокаль

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
См. также:
  • Calendar.getInstance(Locale)

УстановитьОпределениеНедели

public Calendar.Builder setWeekDefinition(int firstDayOfWeek, int minimalDaysInFirstWeek)
Устанавливает параметры определения недели до значений, заданных firstDayOfWeek и minimalDaysInFirstWeek, используемых для определения первой недели года. Параметры, заданные этим методом, имеют приоритет над значениями по умолчанию, заданными локалью setWeekDefinition.
Параметры:
firstDayOfWeek - первый день недели; один из Calendar.SUNDAY до Calendar.SATURDAY
minimalDaysInFirstWeek - минимальное количество дней в первой неделе (1..7)
Возвращает:
этот Calendar.Builder
Исключения:
IllegalArgumentException - если firstDayOfWeek или minimalDaysInFirstWeek некорректны
См. также:
  • Calendar.getFirstDayOfWeek()
  • Calendar.getMinimalDaysInFirstWeek()

создать

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

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

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

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

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

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

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

Spec-Zone.ru

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