101 * <p> |
101 * <p> |
102 * The {@code system} factory methods provide clocks based on the best available |
102 * The {@code system} factory methods provide clocks based on the best available |
103 * system clock This may use {@link System#currentTimeMillis()}, or a higher |
103 * system clock This may use {@link System#currentTimeMillis()}, or a higher |
104 * resolution clock if one is available. |
104 * resolution clock if one is available. |
105 * |
105 * |
106 * <h3>Specification for implementors</h3> |
106 * @implSpec |
107 * This abstract class must be implemented with care to ensure other operate correctly. |
107 * This abstract class must be implemented with care to ensure other operate correctly. |
108 * All implementations that can be instantiated must be final, immutable and thread-safe. |
108 * All implementations that can be instantiated must be final, immutable and thread-safe. |
109 * <p> |
109 * <p> |
110 * The principal methods are defined to allow the throwing of an exception. |
110 * The principal methods are defined to allow the throwing of an exception. |
111 * In normal use, no exceptions will be thrown, however one possible implementation would be to |
111 * In normal use, no exceptions will be thrown, however one possible implementation would be to |
112 * obtain the time from a central time server across the network. Obviously, in this case the |
112 * obtain the time from a central time server across the network. Obviously, in this case the |
113 * lookup could fail, and so the method is permitted to throw an exception. |
113 * lookup could fail, and so the method is permitted to throw an exception. |
114 * <p> |
114 * <p> |
115 * The returned instants from {@code Clock} work on a time-scale that ignores leap seconds. |
115 * The returned instants from {@code Clock} work on a time-scale that ignores leap seconds, |
116 * If the implementation wraps a source that provides leap second information, then a mechanism |
116 * as described in {@link Instant}. If the implementation wraps a source that provides leap |
117 * should be used to "smooth" the leap second, such as UTC-SLS. |
117 * second information, then a mechanism should be used to "smooth" the leap second. |
|
118 * The Java Time-Scale mandates the use of UTC-SLS, however clock implementations may choose |
|
119 * how accurate they are with the time-scale so long as they document how they work. |
|
120 * Implementations are therefore not required to actually perform the UTC-SLS slew or to |
|
121 * otherwise be aware of leap seconds. |
118 * <p> |
122 * <p> |
119 * Implementations should implement {@code Serializable} wherever possible and must |
123 * Implementations should implement {@code Serializable} wherever possible and must |
120 * document whether or not they do support serialization. |
124 * document whether or not they do support serialization. |
|
125 * |
|
126 * @implNote |
|
127 * The clock implementation provided here is based on {@link System#currentTimeMillis()}. |
|
128 * That method provides little to no guarantee about the accuracy of the clock. |
|
129 * Applications requiring a more accurate clock must implement this abstract class |
|
130 * themselves using a different external clock, such as an NTP server. |
121 * |
131 * |
122 * @since 1.8 |
132 * @since 1.8 |
123 */ |
133 */ |
124 public abstract class Clock { |
134 public abstract class Clock { |
125 |
135 |
368 |
378 |
369 //------------------------------------------------------------------------- |
379 //------------------------------------------------------------------------- |
370 /** |
380 /** |
371 * Gets the current millisecond instant of the clock. |
381 * Gets the current millisecond instant of the clock. |
372 * <p> |
382 * <p> |
373 * This returns the millisecond-based instant, measured from 1970-01-01T00:00 UTC. |
383 * This returns the millisecond-based instant, measured from 1970-01-01T00:00Z (UTC). |
374 * This is equivalent to the definition of {@link System#currentTimeMillis()}. |
384 * This is equivalent to the definition of {@link System#currentTimeMillis()}. |
375 * <p> |
385 * <p> |
376 * Most applications should avoid this method and use {@link Instant} to represent |
386 * Most applications should avoid this method and use {@link Instant} to represent |
377 * an instant on the time-line rather than a raw millisecond value. |
387 * an instant on the time-line rather than a raw millisecond value. |
378 * This method is provided to allow the use of the clock in high performance use cases |
388 * This method is provided to allow the use of the clock in high performance use cases |
379 * where the creation of an object would be unacceptable. |
389 * where the creation of an object would be unacceptable. |
380 * <p> |
390 * <p> |
381 * The default implementation currently calls {@link #instant}. |
391 * The default implementation currently calls {@link #instant}. |
382 * |
392 * |
383 * @return the current millisecond instant from this clock, measured from |
393 * @return the current millisecond instant from this clock, measured from |
384 * the Java epoch of 1970-01-01T00:00 UTC, not null |
394 * the Java epoch of 1970-01-01T00:00Z (UTC), not null |
385 * @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations |
395 * @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations |
386 */ |
396 */ |
387 public long millis() { |
397 public long millis() { |
388 return instant().toEpochMilli(); |
398 return instant().toEpochMilli(); |
389 } |
399 } |