Интерфейс TemporalAccessor

public interface TemporalAccessor

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

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

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

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

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

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

Методы

isSupported

boolean isSupported(TemporalField field)

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

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

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

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

Параметры:

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

Возвращает:

true, если эту дату-время можно запросить для поля, false — если нет

range

default ValueRange range(TemporalField field)

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

Реализации должны проверять и обрабатывать все поля, определённые в 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)

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

Реализации должны проверять и обрабатывать все поля, определённые в 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)

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

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

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

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

Параметры:

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

Возвращает:

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

Исключения:

DateTimeException — если значение для поля получить невозможно

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

ArithmeticException — если произошел переполнение целочисленной переменной

query

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

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

Реализация по умолчанию должна вести себя эквивалентно следующему коду:

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 — если произошел переполнение целочисленной переменной