Интерфейс TemporalAccessor

Все известные подинтерфейсы:: ChronoLocalDate, ChronoLocalDateTime<D>, ChronoZonedDateTime<D>, Era, Temporal

Все известные реализующие классы:: DayOfWeek, HijrahDate, HijrahEra, Instant, IsoEra, JapaneseDate, JapaneseEra, LocalDate, LocalDateTime, LocalTime, MinguoDate, MinguoEra, Month, MonthDay, OffsetDateTime, OffsetTime, ThaiBuddhistDate, ThaiBuddhistEra, Year, YearMonth, ZonedDateTime, ZoneOffset

public interface TemporalAccessor

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

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

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

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

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

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

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

Методы

Модификатор и тип	Метод	Описание
`default int`	`get(TemporalField field)`	Возвращает значение указанного поля в виде `int`.
`long`	`getLong(TemporalField field)`	Возвращает значение указанного поля в виде `long`.
`boolean`	`isSupported(TemporalField field)`	Проверяет, поддерживается ли указанное поле.
`default <R> R`	`query(TemporalQuery<R> query)`	Запрашивает это время и дату.
`default ValueRange`	`range(TemporalField field)`	Возвращает диапазон допустимых значений для указанного поля.

Методы

isSupported

boolean isSupported(TemporalField field)

Проверяет, поддерживается ли указанное поле.

Это проверяет, можно ли запросить у даты-времени указанное поле. Если false, то вызов методов range и get вызовет исключение.

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

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

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

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

Параметры:

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

Возвращает:

true, если эта дата-время может быть запрошена для поля, false – в противном случае

range

default ValueRange range(TemporalField field)

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

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

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

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

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

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

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

Реализация по умолчанию должна иметь эквивалентный код:

if (field instanceof ChronoField) {
    if (isSupported(field)) {
      return field.range();
    }
    throw new UnsupportedTemporalTypeException("Unsupported field: " + field);
  }
  return field.rangeRefinedBy(this);

Параметры:

field - поле для запроса диапазона, не null

Возвращает:

диапазон допустимых значений для поля, не null

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

DateTimeException - если диапазон для поля получить нельзя

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

get

default int get(TemporalField field)

Возвращает значение указанного поля в виде int.

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

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

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

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

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

Реализация по умолчанию должна иметь эквивалентный код:

if (range(field).isIntValue()) {
    return range(field).checkValidIntValue(getLong(field), field);
  }
  throw new UnsupportedTemporalTypeException("Invalid field " + field + " + for get() method, use getLong() instead");

Параметры:

field - поле для получения, не null

Возвращает:

значение для поля, в пределах допустимого диапазона значений

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

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

UnsupportedTemporalTypeException - если поле не поддерживается или диапазон значений превышает int

ArithmeticException - если произошел переполнение

getLong

long getLong(TemporalField field)

Возвращает значение указанного поля в виде long.

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

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

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

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

Параметры:

field - поле для получения, не null

Возвращает:

значение для поля

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

DateTimeException - если значение для поля получить нельзя

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

ArithmeticException - если произошел переполнение

query

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

Запрос к этой дате-времени.

Этот запрос к этой дате-времени с использованием указанного объекта стратегии запроса.

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

Наиболее распространённые реализации запросов – ссылки на методы, такие как LocalDate::from и ZoneId::from. Дополнительные реализации предоставляются как статические методы в TemporalQuery.

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

Реализация по умолчанию должна иметь эквивалентный код:

if (query == TemporalQueries.zoneId() ||
        query == TemporalQueries.chronology() || query == TemporalQueries.precision()) {
    return null;
  }
  return query.queryFrom(this);

Будущие версии могут добавить дополнительные запросы в оператор if.

Все классы, реализующие этот интерфейс и переопределяющие этот метод, должны вызывать TemporalAccessor.super.query(query). Классы JDK могут избегать вызова супер, если они обеспечивают поведение, эквивалентное поведению по умолчанию, но вне-JDK классы не могут использовать эту оптимизацию и должны вызывать super.

Если реализация может предоставить значение для одного из запросов, указанных в операторе if реализации по умолчанию, то она должна это сделать. Например, класс HourMin, определенный пользователем, хранящий час и минуту, должен переопределить этот метод следующим образом:

if (query == TemporalQueries.precision()) {
    return MINUTES;
  }
  return TemporalAccessor.super.query(query);

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

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

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

Параметры:

query - запрос для вызова, не null

Возвращает:

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

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

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

ArithmeticException - если произошел переполнение

© 1993, 2020, 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/11/docs/api/java.base/java/time/temporal/TemporalAccessor.html