/*
* Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
/*
*
*
*
*
*
* Copyright (c) 2007-2012, Stephen Colebourne & Michael Nascimento Santos
*
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* * Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* * Neither the name of JSR-310 nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package java.time;
import static java.time.
LocalTime.
NANOS_PER_MINUTE;
import static java.time.
LocalTime.
NANOS_PER_SECOND;
import java.io.
Serializable;
import java.util.
Objects;
import java.util.
TimeZone;
/**
* A clock providing access to the current instant, date and time using a time-zone.
* <p>
* 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()}.
* <p>
* 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.
* <p>
* 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:
* <pre>
* public class MyBean {
* private Clock clock; // dependency inject
* ...
* public void process(LocalDate eventDate) {
* if (eventDate.isBefore(LocalDate.now(clock)) {
* ...
* }
* }
* }
* </pre>
* This approach allows an alternate clock, such as {@link #fixed(Instant, ZoneId) fixed}
* or {@link #offset(Clock, Duration) offset} to be used during testing.
* <p>
* 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.
*
* @implSpec
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
*
* @since 1.8
*/
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.
* <p>
* This clock, rather than {@link #systemDefaultZone()}, should be used when
* you need the current instant without the date or time.
* <p>
* 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.
* <p>
* Conversion from instant to date or time uses the {@linkplain ZoneOffset#UTC UTC time-zone}.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* Conversion from instant to date or time uses the specified time-zone.
* <p>
* 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) {
Objects.
requireNonNull(
zone, "zone");
return new
SystemClock(
zone);
}
//-------------------------------------------------------------------------
/**
* Obtains a clock that returns the current instant ticking in whole seconds
* using best available system clock.
* <p>
* 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)}.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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)}.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* A duration of zero or one nanosecond would have no truncation effect.
* Passing one of these will return the underlying clock.
* <p>
* 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.
* <p>
* 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
* @throws ArithmeticException if the duration is too large to be represented as nanos
*/
public static
Clock tick(
Clock baseClock,
Duration tickDuration) {
Objects.
requireNonNull(
baseClock, "baseClock");
Objects.
requireNonNull(
tickDuration, "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.
* <p>
* 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.
* <p>
* 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) {
Objects.
requireNonNull(
fixedInstant, "fixedInstant");
Objects.
requireNonNull(
zone, "zone");
return new
FixedClock(
fixedInstant,
zone);
}
//-------------------------------------------------------------------------
/**
* Obtains a clock that returns instants from the specified clock with the
* specified duration added
* <p>
* 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.
* <p>
* A duration of zero would have no offsetting effect.
* Passing zero will return the underlying clock.
* <p>
* 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) {
Objects.
requireNonNull(
baseClock, "baseClock");
Objects.
requireNonNull(
offsetDuration, "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.
* <p>
* 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.
* <p>
* 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.
* <p>
* This returns the millisecond-based instant, measured from 1970-01-01T00:00Z (UTC).
* This is equivalent to the definition of {@link System#currentTimeMillis()}.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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(
Object obj) {
return super.equals(
obj);
}
/**
* A hash code for this clock.
* <p>
* 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 static final long
serialVersionUID = 6740630888130243051L;
private final
ZoneId zone;
SystemClock(
ZoneId zone) {
this.
zone =
zone;
}
@
Override
public
ZoneId getZone() {
return
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(
Object obj) {
if (
obj instanceof
SystemClock) {
return
zone.
equals(((
SystemClock)
obj).
zone);
}
return false;
}
@
Override
public int
hashCode() {
return
zone.
hashCode() + 1;
}
@
Override
public
String toString() {
return "SystemClock[" +
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 static final long
serialVersionUID = 7430389292664866958L;
private final
Instant instant;
private final
ZoneId zone;
FixedClock(
Instant fixedInstant,
ZoneId zone) {
this.
instant =
fixedInstant;
this.
zone =
zone;
}
@
Override
public
ZoneId getZone() {
return
zone;
}
@
Override
public
Clock withZone(
ZoneId zone) {
if (
zone.
equals(this.
zone)) { // intentional NPE
return this;
}
return new
FixedClock(
instant,
zone);
}
@
Override
public long
millis() {
return
instant.
toEpochMilli();
}
@
Override
public
Instant instant() {
return
instant;
}
@
Override
public boolean
equals(
Object obj) {
if (
obj instanceof
FixedClock) {
FixedClock other = (
FixedClock)
obj;
return
instant.
equals(
other.
instant) &&
zone.
equals(
other.
zone);
}
return false;
}
@
Override
public int
hashCode() {
return
instant.
hashCode() ^
zone.
hashCode();
}
@
Override
public
String toString() {
return "FixedClock[" +
instant + "," +
zone + "]";
}
}
//-----------------------------------------------------------------------
/**
* Implementation of a clock that adds an offset to an underlying clock.
*/
static final class
OffsetClock extends
Clock implements
Serializable {
private static final long
serialVersionUID = 2007484719125426256L;
private final
Clock baseClock;
private final
Duration offset;
OffsetClock(
Clock baseClock,
Duration offset) {
this.
baseClock =
baseClock;
this.
offset =
offset;
}
@
Override
public
ZoneId getZone() {
return
baseClock.
getZone();
}
@
Override
public
Clock withZone(
ZoneId zone) {
if (
zone.
equals(
baseClock.
getZone())) { // intentional NPE
return this;
}
return new
OffsetClock(
baseClock.
withZone(
zone),
offset);
}
@
Override
public long
millis() {
return
Math.
addExact(
baseClock.
millis(),
offset.
toMillis());
}
@
Override
public
Instant instant() {
return
baseClock.
instant().
plus(
offset);
}
@
Override
public boolean
equals(
Object obj) {
if (
obj instanceof
OffsetClock) {
OffsetClock other = (
OffsetClock)
obj;
return
baseClock.
equals(
other.
baseClock) &&
offset.
equals(
other.
offset);
}
return false;
}
@
Override
public int
hashCode() {
return
baseClock.
hashCode() ^
offset.
hashCode();
}
@
Override
public
String toString() {
return "OffsetClock[" +
baseClock + "," +
offset + "]";
}
}
//-----------------------------------------------------------------------
/**
* Implementation of a clock that adds an offset to an underlying clock.
*/
static final class
TickClock extends
Clock implements
Serializable {
private static final long
serialVersionUID = 6504659149906368850L;
private final
Clock baseClock;
private final long
tickNanos;
TickClock(
Clock baseClock, long
tickNanos) {
this.
baseClock =
baseClock;
this.
tickNanos =
tickNanos;
}
@
Override
public
ZoneId getZone() {
return
baseClock.
getZone();
}
@
Override
public
Clock withZone(
ZoneId zone) {
if (
zone.
equals(
baseClock.
getZone())) { // intentional NPE
return this;
}
return new
TickClock(
baseClock.
withZone(
zone),
tickNanos);
}
@
Override
public long
millis() {
long
millis =
baseClock.
millis();
return
millis -
Math.
floorMod(
millis,
tickNanos / 1000_000L);
}
@
Override
public
Instant instant() {
if ((
tickNanos % 1000_000) == 0) {
long
millis =
baseClock.
millis();
return
Instant.
ofEpochMilli(
millis -
Math.
floorMod(
millis,
tickNanos / 1000_000L));
}
Instant instant =
baseClock.
instant();
long
nanos =
instant.
getNano();
long
adjust =
Math.
floorMod(
nanos,
tickNanos);
return
instant.
minusNanos(
adjust);
}
@
Override
public boolean
equals(
Object obj) {
if (
obj instanceof
TickClock) {
TickClock other = (
TickClock)
obj;
return
baseClock.
equals(
other.
baseClock) &&
tickNanos ==
other.
tickNanos;
}
return false;
}
@
Override
public int
hashCode() {
return
baseClock.
hashCode() ^ ((int) (
tickNanos ^ (
tickNanos >>> 32)));
}
@
Override
public
String toString() {
return "TickClock[" +
baseClock + "," +
Duration.
ofNanos(
tickNanos) + "]";
}
}
}