|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.time.TimeSource
public abstract class TimeSource
A source providing access to the current instant.
The Time Framework for Java abstracts the concept of the "current time" into two interfaces
- TimeSource
and Clock
.
This class, provides access to the current Instant
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.
TimeSource
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 as
fixed
or offsetSystem
to be used during testing.
public void test_process() { MyBean bean = new MyBean(TimeSource.fixed(Instant.EPOCH)) { assert ... }
instant()
.
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 using taiInstant()
.
See the relevant classes for more detail.
This is an abstract class and must be implemented with care
to ensure other classes in the framework operate correctly.
All implementations must be final, immutable and thread-safe.
Subclasses should be Serializable
wherever possible.
They should also implement equals()
, hashCode()
and
toString()
based on their state.
Constructor Summary | |
---|---|
protected |
TimeSource()
Constructor accessible by subclasses. |
Method Summary | |
---|---|
static TimeSource |
fixed(InstantProvider fixedInstantProvider)
Gets a time-source that always returns the same Instant . |
abstract Instant |
instant()
Gets the current Instant . |
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 current TAIInstant . |
UTCInstant |
utcInstant()
Gets the current UTCInstant . |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
protected TimeSource()
Method Detail |
---|
public static TimeSource system()
The time-source wraps System.currentTimeMillis()
, thus it has
at best millisecond resolution.
The returned implementation is Serializable
TimeSource
that uses the system millisecond clock, not nullpublic static TimeSource fixed(InstantProvider fixedInstantProvider)
Instant
.
This method converts the InstantProvider
to an Instant
which it then returns from the TimeSource
.
The returned implementation is Serializable
fixedInstantProvider
- the instant to return from each call to the time-source
TimeSource
that always returns the same instant, not nullpublic static TimeSource offsetSystem(Duration 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
offset
- the duration by which this time-source is offset from the system millisecond clock
TimeSource
that is offset from the system millisecond clock, not nullpublic abstract Instant instant()
Instant
.
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 on System.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.
Instant
from this time-source, not null
CalendricalException
- if the instant cannot be obtained, not thrown by most implementationspublic UTCInstant utcInstant()
UTCInstant
.
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.
UTCInstant
from this time-source, not null
CalendricalException
- if the instant cannot be obtained, not thrown by most implementationspublic TAIInstant taiInstant()
TAIInstant
.
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.
public long millis()
The instant returned by this method will vary according to the implementation.
For example, the time-source returned by system()
will return
System.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.
CalendricalException
- if the instant cannot be obtained, not thrown by most implementations
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |