Module  java.base
软件包  java.time.chrono

Interface Chronology

  • All Superinterfaces:
    Comparable<Chronology>
    所有已知实现类:
    AbstractChronologyHijrahChronologyIsoChronologyJapaneseChronologyMinguoChronologyThaiBuddhistChronology


    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实例的方法。 日期类用于操纵特定的日期。

    添加新日历

    可用的年表可以通过应用程序进行扩展。 添加一个新的日历系统需要实现的写作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的实例。

        这获得了基于指定时间的年表。 A TemporalAccessor表示一个任意的日期和时间信息集,该工厂转换为Chronology一个实例。

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

        该方法匹配功能接口TemporalQuery的签名,允许其通过方法参考Chronology::from用作查询。

        参数
        temporal - 时间转换,不为空
        结果
        年表,不为空
        异常
        DateTimeException - 如果无法转换为 Chronology
      • ofLocale

        static Chronology ofLocale​(Locale locale)
        从一个地区获取一个Chronology的实例。

        这将返回一个Chronology基于指定的语言环境,通常返回IsoChronology 只有在区域设置中明确选择其他日历系统才会返回。

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

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

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

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

        对于日本的日历系统来说,发生类似但更简单的情况。 以前已使用区域设置“jp_JP_JP”访问日历。 然而,与泰国的语言环境,“ja_JP_JP”会自动转换Locale到现代,并建议“JA-JP-U-CA日”的形式。 因此,此方法与Calendar#getInstance(Locale)之间的行为没有差异。

        参数
        locale - 用于获取日历系统的区域设置,不为空
        结果
        与该区域设置相关联的日历系统,不为null
        异常
        DateTimeException - 如果找不到指定地区的日历
      • of

        static Chronology of​(String id)
        从时间序列ID或日历系统类型获取Chronology的实例。

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

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

        由于某些日历可以自定义,因此ID或类型通常指默认的定制。 例如,公历可以使用Julian的多个切换日期,但查找只提供默认切换日期。

        参数
        id - 年表ID或日历系统类型,不为null
        结果
        具有所请求的标识符的年表不为空
        异常
        DateTimeException - 如果不能找到年表
      • getAvailableChronologies

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

        每个返回的Chronology可用于系统。 一组年表包括系统年表和应用程序通过ServiceLoader配置提供的任何年表。

        结果
        独立的,可修改的可用年表ID的集合,不为空
      • getId

        String getId​()
        获取年表的ID。

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

        结果
        年表ID,不为空
        另请参见:
        getCalendarType()
      • getCalendarType

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

        日历类型是由CLDR和Unicode区域设置数据标记语言(LDML)规范定义的唯一标识日历的标识符。 getCalendarType是CLDR日历类型和变体的连接(如果适用)由“ - ”分隔。 日历类型用于查找Chronology使用of(String)

        结果
        日历系统类型,如果日历未由CLDR / LDML定义,则为null
        另请参见:
        getId()
      • 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)
        从年龄,月份和月份月份获取本年度的年表。
        参数
        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)
        在这个年龄和年龄段的年龄中获得当地的日期。
        参数
        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,不为空
        结果
        当前本地日期使用系统时钟,不为null
        异常
        DateTimeException - 如果无法创建日期
      • dateNow

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

        这将查询指定的时钟以获取当前日期 - 今天。 使用此方法可以使用备用时钟进行测试。 可以使用dependency injection引入备用时钟。

        实现要求:
        默认实现调用 date(TemporalAccessor)
        参数
        clock - 要使用的时钟,不为空
        结果
        当前本地日期,不为null
        异常
        DateTimeException - 如果无法创建日期
      • date

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

        这在这个时间表中基于指定的时间获得日期。 A TemporalAccessor表示日期和时间信息的任意集合,该工厂转换为ChronoLocalDate的实例。

        转换通常使用EPOCH_DAY字段,这是跨日历系统标准化的。

        该方法匹配功能接口TemporalQuery的签名,允许它通过方法参考aChronology::date用作查询。

        参数
        temporal - 要转换的时间对象,不为null
        结果
        这个年代的本地日期,不为空
        异常
        DateTimeException - 如果无法创建日期
        另请参见:
        ChronoLocalDate.from(TemporalAccessor)
      • localDateTime

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

        这在这个时间表中基于指定的时间获得日期时间。 A TemporalAccessor表示日期和时间信息的任意集合,该工厂将转换为ChronoLocalDateTime的实例。

        该转换提取并结合了来自时间对象的ChronoLocalDateLocalTime 允许实现执行优化,例如访问与相关对象相当的那些字段。 结果使用这个年表。

        该方法匹配功能接口TemporalQuery的签名,允许其通过方法参考aChronology::localDateTime用作查询。

        参数
        temporal - 要转换的时间对象,不为null
        结果
        在这个年代的本地日期时间,不为空
        异常
        DateTimeException - 如果无法创建日期时间
        另请参见:
        ChronoLocalDateTime.from(TemporalAccessor)
      • zonedDateTime

        default ChronoZonedDateTime<? extends ChronoLocalDate> zonedDateTime​(TemporalAccessor temporal)
        在另一个时间对象的ChronoZonedDateTime中获得一个ChronoZonedDateTime

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

        转换将首先从时间对象获得一个ZoneId ,如有必要,可以回到ZoneOffset 然后会尝试获得一个Instant ,如有必要,可以回到ChronoLocalDateTime 结果将是ZoneIdZoneOffsetInstantChronoLocalDateTime 允许实现执行优化,例如访问与相关对象相当的那些字段。 结果使用这个年表。

        该方法匹配功能接口TemporalQuery的签名,允许其通过方法参考aChronology::zonedDateTime用作查询。

        参数
        temporal - 要转换的时间对象,不为null
        结果
        在这个年代的分区日期 - 时间,不为空
        异常
        DateTimeException - 如果无法创建日期时间
        另请参见:
        ChronoZonedDateTime.from(TemporalAccessor)
      • zonedDateTime

        default ChronoZonedDateTime<? extends ChronoLocalDate> zonedDateTime​(Instant instant,
                                                                             ZoneId zone)
        获得ChronoZonedDateTime在从这个年表Instant

        这将获得与指定的相同时间的分区日期时间。

        参数
        instant - 即时创建日期时间,不为null
        zone - 时区,不为空
        结果
        划分的日期时间,不为空
        异常
        DateTimeException - 如果结果超出了支持范围
      • isLeapYear

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

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

        • 闰年必须意味着比非闰年更长的一年。
        • 不支持一年概念的年表必须返回假。
        • 正确的结果必须在年龄的有效范围内返回所有年份。

        在有效年龄范围之外,实施可以自由返回最佳猜测或假。 即使该年度超出有效年限的范围,实施也不能抛出异常。

        参数
        prolepticYear - 检查年份,无法验证范围
        结果
        如果这一年是闰年,那么真的
      • prolepticYear

        int prolepticYear​(Era era,
                          int yearOfEra)
        计算年龄和年龄的幼年时期。

        这将时代与时代融为一体的年轻一代。

        如果年表积极使用时代,例如JapaneseChronology那么年龄将在时代得到验证。 对于其他年表,验证是可选的。

        参数
        era - 时代的正确类型为年表,不为空
        yearOfEra - 年代的年代
        结果
        幼稚的一年
        异常
        DateTimeException - 如果无法转化为 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 - 获取范围的字段,不为null
        结果
        字段的有效值的范围不为null
        异常
        DateTimeException - 如果无法获取字段的范围
      • getDisplayName

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

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

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

        ChronoLocalDate resolveDate​(Map<TemporalField,Long> fieldValues,
                                    ResolverStyle resolverStyle)
        解析解析中的日期为ChronoField

        大多数TemporalField实现使用该字段上的resolve方法来解决。 相比之下, ChronoField类定义了与年表相关的字段。 因此,在特定年表的上下文中解决了ChronoField日期字段。

        AbstractChronology提供了默认实现,它解释了典型的解决方案

        参数
        fieldValues - 可以更新的字段映射到值,不为null
        resolverStyle - 请求的解析类型,不为null
        结果
        解决日期,如果信息不足创建日期,则为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的时期获取秒数。

        秒数是使用年龄,年龄,月,月,小时,分钟,秒和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
      • compareTo

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

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

        Specified by:
        compareTo在接口 Comparable<Chronology>
        参数
        other - 其他年表要比较,不是null
        结果
        比较器值为负,如果较小,则如果较大则为正
      • equals

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

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

        重写:
        equalsObject
        参数
        obj - 要检查的对象,null返回false
        结果
        如果这等于其他年表,则为真
        另请参见:
        Object.hashCode()HashMap
      • toString

        String toString​()
        输出这个年表为String

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

        重写:
        toStringObject
        结果
        这个年表的字符串表示,不为null