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:

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 via ZonedDateTime#now(Clock) (or the equivalent thereof)
The update operation is applied to that ZonedDateTime, producing a new ZonedDateTime
The resulting ZonedDateTime is converted to an instant via ZonedDateTime#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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	MutableClock.InstantHolder An identity-having holder object for a mutable instant value.
private static class	MutableClock.SerializationProxy The serialized form of a `MutableClock`.

Field Summary

Modifier and Type	Field and Description
private final transient MutableClock.InstantHolder	instantHolder The mutable instant of this clock.
private static final long	serialVersionUID Serialization version.
private final transient ZoneId	zone The fixed time-zone of this clock.

Constructor Summary

Access	Constructor and Description
private	MutableClock(MutableClock.InstantHolder the mutable instant, validated not null instantHolder, ZoneId the fixed time-zone, validated not null zone) Constructor.

Method Summary

Modifier and Type	Method and Description
public void	add(TemporalAmount the amount to add, not null amountToAdd) Adds the specified amount to this clock.
public void	add(long the amount of the specified unit to add, may be negative amountToAdd, TemporalUnit the unit of the amount to add, not null unit) Adds the specified amount to this clock.
public static MutableClock	Returns: a new `MutableClock`, not null 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.
public boolean	Returns: `true` if this is equal to the other clock equals(Object the object to check, null returns `false` obj) Overrides java.time.Clock.equals. Returns `true` if `obj` is a `MutableClock` that uses the same time-zone as this clock and has shared updates with this clock.
public ZoneId	getZone() Implements abstract java.time.Clock.getZone. Gets the time-zone being used to create dates and times.
public int	Returns: a constant hash code for this instance hashCode() Overrides java.time.Clock.hashCode. A hash code for this clock, which is constant for this instance.
public Instant	instant() Implements abstract java.time.Clock.instant. Implements java.time.InstantSource.instant. Gets the current instant of the clock.
public static MutableClock	Returns: a new `MutableClock`, not null of(Instant the initial value for the clock, not null instant, ZoneId the time-zone to use, not null zone) Obtains a new `MutableClock` set to the specified instant, converting to date and time using the specified time-zone.
private void	readObject(ObjectInputStream ignored s) Throws `InvalidObjectException`.
public void	set(TemporalAdjuster the adjuster to use, not null adjuster) Adjusts this clock.
public void	set(TemporalField the field to set, not null field, long the new value of the field newValue) Alters the specified field of this clock.
public void	setInstant(Instant the new instant for this clock, not null instant) Overrides the instant of this clock with the specified value.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public MutableClock	Returns: a view of this clock in the specified time-zone, not null withZone(ZoneId the time-zone to use for the returned clock, not null zone) Overrides default java.time.InstantSource.withZone. Implements abstract java.time.Clock.withZone. Returns a `MutableClock` that uses the specified time-zone and that has shared updates with this clock.
private Object	Returns: the serialization proxy, not null writeReplace() Returns the serialization proxy to replace this `MutableClock`.

Inherited from java.time.Clock:: fixed millis offset system systemDefaultZone systemUTC tick tickMillis tickMinutes tickSeconds

Field Detail

instantHolder	back to summary
private final transient MutableClock.InstantHolder instantHolder The mutable instant of this clock.

serialVersionUID	back to summary
private static final long serialVersionUID Serialization version.

zone	back to summary
private final transient ZoneId zone The fixed time-zone of this clock.

Constructor Detail

MutableClock	back to summary
private MutableClock(MutableClock.InstantHolder instantHolder, ZoneId zone) Constructor. Parameters instantHolder:MutableClock.InstantHolder the mutable instant, validated not null zone:ZoneId the fixed time-zone, validated not null

MutableClock

back to summary

private MutableClock(MutableClock.InstantHolder instantHolder, ZoneId zone)

Constructor.

Parameters

instantHolder:MutableClock.InstantHolder: the mutable instant, validated not null
zone:ZoneId: the fixed time-zone, validated not null

Method Detail

add back to summary

add	back to summary
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:TemporalAmount the amount to add, not null Exceptions DateTimeException: if the addition cannot be made ArithmeticException: if numeric overflow occurs See Also `ZonedDateTime#plus(TemporalAmount)`

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:TemporalAmount: the amount to add, not null

Exceptions

DateTimeException:: if the addition cannot be made
ArithmeticException:: if numeric overflow occurs

See Also

ZonedDateTime#plus(TemporalAmount)

add back to summary

add	back to summary
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:long the amount of the specified unit to add, may be negative unit:TemporalUnit the unit of the amount to add, not null Exceptions DateTimeException: if the unit cannot be added UnsupportedTemporalTypeException: if the unit is not supported ArithmeticException: if numeric overflow occurs See Also `ZonedDateTime#plus(long, TemporalUnit)`

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:long: the amount of the specified unit to add, may be negative
unit:TemporalUnit: the unit of the amount to add, not null

