java.lang.Object

java.time.Clock

所有已实现的接口:: InstantSource

public abstract class Clock extends Object implements InstantSource

通过时区提供对当前时刻、日期和时间的访问的时钟。

此抽象类的实例用于访问当前时刻的可插拔表示，可以使用存储的时区解释该时刻以找到当前日期和时间。例如，Clock可以用来代替System.currentTimeMillis()和TimeZone.getDefault()。

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

因此，此抽象类不保证结果实际上代表时间线上的当前时刻。相反，它允许应用程序提供关于当前时刻和时区的受控视图。

应用程序的最佳实践是将Clock传递给任何需要当前时刻和时区的方法。依赖注入框架是实现这一目标的一种方法:

  public class MyBean {
    private Clock clock;  // 依赖注入
    ...
    public void process(LocalDate eventDate) {
      if (eventDate.isBefore(LocalDate.now(clock)) {
        ...
      }
    }
  }

这种方法允许在测试期间使用替代时钟，例如fixed或offset。

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

实现要求:

必须谨慎实现此抽象类，以确保其他类能够正确运行。所有实现必须是线程安全的 - 单个实例必须能够从多个线程调用而不会出现负面后果，如竞态条件。

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

Clock返回的时刻在一个忽略闰秒的时间刻度上工作，如Instant中所述。如果实现包装了提供闰秒信息的源，则应使用一种机制来“平滑”闰秒。Java时间刻度规定使用UTC-SLS，但是时钟实现可以选择它们在时间刻度上的准确性，只要它们记录它们的工作方式。因此，实现不需要实际执行UTC-SLS的调整或以其他方式意识到闰秒。

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

自Java版本:

1.8

参见:

Constructor Summary

Constructors

Modifier

Constructor

Description

protected

Clock()

子类可访问的构造函数。
Method Summary

Modifier and Type

Method

Description

boolean

equals(Object obj)

检查此时钟是否等于另一个时钟。

static Clock

fixed(Instant fixedInstant, ZoneId zone)

获取始终返回相同时刻的时钟。

abstract ZoneId

getZone()

获取用于创建日期和时间的时区。

int

hashCode()

此时钟的哈希码。

abstract Instant

instant()

获取时钟的当前时刻。

long

millis()

获取时钟的当前毫秒时刻。

static Clock

offset(Clock baseClock, Duration offsetDuration)

获取一个时钟，该时钟从指定的时钟返回的时刻中添加指定的持续时间。

static Clock

system(ZoneId zone)

获取一个时钟，该时钟使用最佳可用系统时钟返回当前时刻。

static Clock

systemDefaultZone()

获取一个时钟，该时钟使用最佳可用系统时钟返回当前时刻，并使用默认时区转换为日期和时间。

static Clock

systemUTC()

获取一个时钟，该时钟使用最佳可用系统时钟返回当前时刻，并使用UTC时区转换为日期和时间。

static Clock

tick(Clock baseClock, Duration tickDuration)

获取一个时钟，该时钟返回从指定时钟截断到指定持续时间最近发生的时刻。

static Clock

tickMillis(ZoneId zone)

获取一个时钟，该时钟使用最佳可用系统时钟以整毫秒为单位返回当前时刻。

static Clock

tickMinutes(ZoneId zone)

获取一个时钟，该时钟使用最佳可用系统时钟以整分钟为单位返回当前时刻。

static Clock

tickSeconds(ZoneId zone)

获取一个时钟，该时钟使用最佳可用系统时钟以整秒为单位返回当前时刻。

abstract Clock

withZone(ZoneId zone)

返回具有不同时区的此时钟的副本。

Methods declared in class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- Clock
  
  protected Clock()
  
  子类可访问的构造函数。
Method Details
- systemUTC
  
  public static Clock systemUTC()
  
  获取一个时钟，该时钟使用最佳可用系统时钟返回当前时刻，并使用UTC时区转换为日期和时间。
  当您需要当前时刻而不需要日期或时间时，应使用此时钟，而不是systemDefaultZone()。
  
  此时钟基于最佳可用系统时钟。这可能使用System.currentTimeMillis()，或者如果有可用的更高分辨率时钟，则使用该时钟。
  
  从时刻到日期或时间的转换使用UTC时区。
  
  返回的实现是不可变的、线程安全的和Serializable。它等效于system(ZoneOffset.UTC)。
  
  返回:
  
  使用UTC时区中最佳可用系统时钟的时钟，非空
- systemDefaultZone
  
  public static Clock systemDefaultZone()
  
  获取一个时钟，该时钟使用最佳可用系统时钟返回当前时刻，并使用默认时区转换为日期和时间。
  此时钟基于最佳可用系统时钟。这可能使用System.currentTimeMillis()，或者如果有可用的更高分辨率时钟，则使用该时钟。
  
  使用此方法将默认时区的依赖性硬编码到您的应用程序中。建议尽可能避免这样做，并在可能的情况下使用特定的时区。当您需要当前时刻而不需要日期或时间时，应使用UTC时钟。
  
  返回的实现是不可变的、线程安全的和Serializable。它等效于system(ZoneId.systemDefault())。
  返回:
  
  使用默认时区中最佳可用系统时钟的时钟，非空
  
  参见:
  
  ZoneId.systemDefault()
- system
  
  public static Clock system(ZoneId zone)
  
  获取一个时钟，该时钟使用最佳可用系统时钟返回当前时刻。
  此时钟基于最佳可用系统时钟。这可能使用System.currentTimeMillis()，或者如果有可用的更高分辨率时钟，则使用该时钟。
  
  从时刻到日期或时间的转换使用指定的时区。
  
  返回的实现是不可变的、线程安全的和Serializable。
  
  参数:
  
  zone - 用于将时刻转换为日期时间的时区，非空
  
  返回:
  
  使用指定时区中最佳可用系统时钟的时钟，非空
- tickMillis
  
  public static Clock tickMillis(ZoneId zone)
  
  获取一个时钟，该时钟使用最佳可用系统时钟以整毫秒为单位返回当前时刻。
  此时钟将始终将纳秒字段截断为毫秒。这确保可见时间以整毫秒为单位。底层时钟是最佳可用系统时钟，等效于使用system(ZoneId)。
  
  出于性能原因，实现可能使用缓存策略。因此，通过此时钟观察到的毫秒的开始可能晚于直接通过底层时钟观察到的毫秒的开始。
  
  返回的实现是不可变的、线程安全的和Serializable。它等效于tick(system(zone), Duration.ofMillis(1))。
  
  参数:
  
  zone - 用于将时刻转换为日期时间的时区，非空
  
  返回:
  
  使用指定时区中以整毫秒为单位进行滴答的时钟，非空
  
  自Java版本:
  
  9
- tickSeconds
  
  public static Clock tickSeconds(ZoneId zone)
  
  获取一个时钟，该时钟使用最佳可用系统时钟以整秒为单位返回当前时刻。
  此时钟将始终将纳秒字段设置为零。这确保可见时间以整秒为单位。底层时钟是最佳可用系统时钟，等效于使用system(ZoneId)。
  
  出于性能原因，实现可能使用缓存策略。因此，通过此时钟观察到的秒的开始可能晚于直接通过底层时钟观察到的秒的开始。
  
  返回的实现是不可变的、线程安全的和Serializable。它等效于tick(system(zone), Duration.ofSeconds(1))。
  
  参数:
  
  zone - 用于将时刻转换为日期时间的时区，非空
  
  返回:
  
  使用指定时区中以整秒为单位进行滴答的时钟，非空
- tickMinutes
  
  public static Clock tickMinutes(ZoneId zone)
  
  获取一个时钟，该时钟使用最佳可用系统时钟以整分钟为单位返回当前时刻。
  此时钟将始终将纳秒和秒字段设置为零。这确保可见时间以整分钟为单位。底层时钟是最佳可用系统时钟，等效于使用system(ZoneId)。
  
  出于性能原因，实现可能使用缓存策略。因此，通过此时钟观察到的分钟的开始可能晚于直接通过底层时钟观察到的分钟的开始。
  
  返回的实现是不可变的、线程安全的和Serializable。它等效于tick(system(zone), Duration.ofMinutes(1))。
  
  参数:
  
  zone - 用于将时刻转换为日期时间的时区，不能为空
  
  返回:
  
  一个以指定时区整分钟为单位的时钟，不能为空
- tick
  
  public static Clock tick(Clock baseClock, Duration tickDuration)
  
  获取一个时钟，该时钟返回从指定时钟截断到最接近指定持续时间的时刻。
  此时钟将仅按照指定的持续时间进行滴答。因此，如果持续时间为半秒，则时钟将返回截断到半秒的时刻。
  
  滴答持续时间必须为正。如果它的部分小于整毫秒，则整个持续时间必须能够整除一秒而不留下余数。所有正常的滴答持续时间都将符合这些标准，包括任何小时、分钟、秒和毫秒的倍数，以及合理的纳秒持续时间，例如20ns、250,000ns和500,000ns。
  
  持续时间为零或一纳秒将不会产生截断效果。传递其中之一将返回基础时钟。
  
  实现可能会出于性能原因使用缓存策略。因此，通过此时钟观察到的请求持续时间的开始可能晚于直接通过基础时钟观察到的时间。
  
  返回的实现是不可变的、线程安全的，并且如果基础时钟是可序列化的，则也是Serializable。
  
  参数:
  
  baseClock - 用于基于其创建滴答时钟的基础时钟，不能为空
  
  tickDuration - 每个可见滴答的持续时间，不能为负，不能为空
  
  返回:
  
  一个以持续时间整单位为单位的时钟，不能为空
  
  抛出:
  
  IllegalArgumentException - 如果持续时间为负，或者其部分小于整毫秒，以至于整个持续时间不能被整除为一秒
  
  ArithmeticException - 如果持续时间太大而无法表示为纳秒
- fixed
  
  public static Clock fixed(Instant fixedInstant, ZoneId zone)
  
  获取一个始终返回相同时刻的时钟。
  此时钟简单地返回指定的时刻。因此，从传统意义上讲，它不是一个时钟。这种情况的主要用例是在测试中，固定时钟确保测试不依赖于当前时钟。
  
  返回的实现是不可变的、线程安全的，并且Serializable。
  
  参数:
  
  fixedInstant - 用作时钟的时刻，不能为空
  
  zone - 用于将时刻转换为日期时间的时区，不能为空
  
  返回:
  
  一个始终返回相同时刻的时钟，不能为空
- offset
  
  public static Clock offset(Clock baseClock, Duration offsetDuration)
  
  获取一个时钟，该时钟返回从指定时钟中添加指定持续时间后的时刻。
  此时钟包装另一个时钟，返回晚于指定持续时间的时刻。如果持续时间为负，则时刻将早于当前日期和时间。这种情况的主要用例是模拟将来或过去的运行。
  
  持续时间为零将不会产生偏移效果。传递零将返回基础时钟。
  
  返回的实现是不可变的、线程安全的，并且如果基础时钟是可序列化的，则也是Serializable。
  
  参数:
  
  baseClock - 要添加持续时间的基础时钟，不能为空
  
  offsetDuration - 要添加的持续时间，不能为空
  
  返回:
  
  基于基础时钟并添加持续时间的时钟，不能为空
- getZone
  
  public abstract ZoneId getZone()
  
  获取用于创建日期和时间的时区。
  时钟通常会获取当前时刻，然后使用时区将其转换为日期或时间。此方法返回所使用的时区。
  
  返回:
  
  用于解释时刻的时区，不能为空
- withZone
  
  public abstract Clock withZone(ZoneId zone)
  
  返回具有不同时区的此时钟的副本。
  时钟通常会获取当前时刻，然后使用时区将其转换为日期或时间。此方法返回具有类似属性但使用不同时区的时钟。
  
  指定者:
  
  withZone 在接口 InstantSource中
  
  参数:
  
  zone - 要更改为的时区，不能为空
  
  返回:
  
  基于此时钟并具有指定时区的时钟，不能为空
- millis
  
  public long millis()
  
  获取时钟的当前毫秒时刻。
  返回基于毫秒的时刻，从1970-01-01T00:00Z（UTC）开始测量。这等同于System.currentTimeMillis()的定义。
  
  大多数应用程序应避免使用此方法，并使用Instant来表示时间线上的时刻，而不是原始毫秒值。此方法的提供是为了允许在高性能用例中使用时钟，其中创建对象是不可接受的。
  
  默认实现当前调用instant()。
  
  指定者:
  
  millis 在接口 InstantSource中
  
  返回:
  
  从此时钟获取的当前毫秒时刻，从Java纪元1970-01-01T00:00Z（UTC）开始测量，不能为空
  
  抛出:
  
  DateTimeException - 如果无法获取时刻，大多数实现不会抛出
- instant
  
  public abstract Instant instant()
  
  获取时钟的当前时刻。
  返回表示由时钟定义的当前时刻的时刻。
  
  指定者:
  
  instant 在接口 InstantSource中
  
  返回:
  
  从此时钟获取的当前时刻，不能为空
  
  抛出:
  
  DateTimeException - 如果无法获取时刻，大多数实现不会抛出
- equals
  
  public boolean equals(Object obj)
  
  检查此时钟是否等于另一个时钟。
  时钟应该根据其状态覆盖此方法以基于它们的状态进行比较，并满足Object.equals(java.lang.Object)的合同。如果未被覆盖，行为由Object.equals(java.lang.Object)定义
  覆盖:
  
  equals 在类 Object中
  
  参数:
  
  obj - 要检查的对象，null返回false
  
  返回:
  
  如果此时钟等于另一个时钟，则为true
  
  参见:
  
  Object.hashCode()
  
  HashMap
- hashCode
  
  public int hashCode()
  
  此时钟的哈希码。
  时钟应该根据其状态覆盖此方法以基于它们的状态进行比较，并满足Object.hashCode()的合同。如果未被覆盖，行为由Object.hashCode()定义
  覆盖:
  
  hashCode 在类 Object中
  
  返回:
  
  适当的哈希码
  
  参见:
  
  Object.equals(java.lang.Object)
  
  System.identityHashCode(java.lang.Object)

Class Clock

Constructor Summary

Method Summary

Methods declared in class java.lang.Object

Constructor Details

Clock

Method Details

systemUTC

systemDefaultZone

system

tickMillis

tickSeconds

tickMinutes

tick

fixed

offset

getZone

withZone

millis

instant

equals

hashCode