Package org.threeten.extra

Class MutableClock

java.lang.Object
java.time.Clock
org.threeten.extra.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 Details

    • 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:

    • 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:

    • set

      public void set(TemporalAdjuster adjuster)
      Adjusts this clock.

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

         ZonedDateTime.now(thisClock)
                .with(adjuster)
                .toInstant()
      Parameters:
      adjuster - the adjuster to use, not null
      Throws:
      DateTimeException - if the adjustment cannot be made
      ArithmeticException - if numeric overflow occurs
      See Also:

    • set

      public void set(TemporalField field, long newValue)
      Alters the specified field of this clock.

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

         ZonedDateTime.now(thisClock)
                .with(field, newValue)
                .toInstant()
      Parameters:
      field - the field to set, not null
      newValue - the new value of the field
      Throws:
      DateTimeException - if the field cannot be set
      UnsupportedTemporalTypeException - if the field is not supported
      ArithmeticException - if numeric overflow occurs
      See Also:

    • getZone

      public ZoneId getZone()
      Specified by:
      getZone in class Clock

    • 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

    • instant

      public Instant instant()
      Specified by:
      instant in class Clock

    • 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

    • toString

      public String toString()
      Overrides:
      toString in class Object