Интерфейс TemporalAmount

Интерфейс на уровне фреймворка, определяющий количество времени, например, "6 часов", "8 дней" или "2 года и 3 месяца".

Это базовый интерфейсный тип для количества времени. Количество отличается от даты или времени суток тем, что оно не привязано к какой-либо конкретной точке на временной шкале.

Количество можно рассматривать как Map TemporalUnit до long, доступные через getUnits() и get(TemporalUnit). Простой случай может иметь одну пару значение-единица, например, "6 часов". Более сложный случай может иметь несколько пар значение-единица, например, "7 лет, 3 месяца и 5 дней".

Существует две распространённые реализации. Period — это реализация, основанная на дате, хранящая годы, месяцы и дни. Duration — это реализация, основанная на времени, хранящая секунды и наносекунды, но предоставляющая некоторый доступ с использованием других единиц, основанных на продолжительности, таких как минуты, часы и фиксированные 24-часовые дни.

Этот интерфейс является интерфейсом на уровне фреймворка, который не следует широко использовать в коде приложения. Вместо этого приложения должны создавать и передавать экземпляры конкретных типов, таких как Period и Duration.

Методы

get

long get(TemporalUnit unit)

Возвращает значение запрошенной единицы. Единицы, возвращаемые из getUnits(), однозначно определяют значение TemporalAmount. Значение должно быть возвращено для каждой единицы, указанной в getUnits.

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

Реализации могут объявлять поддержку единиц, не указанных в getUnits(). Как правило, реализация определяет дополнительные единицы как преобразования для удобства разработчиков.

Параметры:

unit - TemporalUnit, для которого требуется вернуть значение

Возвращает:

значение типа long для единицы

Исключение:

DateTimeException - если значение для единицы получить невозможно

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

getUnits

List<TemporalUnit> getUnits()

Возвращает список единиц, однозначно определяющих значение этого TemporalAmount. Список TemporalUnits определяется классом реализации. Список является мгновенным снимком единиц на момент вызова getUnits и не является изменяемым. Единицы упорядочены от самой большой продолжительности к самой маленькой продолжительности единицы.

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

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

Возвращает:

список TemporalUnits; не null

addTo

Temporal addTo(Temporal temporal)

// These two lines are equivalent, but the second approach is recommended
   dateTime = amount.addTo(dateTime);
   dateTime = dateTime.plus(adder);

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

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

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

Входной временной объект может быть в другой системе календаря, кроме ISO. Реализации могут выбрать документирование совместимости с другими системами календаря или отклонение не-ISO временных объектов с помощью querying the chronology.

Этот метод может вызываться из нескольких потоков параллельно. Он должен быть потокобезопасным при вызове.

Параметры:

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

Возвращает:

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

Исключение:

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

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

subtractFrom

Temporal subtractFrom(Temporal temporal)

// these two lines are equivalent, but the second approach is recommended
   dateTime = amount.subtractFrom(dateTime);
   dateTime = dateTime.minus(amount);

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

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

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

Входной временной объект может быть в другой системе календаря, кроме ISO. Реализации могут выбрать документирование совместимости с другими системами календаря или отклонение не-ISO временных объектов с помощью querying the chronology.

Этот метод может вызываться из нескольких потоков параллельно. Он должен быть потокобезопасным при вызове.

Параметры:

temporal - временной объект, из которого вычитается количество, не null

Возвращает:

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

Исключение:

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

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