RFR: 8266846: Add java.time.InstantSource

[Roger Riggs]

On Thu, 13 May 2021 20:52:33 GMT, Stephen Colebourne <scolebourne at openjdk.org> wrote:

> 8266846: Add java.time.InstantSource

Changes requested by rriggs (Reviewer).

src/java.base/share/classes/java/time/Clock.java line 128:

> 126:  * Implementations should implement {@code Serializable} wherever possible and must
> 127:  * document whether or not they do support serialization.
> 128:  *

The ImplSpec needs to say how it is implemented.
The 'implements InstantSource' can not mandate any particular implementation. Its just an interface the real behavior comes from its implementations.  In this case Clock.  Referring to the static methods of InstantSource behavior may be sufficient because that behavior is concrete.

src/java.base/share/classes/java/time/InstantSource.java line 36:

> 34:  * Instances of this interface are used to find the current instant.
> 35:  * As such, an {@code InstantSource} can be used instead of {@link System#currentTimeMillis()}.
> 36:  * <p>

The word 'current' is likely to misleading here.  The specification of an interface does not have any context in which to describe what the instant represents or what it is relative to.
Given the intended use cases, it is definitely not always related to System.currentTimeMillis() 
which is bound to the running system.
i think the best you could say is that it returns an instant provided by the source as does the 'instance()' method.

src/java.base/share/classes/java/time/InstantSource.java line 64:

> 62:  * @implSpec
> 63:  * This interface must be implemented with care to ensure other classes operate correctly.
> 64:  * All implementations must be thread-safe.

It  would be useful to expand on the invariants that must be maintained, or examples of incorrect implementations.

src/java.base/share/classes/java/time/InstantSource.java line 165:

> 163:      */
> 164:     static InstantSource fixed(Instant fixedInstant) {
> 165:         return Clock.fixed(fixedInstant, ZoneOffset.UTC);

Instant might also implement InstantSource, returning itself.
This fixed method would be unnecessary because an Instant is itself a InstantSource.

-------------

PR: https://git.openjdk.java.net/jdk/pull/4016