Exceptions

DateTimeException:: if the unit cannot be added
UnsupportedTemporalTypeException:: if the unit is not supported
ArithmeticException:: if numeric overflow occurs

epochUTC back to summary

epochUTC	back to summary
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:MutableClock a new `MutableClock`, not null

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:MutableClock: a new MutableClock, not null

equals back to summary

equals	back to summary
public boolean equals(Object obj) Overrides java.time.Clock.equals. 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. Parameters obj:Object the object to check, null returns `false` Returns:boolean `true` if this is equal to the other clock Annotations @Override

public boolean equals(Object obj)

Overrides java.time.Clock.equals.

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.

Parameters

obj:Object: the object to check, null returns false

Returns:boolean

true if this is equal to the other clock

Annotations

@Override

getZone	back to summary
public ZoneId getZone() Implements abstract java.time.Clock.getZone. Doc from java.time.Clock.getZone. Gets the time-zone being used to create dates and times. A clock will typically obtain the current instant and then convert that to a date or time using a time-zone. This method returns the time-zone used. Returns:ZoneId the time-zone being used to interpret instants, not null Annotations @Override

getZone

back to summary

public ZoneId getZone()

Implements abstract java.time.Clock.getZone.

Doc from java.time.Clock.getZone.

Gets the time-zone being used to create dates and times.

A clock will typically obtain the current instant and then convert that to a date or time using a time-zone. This method returns the time-zone used.

Returns:ZoneId

the time-zone being used to interpret instants, not null

Annotations

@Override

hashCode	back to summary
public int hashCode() Overrides java.time.Clock.hashCode. A hash code for this clock, which is constant for this instance. Returns:int a constant hash code for this instance Annotations @Override

hashCode

back to summary

public int hashCode()

Overrides java.time.Clock.hashCode.

A hash code for this clock, which is constant for this instance.

Returns:int

a constant hash code for this instance

Annotations

@Override

instant	back to summary
public Instant instant() Implements abstract java.time.Clock.instant. Implements java.time.InstantSource.instant. Doc from java.time.Clock.instant. Gets the current instant of the clock. This returns an instant representing the current instant as defined by the clock. Returns:Instant the current instant from this clock, not null Annotations @Override

instant

back to summary

public Instant instant()

Implements abstract java.time.Clock.instant.

Implements java.time.InstantSource.instant.

Doc from java.time.Clock.instant.

Gets the current instant of the clock.

This returns an instant representing the current instant as defined by the clock.

Returns:Instant

the current instant from this clock, not null

Annotations

@Override

of back to summary

of	back to summary
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:Instant the initial value for the clock, not null zone:ZoneId the time-zone to use, not null Returns:MutableClock a new `MutableClock`, not null

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:Instant: the initial value for the clock, not null
zone:ZoneId: the time-zone to use, not null

Returns:MutableClock

a new MutableClock, not null

readObject back to summary

readObject	back to summary
private void readObject(ObjectInputStream s) throws InvalidObjectException Throws `InvalidObjectException`. Parameters s:ObjectInputStream ignored Exceptions InvalidObjectException: always

private void readObject(ObjectInputStream s) throws InvalidObjectException

Throws InvalidObjectException.

Parameters

s:ObjectInputStream: ignored

Exceptions

InvalidObjectException:: always

set back to summary

set	back to summary
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:TemporalAdjuster the adjuster to use, not null Exceptions DateTimeException: if the adjustment cannot be made ArithmeticException: if numeric overflow occurs See Also `ZonedDateTime#with(TemporalAdjuster)`

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:TemporalAdjuster: the adjuster to use, not null

Exceptions

DateTimeException:: if the adjustment cannot be made
ArithmeticException:: if numeric overflow occurs

See Also

ZonedDateTime#with(TemporalAdjuster)

set back to summary

set	back to summary
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:TemporalField the field to set, not null newValue:long the new value of the field Exceptions DateTimeException: if the field cannot be set UnsupportedTemporalTypeException: if the field is not supported ArithmeticException: if numeric overflow occurs See Also `ZonedDateTime#with(TemporalField, long)`

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:TemporalField: the field to set, not null
newValue:long: the new value of the field

Exceptions

DateTimeException:: if the field cannot be set
UnsupportedTemporalTypeException:: if the field is not supported
ArithmeticException:: if numeric overflow occurs

setInstant	back to summary
public void setInstant(Instant instant) Overrides the instant of this clock with the specified value. Parameters instant:Instant the new instant for this clock, not null

setInstant

back to summary

public void setInstant(Instant instant)

Overrides the instant of this clock with the specified value.

Parameters

instant:Instant: the new instant for this clock, not null

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Returns:String a string representation of the object Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations

@Override

withZone back to summary

