模块 java.base

接口 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) 方法允许通过locale查找。

Chronology 实例提供了一组创建 ChronoLocalDate 实例的方法。日期类用于操作特定日期。

添加新日历

可用的年表集可以通过应用程序进行扩展。添加新的日历系统需要编写 ChronologyChronoLocalDateEra 的实现。特定于日历系统的大部分逻辑将在 ChronoLocalDate 实现中。 Chronology 实现充当工厂。

为了允许发现其他年表,使用了 ServiceLoader 。必须将一个名为“java.time.chrono.Chronology”的文件添加到 META-INF/services 目录,其中列出了实现类。有关服务加载的更多详细信息,请参阅 ServiceLoader。对于按 id 或 calendarType 查找,首先找到系统提供的日历,然后是应用程序提供的日历。

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

实现要求:
必须小心实现此接口以确保其他类正确运行。所有可以实例化的实现都必须是最终的、不可变的和线程安全的。只要有可能,子类就应该是可序列化的。
自从:
1.8
  • 方法详情

    • from

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

      这将根据指定的时间获得年表。 TemporalAccessor 表示一组任意的日期和时间信息,该工厂将其转换为 Chronology 的一个实例。

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

      此方法与功能接口 TemporalQuery 的签名相匹配,允许它通过方法引用 Chronology::from 用作查询。

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

      static Chronology  ofLocale(Locale  locale)
      从locale中获取 Chronology 的实例。

      这会根据指定的locale返回 Chronology,通常会返回 IsoChronology。只有在locale中明确选择了其他日历系统,才会返回它们。

      Locale 类提供对一系列对本地化应用程序有用的信息的访问。这包括语言和地区,例如英国使用的英语的“en-GB”。

      Locale 类还支持可用于识别日历系统的扩展机制。该机制是一种键值对形式,其中日历系统具有键“ca”。例如,区域设置“en-JP-u-ca-japanese”表示日本使用日本日历系统的英语。

      此方法以等同于将“ca”传递给 Locale.getUnicodeLocaleType(String) 的方式找到所需的日历系统。如果“ca”键不存在,则返回IsoChronology

      请注意,此方法的行为不同于旧的 Calendar.getInstance(Locale) 方法。如果该方法接收到“th_TH”的locale,它将返回 BuddhistCalendar 。相比之下,此方法将返回 IsoChronology 。将locale“th-TH-u-ca-buddhist”传递到任何一种方法都将导致泰国佛教日历系统,因此是泰国日历系统本地化的推荐方法。

      日本历法系统也有类似但更简单的情况。区域设置“jp_JP_JP”以前曾用于访问日历。然而,与泰语locale不同的是,“ja_JP_JP”会被 Locale 自动转换为“ja-JP-u-ca-japanese”的现代推荐形式。因此,此方法与 Calendar#getInstance(Locale) 之间的行为没有区别。

      参数:
      locale - 用于获取日历系统的locale,不为空
      返回:
      与locale关联的日历系统,不为空
      抛出:
      DateTimeException - 如果找不到区域指定的日历
    • of

      static Chronology  of(String  id)
      从年表 ID 或日历系统类型中获取 Chronology 的实例。

      这将返回基于 ID 或类型的年表。 chronology ID 唯一标识年表。 calendar system type 由 CLDR 规范定义。

      年表可以是系统年表或应用程序通过 ServiceLoader 配置提供的年表。

      由于某些日历可以自定义,因此 ID 或类型通常指的是默认自定义。例如,Gregorian 日历可以有多个 Julian 的转换日期,但查找仅提供默认转换日期。

      参数:
      id - 年表 ID 或日历系统类型,不为空
      返回:
      请求标识符的年表,不为空
      抛出:
      DateTimeException - 如果找不到年表
    • getAvailableChronologies

      static Set <Chronology > getAvailableChronologies()
      返回可用的年表。

      每个返回的 Chronology 都可以在系统中使用。这组年表包括系统年表和应用程序通过 ServiceLoader 配置提供的任何年表。

      返回:
      独立的、可修改的可用年表 ID 集,不为空
    • getId

      String  getId()
      获取年表的 ID。

      ID 唯一标识 Chronology 。它可用于使用 of(String) 查找 Chronology

      返回:
      年表 ID,不为空
      参见:
    • getCalendarType

      String  getCalendarType()
      获取日历系统的日历类型。

      日历类型是CLDR和Unicode Locale Data Markup Language (LDML)规范定义的标识符,用于唯一标识一个日历。 getCalendarType 是 CLDR 日历类型和变体的串联,如果适用,附加由“-”分隔。日历类型用于使用 of(String) 查找 Chronology

      返回:
      日历系统类型,如果日历不是由 CLDR/LDML 定义的,则为 null
      参见:
    • date

      default ChronoLocalDate  date(Era  era, int yearOfEra, int month, int dayOfMonth)
      从时代、时代年份、月份和月份字段中获取此年表中的本地日期。
      实现要求:
      在调用 date(int, int, int) 之前,默认实现将纪元和纪元年组合成预想年。
      参数:
      era - 年表正确类型的时代,不为空
      yearOfEra - 纪年年代
      month - 年表月份
      dayOfMonth - 年表
      返回:
      此年表中的本地日期,不为空
      抛出:
      DateTimeException - 如果无法创建日期
      ClassCastException - 如果 era 的类型不符合年表
    • date

      ChronoLocalDate  date(int prolepticYear, int month, int dayOfMonth)
      从 proleptic-year、month-of-year 和 day-of-month 字段中获取此年表中的本地日期。
      参数:
      prolepticYear - 年表预测年
      month - 年表月份
      dayOfMonth - 年表
      返回:
      此年表中的本地日期,不为空
      抛出:
      DateTimeException - 如果无法创建日期
    • dateYearDay

      default ChronoLocalDate  dateYearDay(Era  era, int yearOfEra, int dayOfYear)
      从时代、时代年份和年份字段中获取此年表中的本地日期。
      实现要求:
      在调用 dateYearDay(int, int) 之前,默认实现将纪元和纪元年组合成预想年。
      参数:
      era - 年表正确类型的时代,不为空
      yearOfEra - 纪年年代
      dayOfYear - 年表
      返回:
      此年表中的本地日期,不为空
      抛出:
      DateTimeException - 如果无法创建日期
      ClassCastException - 如果 era 的类型不符合年表
    • dateYearDay

      ChronoLocalDate  dateYearDay(int prolepticYear, int dayOfYear)
      从 proleptic-year 和 day-of-year 字段中获取此年表中的本地日期。
      参数:
      prolepticYear - 年表预测年
      dayOfYear - 年表
      返回:
      此年表中的本地日期,不为空
      抛出:
      DateTimeException - 如果无法创建日期
    • dateEpochDay

      ChronoLocalDate  dateEpochDay(long epochDay)
      从纪元日获取此年表中的本地日期。

      EPOCH_DAY 的定义对于所有日历系统都是相同的,因此可以用来转换。

      参数:
      epochDay - 纪元日
      返回:
      此年表中的本地日期,不为空
      抛出:
      DateTimeException - 如果无法创建日期
    • dateNow

      default ChronoLocalDate  dateNow()
      从默认时区的系统时钟获取此年表中的当前本地日期。

      这将在默认时区查询 system clock 以获取当前日期。

      使用此方法将阻止使用备用时钟进行测试的能力,因为时钟是硬编码的。

      实现要求:
      默认实现调用 dateNow(Clock)
      返回:
      使用系统时钟和默认时区的当前本地日期,不为空
      抛出:
      DateTimeException - 如果无法创建日期
    • dateNow

      default ChronoLocalDate  dateNow(ZoneId  zone)
      从指定时区的系统时钟获取此年表中的当前本地日期。

      这将查询 system clock 以获取当前日期。指定时区避免了对默认时区的依赖。

      使用此方法将阻止使用备用时钟进行测试的能力,因为时钟是硬编码的。

      实现要求:
      默认实现调用 dateNow(Clock)
      参数:
      zone - 要使用的区域 ID,不为空
      返回:
      使用系统时钟的当前本地日期,不为空
      抛出:
      DateTimeException - 如果无法创建日期
    • dateNow

      default ChronoLocalDate  dateNow(Clock  clock)
      从指定的时钟获取此年表中的当前本地日期。

      这将查询指定的时钟以获取当前日期 - 今天。使用此方法允许使用备用时钟进行测试。可以使用 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 的一个实例。

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

      此方法与功能接口 TemporalQuery 的签名相匹配,允许它通过方法引用 aChronology::localDateTime 用作查询。

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

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

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

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

      此方法与功能接口 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。
      • 必须为年表的有效年份范围内的所有年份返回正确的结果。

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

      参数:
      prolepticYear - 要检查的预期年份,未针对范围进行验证
      返回:
      如果这一年是闰年,则为真
    • 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)
      获取此年表的文本表示。

      这将返回用于标识年表的文本名称,适合呈现给用户。参数控制返回文本的样式和locale。

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

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

      大多数 TemporalField 实现都是使用字段上的 resolve 方法解析的。相比之下,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 的纪元获取秒数。

      秒数是使用 proleptic-year、month、day-of-month、hour、minute、second 和 zoneOffset 计算的。

      参数:
      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 的纪元获取秒数。

      秒数是使用时代、时代年份、月份、月份日期、小时、分钟、秒和 zoneOffset 计算的。

      参数:
      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 chronology 具有相同的基本结构,即年表具有相同的月数、每个月的天数、年份和闰年与 ISO 年表相同。它还支持 ISO 年表的以周为基础的概念。例如,Minguo ThaiThaiBuddhist Japanese 年表是基于 ISO 的。

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

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

      比较顺序首先按年表 ID 字符串,然后按特定于子类的任何附加信息。正如 Comparable 所定义的那样,它“与等于一致”。

      指定者:
      compareTo 在接口 Comparable<Chronology>
      参数:
      other - 要比较的其他年表,不为空
      返回:
      比较值,小于则为负,大于则为正
    • equals

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

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

      重写:
      equals 在类 Object
      参数:
      obj - 要检查的对象,null 返回 false
      返回:
      如果这等于其他年表,则为真
      参见:
    • hashCode

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

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

      重写:
      hashCode 在类 Object
      返回:
      合适的哈希码
      参见:
    • toString

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

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

      重写:
      toString 在类 Object
      返回:
      此年表的字符串表示形式,不为空