Интерфейс Chronology

public interface Chronology
extends Comparable<Chronology>

Система календаря, используемая для организации и идентификации дат.

Основной API дат и времени построен на системе календаря ISO. Chronology работает за кулисами, чтобы представить общее понятие системы календаря. Например, японской, Minguo, тайской буддийской и других.

Большинство других систем календаря также основаны на общих понятиях года, месяца и дня, связанных с циклами вращения Земли вокруг Солнца и Луны вокруг Земли. Эти общие понятия определяются ChronoField и доступны для использования любой Chronology реализацией:

LocalDate isoDate = ...
   ThaiBuddhistDate thaiDate = ...
   int isoYear = isoDate.get(ChronoField.YEAR);
   int thaiYear = thaiDate.get(ChronoField.YEAR);

Как показано, хотя объекты даты находятся в разных системах календаря, представленных разными Chronology экземплярами, оба могут быть запрошены с помощью одного и того же константы в ChronoField. Для более полного обсуждения последствий этого, см. ChronoLocalDate. В общем, рекомендуется использовать известную ISO-базированную LocalDate, а не ChronoLocalDate.

Хотя объект Chronology обычно использует ChronoField и основан на модели даты эпохи, года эпохи, месяца и дня, это не является обязательным. Экземпляр Chronology может представлять совершенно другую систему календаря, например, майянскую.

Практически экземпляр Chronology также действует как фабрика. Метод of(String) позволяет получить экземпляр по идентификатору, а метод ofLocale(Locale) позволяет поиск по локали.

Экземпляр Chronology предоставляет набор методов для создания экземпляров ChronoLocalDate. Классы дат используются для работы со специфическими датами.

• dateNow()
• dateNow(clock)
• dateNow(zone)
• date(yearProleptic, month, day)
• date(era, yearOfEra, month, day)
• dateYearDay(yearProleptic, dayOfYear)
• dateYearDay(era, yearOfEra, dayOfYear)
• date(TemporalAccessor)

Добавление новых календарей

Набор доступных хронологий может быть расширен приложениями. Добавление новой системы календаря требует написания реализации Chronology, ChronoLocalDate и Era. Большая часть логики, специфичной для системы календаря, будет в реализации ChronoLocalDate. Реализация Chronology действует как фабрика.

Чтобы обеспечить обнаружение дополнительных хронологий, используется ServiceLoader. Файл должен быть добавлен в каталог META-INF/services с именем 'java.time.chrono.Chronology', перечисляющий классы реализации. См. ServiceLoader для получения дополнительной информации о загрузке сервисов. Для поиска по идентификатору или типу календаря сначала находятся предоставленные системой календари, а затем предоставленные приложением.

Каждая хронология должна определить идентификатор хронологии, уникальный в системе. Если хронология представляет систему календаря, определенную спецификацией CLDR, то тип календаря представляет собой конкатенацию типа CLDR и, при необходимости, варианта CLDR.

Методы

from

static Chronology from(TemporalAccessor temporal)

Параметры:

temporal - преобразуемый временной объект, не null

Возвращает:

хронологию, не null

Исключения:

DateTimeException - если невозможно преобразовать во временную Chronology

ofLocale

static Chronology ofLocale(Locale locale)

Параметры:

locale - локаль для получения календарной системы, не null

Возвращает:

календарная система, связанная с локалью, не null

Исключения:

DateTimeException - если календарь, заданный локалью, не найден

of

static Chronology of(String id)

Параметры:

id - идентификатор хронологии или тип календарной системы, не null

Возвращает:

хронология с запрошенным идентификатором, не null

Исключения:

DateTimeException - если хронология не найдена

getAvailableChronologies

static Set<Chronology> getAvailableChronologies()

Возвращает:

независимый, изменяемый набор доступных идентификаторов хронологии, не null

getId

String getId()

Возвращает:

идентификатор хронологии, не null

См. также:

getCalendarType()

getCalendarType

