- 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)
andClock.offset(Clock, Duration)
in that it permits arbitrary, unrestricted updates to its instant. This allows for testing patterns that are not well-supported by thefixed
andoffset
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
ZonedDateTime
viaZonedDateTime.now(Clock)
(or the equivalent thereof) - The update operation is applied to that
ZonedDateTime
, producing a newZonedDateTime
- The resulting
ZonedDateTime
is converted to an instant viaChronoZonedDateTime.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 ofZonedDateTime
.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 usingZonedDateTime
completely or only sometimes, for convenience, efficiency, or any other reason.
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
add(long amountToAdd, TemporalUnit unit)
Adds the specified amount to this clock.void
add(TemporalAmount amountToAdd)
Adds the specified amount to this clock.static MutableClock
epochUTC()
Obtains a newMutableClock
set to the epoch of 1970-01-01T00:00:00Z, converting to date and time using the UTC time-zone.boolean
equals(Object obj)
Returnstrue
ifobj
is aMutableClock
that uses the same time-zone as this clock and has shared updates with this clock.ZoneId
getZone()
int
hashCode()
A hash code for this clock, which is constant for this instance.Instant
instant()
static MutableClock
of(Instant instant, ZoneId zone)
Obtains a newMutableClock
set to the specified instant, converting to date and time using the specified time-zone.void
set(TemporalAdjuster adjuster)
Adjusts this clock.void
set(TemporalField field, long newValue)
Alters the specified field of this clock.void
setInstant(Instant instant)
Overrides the instant of this clock with the specified value.String
toString()
MutableClock
withZone(ZoneId zone)
Returns aMutableClock
that uses the specified time-zone and that has shared updates with this clock.-
Methods inherited from class java.time.Clock
fixed, millis, offset, system, systemDefaultZone, systemUTC, tick, tickMillis, tickMinutes, tickSeconds
-
-
-
-
Method Detail
-
epochUTC
public static MutableClock epochUTC()
Obtains a newMutableClock
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 newMutableClock
set to the specified instant, converting to date and time using the specified time-zone.- Parameters:
instant
- the initial value for the clock, not nullzone
- 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 madeArithmeticException
- 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 negativeunit
- the unit of the amount to add, not null- Throws:
DateTimeException
- if the unit cannot be addedUnsupportedTemporalTypeException
- if the unit is not supportedArithmeticException
- if numeric overflow occurs- See Also:
ZonedDateTime.plus(long, TemporalUnit)
-
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 madeArithmeticException
- if numeric overflow occurs- See Also:
ZonedDateTime.with(TemporalAdjuster)
-
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 nullnewValue
- the new value of the field- Throws:
DateTimeException
- if the field cannot be setUnsupportedTemporalTypeException
- if the field is not supportedArithmeticException
- if numeric overflow occurs- See Also:
ZonedDateTime.with(TemporalField, long)
-
withZone
public MutableClock withZone(ZoneId zone)
Returns aMutableClock
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.
-
equals
public boolean equals(Object obj)
Returnstrue
ifobj
is aMutableClock
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.
-
hashCode
public int hashCode()
A hash code for this clock, which is constant for this instance.
-
-