java.io.Serializable
public final class MutableClock
extends java.time.Clock
implements java.io.Serializable
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:
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:
ZonedDateTime
via ZonedDateTime.now(Clock)
(or the equivalent thereof)
ZonedDateTime
, producing
a new ZonedDateTime
ZonedDateTime
is converted to an instant via ChronoZonedDateTime.toInstant()
(or the equivalent thereof)
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
.
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.
Modifier and Type | Method | Description |
---|---|---|
void |
add(long amountToAdd,
java.time.temporal.TemporalUnit unit) |
Adds the specified amount to this clock.
|
void |
add(java.time.temporal.TemporalAmount amountToAdd) |
Adds the specified amount to this clock.
|
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. |
boolean |
equals(java.lang.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. |
java.time.ZoneId |
getZone() |
|
int |
hashCode() |
A hash code for this clock, which is constant for this instance.
|
java.time.Instant |
instant() |
|
static MutableClock |
of(java.time.Instant instant,
java.time.ZoneId zone) |
Obtains a new
MutableClock set to the specified instant,
converting to date and time using the specified time-zone. |
void |
set(java.time.temporal.TemporalAdjuster adjuster) |
Adjusts this clock.
|
void |
set(java.time.temporal.TemporalField field,
long newValue) |
Alters the specified field of this clock.
|
void |
setInstant(java.time.Instant instant) |
Overrides the instant of this clock with the specified value.
|
java.lang.String |
toString() |
|
MutableClock |
withZone(java.time.ZoneId zone) |
Returns a
MutableClock that uses the specified time-zone and that
has shared updates with this clock. |
public static MutableClock epochUTC()
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.
MutableClock
, not nullpublic static MutableClock of(java.time.Instant instant, java.time.ZoneId zone)
MutableClock
set to the specified instant,
converting to date and time using the specified time-zone.instant
- the initial value for the clock, not nullzone
- the time-zone to use, not nullMutableClock
, not nullpublic void setInstant(java.time.Instant instant)
instant
- the new instant for this clock, not nullpublic void add(java.time.temporal.TemporalAmount amountToAdd)
Atomically updates this clock to the value of the following expression:
ZonedDateTime.now(thisClock) .plus(amountToAdd) .toInstant()
amountToAdd
- the amount to add, not nulljava.time.DateTimeException
- if the addition cannot be madejava.lang.ArithmeticException
- if numeric overflow occursZonedDateTime.plus(TemporalAmount)
public void add(long amountToAdd, java.time.temporal.TemporalUnit unit)
Atomically updates this clock to the value of the following expression:
ZonedDateTime.now(thisClock) .plus(amountToAdd, unit) .toInstant()
amountToAdd
- the amount of the specified unit to add, may be negativeunit
- the unit of the amount to add, not nulljava.time.DateTimeException
- if the unit cannot be addedjava.time.temporal.UnsupportedTemporalTypeException
- if the unit is not supportedjava.lang.ArithmeticException
- if numeric overflow occursZonedDateTime.plus(long, TemporalUnit)
public void set(java.time.temporal.TemporalAdjuster adjuster)
Atomically updates this clock to the value of the following expression:
ZonedDateTime.now(thisClock) .with(adjuster) .toInstant()
adjuster
- the adjuster to use, not nulljava.time.DateTimeException
- if the adjustment cannot be madejava.lang.ArithmeticException
- if numeric overflow occursZonedDateTime.with(TemporalAdjuster)
public void set(java.time.temporal.TemporalField field, long newValue)
Atomically updates this clock to the value of the following expression:
ZonedDateTime.now(thisClock) .with(field, newValue) .toInstant()
field
- the field to set, not nullnewValue
- the new value of the fieldjava.time.DateTimeException
- if the field cannot be setjava.time.temporal.UnsupportedTemporalTypeException
- if the field is not supportedjava.lang.ArithmeticException
- if numeric overflow occursZonedDateTime.with(TemporalField, long)
public java.time.ZoneId getZone()
getZone
in class java.time.Clock
public MutableClock withZone(java.time.ZoneId zone)
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.
withZone
in class java.time.Clock
zone
- the time-zone to use for the returned clock, not nullpublic java.time.Instant instant()
instant
in class java.time.Clock
public boolean equals(java.lang.Object obj)
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.
equals
in class java.time.Clock
obj
- the object to check, null returns false
true
if this is equal to the other clockpublic int hashCode()
hashCode
in class java.time.Clock
public java.lang.String toString()
toString
in class java.lang.Object
Copyright © 2010–2018 ThreeTen.org. All rights reserved.