Интерфейс Temporal

Интерфейс на уровне фреймворка, определяющий чтение и запись доступа к объекту временной шкалы, такому как дата, время, смещение или их комбинации.

Это базовый тип интерфейса для объектов даты, времени и смещения, достаточно полных для манипуляций с помощью операций «плюс» и «минус». Он реализуется теми классами, которые могут предоставлять и обрабатывать информацию в виде полей или запросов. См. TemporalAccessor для чтения-только версии этого интерфейса.

Большая часть информации о дате и времени может быть представлена как число. Они моделируются с использованием TemporalField, а число хранится с помощью long для обработки больших значений. Год, месяц и день месяца являются простыми примерами полей, но они также включают мгновение и смещения. См. ChronoField для стандартного набора полей.

Две части информации о дате/времени не могут быть представлены числами: хронология и часовой пояс. К ним можно получить доступ через queries с помощью статических методов, определённых в TemporalQuery.

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

Когда следует реализовывать

Класс должен реализовывать этот интерфейс, если он соответствует трём критериям:

• он предоставляет доступ к информации о дате/времени/смещении, как указано в TemporalAccessor
• набор полей непрерывный от наибольшего к наименьшему
• набор полей полный, так что ни одно другое поле не требуется для определения допустимого диапазона значений для представленных полей

Четыре примера проясняют это:

• LocalDate реализует этот интерфейс, так как он представляет собой набор полей, непрерывных от дней до бесконечности и не требующих внешней информации для определения валидности каждой даты. Поэтому он может правильно реализовывать «плюс/минус».
• LocalTime реализует этот интерфейс, так как он представляет собой набор полей, непрерывных от наносекунд до дней и не требующих внешней информации для определения валидности. Он может правильно реализовывать «плюс/минус», переходя на следующий день.
• MonthDay, сочетание месяца и дня месяца, не реализует этот интерфейс. Хотя комбинация непрерывна, от дней до месяцев в годах, комбинация не содержит достаточной информации для определения допустимого диапазона значений для дня месяца. Поэтому он не может правильно реализовывать «плюс/минус».
• Комбинация дня недели и дня месяца («пятница 13-е») не должна реализовывать этот интерфейс. Она не представляет непрерывный набор полей, так как дни недели накладываются на дни в месяцах.

Методы

isSupported

boolean isSupported(TemporalUnit unit)

Требования к реализации:

Реализации должны проверить и обработать все единицы, определённые в ChronoUnit. Если единица поддерживается, то должно быть возвращено значение true, в противном случае - false.

Если поле не является ChronoUnit, то результат этого метода получается путём вызова TemporalUnit.isSupportedBy(Temporal) с this в качестве аргумента.

Реализации должны гарантировать, что при вызове этого метода только для чтения не изменяется состояние.

Параметры:

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

Возвращает:

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

with

default Temporal 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

Требования к реализации:

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

Реализация по умолчанию должна вести себя так же, как этот код:

return adjuster.adjustInto(this);

Параметры:

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

Возвращает:

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

Исключения:

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

ArithmeticException - если происходит переполнение чисел

with

Temporal with(TemporalField field,
              long newValue)

Требования к реализации:

Реализации должны проверить и обработать все поля, определённые в ChronoField. Если поле поддерживается, то выполняется корректировка. Если не поддерживается, то должно быть выброшено UnsupportedTemporalTypeException.

Если поле не является ChronoField, то результат этого метода получается путём вызова TemporalField.adjustInto(Temporal, long) с this в качестве первого аргумента.

Реализации не должны изменять этот объект. Вместо этого должен быть возвращён скорректированный экземпляр оригинала. Это обеспечивает эквивалентное, безопасное поведение для неизменяемых и изменяемых реализаций.

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

ArithmeticException - если происходит переполнение чисел

plus

default Temporal 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

Требования к реализации:

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

Реализация по умолчанию должна вести себя так же, как этот код:

return amount.addTo(this);

Параметры:

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

Возвращает:

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

Исключения:

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

ArithmeticException - если происходит переполнение чисел

plus

Temporal plus(long amountToAdd,
              TemporalUnit unit)

Требования к реализации:

Реализации должны проверить и обработать все единицы, определённые в ChronoUnit. Если единица поддерживается, то выполняется добавление. Если не поддерживается, то должно быть выброшено UnsupportedTemporalTypeException.

Если единица не является ChronoUnit, то результат этого метода получается путём вызова TemporalUnit.addTo(Temporal, long) с this в качестве первого аргумента.

Реализации не должны изменять этот объект. Вместо этого должен быть возвращён скорректированный экземпляр оригинала. Это обеспечивает эквивалентное, безопасное поведение для неизменяемых и изменяемых реализаций.

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

ArithmeticException - если происходит переполнение чисел

minus

default Temporal 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

Требования к реализации:

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

Реализация по умолчанию должна вести себя так же, как этот код:

return amount.subtractFrom(this);

Параметры:

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

Возвращает:

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

Исключения:

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

ArithmeticException - если происходит переполнение чисел

minus

default Temporal minus(long amountToSubtract,
                       TemporalUnit unit)

Требования к реализации:

Реализации должны вести себя так же, как реализация по умолчанию.

Реализации не должны изменять этот объект. Вместо этого должен быть возвращён скорректированный экземпляр оригинала. Это обеспечивает эквивалентное, безопасное поведение для неизменяемых и изменяемых реализаций.

Реализация по умолчанию должна вести себя так же, как этот код:

return (amountToSubtract == Long.MIN_VALUE ?
      plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));

Параметры:

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

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

Возвращает:

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

Исключения:

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

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

ArithmeticException - если происходит переполнение чисел

until

long until(Temporal endExclusive,
           TemporalUnit unit)

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

long daysBetween = start.until(end, DAYS);
  // or alternatively
  long daysBetween = DAYS.between(start, end);

Требования к реализации:

Реализации должны начинать с проверки, чтобы входной временной объект был того же наблюдаемого типа, что и реализация. Затем они должны выполнить вычисление для всех экземпляров ChronoUnit. Для UnsupportedTemporalTypeException экземпляров, которые не поддерживаются, должно быть выброшено исключение ChronoUnit.

Если единица измерения не является ChronoUnit, то результат этого метода получается путем вызова TemporalUnit.between(Temporal, Temporal), передав this в качестве первого аргумента и преобразованный входной временной объект в качестве второго аргумента.

Вкратце, реализации должны работать так же, как в этом псевдокоде:

// convert the end temporal to the same type as this class
  if (unit instanceof ChronoUnit) {
    // if unit is supported, then calculate and return result
    // else throw UnsupportedTemporalTypeException for unsupported units
  }
  return unit.between(this, convertedEndTemporal);

Обратите внимание, что метод between единицы должен вызываться только в том случае, если два временных объекта имеют ровно тот же тип, оцененный с помощью getClass().

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

Параметры:

endExclusive - конечный временной объект, исключающий, преобразованный в тот же тип, что и этот объект, не null

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

Возвращает:

количество времени между этим временным объектом и указанным в заданных единицах измерения; положительное, если указанный объект позже, отрицательное, если раньше

Исключения:

DateTimeException - если количество не может быть вычислено или конечный временной объект не может быть преобразован в тот же тип, что и этот временной объект

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

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