MutableClock

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 fixed and offset 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 now (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 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.

Properties

Link copied to clipboard
The fixed time-zone of this clock.

Functions

Link copied to clipboard
open fun add(amountToAdd: TemporalAmount)
open fun add(amountToAdd: Long, unit: TemporalUnit)
Adds the specified amount to this clock.
Link copied to clipboard
Obtains a new MutableClock set to the epoch of 1970-01-01T00:00:00Z, converting to date and time using the UTC time-zone.
Link copied to clipboard
open fun equals(obj: Any): Boolean
Returns true if obj is a MutableClock that uses the same time-zone as this clock and has shared updates with this clock.
Link copied to clipboard
open fun hashCode(): Int
A hash code for this clock, which is constant for this instance.
Link copied to clipboard
open fun instant(): Instant
Link copied to clipboard
open fun of(instant: Instant, zone: ZoneId): MutableClock
Obtains a new MutableClock set to the specified instant, converting to date and time using the specified time-zone.
Link copied to clipboard
open fun set(adjuster: TemporalAdjuster)
Adjusts this clock.
open fun set(field: TemporalField, newValue: Long)
Alters the specified field of this clock.
Link copied to clipboard
open fun setInstant(instant: Instant)
Overrides the instant of this clock with the specified value.
Link copied to clipboard
open fun toString(): String
Link copied to clipboard
open fun withZone(zone: ZoneId): MutableClock
Returns a MutableClock that uses the specified time-zone and that has shared updates with this clock.