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

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

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

public interface Era extends TemporalAccessor, TemporalAdjuster

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

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

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

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

Требования к реализации:: Этот интерфейс должен быть реализован с осторожностью, чтобы обеспечить правильную работу других классов. Все реализации должны быть синглетонами — final, неизменяемыми и потокобезопасными. Рекомендуется использовать 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)

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

Это проверяет, можно ли запрашивать у этой эры указанное поле. Если false, то вызов методов 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, 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/chrono/Era.html