Spec-Zone.ru › OpenJDK 21

Интерфейс 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(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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API