- 所有父级接口:
Comparable<Chronology>
- 所有已知的实现类:
AbstractChronology,HijrahChronology,IsoChronology,JapaneseChronology,MinguoChronology,ThaiBuddhistChronology
主要的日期和时间 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 实例的方法。日期类用于操作特定日期。
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 。必须将一个名为“java.time.chrono.Chronology”的文件添加到 META-INF/services 目录,其中列出了实现类。有关服务加载的更多详细信息,请参阅 ServiceLoader。对于按 id 或 calendarType 查找,首先找到系统提供的日历,然后是应用程序提供的日历。
每个年表必须定义一个在系统内唯一的年表 ID。如果年表表示由 CLDR 规范定义的日历系统,则日历类型是 CLDR 类型和 CLDR 变体(如果适用)的串联。
- 实现要求:
- 必须小心实现此接口以确保其他类正确运行。所有可以实例化的实现都必须是最终的、不可变的和线程安全的。只要有可能,子类就应该是可序列化的。
- 自从:
- 1.8
-
方法总结
修饰符和类型方法描述intcompareTo(Chronology other) 将此年表与另一个年表进行比较。date(int prolepticYear, int month, int dayOfMonth) 从 proleptic-year、month-of-year 和 day-of-month 字段中获取此年表中的本地日期。default ChronoLocalDate从时代、时代年份、月份和月份字段中获取此年表中的本地日期。date(TemporalAccessor temporal) 从另一个时间对象获取此年表中的本地日期。dateEpochDay(long epochDay) 从纪元日获取此年表中的本地日期。default ChronoLocalDatedateNow()从默认时区的系统时钟获取此年表中的当前本地日期。default ChronoLocalDate从指定的时钟获取此年表中的当前本地日期。default ChronoLocalDate从指定时区的系统时钟获取此年表中的当前本地日期。dateYearDay(int prolepticYear, int dayOfYear) 从 proleptic-year 和 day-of-year 字段中获取此年表中的本地日期。default ChronoLocalDatedateYearDay(Era era, int yearOfEra, int dayOfYear) 从时代、时代年份和年份字段中获取此年表中的本地日期。default longepochSecond(int prolepticYear, int month, int dayOfMonth, int hour, int minute, int second, ZoneOffset zoneOffset) 从 1970-01-01T00:00:00Z 的纪元获取秒数。default longepochSecond(Era era, int yearOfEra, int month, int dayOfMonth, int hour, int minute, int second, ZoneOffset zoneOffset) 从 1970-01-01T00:00:00Z 的纪元获取秒数。boolean检查此年表是否等于另一个年表。eraOf(int eraValue) 从数值创建年代对象。eras()获取年表的纪元列表。static Chronologyfrom(TemporalAccessor temporal) 从时间对象中获取Chronology的实例。static Set<Chronology>返回可用的年表。获取日历系统的日历类型。default StringgetDisplayName(TextStyle style, Locale locale) 获取此年表的文本表示。getId()获取年表的 ID。inthashCode()此年表的哈希码。default boolean检查此年表是否基于 ISO。booleanisLeapYear(long prolepticYear) 检查指定年份是否为闰年。default ChronoLocalDateTime<? extends ChronoLocalDate>localDateTime(TemporalAccessor temporal) 从另一个时间对象获取此年表中的本地日期时间。static Chronology从年表 ID 或日历系统类型中获取Chronology的实例。static Chronology从locale中获取Chronology的实例。default ChronoPeriodperiod(int years, int months, int days) 根据年、月和日获取此年表的周期。intprolepticYear(Era era, int yearOfEra) 计算给定时代和时代的预期年份。range(ChronoField field) 获取指定字段的有效值范围。resolveDate(Map<TemporalField, Long> fieldValues, ResolverStyle resolverStyle) 在解析期间将已解析的ChronoField值解析为日期。toString()将此年表输出为String。default ChronoZonedDateTime<? extends ChronoLocalDate>zonedDateTime(Instant instant, ZoneId zone) 从Instant获得此年表中的ChronoZonedDateTime。default ChronoZonedDateTime<? extends ChronoLocalDate>zonedDateTime(TemporalAccessor temporal) 从另一个时间对象获得此年表中的ChronoZonedDateTime。
-
方法详情
-
from
从时间对象中获取Chronology的实例。这将根据指定的时间获得年表。
TemporalAccessor表示一组任意的日期和时间信息,该工厂将其转换为Chronology的一个实例。转换将使用
TemporalQueries.chronology()获取年表。如果指定的时间对象没有年表,则返回IsoChronology。此方法与功能接口
TemporalQuery的签名相匹配,允许它通过方法引用Chronology::from用作查询。- 参数:
temporal- 要转换的时间,不为空- 返回:
- 年表,不为空
- 抛出:
DateTimeException- 如果无法转换为Chronology
-
ofLocale
从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
从年表 ID 或日历系统类型中获取Chronology的实例。这将返回基于 ID 或类型的年表。
chronology ID唯一标识年表。calendar system type由 CLDR 规范定义。年表可以是系统年表或应用程序通过 ServiceLoader 配置提供的年表。
由于某些日历可以自定义,因此 ID 或类型通常指的是默认自定义。例如,Gregorian 日历可以有多个 Julian 的转换日期,但查找仅提供默认转换日期。
- 参数:
id- 年表 ID 或日历系统类型,不为空- 返回:
- 请求标识符的年表,不为空
- 抛出:
DateTimeException- 如果找不到年表
-
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
从时代、时代年份、月份和月份字段中获取此年表中的本地日期。- 实现要求:
-
在调用
date(int, int, int)之前,默认实现将纪元和纪元年组合成预想年。 - 参数:
era- 年表正确类型的时代,不为空yearOfEra- 纪年年代month- 年表月份dayOfMonth- 年表- 返回:
- 此年表中的本地日期,不为空
- 抛出:
DateTimeException- 如果无法创建日期ClassCastException- 如果era的类型不符合年表
-
date
从 proleptic-year、month-of-year 和 day-of-month 字段中获取此年表中的本地日期。- 参数:
prolepticYear- 年表预测年month- 年表月份dayOfMonth- 年表- 返回:
- 此年表中的本地日期,不为空
- 抛出:
DateTimeException- 如果无法创建日期
-
dateYearDay
从时代、时代年份和年份字段中获取此年表中的本地日期。- 实现要求:
-
在调用
dateYearDay(int, int)之前,默认实现将纪元和纪元年组合成预想年。 - 参数:
era- 年表正确类型的时代,不为空yearOfEra- 纪年年代dayOfYear- 年表- 返回:
- 此年表中的本地日期,不为空
- 抛出:
DateTimeException- 如果无法创建日期ClassCastException- 如果era的类型不符合年表
-
dateYearDay
从 proleptic-year 和 day-of-year 字段中获取此年表中的本地日期。- 参数:
prolepticYear- 年表预测年dayOfYear- 年表- 返回:
- 此年表中的本地日期,不为空
- 抛出:
DateTimeException- 如果无法创建日期
-
dateEpochDay
从纪元日获取此年表中的本地日期。EPOCH_DAY的定义对于所有日历系统都是相同的,因此可以用来转换。- 参数:
epochDay- 纪元日- 返回:
- 此年表中的本地日期,不为空
- 抛出:
DateTimeException- 如果无法创建日期
-
dateNow
从默认时区的系统时钟获取此年表中的当前本地日期。这将在默认时区查询
system clock以获取当前日期。使用此方法将阻止使用备用时钟进行测试的能力,因为时钟是硬编码的。
- 实现要求:
-
默认实现调用
dateNow(Clock)。 - 返回:
- 使用系统时钟和默认时区的当前本地日期,不为空
- 抛出:
DateTimeException- 如果无法创建日期
-
dateNow
从指定时区的系统时钟获取此年表中的当前本地日期。这将查询
system clock以获取当前日期。指定时区避免了对默认时区的依赖。使用此方法将阻止使用备用时钟进行测试的能力,因为时钟是硬编码的。
- 实现要求:
-
默认实现调用
dateNow(Clock)。 - 参数:
zone- 要使用的区域 ID,不为空- 返回:
- 使用系统时钟的当前本地日期,不为空
- 抛出:
DateTimeException- 如果无法创建日期
-
dateNow
从指定的时钟获取此年表中的当前本地日期。这将查询指定的时钟以获取当前日期 - 今天。使用此方法允许使用备用时钟进行测试。可以使用
dependency injection引入备用时钟。- 实现要求:
-
默认实现调用
date(TemporalAccessor)。 - 参数:
clock- 使用的时钟,不为空- 返回:
- 当前本地日期,不为空
- 抛出:
DateTimeException- 如果无法创建日期
-
date
从另一个时间对象获取此年表中的本地日期。这将根据指定的时间获取此年表中的日期。
TemporalAccessor表示一组任意的日期和时间信息,该工厂将其转换为ChronoLocalDate的一个实例。转换通常使用跨日历系统标准化的
EPOCH_DAY字段。此方法与功能接口
TemporalQuery的签名相匹配,允许它通过方法引用aChronology::date用作查询。- 参数:
temporal- 要转换的时间对象,不为空- 返回:
- 此年表中的本地日期,不为空
- 抛出:
DateTimeException- 如果无法创建日期- 参见:
-
localDateTime
从另一个时间对象获取此年表中的本地日期时间。这将根据指定的时间在此年表中获取日期时间。
TemporalAccessor表示一组任意的日期和时间信息,该工厂将其转换为ChronoLocalDateTime的一个实例。转换从时间对象中提取并组合
ChronoLocalDate和LocalTime。允许实现执行优化,例如访问与相关对象等效的那些字段。结果使用此年表。此方法与功能接口
TemporalQuery的签名相匹配,允许它通过方法引用aChronology::localDateTime用作查询。- 参数:
temporal- 要转换的时间对象,不为空- 返回:
- 此年表中的本地日期时间,不为空
- 抛出:
DateTimeException- 如果无法创建日期时间- 参见:
-
zonedDateTime
从另一个时间对象获得此年表中的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。
- 必须为年表的有效年份范围内的所有年份返回正确的结果。
在有效年份范围之外,实现可以自由返回最佳猜测或错误。即使年份超出有效年份范围,实现也不得抛出异常。
- 参数:
prolepticYear- 要检查的预期年份,未针对范围进行验证- 返回:
- 如果这一年是闰年,则为真
-
prolepticYear
计算给定时代和时代的预期年份。这将时代和时代结合到单一的预测年字段。
如果年表积极使用纪元,例如
JapaneseChronology,那么纪元年将根据纪元进行验证。对于其他年表,验证是可选的。- 参数:
era- 年表正确类型的时代,不为空yearOfEra- 纪年年代- 返回:
- 推算年份
- 抛出:
DateTimeException- 如果无法转换为预测年份,例如年份对于时代无效ClassCastException- 如果era的类型不符合年表
-
eraOf
从数值创建年代对象。从概念上讲,时代是时间线的最大划分。大多数日历系统都有一个纪元,将时间线分为两个纪元。然而,有些有多个时代,例如每个领导人的统治时期。确切的含义由年表根据以下限制确定。
在 1970-01-01 使用的纪元必须具有值 1。后面的纪元必须依次具有更高的值。较早的时代必须具有顺序较低的值。每个年表必须引用一个枚举或类似的单例来提供时代值。
此方法返回指定纪元值的正确类型的单例纪元。
- 参数:
eraValue- 时代值- 返回:
- 日历系统时代,不为空
- 抛出:
DateTimeException- 如果无法创建时代
-
eras
获取年表的纪元列表。大多数日历系统都有一个时代,其中年份具有意义。如果日历系统不支持时代的概念,则必须返回一个空列表。
- 返回:
- 年表的时代列表,可能是不可变的,不为空
-
range
获取指定字段的有效值范围。所有字段都可以表示为一个
long整数。此方法返回一个描述该值有效范围的对象。请注意,结果仅描述了最小和最大有效值,重要的是不要过多地解读它们。例如,范围内可能存在对该字段无效的值。
无论年表是否支持该字段,此方法都会返回一个结果。
- 参数:
field- 获取范围的字段,不为空- 返回:
- 该字段的有效值范围,不为空
- 抛出:
DateTimeException- 如果无法获得该字段的范围
-
getDisplayName
获取此年表的文本表示。这将返回用于标识年表的文本名称,适合呈现给用户。参数控制返回文本的样式和locale。
- 实现要求:
- 默认实现的行为就像格式化程序用于格式化年表文本名称一样。
- 参数:
style- 所需文本的样式,不为空locale- 要使用的locale,不为空- 返回:
- 年表的文本值,不为空
-
resolveDate
在解析期间将已解析的ChronoField值解析为日期。大多数
TemporalField实现都是使用字段上的 resolve 方法解析的。相比之下,ChronoField类定义的字段仅与年表相关。因此,ChronoField日期字段在特定年表的上下文中在此处解析。AbstractChronology中提供了默认实现,它解释了典型的解析行为。- 参数:
fieldValues- 字段到值的映射,可以更新,不为空resolverStyle- 请求的解析类型,不为空- 返回:
- 解决日期,如果信息不足以创建日期则为 null
- 抛出:
DateTimeException- 如果无法解析日期,通常是因为输入数据存在冲突
-
period
根据年、月和日获取此年表的周期。这将使用指定的年、月和日返回与此年表相关的期间。所有提供的年表都使用基于年、月和日的周期,但是
ChronoPeriodAPI 允许使用其他单位表示周期。- 实现要求:
-
默认实现返回适用于大多数日历系统的实现类。它仅基于三个单元。归一化、加法和减法从
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 到 23minute- 小时,从 0 到 59second- 秒数,从 0 到 59zoneOffset- 区域偏移量,不为空- 返回:
- 相对于 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 到 23minute- 小时,从 0 到 59second- 秒数,从 0 到 59zoneOffset- 区域偏移量,不为空- 返回:
- 相对于 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
将此年表与另一个年表进行比较。比较顺序首先按年表 ID 字符串,然后按特定于子类的任何附加信息。正如
Comparable所定义的那样,它“与等于一致”。- 指定者:
compareTo在接口Comparable<Chronology>中- 参数:
other- 要比较的其他年表,不为空- 返回:
- 比较值,小于则为负,大于则为正
-
equals
检查此年表是否等于另一个年表。比较基于对象的整个状态。
-
hashCode
int hashCode()此年表的哈希码。哈希码应该基于对象的整个状态。
-
toString
String toString()将此年表输出为String。该格式应包括对象的整个状态。
-