Интерфейс Эра

Все суперинтерфейсы:: TemporalAccessor, TemporalAdjuster

Все известные реализующие классы:: HijrahEra, IsoEra, JapaneseEra, MinguoEra, ThaiBuddhistEra

public interface Era extends TemporalAccessor, TemporalAdjuster

Эра на временной шкале.

Большинство систем календарей имеют одну эпоху, делящую временную шкалу на две эры. Однако некоторые системы календарей имеют несколько эр, например, по правлению каждого лидера. В любом случае, эра концептуально является самой большой единицей деления временной шкалы. Каждая хронология определяет известные эры и предоставляет Chronology.eras для получения допустимых эр.

Например, тайская буддийская система календарей делит время на две эры: до и после определённой даты. В свою очередь, японская система календарей имеет одну эру на правление каждого императора.

Экземпляры Era могут сравниваться с помощью оператора ==.

Требования к реализации:: Этот интерфейс должен быть реализован с осторожностью, чтобы обеспечить корректную работу других классов. Все реализации должны быть синглтонами - конечными, неизменяемыми и потокобезопасными. Рекомендуется использовать перечисление (enum), когда это возможно.
С:: 1.8

Краткое описание методов

Модификатор и тип	Метод	Описание
`default Temporal`	`adjustInto(Temporal temporal)`	Настраивает указанный временной объект так, чтобы он имел ту же эру, что и этот объект.
`default int`	`get(TemporalField field)`	Получает значение указанного поля из этой эры как `int`.
`default String`	`getDisplayName(TextStyle style, Locale locale)`	Получает текстовое представление этой эры.
`default long`	`getLong(TemporalField field)`	Получает значение указанного поля из этой эры как `long`.
`int`	`getValue()`	Получает числовое значение, связанное с эрой, как определено хронологией.
`default boolean`	`isSupported(TemporalField field)`	Проверяет, поддерживается ли указанное поле.
`default <R> R`	`query(TemporalQuery<R> query)`	Запрашивает эту эру с помощью указанного запроса.
`default ValueRange`	`range(TemporalField field)`	Получает диапазон допустимых значений для указанного поля.

Подробное описание методов

getValue

int getValue()

Получает числовое значение, связанное с эрой, определённой хронологией. Каждая хронология определяет предопределённые эры и методы для перечисления эр хронологии.

Все поля, включая эры, имеют связанное числовое значение. Значение числового значения для эры определяется хронологией в соответствии с этими принципами:

Эра, используемая в эпоху 1970-01-01 (ISO), имеет значение 1.
Поздние эры имеют последовательно более высокие значения.
Более ранние эры имеют последовательно более низкие значения, которые могут быть отрицательными.

Возвращает:: числовое значение эры

isSupported

default boolean isSupported(TemporalField field)

Проверяет, поддерживается ли указанное поле.

Это проверяет, может ли эта эра быть запрошена для указанного поля. Если ложно, то вызов методов range и get вызовет исключение.

Если поле является ChronoField, то запрос реализуется здесь. Поле ERA возвращает true. Все другие экземпляры ChronoField вернут false.

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

Указано в:: isSupported в интерфейсе TemporalAccessor
Параметры:: field - поле для проверки, null возвращает false
Возвращает:: true, если поле поддерживается в этой эре, false в противном случае

range

default ValueRange range(TemporalField field)

Получает диапазон допустимых значений для указанного поля.

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

Если поле является ChronoField, то запрос реализуется здесь. Поле ERA возвращает диапазон. Все другие экземпляры ChronoField выбросят UnsupportedTemporalTypeException.

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

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

Указано в:: range в интерфейсе TemporalAccessor
Параметры:: field - поле для запроса диапазона, не null
Возвращает:: диапазон допустимых значений для поля, не null
Исключение:: DateTimeException - если диапазон для поля получить невозможно; UnsupportedTemporalTypeException - если единица не поддерживается

get

default int get(TemporalField field)

Получает значение указанного поля из этой эры как int.

Запрашивает эту эру для значения указанного поля. Возвращаемое значение всегда будет в пределах допустимого диапазона значений для поля. Если невозможно вернуть значение, потому что поле не поддерживается или по какой-либо другой причине, выбрасывается исключение.

Если поле является ChronoField, то запрос реализуется здесь. Поле ERA возвращает значение эры. Все другие экземпляры ChronoField выбросят UnsupportedTemporalTypeException.

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

Указано в:: get в интерфейсе TemporalAccessor
Параметры:: field - поле для получения, не null
Возвращает:: значение для поля
Исключение:: DateTimeException - если значение для поля получить невозможно или значение находится за пределами диапазона допустимых значений для поля; UnsupportedTemporalTypeException - если поле не поддерживается или диапазон значений превышает int; ArithmeticException - если происходит переполнение числовых значений

getLong

default long getLong(TemporalField field)

Получает значение указанного поля из этой эры как long.

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

Указано в:: getLong в интерфейсе TemporalAccessor
Параметры:: field - поле для получения, не null
Возвращает:: значение для поля
Исключение:: DateTimeException - если значение для поля получить невозможно; UnsupportedTemporalTypeException - если поле не поддерживается; ArithmeticException - если происходит переполнение числовых значений

query

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

Запрашивает эту эру с помощью указанного запроса.

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

Результат этого метода получается путём вызова метода TemporalQuery.queryFrom(TemporalAccessor) на указанном запросе, передав this в качестве аргумента.

Указано в:: query в интерфейсе TemporalAccessor
Параметры типа:: R - тип результата
Параметры:: query - запрос для вызова, не null
Возвращает:: результат запроса, может быть возвращён null (определяется запросом)
Исключение:: DateTimeException - если запрос выполнить невозможно (определяется запросом); ArithmeticException - если происходит переполнение числовых значений (определяется запросом)

adjustInto

default Temporal adjustInto(Temporal temporal)

Изменяет указанный временной объект, чтобы он имел ту же эру, что и этот объект.

Возвращает временной объект того же наблюдаемого типа, что и входной, с эрой, изменённой на такую же, как эта.

Корректировка эквивалентна использованию Temporal.with(TemporalField, long) передавая ChronoField.ERA как поле.

В большинстве случаев, понятнее перевернуть порядок вызова, используя Temporal.with(TemporalAdjuster):

   // these two lines are equivalent, but the second approach is recommended
   temporal = thisEra.adjustInto(temporal);
   temporal = temporal.with(thisEra);

Этот экземпляр неизменяемый и не затрагивается этим вызовом метода.

Указано в:: adjustInto в интерфейсе TemporalAdjuster
Параметры:: temporal - целевой объект для корректировки, не null
Возвращает:: скорректированный объект, не null
Исключение:: DateTimeException - если корректировку выполнить невозможно; ArithmeticException - если происходит переполнение числовых значений

getDisplayName

default String getDisplayName(TextStyle style, Locale locale)

Получает текстовое представление этой эры.

Возвращает текстовое имя, используемое для идентификации эры, подходящее для представления пользователю. Параметры управляют стилем возвращаемого текста и языковым окружением.

Если текстовое отображение не найдено, то возвращается numeric value.

Примечание API:: Эта реализация по умолчанию подходит для большинства реализаций.
Параметры:: style - стиль требуемого текста, не null; locale - используемое языковое окружение, не null
Возвращает:: текстовое значение эры, не null

© 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/chrono/Era.html