Module java.base
Package java.time.chrono

Interface Chronology

所有超接口:
Comparable<Chronology>
所有已知实现类:
AbstractChronology, HijrahChronology, IsoChronology, JapaneseChronology, MinguoChronology, ThaiBuddhistChronology
public interface Chronology extends Comparable<Chronology>
一个日历系统，用于组织和识别日期。

主要的日期和时间API建立在ISO日历系统上。年表在幕后运行，以表示日历系统的一般概念。例如，日本、民国、泰国佛教等。

大多数其他日历系统也基于年、月和日的共享概念，与地球绕太阳、月亮绕地球的周期相关联。这些共享概念由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实例。日期类用于操作特定日期。

添加新日历

应用程序可以扩展可用的年表集。添加新的日历系统需要编写Chronology、ChronoLocalDate和Era的实现。与日历系统相关的大部分逻辑将在ChronoLocalDate实现中。Chronology实现充当工厂。

为了允许发现额外的年表，使用了ServiceLoader。必须向META-INF/services目录添加一个文件，名称为'java.time.chrono.Chronology'，列出实现类。有关服务加载的更多详细信息，请参见ServiceLoader。通过id或calendarType查找时，首先找到系统提供的日历，然后是应用程序提供的日历。

每个年表必须定义一个在系统内唯一的年表ID。如果年表代表由CLDR规范定义的日历系统，则日历类型是CLDR类型的串联，如果适用，则是CLDR变体。

