Class Clock
- Direct Known Subclasses:
Clock.TimeSourceClock
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.
Implementation notes
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
Implementation of a clock based on a time-source. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic 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.dateTime()
Gets the current date-time with maximum resolution of up to nanoseconds.Gets the current date-time with a resolution of minutes.Gets the current date-time with a resolution of seconds.Gets the time-source being used to create dates and times.getZone()
Gets the time-zone being used to create dates and times.instant()
Gets the current instant.Gets the current offset date.Gets the current offset date-time with maximum resolution of up to nanoseconds.Gets the current offset date-time with a resolution of minutes.Gets the current offset date-time with a resolution of seconds.Gets the current offset time with maximum resolution of up to nanoseconds.Gets the current offset time with a resolution of minutes.Gets the current offset time with a resolution of seconds.static Clock
Gets a clock that obtains the current date and time using the system millisecond clock and the specified time-zone.static Clock
Gets a clock that obtains the current date and time using the system millisecond clock and the default time-zone.time()
Gets the current time with maximum resolution of up to nanoseconds.Gets the current time with a resolution of minutes.Gets the current time with a resolution of seconds.today()
Gets today's date.tomorrow()
Gets tomorrow's date.withSource
(TimeSource timeSource) Returns a copy of this clock with a different time-source.Returns a copy of this clock with a different time-zone.year()
Gets the current year.Gets the current year-month.Gets yesterday's date.Gets the current zoned date-time.Gets the current zoned date-time with a resolution of minutes.Gets the current zoned date-time with a resolution of seconds.
-
Constructor Details
-
Clock
protected Clock()Constructor accessible by subclasses.
-
-
Method Details
-
systemDefaultZone
Gets a clock that obtains the current date and time using the system millisecond clock and the default time-zone.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.
- Returns:
- a clock that uses the system millisecond clock in the specified zone, never null
-
system
Gets a clock that obtains the current date and time using the system millisecond clock and the specified time-zone.The time-source wraps
System.currentTimeMillis()
, thus it has at best millisecond resolution.- Parameters:
zone
- the time-zone to use to convert to date-times, not null- Returns:
- a clock that uses the system millisecond clock in the specified zone, never null
-
clockDefaultZone
Gets a clock that obtains the current date and time using the specified time-source and default time-zone.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.
- Parameters:
timeSource
- the time-source to use to obtain the current time, not null- Returns:
- a clock that uses the system millisecond clock in the specified zone, never null
-
clock
Gets a clock that obtains the current date and time using the specified time-source and time-zone.- Parameters:
timeSource
- the time-source to use to obtain the current time, not nulltimeZone
- the time-zone to use to convert to date-times, not null- Returns:
- a clock that uses the system millisecond clock in the specified zone, never null
-
getSource
Gets the time-source being used to create dates and times.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
.- Returns:
- the time-source being used to obtain instants, never null
- Throws:
UnsupportedOperationException
- if the implementation does not support accessing the time-source
-
withSource
Returns a copy of this clock with a different time-source.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
.- Parameters:
timeSource
- the time-source to change to, not null- Returns:
- the new clock with the altered time-source, never null
- Throws:
UnsupportedOperationException
- if the implementation does not support changing the time-source
-
getZone
Gets the time-zone being used to create dates and times.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
.- Returns:
- the time-zone being used to interpret instants, never null
- Throws:
UnsupportedOperationException
- if the implementation does not support accessing the time-zone
-
withZone
Returns a copy of this clock with a different time-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
.- Parameters:
zone
- the time-zone to change to, not null- Returns:
- the new clock with the altered time-zone, never null
- Throws:
UnsupportedOperationException
- if the implementation does not support changing the time-zone
-
instant
Gets the current 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 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 the time-source, never null
- Throws:
CalendricalException
- if the instant cannot be obtained, not thrown by most implementations
-
today
Gets today's date.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()
.- Returns:
- the current date, never null
- Throws:
CalendricalException
- if the date cannot be created
-
yesterday
Gets yesterday's date.This returns yesterday's date from the clock. This is calculated relative to
today()
.- Returns:
- the date yesterday, never null
- Throws:
CalendricalException
- if the date cannot be created
-
tomorrow
Gets tomorrow's date.This returns tomorrow's date from the clock. This is calculated relative to
today()
.- Returns:
- the date tomorrow, never null
- Throws:
CalendricalException
- if the date cannot be created
-
yearMonth
Gets the current year-month.This returns the current year-month from the clock. This is derived from
today()
.- Returns:
- the current year-month, never null
- Throws:
CalendricalException
- if the year cannot be created
-
year
Gets the current year.This returns the current year from the clock. This is derived from
today()
.- Returns:
- the current year, never null
- Throws:
CalendricalException
- if the year cannot be created
-
time
Gets the current time with maximum resolution of up to nanoseconds.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()
.- Returns:
- the current time, never null
- Throws:
CalendricalException
- if the time cannot be created
-
timeToSecond
Gets the current time with a resolution of seconds.This returns the current time from the clock rounded to the second. This is achieved by setting the nanosecond part to be zero.
- Returns:
- the current time to the nearest second, never null
- Throws:
CalendricalException
- if the time cannot be created
-
timeToMinute
Gets the current time with a resolution of minutes.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.
- Returns:
- the current time to the nearest minute, never null
- Throws:
CalendricalException
- if the time cannot be created
-
dateTime
Gets the current date-time with maximum resolution of up to nanoseconds.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()
.- Returns:
- the current date-time, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-
dateTimeToSecond
Gets the current date-time with a resolution of seconds.This returns the current date-time from the clock rounded to the second. This is achieved by setting the nanosecond part to be zero.
- Returns:
- the current date-time to the nearest second, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-
dateTimeToMinute
Gets the current date-time with a resolution of minutes.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.
- Returns:
- the current date-time to the nearest minute, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-
offsetDate
Gets the current offset date.This returns the current offset date from the clock with the correct offset from
getZone()
.The offset date is derived by default from
instant()
andgetZone()
.- Returns:
- the current offset date, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-
offsetTime
Gets the current offset time with maximum resolution of up to nanoseconds.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, thesystem clock
has up to millisecond resolution.The offset time is derived by default from
instant()
andgetZone()
.- Returns:
- the current offset time, never null
- Throws:
CalendricalException
- if the time cannot be created
-
offsetTimeToSecond
Gets the current offset time with a resolution of seconds.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.- Returns:
- the current offset time to the nearest second, never null
- Throws:
CalendricalException
- if the time cannot be created
-
offsetTimeToMinute
Gets the current offset time with a resolution of minutes.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.- Returns:
- the current offset time to the nearest minute, never null
- Throws:
CalendricalException
- if the time cannot be created
-
offsetDateTime
Gets the current offset date-time with maximum resolution of up to nanoseconds.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, thesystem clock
has up to millisecond resolution.The offset date-time is derived by default from
instant()
andgetZone()
.- Returns:
- the current offset date-time, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-
offsetDateTimeToSecond
Gets the current offset date-time with a resolution of seconds.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.- Returns:
- the current offset date-time to the nearest second, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-
offsetDateTimeToMinute
Gets the current offset date-time with a resolution of minutes.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.- Returns:
- the current offset date-time to the nearest minute, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-
zonedDateTime
Gets the current zoned date-time.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, thesystem clock
has up to millisecond resolution.The zoned date-time is derived by default from
instant()
andgetZone()
.- Returns:
- the current zoned date-time, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-
zonedDateTimeToSecond
Gets the current zoned date-time with a resolution of seconds.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.- Returns:
- the current zoned date-time to the nearest second, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-
zonedDateTimeToMinute
Gets the current zoned date-time with a resolution of minutes.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.- Returns:
- the current zoned date-time to the nearest minute, never null
- Throws:
CalendricalException
- if the date-time cannot be created
-