public abstract class Clock extends Object
The Time Framework for Java abstracts the concept of the 'current time' into two interfaces
- TimeSource
and Clock
.
The former, TimeSource
, provides access to the current instant and
is independent of local factors such as time-zone.
The latter, this class, provides access to the current date and
time 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.
Applications should avoid using the static methods on this class.
Instead, they should pass a Clock
into any method that requires it.
A dependency injection framework is one way to achieve this:
public class MyBean { private Clock clock; // dependency inject ... public void process(LocalDate eventDate) { if (eventDate.isBefore(clock.today()) { ... } } }This approach allows alternate time-source implementations, such as
TimeSource.fixed(javax.time.InstantProvider)
to be used during testing.
Clock
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.
The class is designed to be subclassed, however this will rarely be necessary.
In most cases, you should subclass TimeSource
instead.
A subclass will normally override getSource()
and getZone()
.
This will cause all the other methods to work as they are derived from just these two.
Subclasses should implement withSource()
and withZone()
if possible to allow the user to change the time-source and time-zone.
The default implementation of these four methods throws an UnsupportedOperationException
.
One reason to subclass this class would be to provide only a hard coded date for testing
and not a time or date-time. In this case, the subclass would only override today()
.
Other methods would thus throw UnsupportedOperationException
, which would be fine
for testing but not recommended for production usage.
Subclass implementations should implement Serializable
wherever possible.
They should also implement equals()
, hashCode()
and
toString()
based on their state.
Modifier | Constructor and Description |
---|---|
protected |
Clock()
Constructor accessible by subclasses.
|
Modifier and Type | Method and Description |
---|---|
static Clock |
clock(TimeSource timeSource,
TimeZone timeZone)
Gets a clock that obtains the current date and time using the specified
time-source and time-zone.
|
static Clock |
clockDefaultZone(TimeSource timeSource)
Gets a clock that obtains the current date and time using the specified
time-source and default time-zone.
|
LocalDateTime |
dateTime()
Gets the current date-time with maximum resolution of up to nanoseconds.
|
LocalDateTime |
dateTimeToMinute()
Gets the current date-time with a resolution of minutes.
|
LocalDateTime |
dateTimeToSecond()
Gets the current date-time with a resolution of seconds.
|
TimeSource |
getSource()
Gets the time-source being used to create dates and times.
|
TimeZone |
getZone()
Gets the time-zone being used to create dates and times.
|
Instant |
instant()
Gets the current instant.
|
OffsetDate |
offsetDate()
Gets the current offset date.
|
OffsetDateTime |
offsetDateTime()
Gets the current offset date-time with maximum resolution of up to nanoseconds.
|
OffsetDateTime |
offsetDateTimeToMinute()
Gets the current offset date-time with a resolution of minutes.
|
OffsetDateTime |
offsetDateTimeToSecond()
Gets the current offset date-time with a resolution of seconds.
|
OffsetTime |
offsetTime()
Gets the current offset time with maximum resolution of up to nanoseconds.
|
OffsetTime |
offsetTimeToMinute()
Gets the current offset time with a resolution of minutes.
|
OffsetTime |
offsetTimeToSecond()
Gets the current offset time with a resolution of seconds.
|
static Clock |
system(TimeZone zone)
Gets a clock that obtains the current date and time using the system millisecond
clock and the specified time-zone.
|
static Clock |
systemDefaultZone()
Gets a clock that obtains the current date and time using the system millisecond
clock and the default time-zone.
|
LocalTime |
time()
Gets the current time with maximum resolution of up to nanoseconds.
|
LocalTime |
timeToMinute()
Gets the current time with a resolution of minutes.
|
LocalTime |
timeToSecond()
Gets the current time with a resolution of seconds.
|
LocalDate |
today()
Gets today's date.
|
LocalDate |
tomorrow()
Gets tomorrow's date.
|
Clock |
withSource(TimeSource timeSource)
Returns a copy of this clock with a different time-source.
|
Clock |
withZone(TimeZone zone)
Returns a copy of this clock with a different time-zone.
|
Year |
year()
Gets the current year.
|
YearMonth |
yearMonth()
Gets the current year-month.
|
LocalDate |
yesterday()
Gets yesterday's date.
|
ZonedDateTime |
zonedDateTime()
Gets the current zoned date-time.
|
ZonedDateTime |
zonedDateTimeToMinute()
Gets the current zoned date-time with a resolution of minutes.
|
ZonedDateTime |
zonedDateTimeToSecond()
Gets the current zoned date-time with a resolution of seconds.
|
public static Clock systemDefaultZone()
The time-source wraps System.currentTimeMillis()
, thus it has
at best millisecond resolution.
Using this method hard codes a dependency to the default time-zone into your application. It is recommended to avoid this and use a specific time-zone whenever possible.
public static Clock system(TimeZone zone)
The time-source wraps System.currentTimeMillis()
, thus it has
at best millisecond resolution.
zone
- the time-zone to use to convert to date-times, not nullpublic static Clock clockDefaultZone(TimeSource timeSource)
Using this method hard codes a dependency to the default time-zone into your application. It is recommended to avoid this and use a specific time-zone whenever possible.
timeSource
- the time-source to use to obtain the current time, not nullpublic static Clock clock(TimeSource timeSource, TimeZone timeZone)
timeSource
- the time-source to use to obtain the current time, not nulltimeZone
- the time-zone to use to convert to date-times, not nullpublic TimeSource getSource()
The standard implementation of Clock
uses a time-source to
provide the current instant. This method returns that time-source.
Non-standard implementations may choose to use another means to obtain
instants, dates and times, thus this method is allowed to throw
UnsupportedOperationException
.
UnsupportedOperationException
- if the implementation does not support accessing the time-sourcepublic Clock withSource(TimeSource timeSource)
The standard implementation of Clock
uses a time-source to
provide the current instant. This method allows that time-source to be changed.
Non-standard implementations may choose to use another means to obtain
instants, dates and times, thus this method is allowed to throw
UnsupportedOperationException
.
timeSource
- the time-source to change to, not nullUnsupportedOperationException
- if the implementation does not support changing the time-sourcepublic TimeZone getZone()
The standard implementation of Clock
uses a time-zone to
interpret the current instant. This method returns that time-zone.
Non-standard implementations may choose to use another means to interpret
instants, dates and times, thus this method is allowed to throw
UnsupportedOperationException
.
UnsupportedOperationException
- if the implementation does not support accessing the time-zonepublic Clock withZone(TimeZone zone)
The standard implementation of Clock
uses a time-zone to
interpret the current instant. This method allows that time-zone to be changed.
Non-standard implementations may choose to use another means to interpret
instants, dates and times, thus this method is allowed to throw
UnsupportedOperationException
.
zone
- the time-zone to change to, not nullUnsupportedOperationException
- if the implementation does not support changing the time-zonepublic Instant instant()
The instant returned by this method will vary according to the implementation.
For example, the time-source returned by system(TimeZone)
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.
CalendricalException
- if the instant cannot be obtained, not thrown by most implementationspublic LocalDate today()
This returns today's date from the clock.
The local date can only be calculated from an instant if the time-zone is known.
As such, the local date is derived by default from offsetDate()
.
CalendricalException
- if the date cannot be createdpublic LocalDate yesterday()
This returns yesterday's date from the clock.
This is calculated relative to today()
.
CalendricalException
- if the date cannot be createdpublic LocalDate tomorrow()
This returns tomorrow's date from the clock.
This is calculated relative to today()
.
CalendricalException
- if the date cannot be createdpublic YearMonth yearMonth()
This returns the current year-month from the clock.
This is derived from today()
.
CalendricalException
- if the year cannot be createdpublic Year year()
This returns the current year from the clock.
This is derived from today()
.
CalendricalException
- if the year cannot be createdpublic LocalTime time()
This returns the current time from the clock.
The result is not filtered, and so will have whatever resolution the clock has.
For example, the system clock
has up to millisecond resolution.
The local time can only be calculated from an instant if the time-zone is known.
As such, the local time is derived by default from offsetTime()
.
CalendricalException
- if the time cannot be createdpublic LocalTime timeToSecond()
This returns the current time from the clock rounded to the second. This is achieved by setting the nanosecond part to be zero.
CalendricalException
- if the time cannot be createdpublic LocalTime timeToMinute()
This returns the current time from the clock rounded to the minute. This is achieved by setting the second and nanosecond parts to be zero.
CalendricalException
- if the time cannot be createdpublic LocalDateTime dateTime()
This returns the current date-time from the clock.
The result is not filtered, and so will have whatever resolution the clock has.
For example, the system clock
has up to millisecond resolution.
The local date-time can only be calculated from an instant if the time-zone is known.
As such, the local date-time is derived by default from offsetDateTime()
.
CalendricalException
- if the date-time cannot be createdpublic LocalDateTime dateTimeToSecond()
This returns the current date-time from the clock rounded to the second. This is achieved by setting the nanosecond part to be zero.
CalendricalException
- if the date-time cannot be createdpublic LocalDateTime dateTimeToMinute()
This returns the current date-time from the clock rounded to the minute. This is achieved by setting the second and nanosecond parts to be zero.
CalendricalException
- if the date-time cannot be createdpublic OffsetDate offsetDate()
This returns the current offset date from the clock with the correct offset from getZone()
.
The offset date is derived by default from instant()
and getZone()
.
CalendricalException
- if the date-time cannot be createdpublic OffsetTime offsetTime()
This returns the current offset time from the clock with the correct offset from getZone()
.
The result is not filtered, and so will have whatever resolution the clock has.
For example, the system clock
has up to millisecond resolution.
The offset time is derived by default from instant()
and getZone()
.
CalendricalException
- if the time cannot be createdpublic OffsetTime offsetTimeToSecond()
This returns the current offset time from the clock with the correct offset from getZone()
.
The time is rounded to the second by setting the nanosecond part to be zero.
CalendricalException
- if the time cannot be createdpublic OffsetTime offsetTimeToMinute()
This returns the current offset time from the clock with the correct offset from getZone()
.
The time is rounded to the second by setting the second and nanosecond parts to be zero.
CalendricalException
- if the time cannot be createdpublic OffsetDateTime offsetDateTime()
This returns the current offset date-time from the clock with the correct offset from getZone()
.
The result is not filtered, and so will have whatever resolution the clock has.
For example, the system clock
has up to millisecond resolution.
The offset date-time is derived by default from instant()
and getZone()
.
CalendricalException
- if the date-time cannot be createdpublic OffsetDateTime offsetDateTimeToSecond()
This returns the current offset date-time from the clock with the correct offset from getZone()
.
The time is rounded to the second by setting the nanosecond part to be zero.
CalendricalException
- if the date-time cannot be createdpublic OffsetDateTime offsetDateTimeToMinute()
This returns the current offset date-time from the clock with the correct offset from getZone()
.
The time is rounded to the second by setting the second and nanosecond parts to be zero.
CalendricalException
- if the date-time cannot be createdpublic ZonedDateTime zonedDateTime()
This returns the current zoned date-time from the clock with the zone from getZone()
.
The result is not filtered, and so will have whatever resolution the clock has.
For example, the system clock
has up to millisecond resolution.
The zoned date-time is derived by default from instant()
and getZone()
.
CalendricalException
- if the date-time cannot be createdpublic ZonedDateTime zonedDateTimeToSecond()
This returns the current zoned date-time from the clock with the zone from getZone()
.
The time is rounded to the second by setting the nanosecond part to be zero.
CalendricalException
- if the date-time cannot be createdpublic ZonedDateTime zonedDateTimeToMinute()
This returns the current zoned date-time from the clock with the zone from getZone()
.
The time is rounded to the second by setting the second and nanosecond parts to be zero.
CalendricalException
- if the date-time cannot be createdCopyright © 2014. All rights reserved.