Class TimeSource
- java.lang.Object
-
- javax.time.TimeSource
-
public abstract class TimeSource extends Object
A source providing access to the current instant.The Time Framework for Java abstracts the concept of the "current time" into two interfaces -
TimeSource
andClock
. This class, provides access to the currentInstant
which is independent of local factors such as time-zone and cannot be queried for human-scale fields. By comparison,Clock
provides access to the current date and time, via human-scale fields, but requires a time-zone.The purpose of this abstraction is to allow alternate time-sources to be plugged in as and when required. Applications use an object to obtain the current time rather than a static method. This simplifies testing.
Best practice
The recommended best practice for most applications is to avoid using the static methods. Instead, the main application should obtain the current time from aTimeSource
instance that is passed to the object or method. This approach is typically implemented using a dependency injection framework.public class MyBean { final TimeSource timeSource; @Inject MyBean(TimeSource ts) { this.timeSource = ts; } public void process(Instant eventTime) { if (eventTime.isBefore(timeSource.instant()) { ... } } }
This approach allows alternate time-source implementations, such asfixed
oroffsetSystem
to be used during testing.public void test_process() { MyBean bean = new MyBean(TimeSource.fixed(Instant.EPOCH)) { assert ... }
Accuracy
The main method used by applications isinstant()
. This returns the best value available for the current instant ignoring leap-seconds. To achieve this, the instant may not be fully accurate around a leap-second.Two alternative methods are available and may return a more accurate instant depending on the implementation. The instant in UTC, taking into account leap seconds, can be obtained using
utcInstant()
. The instant in TAI, which is a simple incrementing number ignoring all human time concepts, can be obtained usingtaiInstant()
. See the relevant classes for more detail.Implementation notes
TimeSource
is an abstract class and must be implemented with care to ensure other classes in the framework operate correctly. All instantiable implementations must be final, immutable and thread-safe.Subclass implementations should implement
Serializable
wherever possible. They should also implementequals()
,hashCode()
andtoString()
based on their state.- Author:
- Michael Nascimento Santos, Stephen Colebourne
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
TimeSource()
Constructor accessible by subclasses.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description static TimeSource
fixed(InstantProvider fixedInstantProvider)
Gets a time-source that always returns the sameInstant
.abstract Instant
instant()
Gets the currentInstant
.long
millis()
Gets the current millisecond instant.static TimeSource
offsetSystem(Duration offset)
Gets a time-source that obtains the current instant using the system millisecond clock and adjusts by a fixed offset.static TimeSource
system()
Gets a time-source that obtains the current instant using the system millisecond clock.TAIInstant
taiInstant()
Gets the currentTAIInstant
.UTCInstant
utcInstant()
Gets the currentUTCInstant
.
-
-
-
Method Detail
-
system
public static TimeSource system()
Gets a time-source that obtains the current instant using the system millisecond clock.The time-source wraps
System.currentTimeMillis()
, thus it has at best millisecond resolution.The returned implementation is
Serializable
- Returns:
- a
TimeSource
that uses the system millisecond clock, never null
-
fixed
public static TimeSource fixed(InstantProvider fixedInstantProvider)
Gets a time-source that always returns the sameInstant
.This method converts the
InstantProvider
to anInstant
which it then returns from theTimeSource
.The returned implementation is
Serializable
- Parameters:
fixedInstantProvider
- the instant to return from each call to the time-source- Returns:
- a
TimeSource
that always returns the same instant, never null
-
offsetSystem
public static TimeSource offsetSystem(Duration offset)
Gets a time-source that obtains the current instant using the system millisecond clock and adjusts by a fixed offset.The time-source wraps
System.currentTimeMillis()
, thus it has at best millisecond resolution.The final instant is adjusted by adding the offset. This is useful for simulating an application running at a later or earlier point in time.
The returned implementation is
Serializable
- Parameters:
offset
- the duration by which this time-source is offset from the system millisecond clock- Returns:
- a
TimeSource
that is offset from the system millisecond clock, never null
-
instant
public abstract Instant instant()
Gets the currentInstant
.The instant returned by this method will vary according to the implementation. For example, the time-source returned by
system()
will return an instant based onSystem.currentTimeMillis()
.Normally, this method will not throw an exception. However, one possible implementation would be to obtain the time from a central time server across the network. Obviously, in this case the lookup could fail, and so the method is permitted to throw an exception.
- Returns:
- the current
Instant
from this time-source, never null - Throws:
CalendricalException
- if the instant cannot be obtained, not thrown by most implementations
-
utcInstant
public UTCInstant utcInstant()
Gets the currentUTCInstant
.The UTC time-scale differs from that used by
Instant
because it includes leap-seconds. An accurate implementation of this abstract class will return a UTC value that includes leap-second information.The default implementation of this method converts the value from
instant()
and thus is no more accurate than that method.Normally, this method will not throw an exception. However, one possible implementation would be to obtain the time from a central time server across the network. Obviously, in this case the lookup could fail, and so the method is permitted to throw an exception.
- Returns:
- the current
UTCInstant
from this time-source, never null - Throws:
CalendricalException
- if the instant cannot be obtained, not thrown by most implementations
-
taiInstant
public TAIInstant taiInstant()
Gets the currentTAIInstant
.The TAI time-scale is a simple incrementing number of seconds from the TAI epoch of 1958-01-01(TAI). It ignores all human concepts of time such as days. An accurate implementation of this abstract class will return a TAI value in accordance with international standards.
The default implementation of this method converts the value from
instant()
and thus is no more accurate than that method.Normally, this method will not throw an exception. However, one possible implementation would be to obtain the time from a central time server across the network. Obviously, in this case the lookup could fail, and so the method is permitted to throw an exception.
-
millis
public long millis()
Gets the current millisecond instant.The instant returned by this method will vary according to the implementation. For example, the time-source returned by
system()
will returnSystem.currentTimeMillis()
.This method is provided for backwards compatibility. New code should use classes such as
Instant
to represent an instant rather than a raw millisecond value.Normally, this method will not throw an exception. However, one possible implementation would be to obtain the time from a central time server across the network. Obviously, in this case the lookup could fail, and so the method is permitted to throw an exception.
- Returns:
- the current millisecond instant from this time-source, measured from the Java epoch of 1970-01-01T00:00 UTC, never null
- Throws:
CalendricalException
- if the instant cannot be obtained, not thrown by most implementations
-
-