Module org.threeten.extra
Package org.threeten.extra

Class MutableClock

  • All Implemented Interfaces:
    Serializable
    public final class MutableClock
extends Clock
implements Serializable
    A clock that does not advance on its own and that must be updated manually.

    This class is designed for testing clock-sensitive components by simulating the passage of time. This class differs from Clock.fixed(Instant, ZoneId) and Clock.offset(Clock, Duration) in that it permits arbitrary, unrestricted updates to its instant. This allows for testing patterns that are not well-supported by the fixed and offset clocks such as the following pattern:

    1. Create the clock-sensitive component to be tested
    2. Verify some behavior of the component in the initial state
    3. Advance the clock without recreating the component
    4. Verify that the component behaves as expected given the (artificial) delta in clock time since the initial state

    This class is mutable. The time-zone of the clock is fixed, but the instant may be updated at will.

    The instant may be set to any value even if that new value is less than the previous value. Caution should be exercised when moving the clock backwards, since clock-sensitive components are likely to assume that time is monotonically increasing.

    Update semantics are expressed in terms of ZonedDateTime. The steps of each update are as follows:

    1. The clock captures its own state in a ZonedDateTime via ZonedDateTime.now(Clock) (or the equivalent thereof)
    2. The update operation is applied to that ZonedDateTime, producing a new ZonedDateTime
    3. The resulting ZonedDateTime is converted to an instant via ChronoZonedDateTime.toInstant() (or the equivalent thereof)
    4. The clock's instant is set to that new instant

    Therefore, whenever there is a question about what argument types, units, fields, or values an update operation supports, or what the result will be, refer to the corresponding method of ZonedDateTime. Links are provided from the documentation of each update operation of this class to the corresponding method of ZonedDateTime.

    Implementation Requirements:

    This class is thread-safe. Updates are atomic and synchronized.

    While update semantics are expressed in terms of ZonedDateTime, that imposes no requirements on implementation details. The implementation may avoid using ZonedDateTime completely or only sometimes, for convenience, efficiency, or any other reason.

    • Method Detail

      • epochUTC

        public static MutableClock epochUTC()
        Obtains a new MutableClock set to the epoch of 1970-01-01T00:00:00Z, converting to date and time using the UTC time-zone.

        Use this method when a MutableClock is needed and neither its initial value nor its time-zone are important. This is often true when testing behavior that depends on elapsed relative time rather than absolute time.

        Returns:
        a new MutableClock, not null

      • of

        public static MutableClock of​(Instant instant,
                              ZoneId zone)
        Obtains a new MutableClock set to the specified instant, converting to date and time using the specified time-zone.
        Parameters:
        instant - the initial value for the clock, not null
        zone - the time-zone to use, not null
        Returns:
        a new MutableClock, not null

      • setInstant

        public void setInstant​(Instant instant)
        Overrides the instant of this clock with the specified value.
        Parameters:
        instant - the new instant for this clock, not null

      • add

        public void add​(TemporalAmount amountToAdd)
        Adds the specified amount to this clock.

        Atomically updates this clock to the value of the following expression: 

           ZonedDateTime.now(thisClock)
                .plus(amountToAdd)
                .toInstant()
        Parameters:
        amountToAdd - the amount to add, not null
        Throws:
        DateTimeException - if the addition cannot be made
        ArithmeticException - if numeric overflow occurs
        See Also:
        ZonedDateTime.plus(TemporalAmount)

      • add

        public void add​(long amountToAdd,
                TemporalUnit unit)
        Adds the specified amount to this clock.

        Atomically updates this clock to the value of the following expression: 

           ZonedDateTime.now(thisClock)
                .plus(amountToAdd, unit)
                .toInstant()
        Parameters:
        amountToAdd - the amount of the specified unit to add, may be negative
        unit - the unit of the amount to add, not null
        Throws:
        DateTimeException - if the unit cannot be added
        UnsupportedTemporalTypeException - if the unit is not supported
        ArithmeticException - if numeric overflow occurs
        See Also:
        ZonedDateTime.plus(long, TemporalUnit)

      • withZone

        public MutableClock withZone​(ZoneId zone)
        Returns a MutableClock that uses the specified time-zone and that has shared updates with this clock.

        Two clocks with shared updates always have the same instant, and all updates applied to either clock affect both clocks.

        Specified by:
        withZone in class Clock
        Parameters:
        zone - the time-zone to use for the returned clock, not null
        Returns:
        a view of this clock in the specified time-zone, not null

      • equals

        public boolean equals​(Object obj)
        Returns true if obj is a MutableClock that uses the same time-zone as this clock and has shared updates with this clock.

        Two clocks with shared updates always have the same instant, and all updates applied to either clock affect both clocks.

        A deserialized MutableClock is not equal to the original clock that was serialized, since the two clocks do not have shared updates.

        Overrides:
        equals in class Clock
        Parameters:
        obj - the object to check, null returns false
        Returns:
        true if this is equal to the other clock

      • hashCode

        public int hashCode()
        A hash code for this clock, which is constant for this instance.
        Overrides:
        hashCode in class Clock
        Returns:
        a constant hash code for this instance