Интерфейс TemporalAmount

Все известные подинтерфейсы:: ChronoPeriod

Все известные реализующие классы:: Duration, Period

public interface TemporalAmount

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

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

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

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

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

Требования к реализации:: Этот интерфейс не накладывает ограничений на изменчивость реализаций, но неизменяемость настоятельно рекомендуется.
С:: 1.8

Методы

Модификатор и тип	Метод	Описание
`Temporal`	`addTo(Temporal temporal)`	Добавляет к указанному временному объекту.
`long`	`get(TemporalUnit unit)`	Возвращает значение запрошенной единицы.
`List<TemporalUnit>`	`getUnits()`	Возвращает список единиц, однозначно определяющих значение этого TemporalAmount.
`Temporal`	`subtractFrom(Temporal temporal)`	Вычитает этот объект из указанного временного объекта.

Методы

get

long get(TemporalUnit unit)

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

Требования к реализации:: Реализации могут объявлять поддержку единиц, не указанных в getUnits(). Как правило, реализация определяет дополнительные единицы в качестве преобразований для удобства разработчиков.
Параметры:: unit - единица, для которой нужно вернуть значение
Возвращает:: значение единицы типа long
Выбрасывает:: DateTimeException - если значение для единицы получить невозможно; UnsupportedTemporalTypeException - если unit не поддерживается

getUnits

List<TemporalUnit> getUnits()

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

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

addTo

Temporal addTo(Temporal temporal)

Добавляет к указанному временному объекту.

Добавляет значение к указанному временному объекту, используя логику, заключённую в реализующем классе.

Существует два эквивалентных способа использования этого метода. Первый — вызвать этот метод напрямую. Второй — использовать Temporal.plus(TemporalAmount):

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

Рекомендуется использовать второй подход, plus(TemporalAmount), так как он намного понятнее в коде.

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

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

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

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

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

Параметры:

temporal - временной объект, к которому нужно добавить значение, не null

Возвращает:

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

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

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

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

subtractFrom

Temporal subtractFrom(Temporal temporal)

Вычитает этот объект из указанного временного объекта.

Вычитает значение из указанного временного объекта, используя логику, заключённую в реализующем классе.

Существует два эквивалентных способа использования этого метода. Первый — вызвать этот метод напрямую. Второй — использовать Temporal.minus(TemporalAmount):

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

Рекомендуется использовать второй подход, minus(TemporalAmount), так как он намного понятнее в коде.

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

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

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

Параметры:

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

Возвращает:

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

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

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

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