* Instances of this class are used to find the current instant, which can be interpreted using the stored time-zone to * find the current date and time. As such, a clock can be used instead of {@link System#currentTimeMillis()} and * {@link TimeZone#getDefault()}. *
* Use of a {@code Clock} is optional. All key date-time classes also have a {@code now()} factory method that uses the * system clock in the default time zone. The primary purpose of this abstraction is to allow alternate clocks to be * plugged in as and when required. Applications use an object to obtain the current time rather than a static method. * This can simplify testing. *
* Best practice for applications is to pass a {@code Clock} into any method that requires the current instant. A * dependency injection framework is one way to achieve this: * *
* public class MyBean {
* private Clock clock; // dependency inject
* ...
* public void process(LocalDate eventDate) {
* if (eventDate.isBefore(LocalDate.now(clock)) {
* ...
* }
* }
* }
*
*
* This approach allows an alternate clock, such as {@link #fixed(Instant, ZoneId) fixed} or
* {@link #offset(Clock, Duration) offset} to be used during testing.
* * The {@code system} factory methods provide clocks based on the best available system clock This may use * {@link System#currentTimeMillis()}, or a higher resolution clock if one is available. *
This abstract class must be implemented with care to ensure other classes operate correctly. All * implementations that can be instantiated must be final, immutable and thread-safe. *
* The principal methods are defined to allow the throwing of an exception. In normal use, no exceptions will be thrown, * however one possible implementation would be to obtain the time from a central time server across the network. * Obviously, in this case the lookup could fail, and so the method is permitted to throw an exception. *
* The returned instants from {@code Clock} work on a time-scale that ignores leap seconds, as described in * {@link Instant}. If the implementation wraps a source that provides leap second information, then a mechanism should * be used to "smooth" the leap second. The Java Time-Scale mandates the use of UTC-SLS, however clock implementations * may choose how accurate they are with the time-scale so long as they document how they work. Implementations are * therefore not required to actually perform the UTC-SLS slew or to otherwise be aware of leap seconds. *
* Implementations should implement {@code Serializable} wherever possible and must document whether or not they do * support serialization. * implNote The clock implementation provided here is based on {@link System#currentTimeMillis()}. That method provides * little to no guarantee about the accuracy of the clock. Applications requiring a more accurate clock must implement * this abstract class themselves using a different external clock, such as an NTP server. */ public abstract class Clock { /** * Obtains a clock that returns the current instant using the best available system clock, converting to date and * time using the UTC time-zone. *
* This clock, rather than {@link #systemDefaultZone()}, should be used when you need the current instant without * the date or time. *
* This clock is based on the best available system clock. This may use {@link System#currentTimeMillis()}, or a * higher resolution clock if one is available. *
* Conversion from instant to date or time uses the {@linkplain ZoneOffset#UTC UTC time-zone}. *
* The returned implementation is immutable, thread-safe and {@code Serializable}. It is equivalent to * {@code system(ZoneOffset.UTC)}. * * @return a clock that uses the best available system clock in the UTC zone, not null */ public static Clock systemUTC() { return new SystemClock(ZoneOffset.UTC); } /** * Obtains a clock that returns the current instant using the best available system clock, converting to date and * time using the default time-zone. *
* This clock is based on the best available system clock. This may use {@link System#currentTimeMillis()}, or a * higher resolution clock if one is available. *
* Using this method hard codes a dependency to the default time-zone into your application. It is recommended to * avoid this and use a specific time-zone whenever possible. The {@link #systemUTC() UTC clock} should be used when * you need the current instant without the date or time. *
* The returned implementation is immutable, thread-safe and {@code Serializable}. It is equivalent to * {@code system(ZoneId.systemDefault())}. * * @return a clock that uses the best available system clock in the default zone, not null * @see ZoneId#systemDefault() */ public static Clock systemDefaultZone() { return new SystemClock(ZoneId.systemDefault()); } /** * Obtains a clock that returns the current instant using best available system clock. *
* This clock is based on the best available system clock. This may use {@link System#currentTimeMillis()}, or a * higher resolution clock if one is available. *
* Conversion from instant to date or time uses the specified time-zone. *
* The returned implementation is immutable, thread-safe and {@code Serializable}. * * @param zone * the time-zone to use to convert the instant to date-time, not null * @return a clock that uses the best available system clock in the specified zone, not null */ public static Clock system(ZoneId zone) { return new SystemClock(zone); } // ------------------------------------------------------------------------- /** * Obtains a clock that returns the current instant ticking in whole seconds using best available system clock. *
* This clock will always have the nano-of-second field set to zero. This ensures that the visible time ticks in * whole seconds. The underlying clock is the best available system clock, equivalent to using * {@link #system(ZoneId)}. *
* Implementations may use a caching strategy for performance reasons. As such, it is possible that the start of the * second observed via this clock will be later than that observed directly via the underlying clock. *
* The returned implementation is immutable, thread-safe and {@code Serializable}. It is equivalent to * {@code tick(system(zone), Duration.ofSeconds(1))}. * * @param zone * the time-zone to use to convert the instant to date-time, not null * @return a clock that ticks in whole seconds using the specified zone, not null */ public static Clock tickSeconds(ZoneId zone) { return new TickClock(system(zone), NANOS_PER_SECOND); } /** * Obtains a clock that returns the current instant ticking in whole minutes using best available system clock. *
* This clock will always have the nano-of-second and second-of-minute fields set to zero. This ensures that the * visible time ticks in whole minutes. The underlying clock is the best available system clock, equivalent to using * {@link #system(ZoneId)}. *
* Implementations may use a caching strategy for performance reasons. As such, it is possible that the start of the * minute observed via this clock will be later than that observed directly via the underlying clock. *
* The returned implementation is immutable, thread-safe and {@code Serializable}. It is equivalent to * {@code tick(system(zone), Duration.ofMinutes(1))}. * * @param zone * the time-zone to use to convert the instant to date-time, not null * @return a clock that ticks in whole minutes using the specified zone, not null */ public static Clock tickMinutes(ZoneId zone) { return new TickClock(system(zone), NANOS_PER_MINUTE); } /** * Obtains a clock that returns instants from the specified clock truncated to the nearest occurrence of the * specified duration. *
* This clock will only tick as per the specified duration. Thus, if the duration is half a second, the clock will * return instants truncated to the half second. *
* The tick duration must be positive. If it has a part smaller than a whole millisecond, then the whole duration * must divide into one second without leaving a remainder. All normal tick durations will match these criteria, * including any multiple of hours, minutes, seconds and milliseconds, and sensible nanosecond durations, such as * 20ns, 250,000ns and 500,000ns. *
* A duration of zero or one nanosecond would have no truncation effect. Passing one of these will return the * underlying clock. *
* Implementations may use a caching strategy for performance reasons. As such, it is possible that the start of the * requested duration observed via this clock will be later than that observed directly via the underlying clock. *
* The returned implementation is immutable, thread-safe and {@code Serializable} providing that the base clock is. * * @param baseClock * the base clock to base the ticking clock on, not null * @param tickDuration * the duration of each visible tick, not negative, not null * @return a clock that ticks in whole units of the duration, not null * @throws IllegalArgumentException * if the duration is negative, or has a part smaller than a whole millisecond such that the whole * duration is not divisible into one second */ public static Clock tick(Clock baseClock, Duration tickDuration) { if (tickDuration.isNegative()) { throw new IllegalArgumentException("Tick duration must not be negative"); } long tickNanos = tickDuration.toNanos(); if (tickNanos % 1000_000 == 0) { // ok, no fraction of millisecond } else if (1000_000_000 % tickNanos == 0) { // ok, divides into one second without remainder } else { throw new IllegalArgumentException("Invalid tick duration"); } if (tickNanos <= 1) { return baseClock; } return new TickClock(baseClock, tickNanos); } // ----------------------------------------------------------------------- /** * Obtains a clock that always returns the same instant. *
* This clock simply returns the specified instant. As such, it is not a clock in the conventional sense. The main * use case for this is in testing, where the fixed clock ensures tests are not dependent on the current clock. *
* The returned implementation is immutable, thread-safe and {@code Serializable}. * * @param fixedInstant * the instant to use as the clock, not null * @param zone * the time-zone to use to convert the instant to date-time, not null * @return a clock that always returns the same instant, not null */ public static Clock fixed(Instant fixedInstant, ZoneId zone) { return new FixedClock(fixedInstant, zone); } // ------------------------------------------------------------------------- /** * Obtains a clock that returns instants from the specified clock with the specified duration added *
* This clock wraps another clock, returning instants that are later by the specified duration. If the duration is * negative, the instants will be earlier than the current date and time. The main use case for this is to simulate * running in the future or in the past. *
* A duration of zero would have no offsetting effect. Passing zero will return the underlying clock. *
* The returned implementation is immutable, thread-safe and {@code Serializable} providing that the base clock is. * * @param baseClock * the base clock to add the duration to, not null * @param offsetDuration * the duration to add, not null * @return a clock based on the base clock with the duration added, not null */ public static Clock offset(Clock baseClock, Duration offsetDuration) { if (offsetDuration.equals(Duration.ZERO)) { return baseClock; } return new OffsetClock(baseClock, offsetDuration); } // ----------------------------------------------------------------------- /** * Constructor accessible by subclasses. */ protected Clock() { } // ----------------------------------------------------------------------- /** * Gets the time-zone being used to create dates and times. *
* A clock will typically obtain the current instant and then convert that to a date or time using a time-zone. This * method returns the time-zone used. * * @return the time-zone being used to interpret instants, not null */ public abstract ZoneId getZone(); /** * Returns a copy of this clock with a different time-zone. *
* A clock will typically obtain the current instant and then convert that to a date or time using a time-zone. This * method returns a clock with similar properties but using a different time-zone. * * @param zone * the time-zone to change to, not null * @return a clock based on this clock with the specified time-zone, not null */ public abstract Clock withZone(ZoneId zone); // ------------------------------------------------------------------------- /** * Gets the current millisecond instant of the clock. *
* This returns the millisecond-based instant, measured from 1970-01-01T00:00Z (UTC). This is equivalent to the * definition of {@link System#currentTimeMillis()}. *
* Most applications should avoid this method and use {@link Instant} to represent an instant on the time-line * rather than a raw millisecond value. This method is provided to allow the use of the clock in high performance * use cases where the creation of an object would be unacceptable. *
* The default implementation currently calls {@link #instant}. * * @return the current millisecond instant from this clock, measured from the Java epoch of 1970-01-01T00:00Z (UTC), * not null * @throws DateTimeException * if the instant cannot be obtained, not thrown by most implementations */ public long millis() { return instant().toEpochMilli(); } // ----------------------------------------------------------------------- /** * Gets the current instant of the clock. *
* This returns an instant representing the current instant as defined by the clock. * * @return the current instant from this clock, not null * @throws DateTimeException * if the instant cannot be obtained, not thrown by most implementations */ public abstract Instant instant(); // ----------------------------------------------------------------------- /** * Checks if this clock is equal to another clock. *
* Clocks should override this method to compare equals based on their state and to meet the contract of * {@link Object#equals}. If not overridden, the behavior is defined by {@link Object#equals} * * @param obj * the object to check, null returns false * @return true if this is equal to the other clock */ @Override public boolean equals(@Nullable Object obj) { return super.equals(obj); } /** * A hash code for this clock. *
* Clocks should override this method based on their state and to meet the contract of {@link Object#hashCode}. If * not overridden, the behavior is defined by {@link Object#hashCode} * * @return a suitable hash code */ @Override public int hashCode() { return super.hashCode(); } // ----------------------------------------------------------------------- /** * Implementation of a clock that always returns the latest time from {@link System#currentTimeMillis()}. */ static final class SystemClock extends Clock implements Serializable { private final ZoneId zone; SystemClock(ZoneId zone) { this.zone = zone; } @Override public ZoneId getZone() { return this.zone; } @Override public Clock withZone(ZoneId zone) { if (zone.equals(this.zone)) { // intentional NPE return this; } return new SystemClock(zone); } @Override public long millis() { return System.currentTimeMillis(); } @Override public Instant instant() { return Instant.ofEpochMilli(millis()); } @Override public boolean equals(@Nullable Object obj) { if (obj instanceof SystemClock) { return this.zone.equals(((SystemClock) obj).zone); } return false; } @Override public int hashCode() { return this.zone.hashCode() + 1; } @Override public String toString() { return "SystemClock[" + this.zone + "]"; } } // ----------------------------------------------------------------------- /** * Implementation of a clock that always returns the same instant. This is typically used for testing. */ static final class FixedClock extends Clock implements Serializable { private final Instant instant; private final ZoneId zone; FixedClock(Instant fixedInstant, ZoneId zone) { this.instant = fixedInstant; this.zone = zone; } @Override public ZoneId getZone() { return this.zone; } @Override public Clock withZone(ZoneId zone) { if (zone.equals(this.zone)) { // intentional NPE return this; } return new FixedClock(this.instant, zone); } @Override public long millis() { return this.instant.toEpochMilli(); } @Override public Instant instant() { return this.instant; } @Override public boolean equals(@Nullable Object obj) { if (obj instanceof FixedClock) { FixedClock other = (FixedClock) obj; return this.instant.equals(other.instant) && this.zone.equals(other.zone); } return false; } @Override public int hashCode() { return this.instant.hashCode() ^ this.zone.hashCode(); } @Override public String toString() { return "FixedClock[" + this.instant + "," + this.zone + "]"; } } // ----------------------------------------------------------------------- /** * Implementation of a clock that adds an offset to an underlying clock. */ static final class OffsetClock extends Clock implements Serializable { private final Clock baseClock; private final Duration offset; OffsetClock(Clock baseClock, Duration offset) { this.baseClock = baseClock; this.offset = offset; } @Override public ZoneId getZone() { return this.baseClock.getZone(); } @Override public Clock withZone(ZoneId zone) { if (zone.equals(this.baseClock.getZone())) { // intentional NPE return this; } return new OffsetClock(this.baseClock.withZone(zone), this.offset); } @Override public long millis() { return this.baseClock.millis() + this.offset.toMillis(); } @Override public Instant instant() { return this.baseClock.instant().plus(this.offset); } @Override public boolean equals(@Nullable Object obj) { if (obj instanceof OffsetClock) { OffsetClock other = (OffsetClock) obj; return this.baseClock.equals(other.baseClock) && this.offset.equals(other.offset); } return false; } @Override public int hashCode() { return this.baseClock.hashCode() ^ this.offset.hashCode(); } @Override public String toString() { return "OffsetClock[" + this.baseClock + "," + this.offset + "]"; } } // ----------------------------------------------------------------------- /** * Implementation of a clock that adds an offset to an underlying clock. */ static final class TickClock extends Clock implements Serializable { private final Clock baseClock; private final long tickNanos; TickClock(Clock baseClock, long tickNanos) { this.baseClock = baseClock; this.tickNanos = tickNanos; } @Override public ZoneId getZone() { return this.baseClock.getZone(); } @Override public Clock withZone(ZoneId zone) { if (zone.equals(this.baseClock.getZone())) { // intentional NPE return this; } return new TickClock(this.baseClock.withZone(zone), this.tickNanos); } @Override public long millis() { long millis = this.baseClock.millis(); return millis - MathUtils.floorMod(millis, this.tickNanos / 1000_000L); } @Override public Instant instant() { if ((this.tickNanos % 1000_000) == 0) { long millis = this.baseClock.millis(); return Instant.ofEpochMilli(millis - MathUtils.floorMod(millis, this.tickNanos / 1000_000L)); } Instant instant = this.baseClock.instant(); long nanos = instant.getNano(); long adjust = MathUtils.floorMod(nanos, this.tickNanos); return instant.minusNanos(adjust); } @Override public boolean equals(@Nullable Object obj) { if (obj instanceof TickClock) { TickClock other = (TickClock) obj; return this.baseClock.equals(other.baseClock) && this.tickNanos == other.tickNanos; } return false; } @Override public int hashCode() { return this.baseClock.hashCode() ^ ((int) (this.tickNanos ^ (this.tickNanos >>> 32))); } @Override public String toString() { return "TickClock[" + this.baseClock + "," + Duration.ofNanos(this.tickNanos) + "]"; } } }