模块  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上的相同常量进行ChronoField 有关此含义的完整讨论,请参阅ChronoLocalDate 一般来说,建议是使用已知的基于ISO的LocalDate ,而不是ChronoLocalDate

    虽然Chronology对象通常使用ChronoField ,并且基于时代,年份,月份,日期的日期模型,但这不是必需的。 Chronology实例可能代表完全不同类型的日历系统,例如Mayan。

    实际上, Chronology实例也可以作为工厂。 of(String)方法允许通过标识符查找实例,而ofLocale(Locale)方法允许按区域设置查找。

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

    添加新日历

    应用程序可以扩展可用的年表集。 添加一个新的日历系统需要实现的写作ChronologyChronoLocalDateEra 特定于日历系统的大多数逻辑将在ChronoLocalDate实现中。 Chronology实施充当工厂。

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

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

    实现要求:
    必须小心实现此接口,以确保其他类正常运行。 可以实例化的所有实现必须是最终的,不可变的和线程安全的。 只要有可能,子类应该是Serializable。
    从以下版本开始:
    1.8
    • 方法详细信息

      • from

        static Chronology from​(TemporalAccessor temporal)
        从时态对象获得Chronology的实例。

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

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

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

        参数
        temporal - 要转换的时间,而不是null
        结果
        年表,不是空的
        异常
        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-japanese”。 因此,此方法与Calendar#getInstance(Locale)之间的行为没有差异。

        参数
        locale - 用于获取日历系统的语言环境,不为null
        结果
        与区域设置关联的日历系统,不为null
        异常
        DateTimeException - 如果 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,不是null
        另请参见:
        getCalendarType()
      • getCalendarType

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

        日历类型是由CLDR和Unicode区域设置数据标记语言(LDML)规范定义的标识符,用于唯一标识日历。 getCalendarType是CLDR日历类型的串联,如果适用,变量getCalendarType “ - ”分隔。 日历类型用于查找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 - dayOfMonth的年表
        结果
        此年表中的本地日期,不为空
        异常
        DateTimeException - 如果无法创建日期
        ClassCastException - 如果 era不是年表的正确类型
      • date

        ChronoLocalDate date​(int prolepticYear,
                             int month,
                             int dayOfMonth)
        从预测年,月份和日期字段中获取此年表中的本地日期。
        参数
        prolepticYear - 年代学 prolepticYear
        month - 每年的年表
        dayOfMonth - 每月的年表
        结果
        此年表中的本地日期,不为空
        异常
        DateTimeException - 如果无法创建日期
      • dateYearDay

        default ChronoLocalDate dateYearDay​(Era era,
                                            int yearOfEra,
                                            int dayOfYear)
        从时代,年代和日期字段中获得此年表中的本地日期。
        实现要求:
        在致电 dateYearDay(int, int)之前,默认实施将时代和年代结合在一起。
        参数
        era - 年表的正确类型的时代,而不是空
        yearOfEra - 年代年代
        dayOfYear - 年度年表
        结果
        此年表中的本地日期,不为空
        异常
        DateTimeException - 如果无法创建日期
        ClassCastException - 如果 era的年代 era不正确
      • dateYearDay

        ChronoLocalDate dateYearDay​(int prolepticYear,
                                    int dayOfYear)
        从预测年和日期字段中获得此年表中的本地日期。
        参数
        prolepticYear - 年代 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 - 要使用的时钟,不为空
        结果
        当前的本地日期,不是null
        异常
        DateTimeException - 如果无法创建日期
      • date

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

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

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

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

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

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

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

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

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

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

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

        这将根据指定的时间在此年表中获取分区日期时间。 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年份,未经过范围验证
        结果
        如果年份是闰年,则为true
      • 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()
        获取年表的时代列表。

        大多数日历系统都有一个时代,这一年有意义。 如果日历系统不支持eras的概念,则必须返回空列表。

        结果
        年表的时代列表可能是不可变的,而不是空的
      • range

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

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

        请注意,结果仅描述了最小和最大有效值,重要的是不要过多地阅读它们。 例如,该范围内的值可能对该字段无效。

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

        参数
        字段 - 获取范围的字段,而不是null
        结果
        字段的有效值范围,不为null
        异常
        DateTimeException - 如果无法获得该字段的范围
      • getDisplayName

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

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

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

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

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

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

        参数
        prolepticYear - 年代学 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 in interface Comparable<Chronology>
        参数
        other - 要比较的其他年表,不是null
        结果
        比较器值,如果更小则为负,如果更大则为正
      • equals

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

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

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

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

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

        重写:
        toString in class Object
        结果
        此年表的字符串表示形式,不为null