Интерфейс 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 |
Возвращает значение указанного поля в качестве int. |
long |
getLong |
Возвращает значение указанного поля в качестве long. |
boolean |
isSupported |
Проверяет, поддерживается ли указанное поле. |
default <R> R |
query |
Запрос для этой даты-времени. |
default ValueRange |
range |
Получение диапазона допустимых значений для указанного поля. |
Подробное описание методов
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(TemporalAccessor)с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.Если поле не является
ChronoField, то результат этого метода получается путем вызоваTemporalField.getFrom(TemporalAccessor)сthisв качестве аргумента.Реализации должны гарантировать, что при вызове этого только для чтения метода не изменяется состояние.
- Параметры:
-
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 могут избегать вызова super, если они обеспечивают поведение, эквивалентное поведению по умолчанию, однако классы не из JDK не могут использовать эту оптимизацию и должны вызыватьsuper.Если реализация может предоставить значение для одного из запросов, перечисленных в операторе if реализации по умолчанию, то она должна это сделать. Например, приложение-определенный класс
HourMin, хранящий час и минуты, должен переопределить этот метод следующим образом:if (query == TemporalQueries.precision()) { return MINUTES; } return TemporalAccessor.super.query(query);Реализации должны гарантировать, что при вызове этого только для чтения метода не изменяется состояние.
- Параметры типа:
-
R- тип результата - Параметры:
-
query- запрос для вызова, не null - Возвращает:
- результат запроса, может быть null (определяется запросом)
- Исключения:
-
DateTimeException- если запрос выполнить невозможно -
ArithmeticException- если происходит переполнение числовых типов
© 1993, 2023, 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/21/docs/api/java.base/java/time/temporal/TemporalAccessor.html