What is the main purpose of the new interface java.time.InstantSource over existing abstract class Clock?

Question

A new interface java.time.InstantSource was added in Java 17. What is the use case of that additional abstraction if all implementations of that interface are Clock implementations too anyway?

Answer 1

With thanks to NoDataFound for the link in the comment (link repeated at the bottom of this answer). The “bug” report by Stephen Colebourne (original developer of java.time) says:

Problem

Since java.time was first added in Java 8, it has become apparent that there is a missing concept - a source of Instant independent of time zone. Put simply, if the only thing you want is an Instant, then Clock isn't the right API because it forces you to think about time zones.

A good architectural design for time-based code would have a separation between the abstraction of the OS clock (dependency injected for unit testing), and the time zone linked to user localization. Passing these two things around separately is key. To achieve this as it stands, developers must either write their own TimeSource or InstantSource interface, or use Clock and "hold their nose" to ignore the time zone held within.

A Supplier<Instant> obviously performs similar functionality, but it lacks discoverability and understandability. Plus, injecting generified interfaces tends to be painful.

In my words: The Clock class was introduced as a source of the current time. Conceptually a source of the current time should be independent of time zone. The Clock nevertheless has a time zone. Possibly for practical purposes so that you can draw all sorts of date-time objects from it: LocalDate, ZonedDateTime, LocalTime, etc.

The InstantSource interface asked about realizes the clock concept that I just described: a source of the current time that is independent of time zone. For when a clock with time zone is too heavyweight for your purpose.

One of the purposes of both Clock and InstantSource is testability: With those you can control which time is considered “the current time” when your tests are run, which is often required when you want reproducible tests.

… if anyway all implementations of that interface are Clock implementations also?

I haven’t checked whether all InstantSource implementations shipped with Java 17 are Clock subclasses. Even if this is the case, (1) it is not the point, and (2) there’s no one stopping you implementing an InstantSource that is not a Clock. Abstraction is a key concept in programming. If you want only Instants, then you want to program against a simple interface that can give you only Instants. InstantSource abstracts away the fact that the object you are using would also be able to play the rôle of a Clock in some other context. The InstantSource interface is a school example of applying the well-respected Façade design pattern (link below). With Stephen Colebourne’s descriptive words from the bug system, the interface frees the programmer from „holding their nose” while obtaining Instants.

Links

• Add java.time.InstantSource in the OpenJDK Bug System.
• Facade pattern on Wikipedia.