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:
- Create the clock-sensitive component to be tested
- Verify some behavior of the component in the initial state
- Advance the clock without recreating the component
- 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:
- The clock captures its own state in a
ZonedDateTimevia now (or the equivalent thereof) - The update operation is applied to that
ZonedDateTime, producing a newZonedDateTime - The resulting
ZonedDateTimeis converted to an instant via toInstant (or the equivalent thereof) - 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.
Functions
MutableClock set to the epoch of 1970-01-01T00:00:00Z, converting to date and time using the UTC time-zone.MutableClock set to the specified instant, converting to date and time using the specified time-zone.MutableClock that uses the specified time-zone and that has shared updates with this clock.