Module  java.base
软件包  java.time

Class ZoneId

  • All Implemented Interfaces:
    Serializable
    已知直接子类:
    ZoneOffset


    public abstract class ZoneId
    extends Object
    implements Serializable
    时区ID,如Europe/Paris

    A ZoneId用于标识用于在InstantLocalDateTime之间转换的规则。 有两种不同类型的ID:

    • 固定偏移量 - 从UTC /格林威治完全解析的偏移量,对所有本地日期时间使用相同的偏移量
    • 地理区域 - 适用于查找UTC /格林威治的偏移量的特定规则集的区域
    大多数固定偏移量由ZoneOffset表示。 主叫normalized()上任何ZoneId将确保一个固定的偏移ID将被表示为ZoneOffset

    描述偏移变化的时间和方式的实际规则由ZoneRules定义。 这个类只是一个用于获取基本规则的ID。 采取这种方法是因为规则由政府定义并且频繁变化,而ID是稳定的。

    这个区别有其他的影响。 序列化ZoneId只会发送ID,而序列化规则会发送整个数据集。 类似地,两个ID的比较仅检查ID,而两个规则的比较检查整个数据集。

    时区ID

    该ID在系统内是唯一的。 有三种类型的ID。

    最简单的ID是ZoneOffset 这由“Z”和以“+”或“ - ”开头的ID组成。

    下一种类型的ID是具有某些形式的前缀的偏移样式ID,例如“GMT + 2”或“UTC + 01:00”。 识别的前缀是“UTC”,“GMT”和“UT”。 偏移量是后缀,在创建过程中将被归一化。 这些ID可以使用normalized()归一ZoneOffset normalized()

    第三种类型的ID是基于区域的ID。 基于区域的ID必须为两个或更多个字符,而不是以“UTC”,“GMT”,“UT”+“或” - “开头。 基于区域的ID由配置定义,请参见ZoneRulesProvider 配置重点是提供从ID到底层的查找ZoneRules

    时区规则由政府界定,频繁变化。 有一些组织,这里被称为组,监视时区更改并整理它们。 默认组是IANA时区数据库(TZDB)。 其他组织包括国际航协(航空业机构)和微软。

    每个组为其提供的区域ID定义其自己的格式。 TZDB组定义了诸如“Europe / London”或“America / New_York”之类的ID。 TZDB ID优先于其他组。

    强烈建议组名称包含在TZDB以外的组所提供的所有ID中,以避免冲突。 例如,IATA航空公司时区区域ID通常与三字母机场代码相同。 但是,乌特勒支机场的代码“UTC”显然是一个冲突。 来自TZDB以外的组的区域ID的推荐格式为“group〜region”。 因此,如果定义了IATA数据,乌得勒支机场将是“IATA〜UTC”。

    序列化

    该类可以序列化,并将字符串区域ID存储在外部表单中。 ZoneOffset子类使用仅存储UTC /格林威治的偏移量的专用格式。

    A ZoneId可以在Java运行时反序列化,其中ID是未知的。 例如,如果服务器端Java运行时已经使用新的区域ID更新,但是客户端Java运行时尚未更新。 在这种情况下, ZoneId对象会存在,并且可以使用被查询getIdequalshashCodetoStringgetDisplayNamenormalized 但是,任何拨打getRules电话getRules将与ZoneRulesException失败。 此方法旨在允许在具有不完整时区信息的Java运行时上加载和查询ZonedDateTime ,但不进行修改。

    这是一个value-based课; ZoneId实例上使用身份敏感操作(包括引用等式( == ),身份哈希码或同步)可能会产生不可预知的结果,应该避免。 equals方法应用于比较。

    实现要求:
    这个抽象类有两个实现,这两个实现是不可变的和线程安全的。 一个实现模型基于区域的ID,另一个是基于偏移的ID建立ZoneOffset 这种差异在序列化中可见。
    从以下版本开始:
    1.8
    另请参见:
    Serialized Form
    • 字段详细信息

      • SHORT_IDS

        public static final Map<String,String> SHORT_IDS
        区域覆盖的映射,以启用短时区名称。

        java.util.TimeZone已经不推荐使用短区域ID。 该地图允许通过of(String, Map)工厂方法继续使用ID。

        此映射包含与TZDB 2005r及更高版本一致的ID的映射,其中“EST”,“MST”和“HST”映射到不包括夏令时的ID。

        这个地图如下:

        • EST - -05:00
        • HST - -10:00
        • MST - -07:00
        • ACT - 澳大利亚/达尔文
        • 澳大利亚/悉尼
        • AGT - 美洲/阿根廷/布宜诺斯艾利斯
        • 艺术 - 非洲/开罗
        • AST - 美国/安克拉治
        • BET - America / Sao_Paulo
        • BST - 亚洲/达卡
        • CAT - 非洲/哈拉雷
        • CNT - America / St_Johns
        • CST - 美国/芝加哥
        • CTT - 亚洲/上海
        • EAT - 非洲/ Addis_Ababa
        • ECT - 欧洲/巴黎
        • IET - 美洲/印第安纳州/印第安纳州
        • IST - 亚洲/加尔各答
        • JST - 亚洲/东京
        • 麻省理工学院 - 太平洋/阿皮亚
        • NET - 亚洲/埃里温
        • NST - 太平洋/奥克兰
        • PLT - 亚洲/卡拉奇
        • PNT - 美国/凤凰城
        • PRT - 美洲/波多黎各
        • PST - 美国/ Los_Angeles
        • 太平洋岛屿/瓜达尔卡纳群岛
        • VST - 亚洲/ Ho_Chi_Minh
        地图是不可修改的。
    • 方法详细信息

      • getAvailableZoneIds

        public static Set<String> getAvailableZoneIds​()
        获取一组可用的区域ID。

        该集合包括所有可用的基于区域的ID的字符串形式。 返回的集合中不包括基于偏移的区域ID。 该ID可以传递给of(String)创建一个ZoneId

        区域ID的集合可以随着时间而增加,尽管在典型的应用中,ID集合是固定的。 每次调用此方法都是线程安全的。

        结果
        一组区域ID的可修改副本,不为空
      • of

        public static ZoneId of​(String zoneId,
                                Map<String,String> aliasMap)
        获取使用其ID的ZoneId实例,使用别名映射来补充标准区域ID。

        时区的许多用户使用简短的缩写,例如“太平洋标准时间”的PST和“太平洋夏令时”的PDT。 这些缩写不是唯一的,因此不能用作ID。 该方法允许在应用程序内设置和重新使用字符串到时区的映射。

        参数
        zoneId - 时区ID,不为空
        aliasMap - 实际区域ID的别名区域ID(通常为缩写)的映射,不为空
        结果
        区域ID,不为空
        异常
        DateTimeException - 区域ID是否格式无效
        ZoneRulesException - 如果区域ID是无法找到的区域ID
      • of

        public static ZoneId of​(String zoneId)
        从ID获取ZoneId的实例,确保该ID有效并可供使用。

        此方法解析产生一个ZoneIdZoneOffset的ID。 如果ID为“Z”,则返回A ZoneOffset ,或以“+”或“ - ”开头。 结果将永远是一个有效的ID, 可以获得ZoneRules

        解析如下一步地匹配区域ID。

        • 如果区域ID等于'Z',结果为ZoneOffset.UTC
        • 如果区域ID由单个字母组成,则区域ID无效, DateTimeException抛出DateTimeException
        • 如果区域ID以“+”或“ - ” ZoneOffset使用ZoneOffset.of(String)将该ID解析为ZoneOffset
        • 如果区域ID等于'GMT','UTC'或'UT',那么结果是一个ZoneId ,其ID和规则相当于ZoneOffset.UTC
        • 如果区域ID以“UTC +”,“UTC-”,“GMT +”,“GMT-”,“UT +”或“UT-”开头,那么ID就是前缀的基于偏移量的ID。 ID分为两个,两个或三个字母的前缀和一个以符号开头的后缀。 后缀被解析为ZoneOffset 其结果将是一个ZoneId与指定UTC / GMT / UT前缀和归一化的偏移ID作为每ZoneOffset.getId() 返回的ZoneId的规则将相当于已解析的ZoneOffset
        • 所有其他ID都将被分析为基于区域的区域ID。 区域ID必须与正则表达式[A-Za-z][A-Za-z0-9~/._+-]+匹配,否则抛出DateTimeException 如果区域ID不在配置的ID ZoneRulesException则抛出ZoneRulesException 区域ID的详细格式取决于提供数据的组。 默认数据集由IANA时区数据库(TZDB)提供。 它具有“{area} / {city}”形式的区域ID,例如“Europe / Paris”或“America / New_York”。 这与TimeZone中的大多数ID兼容。
        参数
        zoneId - 时区ID,不为空
        结果
        区域ID,不为空
        异常
        DateTimeException - 区域ID是否格式无效
        ZoneRulesException - 如果区域ID是无法找到的区域ID
      • ofOffset

        public static ZoneId ofOffset​(String prefix,
                                      ZoneOffset offset)
        获取一个ZoneId包装偏移的实例。

        如果前缀为“GMT”,“UTC”或“UT”,则ZoneId带前缀和非零偏移的ZoneId 如果前缀为空"" ,则返回ZoneOffset

        参数
        prefix - 时区ID,不为空
        offset - offset,not null
        结果
        区域ID,不为空
        异常
        IllegalArgumentException - 如果前缀不是“GMT”,“UTC”或“UT”或“”
      • from

        public static ZoneId from​(TemporalAccessor temporal)
        从时间对象获取一个ZoneId的实例。

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

        A TemporalAccessor表示某种形式的日期和时间信息。 该工厂将任意的时间对象转换为ZoneId的实例。

        转换将尝试使用TemporalQueries.zone()以基于偏移的区域为基础的区域获取区域。

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

        参数
        temporal - 要转换的时间对象,不为null
        结果
        区域ID,不为空
        异常
        DateTimeException - 如果无法转换为 ZoneId
      • getId

        public abstract String getId​()
        获取唯一的时区ID。

        此ID唯一地定义了该对象。 基于偏移的ID的格式由ZoneOffset.getId()定义。

        结果
        时区唯一ID,不为空
      • getDisplayName

        public String getDisplayName​(TextStyle style,
                                     Locale locale)
        获取区域的文字表示,例如“英国时间”或“+02:00”。

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

        如果没有发现文本映射,则返回full ID

        参数
        style - 所需文本的长度,不为空
        locale - 要使用的语言环境,不为空
        结果
        区域的文本值,不为空
      • getRules

        public abstract ZoneRules getRules​()
        获取此ID的时区规则,允许执行计算。

        规则提供与时区相关联的功能,例如查找给定即时或本地日期时间的偏移量。

        如果在Java运行时反序列化时区,则该时区不能与存储它的Java运行时加载相同的规则。 在这种情况下,调用此方法将抛出一个ZoneRulesException

        规则由ZoneRulesProvider提供。 高级提供商可以支持规则的动态更新,而无需重新启动Java运行时。 如果是这样,则该方法的结果可能会随时间而变化。 每个单独的呼叫仍将保持线程安全。

        ZoneOffset将始终返回一组规则,其中偏移量不会更改。

        结果
        规则,不为空
        异常
        ZoneRulesException - 如果没有规则可用于此ID
      • normalized

        public ZoneId normalized​()
        规范时区ID,尽可能返回ZoneOffset

        返回归一化的ZoneId可以用于代替此ID。 结果将具有ZoneRules相当于该对象返回的值,但是由getId()返回的ID可能不同。

        规范化检查此ZoneId的规则ZoneId具有固定的偏移量。 如果这样做,则ZoneOffset等于该偏移量的ZoneOffset 否则返回this

        结果
        时区唯一ID,不为空
      • equals

        public boolean equals​(Object obj)
        检查此时区ID是否等于其他时区ID。

        比较是基于ID。

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

        public String toString​()
        输出此区域为 String ,使用ID。
        重写:
        toStringObject
        结果
        此时区ID的字符串表示形式,不为空