Spec-Zone.ru › OpenJDK 17

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

Spec-Zone.ru

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