String getCalendarType()

Возвращает:

тип календарной системы, null если календарь не определен CLDR/LDML

См. также:

getId()

date

default ChronoLocalDate date(Era era,
                             int yearOfEra,
                             int month,
                             int dayOfMonth)

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

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

Стандартная реализация объединяет эпоху и год в эпоху в пролептический год перед вызовом date(int, int, int).

Параметры:

era - эпоха правильного типа для хронологии, не null

yearOfEra - год в эпохе

month - месяц

dayOfMonth - день

Возвращает:

локальную дату в этой хронологии, не null

Исключения:

DateTimeException - если дату создать невозможно

ClassCastException - если эпоха не соответствует типу хронологии

date

ChronoLocalDate date(int prolepticYear,
                     int month,
                     int dayOfMonth)

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

Параметры:

prolepticYear - пролептический год

month - месяц

dayOfMonth - день

Возвращает:

локальную дату в этой хронологии, не null

Исключения:

DateTimeException - если дату создать невозможно

dateYearDay

default ChronoLocalDate dateYearDay(Era era,
                                    int yearOfEra,
                                    int dayOfYear)

Получает локальную дату в этой хронологии из эпохи, года в эпохе и дня года.

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

Стандартная реализация объединяет эпоху и год в эпоху в пролептический год перед вызовом dateYearDay(int, int).

Параметры:

era - эпоха правильного типа для хронологии, не null

yearOfEra - год в эпохе

dayOfYear - день года

Возвращает:

локальную дату в этой хронологии, не null

Исключения:

DateTimeException - если дату создать невозможно

ClassCastException - если эпоха не соответствует типу хронологии

dateYearDay

ChronoLocalDate dateYearDay(int prolepticYear,
                            int dayOfYear)

Получает локальную дату в этой хронологии из пролептического года и дня года.

Параметры:

prolepticYear - пролептический год

dayOfYear - день года

Возвращает:

локальную дату в этой хронологии, не null

Исключения:

DateTimeException - если дату создать невозможно

dateEpochDay

ChronoLocalDate dateEpochDay(long epochDay)

Параметры:

epochDay - день эпохи

Возвращает:

локальную дату в этой хронологии, не null

Исключения:

DateTimeException - если дату создать невозможно

dateNow

default ChronoLocalDate dateNow()

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

Стандартная реализация вызывает dateNow(Clock).

Возвращает:

текущую локальную дату с использованием системных часов и часового пояса по умолчанию, не null

Исключения:

DateTimeException - если дату создать невозможно

dateNow

default ChronoLocalDate dateNow(ZoneId zone)

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

Стандартная реализация вызывает dateNow(Clock).

Параметры:

zone - используемый часовой пояс, не null

Возвращает:

текущую локальную дату с использованием системных часов, не null

Исключения:

DateTimeException - если дату создать невозможно

dateNow

default ChronoLocalDate dateNow(Clock clock)

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

Стандартная реализация вызывает date(TemporalAccessor).

Параметры:

clock - используемый объект Clock, не null

Возвращает:

текущую локальную дату, не null

Исключения:

DateTimeException - если дата не может быть создана

date

ChronoLocalDate date(TemporalAccessor temporal)

Параметры:

temporal - временной объект для преобразования, не null

Возвращает:

локальную дату в этой хронологии, не null

Исключения:

DateTimeException - если дата не может быть создана

См. также:

ChronoLocalDate.from(TemporalAccessor)

localDateTime

default ChronoLocalDateTime<? extends ChronoLocalDate> localDateTime(TemporalAccessor temporal)

Параметры:

temporal - временной объект для преобразования, не null

Возвращает:

локальное время и дату в этой хронологии, не null

Исключения:

DateTimeException - если время и дата не могут быть созданы

См. также:

ChronoLocalDateTime.from(TemporalAccessor)

zonedDateTime

default ChronoZonedDateTime<? extends ChronoLocalDate> zonedDateTime(TemporalAccessor temporal)

