Интерфейс ChronoLocalDate

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

В большинстве приложений следует объявлять сигнатуры методов, поля и переменные как LocalDate, а не этот интерфейс.

Объект ChronoLocalDate представляет собой абстрактное представление даты, где Chronology chronology, или календарная система, является подключаемым модулем. Дата определяется в терминах полей, выраженных через TemporalField, где большинство распространённых реализаций определены в ChronoField. Хронология определяет, как работает календарная система и значение стандартных полей.

Когда следует использовать этот интерфейс

Эта концепция может показаться неожиданной на первый взгляд, так как естественный способ глобализации приложения, поначалу, может заключаться в абстрагировании календарной системы. Однако, как показано ниже, абстрагирование календарной системы обычно является неправильным подходом, приводящим к логическим ошибкам и трудноустранимым багам. Поэтому следует рассматривать использование этого интерфейса вместо LocalDate как архитектурное решение для всего приложения.

Архитектурные вопросы для рассмотрения

1) Приложения, использующие этот интерфейс вместо обычного подхода LocalDate, имеют значительно большую вероятность появления ошибок. Это происходит потому, что используемая календарная система неизвестна на стадии разработки. Основной причиной ошибок является то, что разработчик применяет предположения, основанные на повседневном знании системы ISO, к коду, предназначенному для работы с любой произвольной календарной системой. В следующем разделе описано, как эти предположения могут создавать проблемы. Основным механизмом уменьшения этого повышенного риска ошибок является строгий процесс проверки кода. Это также следует учитывать как дополнительные затраты на обслуживание кода на протяжении всего его жизненного цикла.

2) Этот интерфейс не накладывает ограничений на неизменяемость реализаций. Хотя в примечаниях к реализации указывается, что все реализации должны быть неизменяемыми, в коде или системе типов нет ничего, что налагало бы это требование. Любой метод, объявленный как принимающий ChronoLocalDate , может поэтому получить ненадлежаще или злонамеренно написанную изменяемую реализацию.

3) Приложения, использующие этот интерфейс, должны учитывать влияние эр. LocalDate защищает пользователей от концепции эр, гарантируя, что getYear() возвращает пролептический год. Это решение гарантирует, что разработчики могут рассматривать экземпляры LocalDate как состоящие из трёх полей: года, месяца и дня месяца. В противоположность этому, пользователи этого интерфейса должны рассматривать даты как состоящие из четырёх полей: эры, года эры, месяца и дня месяца. Дополнительное поле эры часто забывают, но оно имеет жизненно важное значение для дат в произвольной календарной системе. Например, в японской календарной системе эра представляет правление императора. В любой момент, когда заканчивается одно правление и начинается другое, год эры сбрасывается до единицы.

4) Единственным согласованным международным стандартом для обмена датами между двумя системами является стандарт ISO-8601, который требует использования системы ISO календаря. Использование этого интерфейса во всём приложении неизбежно приведёт к необходимости обмена данными через сеть или границу компонента, потребовав разработку собственного протокола или формата приложения.

5) Долговременное хранение данных, например, в базе данных, практически всегда допускает только даты в системе ISO-8601 (или связанной системе юлианско-григорианского календаря). Передача дат в других календарных системах увеличивает сложность взаимодействия с хранилищем.

6) Большинство раз, передача ChronoLocalDate через приложение не требуется, как обсуждалось в последнем разделе ниже.

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

Код, запрашивающий день месяца и предполагающий, что значение никогда не превысит 31, неверен. Некоторые календарные системы имеют более 31 дня в некоторых месяцах.

Код, добавляющий 12 месяцев к дате и предполагающий, что к году добавился один год, неверен. В некоторых календарных системах различное количество месяцев, например, 13 в коптском или эфиопском календаре.

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

Код, добавляющий один месяц, а затем второй, и предполагающий, что день месяца останется близким к его исходному значению, неверен. Некоторые календарные системы имеют большие различия между длиной самого длинного и самого короткого месяца. Например, в коптском или эфиопском календарях 12 месяцев по 30 дней и 1 месяц по 5 дней.

Код, добавляющий семь дней и предполагающий, что добавилась неделя, неверен. В некоторых календарных системах недели могут быть не из семи дней, например, в революционном календаре Франции.

Код, предполагающий, что потому что год date1 больше года date2, то date1 после date2, неверен. Это неверно для всех календарных систем, когда речь идёт о году эры, и особенно неверно для японской календарной системы, где год эры начинается заново с правлением каждого нового императора.

Код, рассматривающий месяц 1 и день 1 как начало года, неверен. Не все календарные системы начинают год со значением месяца 1.

В общем случае, обработка даты, и даже запрос даты, открыты для ошибок, когда календарная система неизвестна на стадии разработки. Поэтому крайне важно, чтобы код, использующий этот интерфейс, подвергался дополнительному обзору кода. Это также объясняет, почему архитектурное решение избегать использования этого типа интерфейса обычно является правильным.

Использование LocalDate вместо него

