模块  java.base
软件包  java.time

Class Clock


  • public abstract class Clock
    extends Object
    一个时钟,使用时区提供对当前时刻,日期和时间的访问。

    此类的实例用于查找当前时刻,可以使用存储的时区来解释当前时刻以查找当前日期和时间。 因此,可以使用时钟代替System.currentTimeMillis()TimeZone.getDefault()

    使用Clock是可选的。 所有关键日期时间类还具有now()工厂方法,该方法在默认时区中使用系统时钟。 这种抽象的主要目的是允许在需要时插入备用时钟。 应用程序使用对象来获取当前时间而不是静态方法。 这可以简化测试。

    应用程序的最佳实践是将Clock传递给任何需要当前瞬间的方法。 依赖注入框架是实现此目的的一种方法:

      public class MyBean {
        private Clock clock;  // dependency inject
        ...
        public void process(LocalDate eventDate) {
          if (eventDate.isBefore(LocalDate.now(clock)) {
            ...
          }
        }
      } 
    此方法允许在测试期间使用备用时钟,例如fixedoffset

    system工厂方法基于最佳可用系统时钟提供时钟。这可以使用System.currentTimeMillis() ,或者如果有可用的更高分辨率时钟。

    实现要求:
    必须小心实现此抽象类,以确保其他类正常运行。 可以实例化的所有实现必须是最终的,不可变的和线程安全的。

    定义主要方法以允许抛出异常。 在正常使用中,不会抛出任何异常,但是一种可能的实现方式是从中央时间服务器通过网络获取时间。 显然,在这种情况下,查找可能会失败,因此允许该方法抛出异常。

    Clock返回的瞬间在忽略闰秒的时间尺度上工作,如Instant中所述 如果实现包装提供闰秒信息的源,则应使用一种机制来“平滑”闰秒。 Java Time-Scale要求使用UTC-SLS,但是时钟实现可以选择它们与时间尺度的准确程度,只要它们记录它们的工作方式即可。 因此,实现不需要实际执行UTC-SLS转换或以其他方式了解闰秒。

    实现应尽可能实施Serializable并且必须记录它们是否支持序列化。

    Implementation Note:
    此处提供的时钟实现基于与System.currentTimeMillis()相同的基础时钟,但如果可用,则可能具有比毫秒更精细的精度。 但是,对于基础时钟的准确性几乎没有保证。 需要更精确时钟的应用程序必须使用不同的外部时钟(例如NTP服务器)自行实现此抽象类。
    从以下版本开始:
    1.8
    • 构造方法摘要

      构造方法  
      变量 构造器 描述
      protected Clock()
      子类可访问的构造函数。
    • 构造方法详细信息

      • Clock

        protected Clock()
        子类可访问的构造函数。
    • 方法详细信息

      • systemUTC

        public static Clock systemUTC()
        获得使用最佳可用系统时钟返回当前时刻的时钟,使用UTC时区转换为日期和时间。

        当您需要当前时刻而没有日期或时间时,应使用此时钟而不是systemDefaultZone()

        该时钟基于最佳可用系统时钟。 这可以使用System.currentTimeMillis() ,或者更高分辨率的时钟(如果有)。

        从即日转换为日期或时间使用UTC time-zone

        返回的实现是不可变的,线程安全的和Serializable 它相当于system(ZoneOffset.UTC)

        结果
        使用UTC区域中最佳可用系统时钟的时钟,不为空
      • systemDefaultZone

        public static Clock systemDefaultZone()
        获得使用最佳可用系统时钟返回当前时刻的时钟,使用默认时区转换为日期和时间。

        该时钟基于最佳可用系统时钟。 这可以使用System.currentTimeMillis() ,或者更高分辨率的时钟(如果有)。

        使用此方法硬编码依赖于应用程序的默认时区。 建议尽量避免这种情况并使用特定的时区。 当您需要当前时刻而没有日期或时间时,应使用UTC clock

        返回的实现是不可变的,线程安全的和Serializable 它相当于system(ZoneId.systemDefault())

        结果
        使用默认区域中最佳可用系统时钟的时钟,不为空
        另请参见:
        ZoneId.systemDefault()
      • system

        public static Clock system​(ZoneId zone)
        获得使用最佳可用系统时钟返回当前时刻的时钟。

        该时钟基于最佳可用系统时钟。 这可以使用System.currentTimeMillis() ,或者更高分辨率的时钟(如果有)。

        从即时到日期或时间的转换使用指定的时区。

        返回的实现是不可变的,线程安全的和Serializable

        参数
        zone - 用于将即时转换为日期时间的时区,而不是null
        结果
        使用指定区域中最佳可用系统时钟的时钟,不为空
      • tickMillis

        public static Clock tickMillis​(ZoneId zone)
        获得一个时钟,使用最佳可用系统时钟以整数毫秒返回当前时刻。

        此时钟将始终具有截断到毫秒的纳秒级字段。 这确保了可见时间以整数毫秒为单位。 基础时钟是最佳可用系统时钟,相当于使用system(ZoneId)

        出于性能原因,实现可能会使用缓存策略。 因此,通过该时钟观察到的毫秒开始可能晚于通过基础时钟直接观察到的毫秒。

        返回的实现是不可变的,线程安全的和Serializable 它相当于tick(system(zone), Duration.ofMillis(1))

        参数
        zone - 用于将即时转换为日期时间的时区,而不是null
        结果
        使用指定区域以整数毫秒计时的时钟,不为空
        从以下版本开始:
        9
      • tickSeconds

        public static Clock tickSeconds​(ZoneId zone)
        获得一个时钟,使用最佳可用系统时钟返回当前瞬间滴答作用。

        此时钟始终将纳秒级字段设置为零。 这可确保可见时间在整秒内完成。 基础时钟是最佳可用系统时钟,相当于使用system(ZoneId)

        出于性能原因,实现可能会使用缓存策略。 因此,通过该时钟观察到的第二个开始可能晚于通过底层时钟直接观察到的开始。

        返回的实现是不可变的,线程安全的和Serializable 它相当于tick(system(zone), Duration.ofSeconds(1))

        参数
        zone - 用于将即时转换为日期时间的时区,而不是null
        结果
        使用指定区域在整秒内打勾的时钟,不为空
      • tickMinutes

        public static Clock tickMinutes​(ZoneId zone)
        获得一个时钟,使用最佳可用系统时钟在整个分钟内返回当前时刻。

        此时钟将始终将纳秒级和秒级字段设置为零。 这可确保可见时间在整个分钟内完成。 基础时钟是最佳可用系统时钟,相当于使用system(ZoneId)

        出于性能原因,实现可能会使用缓存策略。 因此,通过该时钟观察到的分钟开始可能晚于通过基础时钟直接观察到的开始。

        返回的实现是不可变的,线程安全的和Serializable 它相当于tick(system(zone), Duration.ofMinutes(1))

        参数
        zone - 用于将即时转换为日期时间的时区,而不是null
        结果
        使用指定区域在整个分钟内打勾的时钟,不为空
      • tick

        public static Clock tick​(Clock baseClock,
                                 Duration tickDuration)
        获得一个时钟,该时钟将指定时钟的瞬间返回到指定持续时间的最近出现位置。

        此时钟仅按指定的持续时间进行计时。 因此,如果持续时间是半秒,则时钟将返回瞬间截断到半秒。

        滴答持续时间必须为正。 如果它的部分小于整个毫秒,则整个持续时间必须分成一秒而不留下余数。 所有正常的滴答持续时间将符合这些标准,包括小时,分钟,秒和毫秒的任何倍数,以及合理的纳秒持续时间,例如20ns,250,000ns和500,000ns。

        零或一纳秒的持续时间将没有截断效应。 传递其中一个将返回基础时钟。

        出于性能原因,实现可能会使用缓存策略。 因此,通过该时钟观察到的所请求持续时间的开始可能晚于通过基础时钟直接观察到的持续时间的开始。

        返回的实现是不可变的,线程安全的, Serializable提供了基本时钟的Serializable

        参数
        baseClock - 基于打勾时钟的基准时钟,非空
        tickDuration - 每个可见刻度的持续时间,不是负数,不是空
        结果
        一个时钟,以持续时间的整个单位为单位,而不是空
        异常
        IllegalArgumentException - 如果持续时间为负,或者部分小于整整毫秒,则整个持续时间不可分为一秒
        ArithmeticException - 如果持续时间太长而无法表示为nanos
      • fixed

        public static Clock fixed​(Instant fixedInstant,
                                  ZoneId zone)
        获得一个始终返回同一时刻的时钟。

        此时钟只返回指定的时刻。 因此,它不是传统意义上的时钟。 其主要用途是测试,其中固定时钟确保测试不依赖于当前时钟。

        返回的实现是不可变的,线程安全的和Serializable

        参数
        fixedInstant - 用作时钟的瞬间,不为空
        zone - 用于将即时转换为日期时间的时区,而不是null
        结果
        一个总是返回同一时刻的时钟,而不是空
      • offset

        public static Clock offset​(Clock baseClock,
                                   Duration offsetDuration)
        获得一个时钟,该时钟返回指定时钟的瞬间,并添加指定的持续时间

        这个时钟包装另一个时钟,返回稍后指定持续时间的瞬间。 如果持续时间为负,则时刻将早于当前日期和时间。 这个的主要用例是模拟将来或过去的运行。

        持续时间为零将没有抵消效应。 传递零将返回基础时钟。

        返回的实现是不可变的,线程安全的, Serializable提供基本时钟的Serializable

        参数
        baseClock - 将持续时间添加到的基准时钟,而不是null
        offsetDuration - 要添加的持续时间,而不是null
        结果
        基于基本时钟的时钟,其持续时间已添加,不为空
      • getZone

        public abstract ZoneId getZone()
        获取用于创建日期和时间的时区。

        时钟通常会获得当前时刻,然后使用时区将其转换为日期或时间。 此方法返回使用的时区。

        结果
        用于解释时刻的时区,而不是空
      • withZone

        public abstract Clock withZone​(ZoneId zone)
        返回具有不同时区的此时钟的副本。

        时钟通常会获得当前时刻,然后使用时区将其转换为日期或时间。 此方法返回具有类似属性但使用不同时区的时钟。

        参数
        zone - 要更改为的时区,而不是null
        结果
        基于此时钟的时钟,具有指定的时区,不为空
      • millis

        public long millis()
        获取时钟的当前毫秒时刻。

        这将返回从1970-01-01T00:00Z(UTC)开始测量的基于毫秒的瞬间。 这相当于System.currentTimeMillis()的定义。

        大多数应用程序应该避免使用此方法,并使用Instant来表示时间线上的瞬间而不是原始毫秒值。 提供该方法是为了允许在高性能用例中使用时钟,其中对象的创建是不可接受的。

        默认实现当前调用instant()

        结果
        这个时钟的当前毫秒时刻,从1970-01-01T00:00Z(UTC)的Java时代测量,不为空
        异常
        DateTimeException - 如果无法获得瞬间,则不会被大多数实现抛出
      • instant

        public abstract Instant instant()
        获取时钟的当前瞬间。

        这将返回表示时钟定义的当前时刻的瞬间。

        结果
        从这个时钟开始的当前瞬间,不是空的
        异常
        DateTimeException - 如果无法获得瞬间,则不会被大多数实现抛出