Параметры:

temporal - временной объект для преобразования, не null

Возвращает:

временную зону с датой и временем в этой хронологии, не null

Исключения:

DateTimeException - если время и дата не могут быть созданы

См. также:

ChronoZonedDateTime.from(TemporalAccessor)

zonedDateTime

default ChronoZonedDateTime<? extends ChronoLocalDate> zonedDateTime(Instant instant,
                                                                     ZoneId zone)

Параметры:

instant - мгновение времени для создания времени и даты, не null

zone - часовой пояс, не null

Возвращает:

временную зону с датой и временем, не null

Исключения:

DateTimeException - если результат выходит за поддерживаемый диапазон

isLeapYear

boolean isLeapYear(long prolepticYear)

Параметры:

prolepticYear - пролептический год для проверки, не валидируется по диапазону

Возвращает:

true, если год високосный

prolepticYear

int prolepticYear(Era era,
                  int yearOfEra)

Параметры:

era - эра правильного типа для хронологии, не null

yearOfEra - год хронологической эры

Возвращает:

пролептический год

Исключения:

DateTimeException - если пролептический год не может быть преобразован, например, если год недействителен для эры

ClassCastException - если era не является правильного типа для хронологии

eraOf

Era eraOf(int eraValue)

Параметры:

eraValue - значение эры

Возвращает:

эра календарной системы, не null

Исключения:

DateTimeException - если эра не может быть создана

eras

List<Era> eras()

Возвращает:

список эр для хронологии, может быть неизменяемым, не null

range

ValueRange range(ChronoField field)

Параметры:

field - поле, для которого нужно получить диапазон, не null

Возвращает:

диапазон допустимых значений для поля, не null

Исключения:

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

getDisplayName

default String getDisplayName(TextStyle style,
                              Locale locale)

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

Стандартная реализация ведет себя так, как будто форматировщик использовался для форматирования текстового имени хронологии.

Параметры:

style - требуемый стиль текста, не null

locale - используемый язык, не null

Возвращает:

текстовое значение хронологии, не null

resolveDate

ChronoLocalDate resolveDate(Map<TemporalField,Long> fieldValues,
                            ResolverStyle resolverStyle)

Параметры:

fieldValues - карта полей и значений, которую можно обновить, не null

resolverStyle - требуемый тип разрешения, не null

Возвращает:

разрешенная дата, null, если информации недостаточно для создания даты

Исключения:

DateTimeException - если дата не может быть разрешена, обычно из-за конфликта в входных данных

period

default ChronoPeriod period(int years,
                            int months,
                            int days)

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

Базовая реализация возвращает класс реализации, подходящий для большинства систем календарей. Он основан только на трех единицах. Нормализация, сложение и вычитание определяют количество месяцев в году из range(ChronoField). Если количество месяцев в году фиксировано, то подход к вычислениям при сложении, вычитании и нормализации немного отличается.

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

Возвращаемый период неизменяемый и потокобезопасный.

Параметры:

years - количество лет, может быть отрицательным

months - количество месяцев, может быть отрицательным

days - количество дней, может быть отрицательным

Возвращает:

период в терминах этой хронологии, не null

compareTo

int compareTo(Chronology other)

Определено в:

compareTo в интерфейсе Comparable<Chronology>

Параметры:

other - другая хронология для сравнения, не null

Возвращает:

значение сравнения, отрицательное, если меньше, положительное, если больше

equals

boolean equals(Object obj)

Переопределяет:

equals в классе Object

Параметры:

obj - объект для проверки, null возвращает false

Возвращает:

true, если эта хронология равна другой хронологии

См. также:

Object.hashCode(), HashMap

hashCode

int hashCode()

Переопределяет:

hashCode в классе Object

Возвращает:

подходящий хеш-код

См. также:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

toString

String toString()

Переопределяет:

toString в классе Object

Возвращает:

строковое представление этой хронологии, не null