• Объявляйте все сигнатуры методов, относящиеся к датам, в терминах LocalDate.
• Храните хронологию (календарную систему) в профиле пользователя или получите её из региональных настроек пользователя.
• Преобразуйте ISO LocalDate в календарную систему пользователя и обратно при печати и парсинге.

Как обсуждалось выше, выполнение вычислений с датой, где правила календарной системы подключаемы, требует навыков и не рекомендуется. К счастью, необходимость выполнения вычислений с датой в произвольной календарной системе крайне редка. Например, маловероятно, что правила бизнеса системы аренды книг позволят арендовать книгу на один месяц, где значение месяца зависит от выбранной пользователем календарной системы.

Ключевой случай использования вычислений с датой в произвольной календарной системе — создание ежемесячного календаря для отображения и взаимодействия с пользователем. Опять же, это проблема пользовательского интерфейса, и использование этого интерфейса только в нескольких методах слоя пользовательского интерфейса может быть оправдано.

В любой другой части системы, где дата должна быть обработана в календарной системе, отличной от ISO, используемый случай обычно указывает календарную систему, которую следует использовать. Например, приложению может потребоваться вычислить ближайший исламский или еврейский праздник, что может потребовать обработки даты. Этот тип случая может быть обработан следующим образом:

• Начать с ISO LocalDate , переданной методу
• Преобразовать дату в альтернативную календарную систему, которая для этого случая известна, а не произвольная
• Выполнить вычисление
• Преобразовать обратно в LocalDate

Методы

timeLineOrder

static Comparator<ChronoLocalDate> timeLineOrder()

Возвращает:

компаратор, сравнивающий в порядке временной шкалы, игнорируя хронологию

См. также:

isAfter(java.time.chrono.ChronoLocalDate), isBefore(java.time.chrono.ChronoLocalDate), isEqual(java.time.chrono.ChronoLocalDate)

from

static ChronoLocalDate from(TemporalAccessor temporal)

Параметры:

temporal - временной объект для преобразования, не null

Возвращает:

дата, не null

Исключения:

DateTimeException - если невозможно преобразовать в ChronoLocalDate

См. также:

Chronology.date(TemporalAccessor)

getChronology

Chronology getChronology()

Возвращает:

хронология, не null

getEra

default Era getEra()

Возвращает:

константа эры, специфичная для хронологии, применимая к этой дате, не null

isLeapYear

default boolean isLeapYear()

Возвращает:

true, если эта дата в високосный год, false в противном случае

lengthOfMonth

int lengthOfMonth()

Возвращает:

длительность месяца в днях

lengthOfYear

default int lengthOfYear()

Возвращает:

длительность года в днях

isSupported

default boolean isSupported(TemporalField field)

Определено в:

isSupported в интерфейсе TemporalAccessor

Параметры:

field - поле для проверки, null возвращает false

Возвращает:

true, если поле можно запросить, false — если нет

isSupported

default boolean isSupported(TemporalUnit unit)

Определено в:

isSupported в интерфейсе Temporal

Параметры:

unit - интервал для проверки, null возвращает false

Возвращает:

true, если интервал можно добавить/вычесть, false — если нет

with

default ChronoLocalDate with(TemporalAdjuster adjuster)

date = date.with(Month.JULY);        // most key classes implement TemporalAdjuster
  date = date.with(lastDayOfMonth());  // static import from Adjusters
  date = date.with(next(WEDNESDAY));   // static import from Adjusters and DayOfWeek

Определено в:

with в интерфейсе Temporal

Параметры:

adjuster - корректировщик для использования, не null

Возвращает:

объект того же типа с произведенной корректировкой, не null

Исключения:

DateTimeException - если корректировка невозможна

ArithmeticException - если происходит переполнение числовых значений

with

default ChronoLocalDate with(TemporalField field,
                             long newValue)

Определено в:

with в интерфейсе Temporal

Параметры:

field - поле для установки в результате, не null

newValue - новое значение поля в результате

Возвращает:

объект того же типа со значением указанного поля, установленного, не null

Исключения:

DateTimeException - если поле не может быть установлено

UnsupportedTemporalTypeException - если поле не поддерживается

ArithmeticException - если происходит переполнение числовых значений

plus

default ChronoLocalDate plus(TemporalAmount amount)

date = date.plus(period);                // add a Period instance
  date = date.plus(duration);              // add a Duration instance
  date = date.plus(workingDays(6));        // example user-written workingDays method

Определено в:

plus в интерфейсе Temporal

Параметры:

amount - значение для добавления, не null

Возвращает:

объект того же типа с произведенной корректировкой, не null

Исключения:

DateTimeException - если добавление невозможно

ArithmeticException - если происходит переполнение числовых значений

plus

default ChronoLocalDate plus(long amountToAdd,
                             TemporalUnit unit)

Определено в:

plus в интерфейсе Temporal

Параметры:

amountToAdd - количество указанной единицы для добавления, может быть отрицательным

unit - единица количества для добавления, не null

Возвращает:

объект того же типа с добавленным указанным периодом, не null

Издает:

DateTimeException - если единица не может быть добавлена

ArithmeticException - если произошел переполнение числовых значений

minus

default ChronoLocalDate minus(TemporalAmount amount)

date = date.minus(period);               // subtract a Period instance
  date = date.minus(duration);             // subtract a Duration instance
  date = date.minus(workingDays(6));       // example user-written workingDays method

Определено в:

minus в интерфейсе Temporal

Параметры:

amount - величина для вычитания, не null

Возвращает:

объект того же типа со сделанной корректировкой, не null

Издает:

DateTimeException - если вычитание невозможно

ArithmeticException - если произошло переполнение числовых значений

minus

default ChronoLocalDate minus(long amountToSubtract,
                              TemporalUnit unit)

Определено в:

minus в интерфейсе Temporal

Параметры:

amountToSubtract - количество указанной единицы для вычитания, может быть отрицательным

unit - единица количества для вычитания, не null

Возвращает:

объект того же типа с вычтенным указанным периодом, не null

Издает:

DateTimeException - если единица не может быть вычтена

UnsupportedTemporalTypeException - если единица не поддерживается

ArithmeticException - если произошел переполнение числовых значений

query

default <R> R query(TemporalQuery<R> query)

Определено в:

query в интерфейсе TemporalAccessor

Параметры типа:

R - тип результата

Параметры:

query - вызываемый запрос, не null

Возвращает:

результат запроса, может быть null (определяется запросом)

Издает:

DateTimeException - если запрос невозможен (определяется запросом)

ArithmeticException - если произошел переполнение числовых значений (определяется запросом)

adjustInto

default Temporal adjustInto(Temporal temporal)

// these two lines are equivalent, but the second approach is recommended
   temporal = thisLocalDate.adjustInto(temporal);
   temporal = temporal.with(thisLocalDate);

Определено в:

adjustInto в интерфейсе TemporalAdjuster

Параметры:

temporal - целевой объект, который должен быть скорректирован, не null

Возвращает:

скорректированный объект, не null

Издает:

DateTimeException - если корректировка невозможна

ArithmeticException - если произошел переполнение числовых значений

until

long until(Temporal endExclusive,
           TemporalUnit unit)

// these two lines are equivalent
   amount = start.until(end, MONTHS);
   amount = MONTHS.between(start, end);

Определено в:

until в интерфейсе Temporal

Параметры:

endExclusive - конечная дата, исключая, которая преобразуется в ChronoLocalDate в той же хронологии, не null

unit - единица измерения количества, не null

Возвращает:

количество времени между этой датой и конечной датой

Издает:

DateTimeException - если количество не может быть рассчитано или конечная временная метка не может быть преобразована в ChronoLocalDate

UnsupportedTemporalTypeException - если единица не поддерживается

ArithmeticException - если произошел переполнение числовых значений

until

ChronoPeriod until(ChronoLocalDate endDateExclusive)

Параметры:

endDateExclusive - конечная дата, исключая, которая может быть в любой хронологии, не null

Возвращает:

период между этой датой и конечной датой, не null

Издает:

DateTimeException - если период не может быть рассчитан

ArithmeticException - если произошел переполнение числовых значений

format

default String format(DateTimeFormatter formatter)

return formatter.format(this);

Параметры:

formatter - форматировщик для использования, не null

Возвращает:

строка отформатированной даты, не null

Издает:

DateTimeException - если произошла ошибка во время печати

atTime

default ChronoLocalDateTime<?> atTime(LocalTime localTime)

Параметры:

localTime - локальное время для использования, не null

Возвращает:

локальное дата-время, сформированное из этой даты и указанного времени, не null

toEpochDay

default long toEpochDay()

Возвращает:

эквивалент этой даты в эпохальном дне

compareTo

default int compareTo(ChronoLocalDate other)

Определено в:

compareTo в интерфейсе Comparable<ChronoLocalDate>

Параметры:

other — другая дата для сравнения, не null

Возвращает:

значение компаратора, отрицательное, если меньше, положительное, если больше

isAfter

default boolean isAfter(ChronoLocalDate other)

Параметры:

other — другая дата для сравнения, не null

Возвращает:

true, если эта дата следует за указанной

isBefore

default boolean isBefore(ChronoLocalDate other)

Параметры:

other — другая дата для сравнения, не null

Возвращает:

true, если эта дата предшествует указанной

isEqual

default boolean isEqual(ChronoLocalDate other)

Параметры:

other — другая дата для сравнения, не null

Возвращает:

true, если базовая дата равна указанной дате

equals

boolean equals(Object obj)

Переопределяет:

equals в классе Object

Параметры:

obj — объект для проверки, null возвращает false

Возвращает:

true, если эта дата равна другой дате

См. также:

Object.hashCode(), HashMap

hashCode

int hashCode()

Хеш-код для этой даты.

Переопределяет:

hashCode в классе Object

Возвращает:

подходящий хеш-код

См. также:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

toString

String toString()

Переопределяет:

toString в классе Object

Возвращает:

отформатированную дату, не null