模块  java.base
软件包  java.time

Class ZoneId

  • 实现的所有接口
    Serializable
    已知直接子类:
    ZoneOffset

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

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

    • 固定偏移 - 与UTC / Greenwich完全解析的偏移量,对所有本地日期时间使用相同的偏移量
    • 地理区域 - 用于查找从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可以被归到ZoneOffset使用normalized()

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

    时区规则由政府定义并经常变更。 有许多组织,这里称为组,它们监视时区变化并整理它们。 默认组是IANA时区数据库(TZDB)。 其他组织包括IATA(航空业机构)和微软。

    每个组都为其提供的区域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 / Greenwich的偏移量。

    可以在ID未知的Java运行时中反序列化ZoneId 例如,如果使用新的区域ID更新了服务器端Java Runtime,但尚未更新客户端Java Runtime。 在这种情况下, 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 - 澳大利亚/达尔文
        • AET - 澳大利亚/悉尼
        • 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 - America / Puerto_Rico
        • PST - America / Los_Angeles
        • SST - 太平洋/瓜达尔卡纳尔岛
        • VST - Asia / Ho_Chi_Minh
        地图是不可修改的。
    • 方法详细信息

      • getAvailableZoneIds

        public static Set<String> getAvailableZoneIds()
        获取可用区域ID的集合。

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

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

        结果
        区域ID集的可修改副本,不为null
      • of

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

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

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

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

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

        解析与区域ID逐步匹配如下。

        • 如果区域ID等于'Z',则结果为ZoneOffset.UTC
        • 如果区域ID由单个字母组成,则区域ID无效并且将引发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 - 偏移量,不为空
        结果
        区域ID,不为空
        异常
        IllegalArgumentException - 如果前缀不是“GMT”,“UTC”或“UT”或“”之一
      • from

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

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

        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)
        获取区域的文本表示,例如“British Time”或“+02:00”。

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

        如果未找到文本映射,则返回full ID

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

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

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

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

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

        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。

        重写:
        equals在类 Object
        参数
        obj - 要检查的对象,null返回false
        结果
        如果它等于另一个时区ID,则返回true
        另请参见:
        Object.hashCode()HashMap
      • toString

        public String toString()
        使用ID将此区域输出为 String
        重写:
        toString在课程 Object
        结果
        此时区ID的字符串表示形式,不为null