实现要求:
必须小心实现此接口，以确保其他类能够正确运行。所有可实例化的实现必须是final、不可变且线程安全的。子类应尽可能可序列化。
自 JDK 版本:
1.8

  • Method Details

    • from

      static Chronology from(TemporalAccessor temporal)
      从时间对象获取Chronology的实例。

      此方法基于指定的时间获取年表。一个TemporalAccessor表示一组任意的日期和时间信息，此工厂将其转换为Chronology的实例。

      转换将使用TemporalQueries.chronology()获取年表。如果指定的时间对象没有年表，则返回IsoChronology。

      此方法与函数接口TemporalQuery的签名匹配，允许通过方法引用Chronology::from来使用它作为查询。

      参数:
      temporal - 要转换的时间，不能为空
      返回:
      年表，不能为空
      抛出:
      DateTimeException - 如果无法转换为Chronology

    • ofLocale

      static Chronology ofLocale(Locale locale)
      Obtains an instance of Chronology from a locale.

      This returns a Chronology based on the specified locale, typically returning IsoChronology. Other calendar systems are only returned if they are explicitly selected within the locale.

      The Locale class provide access to a range of information useful for localizing an application. This includes the language and region, such as "en-GB" for English as used in Great Britain.

      The Locale class also supports an extension mechanism that can be used to identify a calendar system. The mechanism is a form of key-value pairs, where the calendar system has the key "ca". For example, the locale "en-JP-u-ca-japanese" represents the English language as used in Japan with the Japanese calendar system.

      This method finds the desired calendar system in a manner equivalent to passing "ca" to Locale.getUnicodeLocaleType(String). If the "ca" key is not present, then IsoChronology is returned.

      Note that the behavior of this method differs from the older Calendar.getInstance(Locale) method. If that method receives a locale of "th_TH" it will return BuddhistCalendar. By contrast, this method will return IsoChronology. Passing the locale "th-TH-u-ca-buddhist" into either method will result in the Thai Buddhist calendar system and is therefore the recommended approach going forward for Thai calendar system localization.

      A similar, but simpler, situation occurs for the Japanese calendar system. The locale "jp_JP_JP" has previously been used to access the calendar. However, unlike the Thai locale, "ja_JP_JP" is automatically converted by Locale to the modern and recommended form of "ja-JP-u-ca-japanese". Thus, there is no difference in behavior between this method and Calendar#getInstance(Locale).

      Parameters:
      locale - the locale to use to obtain the calendar system, not null
      Returns:
      the calendar system associated with the locale, not null
      Throws:
      DateTimeException - if the locale-specified calendar cannot be found

    • of

      static Chronology of(String id)
      Obtains an instance of Chronology from a chronology ID or calendar system type.

      This returns a chronology based on either the ID or the type. The chronology ID uniquely identifies the chronology. The calendar system type is defined by the CLDR specification.

      The chronology may be a system chronology or a chronology provided by the application via ServiceLoader configuration.

      Since some calendars can be customized, the ID or type typically refers to the default customization. For example, the Gregorian calendar can have multiple cutover dates from the Julian, but the lookup only provides the default cutover date.

      Parameters:
      id - the chronology ID or calendar system type, not null
      Returns:
      the chronology with the identifier requested, not null
      Throws:
      DateTimeException - if the chronology cannot be found

    • getAvailableChronologies

      static Set<Chronology> getAvailableChronologies()
      Returns the available chronologies.

      Each returned Chronology is available for use in the system. The set of chronologies includes the system chronologies and any chronologies provided by the application via ServiceLoader configuration.

      Returns:
      the independent, modifiable set of the available chronology IDs, not null

    • getId

      String getId()
      Gets the ID of the chronology.

      The ID uniquely identifies the Chronology. It can be used to lookup the Chronology using of(String).

      Returns:
      the chronology ID, not null
      See Also:

    • getCalendarType

      String getCalendarType()
      Gets the calendar type of the calendar system.

      The calendar type is an identifier defined by the CLDR and Unicode Locale Data Markup Language (LDML) specifications to uniquely identify a calendar. The getCalendarType is the concatenation of the CLDR calendar type and the variant, if applicable, is appended separated by "-". The calendar type is used to lookup the Chronology using of(String).

      Returns:
      the calendar system type, null if the calendar is not defined by CLDR/LDML
      See Also:

    • date

      default ChronoLocalDate date(Era era, int yearOfEra, int month, int dayOfMonth)
      Obtains a local date in this chronology from the era, year-of-era, month-of-year and day-of-month fields.
      Implementation Requirements:
      The default implementation combines the era and year-of-era into a proleptic year before calling date(int, int, int).
      Parameters:
      era - the era of the correct type for the chronology, not null
      yearOfEra - the chronology year-of-era
      month - the chronology month-of-year
      dayOfMonth - the chronology day-of-month
      Returns:
      the local date in this chronology, not null
      Throws:
      DateTimeException - if unable to create the date
      ClassCastException - if the era is not of the correct type for the chronology

    • date

      ChronoLocalDate date(int prolepticYear, int month, int dayOfMonth)
      Obtains a local date in this chronology from the proleptic-year, month-of-year and day-of-month fields.
      Parameters:
      prolepticYear - the chronology proleptic-year
      month - the chronology month-of-year
      dayOfMonth - the chronology day-of-month
      Returns:
      the local date in this chronology, not null
      Throws:
      DateTimeException - if unable to create the date

    • dateYearDay

      default ChronoLocalDate dateYearDay(Era era, int yearOfEra, int dayOfYear)
      Obtains a local date in this chronology from the era, year-of-era and day-of-year fields.
      Implementation Requirements:
      The default implementation combines the era and year-of-era into a proleptic year before calling dateYearDay(int, int).
      Parameters:
      era - the era of the correct type for the chronology, not null
      yearOfEra - the chronology year-of-era
      dayOfYear - the chronology day-of-year
      Returns:
      the local date in this chronology, not null
      Throws:
      DateTimeException - if unable to create the date
      ClassCastException - if the era is not of the correct type for the chronology

    • dateYearDay

      ChronoLocalDate dateYearDay(int prolepticYear, int dayOfYear)
      Obtains a local date in this chronology from the proleptic-year and day-of-year fields.
      Parameters:
      prolepticYear - the chronology proleptic-year
      dayOfYear - the chronology day-of-year
      Returns:
      the local date in this chronology, not null
      Throws:
      DateTimeException - if unable to create the date

    • dateEpochDay

      ChronoLocalDate dateEpochDay(long epochDay)
      Obtains a local date in this chronology from the epoch-day.

      The definition of EPOCH_DAY is the same for all calendar systems, thus it can be used for conversion.

      Parameters:
      epochDay - the epoch day
      Returns:
      the local date in this chronology, not null
      Throws:
      DateTimeException - if unable to create the date

    • dateNow

      default ChronoLocalDate dateNow()
      Obtains the current local date in this chronology from the system clock in the default time-zone.

      This will query the system clock in the default time-zone to obtain the current date.

      Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.

      Implementation Requirements:
      The default implementation invokes dateNow(Clock).
      Returns:
      the current local date using the system clock and default time-zone, not null
      Throws:
      DateTimeException - if unable to create the date

    • dateNow

      default ChronoLocalDate dateNow(ZoneId zone)
      Obtains the current local date in this chronology from the system clock in the specified time-zone.

      This will query the system clock to obtain the current date. Specifying the time-zone avoids dependence on the default time-zone.

      Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.

      Implementation Requirements:
      The default implementation invokes dateNow(Clock).
      Parameters:
      zone - the zone ID to use, not null
      Returns:
      the current local date using the system clock, not null
      Throws:
      DateTimeException - if unable to create the date

    • dateNow

      default ChronoLocalDate dateNow(Clock clock)
      Obtains the current local date in this chronology from the specified clock.

      This will query the specified clock to obtain the current date - today. Using this method allows the use of an alternate clock for testing. The alternate clock may be introduced using dependency injection.

      实现要求:
      默认实现调用 date(TemporalAccessor)。
      参数:
      clock - 要使用的时钟，不能为空
      返回:
      当前本地日期，不能为空
      抛出:
      DateTimeException - 如果无法创建日期

    • date

      ChronoLocalDate date(TemporalAccessor temporal)
      从另一个时间对象中获取此年表中的本地日期。

      根据指定的时间获取此年表中的日期。 TemporalAccessor 表示一组任意的日期和时间信息，此工厂将其转换为 ChronoLocalDate 的实例。

      转换通常使用标准化的跨日字段 EPOCH_DAY，该字段在日历系统中是标准化的。

      此方法与函数接口 TemporalQuery 的签名匹配，允许通过方法引用 aChronology::date 使用它作为查询。

      参数:
      temporal - 要转换的时间对象，不能为空
      返回:
      此年表中的本地日期，不能为空
      抛出:
      DateTimeException - 如果无法创建日期
      参见:

    • localDateTime

      default ChronoLocalDateTime<? extends ChronoLocalDate> localDateTime(TemporalAccessor temporal)
      从另一个时间对象中获取此年表中的本地日期时间。

      根据指定的时间获取此年表中的日期时间。 TemporalAccessor 表示一组任意的日期和时间信息，此工厂将其转换为 ChronoLocalDateTime 的实例。

      转换从时间对象中提取并组合 ChronoLocalDate 和 LocalTime。 实现允许执行优化，例如访问等效于相关对象的字段。 结果使用此年表。

      此方法与函数接口 TemporalQuery 的签名匹配，允许通过方法引用 aChronology::localDateTime 使用它作为查询。

      参数:
      temporal - 要转换的时间对象，不能为空
      返回:
      此年表中的本地日期时间，不能为空
      抛出:
      DateTimeException - 如果无法创建日期时间
      参见:

    • zonedDateTime

      default ChronoZonedDateTime<? extends ChronoLocalDate> zonedDateTime(TemporalAccessor temporal)
      从另一个时间对象中获取此年表中的 ChronoZonedDateTime。

      根据指定的时间获取此年表中的分区日期时间。 TemporalAccessor 表示一组任意的日期和时间信息，此工厂将其转换为 ChronoZonedDateTime 的实例。

      转换将首先从时间对象中获取 ZoneId，必要时回退到 ZoneOffset。 然后尝试获取 Instant，必要时回退到 ChronoLocalDateTime。 结果将是 ZoneId 或 ZoneOffset 与 Instant 或 ChronoLocalDateTime 的组合。 实现允许执行优化，例如访问等效于相关对象的字段。 结果使用此年表。

      此方法与函数接口 TemporalQuery 的签名匹配，允许通过方法引用 aChronology::zonedDateTime 使用它作为查询。

      参数:
      temporal - 要转换的时间对象，不能为空
      返回:
      此年表中的分区日期时间，不能为空
      抛出:
      DateTimeException - 如果无法创建日期时间
      参见:

    • zonedDateTime

      default ChronoZonedDateTime<? extends ChronoLocalDate> zonedDateTime(Instant instant, ZoneId zone)
      从 Instant 中获取此年表中的 ChronoZonedDateTime。

      获取具有与指定时间相同的瞬时的分区日期时间。

      参数:
      instant - 从中创建日期时间的瞬时，不能为空
      zone - 时区，不能为空
      返回:
      分区日期时间，不能为空
      抛出:
      DateTimeException - 如果结果超出支持的范围

    • isLeapYear

      boolean isLeapYear(long prolepticYear)
      检查指定的年份是否为闰年。

      闰年是比正常年份长的一年。确切含义由年表根据以下约束确定。

      • 闰年必须意味着年份长度比非闰年长。
      • 不支持年份概念的年表必须返回 false。
      • 对于年表的有效年份范围内的所有年份，必须返回正确的结果。

      在有效年份范围之外，实现可以自由返回最佳猜测或 false。即使年份超出有效年份范围，实现也不得抛出异常。

      参数:
      prolepticYear - 要检查的纪年，未验证范围
      返回:
      如果年份是闰年，则为 true

    • prolepticYear

      int prolepticYear(Era era, int yearOfEra)
      根据纪元和纪元年计算纪年。

      将纪元和纪元年合并为单个纪年字段。

      如果年表积极使用纪元，例如 JapaneseChronology，则将根据纪元验证纪元年。对于其他年表，验证是可选的。

      参数:
      era - 适合年表的纪元，不能为空
      yearOfEra - 年表纪元年
      返回:
      纪年
      抛出:
      DateTimeException - 如果无法转换为纪年，例如如果年份对于纪元无效
      ClassCastException - 如果 era 不是适合年表的正确类型

    • eraOf

      Era eraOf(int eraValue)
      从数字值创建年表纪元对象。

      纪元在概念上是时间线的最大划分。大多数日历系统有一个单一的时代将时间线分为两个时代。但是，有些日历系统有多个时代，例如每位领导人的统治一个时代。确切含义由年表根据以下约束确定。

      在 1970-01-01 使用的时代必须具有值 1。后续时代必须具有依次更高的值。较早的时代必须具有依次更低的值。每个年表必须引用一个枚举或类似的单例以提供时代值。

      此方法返回指定时代值的正确类型的单例时代。

      参数:
      eraValue - 时代值
      返回:
      日历系统时代，不能为空
      抛出:
      DateTimeException - 如果无法创建时代

    • eras

      List<Era> eras()
      获取年表的时代列表。

      大多数日历系统有一个时代，其中年份具有意义。如果日历系统不支持时代概念，则必须返回空列表。

      返回:
      年表的时代列表，可能是不可变的，不能为空

    • range

      ValueRange range(ChronoField field)
      获取指定字段的有效值范围。

      所有字段都可以表示为 long 整数。此方法返回描述该值的有效范围的对象。

      请注意，结果仅描述最小和最大有效值，重要的是不要读取太多内容。例如，范围内可能存在对于字段无效的值。

      无论年表是否支持该字段，此方法都将返回结果。

      参数:
      field - 要获取范围的字段，不能为空
      返回:
      字段的有效值范围，不能为空
      抛出:
      DateTimeException - 如果无法获取字段的范围

    • getDisplayName

      default String getDisplayName(TextStyle style, Locale locale)
      获取此年表的文本表示。

      返回用于标识年表的文本名称，适合向用户展示。参数控制返回文本的样式和区域设置。

      实现要求:
      默认实现的行为就像使用格式化程序格式化年表文本名称一样。
      参数:
      style - 所需文本的样式，不能为空
      locale - 要使用的区域设置，不能为空
      返回:
      年表的文本值，不能为空

    • resolveDate

      ChronoLocalDate resolveDate(Map<TemporalField,Long> fieldValues, ResolverStyle resolverStyle)
      将解析的 ChronoField 值解析为解析期间的日期。

      大多数 TemporalField 实现使用字段的解析方法进行解析。相比之下，ChronoField 类定义的字段仅相对于年表具有意义。因此，在特定年表的上下文中，在此处解析 ChronoField 日期字段。

      提供了默认实现，解释了典型的解析行为，提供在 AbstractChronology 中。

      参数:
      fieldValues - 字段到值的映射，可以更新，不能为空
      resolverStyle - 请求的解析类型，不能为空
      返回:
      解析后的日期，如果信息不足无法创建日期则返回null
      抛出:
      DateTimeException - 如果无法解析日期，通常是因为输入数据冲突

    • period

      default ChronoPeriod period(int years, int months, int days)
      基于年、月和日获取此年表的期间。

      使用指定的年、月和日返回与此年表相关联的期间。所有提供的年表都使用基于年、月和日的期间，但是ChronoPeriod API允许使用其他单位表示期间。

      实现要求:
      默认实现返回适用于大多数日历系统的实现类。它仅基于这三个单位。规范化、加法和减法从range(ChronoField)中获取一年中的月数。如果一年中的月数固定，则加法、减法和规范化的计算方法略有不同。

      如果实现的是不基于年、月和日的不寻常日历系统，或者您想要直接控制，则必须直接实现ChronoPeriod接口。

      返回的期间是不可变且线程安全的。

      参数:
      years - 年数，可以为负数
      months - 月数，可以为负数
      days - 天数，可以为负数
      返回:
      以此年表为单位的期间，不能为空

    • epochSecond

      default long epochSecond(int prolepticYear, int month, int dayOfMonth, int hour, int minute, int second, ZoneOffset zoneOffset)
      获取从1970-01-01T00:00:00Z时代开始的秒数。

      秒数是使用历元年、月、日、小时、分钟、秒和区偏移计算的。

      参数:
      prolepticYear - 年表历元年
      month - 年表年中的月份
      dayOfMonth - 年表月中的日期
      hour - 小时，从0到23
      minute - 分钟，从0到59
      second - 秒，从0到59
      zoneOffset - 区偏移，不能为空
      返回:
      相对于1970-01-01T00:00:00Z的秒数，可以为负数
      抛出:
      DateTimeException - 如果任何值超出范围
      自:
      9

    • epochSecond

      default long epochSecond(Era era, int yearOfEra, int month, int dayOfMonth, int hour, int minute, int second, ZoneOffset zoneOffset)
      获取从1970-01-01T00:00:00Z时代开始的秒数。

      秒数是使用纪元、纪元年、月、日、小时、分钟、秒和区偏移计算的。

      参数:
      era - 适合该年表的纪元，不能为空
      yearOfEra - 年表纪元年
      month - 年表年中的月份
      dayOfMonth - 年表月中的日期
      hour - 小时，从0到23
      minute - 分钟，从0到59
      second - 秒，从0到59
      zoneOffset - 区偏移，不能为空
      返回:
      相对于1970-01-01T00:00:00Z的秒数，可以为负数
      抛出:
      DateTimeException - 如果任何值超出范围
      自:
      9

    • isIsoBased

      default boolean isIsoBased()
      检查此年表是否基于ISO。

      基于ISO的年表具有与ISO年表相同的基本结构，即年表具有相同数量的月份，每个月的天数，以及一年中的日期和闰年与ISO年表相同。它还支持ISO年表的基于周的年份概念。例如，Minguo、ThaiBuddhist和Japanese年表都是基于ISO的。

      实现要求:
      默认实现返回false。
      返回:
      仅当此年表支持IsoFields的所有字段时返回true。否则返回false。
      自:
      19
      参见:

    • compareTo

      int compareTo(Chronology other)
      将此年表与另一个年表进行比较。

      比较顺序首先按年表ID字符串，然后按子类特定的任何其他信息。它符合Comparable定义的"与equals一致"。

      指定者:
      compareTo 在接口 Comparable<Chronology>
      参数:
      other - 要比较的另一个年表，不能为空
      返回:
      比较器值，即将此ID字符串与other的ID字符串进行比较，除非ID字符串相等且年表使用其他信息区分实例

    • equals

      boolean equals(Object obj)
      检查此年表是否等于另一个年表。

      比较基于对象的整个状态。

      覆盖:
      equals 在类 Object
      参数:
      obj - 要检查的对象，null返回false
      返回:
      如果此年表等于另一个年表则返回true
      参见:

    • hashCode

      int hashCode()
      此年表的哈希码。

      哈希码应基于对象的整个状态。

      覆盖:
      hashCode 在类 Object
      返回:
      适当的哈希码
      参见:

    • toString

      String toString()
      将此年表输出为String。

      格式应包括对象的整个状态。

      覆盖:
      toString 在类 Object
      返回:
      此年表的字符串表示，不能为空