Class Clock
- java.lang.Object
-
- javax.time.calendar.Clock
-
- Direct Known Subclasses:
Clock.TimeSourceClock
public abstract class Clock extends java.lang.Object
A clock providing access to the current date and time.The Time Framework for Java abstracts the concept of the 'current time' into two interfaces -
TimeSource
andClock
. 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 asTimeSource.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()
andgetZone()
. This will cause all the other methods to work as they are derived from just these two. Subclasses should implementwithSource()
andwithZone()
if possible to allow the user to change the time-source and time-zone. The default implementation of these four methods throws anUnsupportedOperationException
.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 throwUnsupportedOperationException
, which would be fine for testing but not recommended for production usage.Subclass implementations should implement
Serializable
wherever possible. They should also implementequals()
,hashCode()
andtoString()
based on their state.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
Clock.TimeSourceClock
Implementation of a clock based on a time-source.
-
Constructor Summary
Constructors Modifier Constructor Description protected
Clock()
Constructor accessible by subclasses.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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.
-
-
-
Method Detail
-
systemDefaultZone
public static Clock 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
public 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.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
public static Clock clockDefaultZone(TimeSource timeSource)
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
public 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.- 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
public TimeSource 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:
java.lang.UnsupportedOperationException
- if the implementation does not support accessing the time-source
-
withSource
public Clock withSource(TimeSource timeSource)
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:
java.lang.UnsupportedOperationException
- if the implementation does not support changing the time-source
-
getZone
public TimeZone 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:
java.lang.UnsupportedOperationException
- if the implementation does not support accessing the time-zone
-
withZone
public Clock withZone(TimeZone zone)
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:
java.lang.UnsupportedOperationException
- if the implementation does not support changing the time-zone
-
instant
public Instant 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
public LocalDate 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
public LocalDate 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
public LocalDate 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
public YearMonth 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
public Year 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
public LocalTime 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
public LocalTime 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
public LocalTime 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
public LocalDateTime 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
public LocalDateTime 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
public LocalDateTime 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
public OffsetDate 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
public OffsetTime 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
public OffsetTime 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
public OffsetTime 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
public OffsetDateTime 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
public OffsetDateTime 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
public OffsetDateTime 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
public ZonedDateTime 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
public ZonedDateTime 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
public ZonedDateTime 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
-
-