Class 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 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.

    • Constructor Detail

      • Clock

        protected Clock()
        Constructor accessible by subclasses.
    • 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 null
        timeZone - 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 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.

        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() and getZone().

        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, the system clock has up to millisecond resolution.

        The offset time is derived by default from instant() and getZone().

        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, the system clock has up to millisecond resolution.

        The offset date-time is derived by default from instant() and getZone().

        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, the system clock has up to millisecond resolution.

        The zoned date-time is derived by default from instant() and getZone().

        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