Module java.base

Package java.time

Interface InstantSource

所有已知的实现类:

Clock

       public interface InstantSource
      

提供对当前时刻的访问。

此接口的实例用于访问当前时刻的可插拔表示。例如，可以使用InstantSource代替System.currentTimeMillis()。

此抽象的主要目的是允许根据需要插入替代时刻源。应用程序使用对象来获取当前时间，而不是静态方法。这可以简化测试。

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

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

  public class MyBean {
    private InstantSource source;  // 依赖注入
    ...
    public void process(Instant endInstant) {
      if (source.instant().isAfter(endInstant) {
        ...
      }
    }
  }
 

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

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

实现要求:

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

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

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

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

实现注意:

此处提供的实现基于与System.currentTimeMillis()相同的底层系统时钟，但如果可用，精度可能比毫秒更高。但是，对底层系统时钟的准确性提供了很少或没有保证。需要更准确系统时钟的应用程序必须自己实现这个抽象类，使用不同的外部系统时钟，如NTP服务器。

自:

17

Method Summary

Modifier and Type	Method	Description
static InstantSource	fixed(Instant fixedInstant)	获取始终返回相同时刻的源。
Instant	instant()	获取源的当前时刻。
default long	millis()	获取源的当前毫秒时刻。
static InstantSource	offset(InstantSource baseSource, Duration offsetDuration)	获取从指定源返回的时刻，并添加指定的持续时间的源。
static InstantSource	system()	获取使用最佳可用系统时钟返回当前时刻的源。
static InstantSource	tick(InstantSource baseSource, Duration tickDuration)	获取从指定源返回的时刻，并将其截断到指定持续时间的最近发生。
default Clock	withZone(ZoneId zone)	返回具有指定时区的时钟。

Method Details

system

             static InstantSource system()
            

获取使用最佳可用系统时钟返回当前时刻的源。

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

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

返回:

使用最佳可用系统时钟的源，非空

tick

             static InstantSource tick(InstantSource baseSource, Duration tickDuration)
            

获取从指定源返回的时刻，并将其截断到指定持续时间的最近发生。

此源将按照指定的持续时间进行滴答。因此，如果持续时间为半秒，则源将返回截断到半秒的时刻。

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

持续时间为零或一纳秒将不会有截断效果。传递其中之一将返回基础源。

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

返回的实现是不可变的、线程安全的和Serializable，前提是基础源是这样的。

参数:

baseSource - 用于基于滴答源的基础源，非空

tickDuration - 每个可见滴答的持续时间，非负，非空

返回:

以持续时间的整数单位进行滴答的源，非空

抛出:

IllegalArgumentException - 如果持续时间为负，或者其一部分小于整毫秒，以至于整个持续时间不能被一秒整除

ArithmeticException - 如果持续时间太大而无法表示为纳秒

fixed

             static InstantSource fixed(Instant fixedInstant)
            

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

此源简单地返回指定的时刻。因此，它不是代表当前时刻的源。这种情况的主要用例是在测试中，固定源确保测试不依赖于当前源。

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

参数:

fixedInstant - 要使用的时刻，非空

返回:

始终返回相同时刻的源，非空

offset

             static InstantSource offset(InstantSource baseSource, Duration offsetDuration)
            

获取从指定源返回的时刻，并添加指定的持续时间的源。

此源包装另一个源，返回比指定持续时间晚的时刻。如果持续时间为负，则时刻将早于当前日期和时间。这种情况的主要用例是模拟将来或过去的运行。

持续时间为零将不会有偏移效果。传递零将返回基础源。

返回的实现是不可变的、线程安全的和Serializable，前提是基础源是这样的。

参数:

baseSource - 要添加持续时间的基础源，非空

offsetDuration - 要添加的持续时间，非空

返回:

基于基础源并添加持续时间的源，非空

instant

             Instant instant()
            

获取源的当前时刻。

这将返回一个表示源定义的当前时刻的时刻。

返回:

来自此源的当前时刻，非空

抛出:

DateTimeException - 如果无法获取时刻，大多数实现不会抛出

millis

             default long millis()
            

获取源的当前毫秒时刻。

这将返回基于毫秒的时刻，从1970-01-01T00:00Z（UTC）开始计算。这等同于System.currentTimeMillis()的定义。

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

实现要求:

默认实现调用instant()。

返回:

来自此源的当前毫秒时刻，从1970-01-01T00:00Z（UTC）的Java纪元开始计算，非空

抛出:

DateTimeException - 如果无法获取时刻，大多数实现不会抛出

withZone

             default Clock withZone(ZoneId zone)
            

返回具有指定时区的时钟。

这将返回一个Clock，它是此接口的扩展，结合了此源和指定的时区。

返回的实现是不可变的、线程安全的和Serializable，前提是此源是这样的。

实现要求:

默认实现返回一个不可变的、线程安全的、Serializable子类的Clock，它结合了此源和指定的时区。

参数:

zone - 要使用的时区，非空

返回:

基于此源并具有指定时区的时钟，非空