Интерфейс 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, 2021, 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/17/docs/api/java.base/java/time/temporal/TemporalAccessor.html