- java.lang.Object
-
- java.time.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)) { ... } } }
这种方法允许在测试期间使用替代时钟,例如fixed
或offset
。system
工厂方法基于最佳可用系统时钟提供时钟这可能使用System.currentTimeMillis()
或更高分辨率的时钟(如果有)。- 实现要求:
-
这个抽象类必须小心实现,以确保其他类正确运行。
可以实例化的所有实现必须是最终的,不可变的和线程安全的。
主要方法被定义为允许抛出异常。 在正常使用中,不会抛出任何异常,但是一个可能的实现是从中央时间服务器通过网络获取时间。 显然,在这种情况下,查找可能会失败,因此允许该方法抛出异常。
从返回的时刻
Clock
上的时间尺度工作忽略闰秒,如在描述Instant
。 如果实现包装了提供闰秒信息的源,那么应该使用一个机制来“平滑”闰秒。 Java时间尺度要求使用UTC-SLS,但是只要记录它们的工作原理,时钟实现可以选择它们与时间尺度的准确度。 因此实际上不需要实际执行UTC-SLS转换,否则不需要知道闰秒。实施应尽可能实施
Serializable
并且必须记录它们是否支持序列化。 - Implementation Note:
-
这里提供的时钟实现基于与
System.currentTimeMillis()
相同的底层时钟,但是如果可用,则可能具有比毫秒更精细的精度。 然而,关于基础时钟的准确性几乎没有保证。 需要更精确时钟的应用程序必须使用不同的外部时钟(如NTP服务器)实现此抽象类。 - 从以下版本开始:
- 1.8
-
-
构造方法摘要
构造方法 Modifier Constructor 描述 protected
Clock()
子类可访问的构造方法。
-
方法摘要
所有方法 静态方法 接口方法 抽象方法 具体的方法 Modifier and Type 方法 描述 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)
以不同的时区返回此时钟的副本。
-
-
-
方法详细信息
-
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
- 用于将即时转换为日期时间的时区,不为空 - 结果
- 在指定区域中使用最佳可用系统时钟的时钟,不为空
-
tickMillis
public static Clock tickMillis(ZoneId zone)
获取时钟,使用最佳可用系统时钟返回当前瞬间滴答整数毫秒。这个时钟将始终将纳秒的字段截断为毫秒。 这可以确保可见的时间在整个毫秒内打勾。 底层时钟是最佳可用系统时钟,相当于使用
system(ZoneId)
。出于性能原因,实施可能会使用缓存策略。 因此,可能通过该时钟观察到的毫秒的开始将晚于通过底层时钟直接观察到的毫秒的开始。
返回的实现是不可变的,线程安全的和
Serializable
。 相当于tick(system(zone), Duration.ofMillis(1))
。- 参数
-
zone
- 用于将即时转换为日期时间的时区,不为空 - 结果
- 一个使用指定区域,以毫秒为单位的时钟,不为空
- 从以下版本开始:
- 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
- 每个可见tick的持续时间,而不是负数,不为null - 结果
- 一个以整个单位记录的时钟,不为零
- 异常
-
IllegalArgumentException
- 如果持续时间为负,或者具有小于整个毫秒的部分,使得整个持续时间不能被整除为一秒 -
ArithmeticException
- 如果持续时间太大而无法表示为纳米
-
fixed
public static Clock fixed(Instant fixedInstant, ZoneId zone)
获得始终返回相同时刻的时钟。这个时钟只需返回指定的时刻。 因此,它不是常规意义上的时钟。 主要用例是测试,固定时钟确保测试不依赖于当前时钟。
返回的实现是不可变的,线程安全的和
Serializable
。- 参数
-
fixedInstant
- 即时使用时钟,不为空 -
zone
- 用于将即时转换为日期时间的时区,不为空 - 结果
- 一个总是返回相同时刻的时钟,而不是null
-
offset
public static Clock offset(Clock baseClock, Duration offsetDuration)
获取一个时钟,从指定的时钟周期返回时钟,并添加指定的时间这个时钟包裹另一个时钟,返回稍后指定持续时间的时刻。 如果持续时间为负,则时间将早于当前日期和时间。 这个的主要用例是模拟未来或过去的运行。
零的持续时间将没有抵消效果。 传递零将返回底层时钟。
返回的实现是不可变的,线程安全的,
Serializable
提供基本时钟。- 参数
-
baseClock
- 基本时钟添加持续时间,不为null -
offsetDuration
- 添加的持续时间,不为null - 结果
- 基于基本时钟的时钟,持续时间加上,不为空
-
getZone
public abstract ZoneId getZone()
获取用于创建日期和时间的时区。时钟通常将获得当前时刻,然后使用时区将其转换为日期或时间。 此方法返回使用的时区。
- 结果
- 用于解释时刻的时区,不为空
-
withZone
public abstract Clock withZone(ZoneId zone)
以不同的时区返回此时钟的副本。时钟通常将获得当前时刻,然后使用时区将其转换为日期或时间。 此方法返回具有相似属性但使用不同时区的时钟。
- 参数
-
zone
- 时区改为,不为空 - 结果
- 基于此时钟的时钟具有指定的时区,不为空
-
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
- 如果无法获取该时刻,则不会被大多数实现抛出
-
equals
public boolean equals(Object obj)
检查这个时钟是否等于另一个时钟。时钟应该覆盖此方法,以根据其状态比较平等,并符合
Object.equals(java.lang.Object)
的合同。 如果不覆盖,行为由Object.equals(java.lang.Object)
定义- 重写:
-
equals
在Object
- 参数
-
obj
- 要检查的对象,null返回false - 结果
- 如果这等于其他时钟,则为真
- 另请参见:
-
Object.hashCode()
,HashMap
-
hashCode
public int hashCode()
这个时钟的哈希码。时钟应根据其状态来覆盖此方法,并符合
Object.hashCode()
的合同。 如果不覆盖,行为由Object.hashCode()
定义- 重写:
-
hashCode
在Object
- 结果
- 一个合适的哈希码
- 另请参见:
-
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
-