* Best practice for applications is to pass a {@code Clock} into any method - * that requires the current instant and time-zone. A dependency injection framework - * is one way to achieve this: + * that requires the current instant. A dependency injection framework is one + * way to achieve this: *
* public class MyBean {
* private Clock clock; // dependency inject
@@ -105,16 +105,39 @@ import jdk.internal.misc.VM;
* The {@code system} factory methods provide clocks based on the best available
* system clock This may use {@link System#currentTimeMillis()}, or a higher
* resolution clock if one is available.
+ *
+ * @implSpec
+ * This abstract class must be implemented with care to ensure other classes operate correctly.
+ * All implementations that can be instantiated must be final, immutable and thread-safe.
+ *
+ * The principal methods are defined to allow the throwing of an exception.
+ * In normal use, no exceptions will be thrown, 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.
+ *
+ * The returned instants from {@code Clock} work on a time-scale that ignores leap seconds,
+ * as described in {@link Instant}. If the implementation wraps a source that provides leap
+ * second information, then a mechanism should be used to "smooth" the leap second.
+ * The Java Time-Scale mandates the use of UTC-SLS, however clock implementations may choose
+ * how accurate they are with the time-scale so long as they document how they work.
+ * Implementations are therefore not required to actually perform the UTC-SLS slew or to
+ * otherwise be aware of leap seconds.
*
- * Related to this class is {@link InstantSource} which is an interface that only
- * provides access to the current instant, and does not provide access to the time-zone.
- * Where an application only requires the current instant {@code InstantSource} should
- * be preferred to this class. For example, his might be the case where the time-zone
- * is provided by a separate user localization subsystem.
+ * Implementations should implement {@code Serializable} wherever possible and must
+ * document whether or not they do support serialization.
+ *
+ * @implNote
+ * The clock implementation provided here is based on the same underlying clock
+ * as {@link System#currentTimeMillis()}, but may have a precision finer than
+ * milliseconds if available.
+ * However, little to no guarantee is provided about the accuracy of the
+ * underlying clock. Applications requiring a more accurate clock must implement
+ * this abstract class themselves using a different external clock, such as an
+ * NTP server.
*
* @since 1.8
*/
-public abstract class Clock implements InstantSource {
+public abstract class Clock {
/**
* Obtains a clock that returns the current instant using the best available
@@ -385,7 +408,6 @@ public abstract class Clock implements InstantSource {
* @param zone the time-zone to change to, not null
* @return a clock based on this clock with the specified time-zone, not null
*/
- @Override
public abstract Clock withZone(ZoneId zone);
//-------------------------------------------------------------------------
@@ -406,7 +428,6 @@ public abstract class Clock implements InstantSource {
* the Java epoch of 1970-01-01T00:00Z (UTC), not null
* @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations
*/
- @Override
public long millis() {
return instant().toEpochMilli();
}
@@ -420,7 +441,6 @@ public abstract class Clock implements InstantSource {
* @return the current instant from this clock, not null
* @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations
*/
- @Override
public abstract Instant instant();
//-----------------------------------------------------------------------
@@ -720,54 +740,4 @@ public abstract class Clock implements InstantSource {
}
}