withZone	back to summary
public MutableClock withZone(ZoneId zone) Overrides default java.time.InstantSource.withZone. Implements abstract java.time.Clock.withZone. 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. Parameters zone:ZoneId the time-zone to use for the returned clock, not null Returns:MutableClock a view of this clock in the specified time-zone, not null Annotations @Override

public MutableClock withZone(ZoneId zone)

Overrides default java.time.InstantSource.withZone.

Implements abstract java.time.Clock.withZone.

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.

Parameters

zone:ZoneId: the time-zone to use for the returned clock, not null

Returns:MutableClock

a view of this clock in the specified time-zone, not null

Annotations

@Override

writeReplace back to summary

writeReplace	back to summary
private Object writeReplace() Returns the serialization proxy to replace this `MutableClock`. Returns:Object the serialization proxy, not null

private Object writeReplace()

Returns the serialization proxy to replace this MutableClock.

Returns:Object: the serialization proxy, not null

org.threeten.extra back to summary

private final Class MutableClock.InstantHolder

Class Inheritance

extends Object

java.lang.Object
org.threeten.extra.MutableClock.InstantHolder

An identity-having holder object for a mutable instant value.

Clocks have shared updates when they share a holder object. Clocks rely on the identity of the holder object in their equals and hashCode methods.

Reads of the value are volatile and are never stale. Blind writes to the value are volatile and do not need to synchronize. Atomic read-and-write operations must synchronize on the holder object instance.

Field Summary

Modifier and Type	Field and Description
private volatile Instant	value The current value.

Constructor Summary

Access	Constructor and Description
pack-priv	InstantHolder(Instant the initial value, validated not null value) Constructor.

Method Summary

Modifier and Type	Method and Description
pack-priv Instant	Returns: the current value, not null get() Reads the value.
pack-priv void	set(Instant the new value, validated not null value) Writes the value.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

value	back to summary
private volatile Instant value The current value.

Constructor Detail

InstantHolder	back to summary
pack-priv InstantHolder(Instant value) Constructor. Parameters value:Instant the initial value, validated not null

InstantHolder

back to summary

pack-priv InstantHolder(Instant value)

Constructor.

Parameters

value:Instant: the initial value, validated not null

Method Detail

get	back to summary
pack-priv Instant get() Reads the value. Returns:Instant the current value, not null

get

back to summary

pack-priv Instant get()

Reads the value.

Returns:Instant: the current value, not null

set	back to summary
pack-priv void set(Instant value) Writes the value. Parameters value:Instant the new value, validated not null

set

back to summary

pack-priv void set(Instant value)

Writes the value.

Parameters

value:Instant: the new value, validated not null

org.threeten.extra back to summary

private final Class MutableClock.SerializationProxy

Class Inheritance

extends Object
implements Serializable

java.lang.Object
org.threeten.extra.MutableClock.SerializationProxy

All Implemented Interfaces

java.io.Serializable

The serialized form of a MutableClock.

Field Summary

Modifier and Type	Field and Description
private final Instant	instant A snapshot of the instant of the `MutableClock`, taken when the clock was serialized, not null.
private static final long	serialVersionUID Serialization version.
private final ZoneId	zone The time-zone of the `MutableClock`, not null.

Constructor Summary

Access	Constructor and Description
pack-priv	SerializationProxy(MutableClock the `MutableClock` to be serialized, not null clock) Constructor.

Method Summary

Modifier and Type	Method and Description
private Object	Returns: the `MutableClock`, not null readResolve() Returns the `MutableClock` to replace this serialization proxy.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

instant	back to summary
private final Instant instant A snapshot of the instant of the `MutableClock`, taken when the clock was serialized, not null.

serialVersionUID	back to summary
private static final long serialVersionUID Serialization version.

zone	back to summary
private final ZoneId zone The time-zone of the `MutableClock`, not null.

Constructor Detail

SerializationProxy back to summary

SerializationProxy	back to summary
pack-priv SerializationProxy(MutableClock clock) Constructor. Parameters clock:MutableClock the `MutableClock` to be serialized, not null

pack-priv SerializationProxy(MutableClock clock)

Constructor.

Parameters

clock:MutableClock: the MutableClock to be serialized, not null

Method Detail

readResolve back to summary

readResolve	back to summary
private Object readResolve() throws InvalidObjectException Returns the `MutableClock` to replace this serialization proxy. Returns:Object the `MutableClock`, not null Exceptions InvalidObjectException: if the instant or time-zone is null

private Object readResolve() throws InvalidObjectException

Returns the MutableClock to replace this serialization proxy.

Returns:Object

the MutableClock, not null

Exceptions

InvalidObjectException:: if the instant or time-zone is null

public final Class MutableClock

Implementation Requirements:

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class MutableClock.InstantHolder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class MutableClock.SerializationProxy

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail