Class TimezoneConverter

java.lang.Object
cloud.opencode.base.date.timezone.TimezoneConverter
public final class TimezoneConverter extends Object
Timezone converter for date/time conversions between timezones 时区转换器，用于不同时区之间的日期时间转换

This class provides fluent API for converting dates and times between different timezones with proper handling of DST and other timezone rules.

此类提供流畅的API，用于在不同时区之间转换日期和时间，并正确处理夏令时和其他时区规则。

Features | 主要功能:

  • Fluent API for timezone conversion - 流畅的时区转换API
  • Support for common timezone aliases - 支持常用时区别名
  • DST-aware conversions - 夏令时感知的转换
  • Batch conversion support - 批量转换支持

Usage Examples | 使用示例:

// Convert from Beijing to New York
ZonedDateTime nyTime = TimezoneConverter.from(ZoneId.of("Asia/Shanghai"))
    .to(ZoneId.of("America/New_York"))
    .convert(LocalDateTime.now());

// Using common timezone constants
ZonedDateTime result = TimezoneConverter.fromUTC()
    .to(TimezoneConverter.CHINA)
    .convert(Instant.now());

Security | 安全性:

  • Thread-safe: Yes (immutable after construction) - 线程安全: 是（构造后不可变）
  • Null-safe: Yes (with explicit null checks) - 空值安全: 是（有明确的空值检查）

Performance | 性能特性:

  • Time complexity: O(1) - all conversions are single arithmetic timezone offset operations - 时间复杂度: O(1) - 所有转换均为单次时区偏移算术运算
  • Space complexity: O(1) - stores only source and target ZoneId references - 空间复杂度: O(1) - 仅存储源和目标 ZoneId 引用
Since:
JDK 25, opencode-base-date V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Details

    • UTC

      public static final ZoneId UTC

    • CHINA

      public static final ZoneId CHINA

    • BEIJING

      public static final ZoneId BEIJING

    • HONG_KONG

      public static final ZoneId HONG_KONG

    • TOKYO

      public static final ZoneId TOKYO

    • SEOUL

      public static final ZoneId SEOUL

    • SINGAPORE

      public static final ZoneId SINGAPORE

    • NEW_YORK

      public static final ZoneId NEW_YORK

    • LOS_ANGELES

      public static final ZoneId LOS_ANGELES

    • CHICAGO

      public static final ZoneId CHICAGO

    • LONDON

      public static final ZoneId LONDON

    • PARIS

      public static final ZoneId PARIS

    • BERLIN

      public static final ZoneId BERLIN

    • SYDNEY

      public static final ZoneId SYDNEY

  • Method Details

    • from

      public static TimezoneConverter from(ZoneId sourceZone)
      Creates a converter from the specified source timezone 从指定的源时区创建转换器
      Parameters:
      sourceZone - the source timezone | 源时区
      Returns:
      the converter | 转换器

    • fromUTC

      public static TimezoneConverter fromUTC()
      Creates a converter from UTC 从UTC创建转换器
      Returns:
      the converter | 转换器

    • fromChina

      public static TimezoneConverter fromChina()
      Creates a converter from China timezone 从中国时区创建转换器
      Returns:
      the converter | 转换器

    • fromSystem

      public static TimezoneConverter fromSystem()
      Creates a converter from system default timezone 从系统默认时区创建转换器
      Returns:
      the converter | 转换器

    • to

      public TimezoneConverter to(ZoneId targetZone)
      Sets the target timezone 设置目标时区
      Parameters:
      targetZone - the target timezone | 目标时区
      Returns:
      this converter | 此转换器

    • toUTC

      public TimezoneConverter toUTC()
      Sets the target timezone to UTC 设置目标时区为UTC
      Returns:
      this converter | 此转换器

    • toChina

      public TimezoneConverter toChina()
      Sets the target timezone to China 设置目标时区为中国
      Returns:
      this converter | 此转换器

    • toSystem

      public TimezoneConverter toSystem()
      Sets the target timezone to system default 设置目标时区为系统默认
      Returns:
      this converter | 此转换器

    • convert

      public ZonedDateTime convert(LocalDateTime dateTime)
      Converts a LocalDateTime to the target timezone 将LocalDateTime转换到目标时区
      Parameters:
      dateTime - the date time in source timezone | 源时区中的日期时间
      Returns:
      the date time in target timezone | 目标时区中的日期时间

    • convert

      public ZonedDateTime convert(Instant instant)
      Converts an Instant to the target timezone 将Instant转换到目标时区
      Parameters:
      instant - the instant | 时刻
      Returns:
      the date time in target timezone | 目标时区中的日期时间

    • convert

      public ZonedDateTime convert(ZonedDateTime zonedDateTime)
      Converts a ZonedDateTime to the target timezone 将ZonedDateTime转换到目标时区
      Parameters:
      zonedDateTime - the zoned date time | 带时区的日期时间
      Returns:
      the date time in target timezone | 目标时区中的日期时间

    • convert

      public ZonedDateTime convert(long epochMilli)
      Converts epoch milliseconds to the target timezone 将毫秒时间戳转换到目标时区
      Parameters:
      epochMilli - the epoch milliseconds | 毫秒时间戳
      Returns:
      the date time in target timezone | 目标时区中的日期时间

    • convertToLocal

      public LocalDateTime convertToLocal(LocalDateTime dateTime)
      Converts to LocalDateTime in the target timezone 转换为目标时区中的LocalDateTime
      Parameters:
      dateTime - the date time in source timezone | 源时区中的日期时间
      Returns:
      the local date time in target timezone | 目标时区中的本地日期时间

    • convertToOffset

      public OffsetDateTime convertToOffset(LocalDateTime dateTime)
      Converts to OffsetDateTime in the target timezone 转换为目标时区中的OffsetDateTime
      Parameters:
      dateTime - the date time in source timezone | 源时区中的日期时间
      Returns:
      the offset date time in target timezone | 目标时区中的偏移日期时间

    • convert

      public static ZonedDateTime convert(LocalDateTime dateTime, ZoneId fromZone, ZoneId toZone)
      Converts a datetime between two timezones 在两个时区之间转换日期时间
      Parameters:
      dateTime - the date time | 日期时间
      fromZone - the source timezone | 源时区
      toZone - the target timezone | 目标时区
      Returns:
      the converted date time | 转换后的日期时间

    • fromUTC

      public static ZonedDateTime fromUTC(LocalDateTime utcDateTime, ZoneId toZone)
      Converts UTC to the specified timezone 将UTC转换为指定时区
      Parameters:
      utcDateTime - the UTC date time | UTC日期时间
      toZone - the target timezone | 目标时区
      Returns:
      the converted date time | 转换后的日期时间

    • toUTC

      public static ZonedDateTime toUTC(LocalDateTime dateTime, ZoneId fromZone)
      Converts to UTC from the specified timezone 从指定时区转换为UTC
      Parameters:
      dateTime - the date time | 日期时间
      fromZone - the source timezone | 源时区
      Returns:
      the UTC date time | UTC日期时间

    • now

      public static ZonedDateTime now(ZoneId zone)
      Gets the current time in the specified timezone 获取指定时区的当前时间
      Parameters:
      zone - the timezone | 时区
      Returns:
      the current time | 当前时间

    • getOffsetHours

      public static double getOffsetHours(ZoneId zone1, ZoneId zone2)
      Gets the offset hours between two timezones 获取两个时区之间的偏移小时数
      Parameters:
      zone1 - the first timezone | 第一个时区
      zone2 - the second timezone | 第二个时区
      Returns:
      the offset hours (zone2 - zone1) | 偏移小时数

    • format

      public static String format(Instant instant, ZoneId zone, DateTimeFormatter formatter)
      Formats a datetime in the specified timezone 以指定时区格式化日期时间
      Parameters:
      instant - the instant | 时刻
      zone - the timezone | 时区
      formatter - the formatter | 格式化器
      Returns:
      the formatted string | 格式化后的字符串