1 /*
2 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 /*
27 * This file is available under and governed by the GNU General Public
28 * License version 2 only, as published by the Free Software Foundation.
29 * However, the following notice accompanied the original version of this
30 * file:
31 *
32 * Copyright (c) 2007-2012, Stephen Colebourne & Michael Nascimento Santos
33 *
34 * All rights reserved.
35 *
36 * Redistribution and use in source and binary forms, with or without
37 * modification, are permitted provided that the following conditions are met:
38 *
39 * * Redistributions of source code must retain the above copyright notice,
40 * this list of conditions and the following disclaimer.
41 *
42 * * Redistributions in binary form must reproduce the above copyright notice,
43 * this list of conditions and the following disclaimer in the documentation
44 * and/or other materials provided with the distribution.
45 *
46 * * Neither the name of JSR-310 nor the names of its contributors
47 * may be used to endorse or promote products derived from this software
48 * without specific prior written permission.
49 *
50 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
51 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
52 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
53 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
54 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
55 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
56 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
57 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
58 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
59 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
60 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
61 */
62 package java.time;
63
64 import static java.time.LocalTime.NANOS_PER_MINUTE;
65 import static java.time.LocalTime.NANOS_PER_SECOND;
66
67 import java.io.Serializable;
68 import java.util.Objects;
69 import java.util.TimeZone;
70
71 /**
72 * A clock providing access to the current instant, date and time using a time-zone.
73 * <p>
74 * Instances of this class are used to find the current instant, which can be
75 * interpreted using the stored time-zone to find the current date and time.
76 * As such, a clock can be used instead of {@link System#currentTimeMillis()}
77 * and {@link TimeZone#getDefault()}.
78 * <p>
79 * Use of a {@code Clock} is optional. All key date-time classes also have a
80 * {@code now()} factory method that uses the system clock in the default time zone.
81 * The primary purpose of this abstraction is to allow alternate clocks to be
82 * plugged in as and when required. Applications use an object to obtain the
83 * current time rather than a static method. This can simplify testing.
84 * <p>
85 * Best practice for applications is to pass a {@code Clock} into any method
86 * that requires the current instant. A dependency injection framework is one
87 * way to achieve this:
88 * <pre>
89 * public class MyBean {
90 * private Clock clock; // dependency inject
91 * ...
92 * public void process(LocalDate eventDate) {
93 * if (eventDate.isBefore(LocalDate.now(clock)) {
94 * ...
95 * }
96 * }
97 * }
98 * </pre>
99 * This approach allows an alternate clock, such as {@link #fixed(Instant, ZoneId) fixed}
100 * or {@link #offset(Clock, Duration) offset} to be used during testing.
101 * <p>
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
104 * resolution clock if one is available.
105 *
106 * @implSpec
107 * This abstract class must be implemented with care to ensure other classes operate correctly.
108 * All implementations that can be instantiated must be final, immutable and thread-safe.
109 * <p>
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
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.
114 * <p>
115 * The returned instants from {@code Clock} work on a time-scale that ignores leap seconds,
116 * as described in {@link Instant}. If the implementation wraps a source that provides leap
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.
122 * <p>
123 * Implementations should implement {@code Serializable} wherever possible and must
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.
131 *
132 * @since 1.8
133 */
134 public abstract class Clock {
135
136 /**
137 * Obtains a clock that returns the current instant using the best available
138 * system clock, converting to date and time using the UTC time-zone.
139 * <p>
140 * This clock, rather than {@link #systemDefaultZone()}, should be used when
141 * you need the current instant without the date or time.
142 * <p>
143 * This clock is based on the best available system clock.
144 * This may use {@link System#currentTimeMillis()}, or a higher resolution
145 * clock if one is available.
146 * <p>
147 * Conversion from instant to date or time uses the {@linkplain ZoneOffset#UTC UTC time-zone}.
148 * <p>
149 * The returned implementation is immutable, thread-safe and {@code Serializable}.
150 * It is equivalent to {@code system(ZoneOffset.UTC)}.
151 *
152 * @return a clock that uses the best available system clock in the UTC zone, not null
153 */
154 public static Clock systemUTC() {
155 return new SystemClock(ZoneOffset.UTC);
156 }
157
158 /**
159 * Obtains a clock that returns the current instant using the best available
160 * system clock, converting to date and time using the default time-zone.
161 * <p>
162 * This clock is based on the best available system clock.
163 * This may use {@link System#currentTimeMillis()}, or a higher resolution
164 * clock if one is available.
165 * <p>
166 * Using this method hard codes a dependency to the default time-zone into your application.
167 * It is recommended to avoid this and use a specific time-zone whenever possible.
168 * The {@link #systemUTC() UTC clock} should be used when you need the current instant
169 * without the date or time.
170 * <p>
171 * The returned implementation is immutable, thread-safe and {@code Serializable}.
172 * It is equivalent to {@code system(ZoneId.systemDefault())}.
173 *
174 * @return a clock that uses the best available system clock in the default zone, not null
175 * @see ZoneId#systemDefault()
176 */
177 public static Clock systemDefaultZone() {
178 return new SystemClock(ZoneId.systemDefault());
179 }
180
181 /**
182 * Obtains a clock that returns the current instant using best available
183 * system clock.
184 * <p>
185 * This clock is based on the best available system clock.
186 * This may use {@link System#currentTimeMillis()}, or a higher resolution
187 * clock if one is available.
188 * <p>
189 * Conversion from instant to date or time uses the specified time-zone.
190 * <p>
191 * The returned implementation is immutable, thread-safe and {@code Serializable}.
192 *
193 * @param zone the time-zone to use to convert the instant to date-time, not null
194 * @return a clock that uses the best available system clock in the specified zone, not null
195 */
196 public static Clock system(ZoneId zone) {
197 Objects.requireNonNull(zone, "zone");
198 return new SystemClock(zone);
199 }
200
201 //-------------------------------------------------------------------------
202 /**
203 * Obtains a clock that returns the current instant ticking in whole seconds
204 * using best available system clock.
205 * <p>
206 * This clock will always have the nano-of-second field set to zero.
207 * This ensures that the visible time ticks in whole seconds.
208 * The underlying clock is the best available system clock, equivalent to
209 * using {@link #system(ZoneId)}.
210 * <p>
211 * Implementations may use a caching strategy for performance reasons.
212 * As such, it is possible that the start of the second observed via this
213 * clock will be later than that observed directly via the underlying clock.
214 * <p>
215 * The returned implementation is immutable, thread-safe and {@code Serializable}.
216 * It is equivalent to {@code tick(system(zone), Duration.ofSeconds(1))}.
217 *
218 * @param zone the time-zone to use to convert the instant to date-time, not null
219 * @return a clock that ticks in whole seconds using the specified zone, not null
220 */
221 public static Clock tickSeconds(ZoneId zone) {
222 return new TickClock(system(zone), NANOS_PER_SECOND);
223 }
224
225 /**
226 * Obtains a clock that returns the current instant ticking in whole minutes
227 * using best available system clock.
228 * <p>
229 * This clock will always have the nano-of-second and second-of-minute fields set to zero.
230 * This ensures that the visible time ticks in whole minutes.
231 * The underlying clock is the best available system clock, equivalent to
232 * using {@link #system(ZoneId)}.
233 * <p>
234 * Implementations may use a caching strategy for performance reasons.
235 * As such, it is possible that the start of the minute observed via this
236 * clock will be later than that observed directly via the underlying clock.
237 * <p>
238 * The returned implementation is immutable, thread-safe and {@code Serializable}.
239 * It is equivalent to {@code tick(system(zone), Duration.ofMinutes(1))}.
240 *
241 * @param zone the time-zone to use to convert the instant to date-time, not null
242 * @return a clock that ticks in whole minutes using the specified zone, not null
243 */
244 public static Clock tickMinutes(ZoneId zone) {
245 return new TickClock(system(zone), NANOS_PER_MINUTE);
246 }
247
248 /**
249 * Obtains a clock that returns instants from the specified clock truncated
250 * to the nearest occurrence of the specified duration.
251 * <p>
252 * This clock will only tick as per the specified duration. Thus, if the duration
253 * is half a second, the clock will return instants truncated to the half second.
254 * <p>
255 * The tick duration must be positive. If it has a part smaller than a whole
256 * millisecond, then the whole duration must divide into one second without
257 * leaving a remainder. All normal tick durations will match these criteria,
258 * including any multiple of hours, minutes, seconds and milliseconds, and
259 * sensible nanosecond durations, such as 20ns, 250,000ns and 500,000ns.
260 * <p>
261 * A duration of zero or one nanosecond would have no truncation effect.
262 * Passing one of these will return the underlying clock.
263 * <p>
264 * Implementations may use a caching strategy for performance reasons.
265 * As such, it is possible that the start of the requested duration observed
266 * via this clock will be later than that observed directly via the underlying clock.
267 * <p>
268 * The returned implementation is immutable, thread-safe and {@code Serializable}
269 * providing that the base clock is.
270 *
271 * @param baseClock the base clock to base the ticking clock on, not null
272 * @param tickDuration the duration of each visible tick, not negative, not null
273 * @return a clock that ticks in whole units of the duration, not null
274 * @throws IllegalArgumentException if the duration is negative, or has a
275 * part smaller than a whole millisecond such that the whole duration is not
276 * divisible into one second
277 * @throws ArithmeticException if the duration is too large to be represented as nanos
278 */
279 public static Clock tick(Clock baseClock, Duration tickDuration) {
280 Objects.requireNonNull(baseClock, "baseClock");
281 Objects.requireNonNull(tickDuration, "tickDuration");
282 if (tickDuration.isNegative()) {
283 throw new IllegalArgumentException("Tick duration must not be negative");
284 }
285 long tickNanos = tickDuration.toNanos();
286 if (tickNanos % 1000_000 == 0) {
287 // ok, no fraction of millisecond
288 } else if (1000_000_000 % tickNanos == 0) {
289 // ok, divides into one second without remainder
290 } else {
291 throw new IllegalArgumentException("Invalid tick duration");
292 }
293 if (tickNanos <= 1) {
294 return baseClock;
295 }
296 return new TickClock(baseClock, tickNanos);
297 }
298
299 //-----------------------------------------------------------------------
300 /**
301 * Obtains a clock that always returns the same instant.
302 * <p>
303 * This clock simply returns the specified instant.
304 * As such, it is not a clock in the conventional sense.
305 * The main use case for this is in testing, where the fixed clock ensures
306 * tests are not dependent on the current clock.
307 * <p>
308 * The returned implementation is immutable, thread-safe and {@code Serializable}.
309 *
310 * @param fixedInstant the instant to use as the clock, not null
311 * @param zone the time-zone to use to convert the instant to date-time, not null
312 * @return a clock that always returns the same instant, not null
313 */
314 public static Clock fixed(Instant fixedInstant, ZoneId zone) {
315 Objects.requireNonNull(fixedInstant, "fixedInstant");
316 Objects.requireNonNull(zone, "zone");
317 return new FixedClock(fixedInstant, zone);
318 }
319
320 //-------------------------------------------------------------------------
321 /**
322 * Obtains a clock that returns instants from the specified clock with the
323 * specified duration added
324 * <p>
325 * This clock wraps another clock, returning instants that are later by the
326 * specified duration. If the duration is negative, the instants will be
327 * earlier than the current date and time.
328 * The main use case for this is to simulate running in the future or in the past.
329 * <p>
330 * A duration of zero would have no offsetting effect.
331 * Passing zero will return the underlying clock.
332 * <p>
333 * The returned implementation is immutable, thread-safe and {@code Serializable}
334 * providing that the base clock is.
335 *
336 * @param baseClock the base clock to add the duration to, not null
337 * @param offsetDuration the duration to add, not null
338 * @return a clock based on the base clock with the duration added, not null
339 */
340 public static Clock offset(Clock baseClock, Duration offsetDuration) {
341 Objects.requireNonNull(baseClock, "baseClock");
342 Objects.requireNonNull(offsetDuration, "offsetDuration");
343 if (offsetDuration.equals(Duration.ZERO)) {
344 return baseClock;
345 }
346 return new OffsetClock(baseClock, offsetDuration);
347 }
348
349 //-----------------------------------------------------------------------
350 /**
351 * Constructor accessible by subclasses.
352 */
353 protected Clock() {
354 }
355
356 //-----------------------------------------------------------------------
357 /**
358 * Gets the time-zone being used to create dates and times.
359 * <p>
360 * A clock will typically obtain the current instant and then convert that
361 * to a date or time using a time-zone. This method returns the time-zone used.
362 *
363 * @return the time-zone being used to interpret instants, not null
364 */
365 public abstract ZoneId getZone();
366
367 /**
368 * Returns a copy of this clock with a different time-zone.
369 * <p>
370 * A clock will typically obtain the current instant and then convert that
371 * to a date or time using a time-zone. This method returns a clock with
372 * similar properties but using a different time-zone.
373 *
374 * @param zone the time-zone to change to, not null
375 * @return a clock based on this clock with the specified time-zone, not null
376 */
377 public abstract Clock withZone(ZoneId zone);
378
379 //-------------------------------------------------------------------------
380 /**
381 * Gets the current millisecond instant of the clock.
382 * <p>
383 * This returns the millisecond-based instant, measured from 1970-01-01T00:00Z (UTC).
384 * This is equivalent to the definition of {@link System#currentTimeMillis()}.
385 * <p>
386 * Most applications should avoid this method and use {@link Instant} to represent
387 * an instant on the time-line rather than a raw millisecond value.
388 * This method is provided to allow the use of the clock in high performance use cases
389 * where the creation of an object would be unacceptable.
390 * <p>
391 * The default implementation currently calls {@link #instant}.
392 *
393 * @return the current millisecond instant from this clock, measured from
394 * the Java epoch of 1970-01-01T00:00Z (UTC), not null
395 * @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations
396 */
397 public long millis() {
398 return instant().toEpochMilli();
399 }
400
401 //-----------------------------------------------------------------------
402 /**
403 * Gets the current instant of the clock.
404 * <p>
405 * This returns an instant representing the current instant as defined by the clock.
406 *
407 * @return the current instant from this clock, not null
408 * @throws DateTimeException if the instant cannot be obtained, not thrown by most implementations
409 */
410 public abstract Instant instant();
411
412 //-----------------------------------------------------------------------
413 /**
414 * Checks if this clock is equal to another clock.
415 * <p>
416 * Clocks should override this method to compare equals based on
417 * their state and to meet the contract of {@link Object#equals}.
418 * If not overridden, the behavior is defined by {@link Object#equals}
419 *
420 * @param obj the object to check, null returns false
421 * @return true if this is equal to the other clock
422 */
423 @Override
424 public boolean equals(Object obj) {
425 return super.equals(obj);
426 }
427
428 /**
429 * A hash code for this clock.
430 * <p>
431 * Clocks should override this method based on
432 * their state and to meet the contract of {@link Object#hashCode}.
433 * If not overridden, the behavior is defined by {@link Object#hashCode}
434 *
435 * @return a suitable hash code
436 */
437 @Override
438 public int hashCode() {
439 return super.hashCode();
440 }
441
442 //-----------------------------------------------------------------------
443 /**
444 * Implementation of a clock that always returns the latest time from
445 * {@link System#currentTimeMillis()}.
446 */
447 static final class SystemClock extends Clock implements Serializable {
448 private static final long serialVersionUID = 6740630888130243051L;
449 private final ZoneId zone;
450
451 SystemClock(ZoneId zone) {
452 this.zone = zone;
453 }
454 @Override
455 public ZoneId getZone() {
456 return zone;
457 }
458 @Override
459 public Clock withZone(ZoneId zone) {
460 if (zone.equals(this.zone)) { // intentional NPE
461 return this;
462 }
463 return new SystemClock(zone);
464 }
465 @Override
466 public long millis() {
467 return System.currentTimeMillis();
468 }
469 @Override
470 public Instant instant() {
471 return Instant.ofEpochMilli(millis());
472 }
473 @Override
474 public boolean equals(Object obj) {
475 if (obj instanceof SystemClock) {
476 return zone.equals(((SystemClock) obj).zone);
477 }
478 return false;
479 }
480 @Override
481 public int hashCode() {
482 return zone.hashCode() + 1;
483 }
484 @Override
485 public String toString() {
486 return "SystemClock[" + zone + "]";
487 }
488 }
489
490 //-----------------------------------------------------------------------
491 /**
492 * Implementation of a clock that always returns the same instant.
493 * This is typically used for testing.
494 */
495 static final class FixedClock extends Clock implements Serializable {
496 private static final long serialVersionUID = 7430389292664866958L;
497 private final Instant instant;
498 private final ZoneId zone;
499
500 FixedClock(Instant fixedInstant, ZoneId zone) {
501 this.instant = fixedInstant;
502 this.zone = zone;
503 }
504 @Override
505 public ZoneId getZone() {
506 return zone;
507 }
508 @Override
509 public Clock withZone(ZoneId zone) {
510 if (zone.equals(this.zone)) { // intentional NPE
511 return this;
512 }
513 return new FixedClock(instant, zone);
514 }
515 @Override
516 public long millis() {
517 return instant.toEpochMilli();
518 }
519 @Override
520 public Instant instant() {
521 return instant;
522 }
523 @Override
524 public boolean equals(Object obj) {
525 if (obj instanceof FixedClock) {
526 FixedClock other = (FixedClock) obj;
527 return instant.equals(other.instant) && zone.equals(other.zone);
528 }
529 return false;
530 }
531 @Override
532 public int hashCode() {
533 return instant.hashCode() ^ zone.hashCode();
534 }
535 @Override
536 public String toString() {
537 return "FixedClock[" + instant + "," + zone + "]";
538 }
539 }
540
541 //-----------------------------------------------------------------------
542 /**
543 * Implementation of a clock that adds an offset to an underlying clock.
544 */
545 static final class OffsetClock extends Clock implements Serializable {
546 private static final long serialVersionUID = 2007484719125426256L;
547 private final Clock baseClock;
548 private final Duration offset;
549
550 OffsetClock(Clock baseClock, Duration offset) {
551 this.baseClock = baseClock;
552 this.offset = offset;
553 }
554 @Override
555 public ZoneId getZone() {
556 return baseClock.getZone();
557 }
558 @Override
559 public Clock withZone(ZoneId zone) {
560 if (zone.equals(baseClock.getZone())) { // intentional NPE
561 return this;
562 }
563 return new OffsetClock(baseClock.withZone(zone), offset);
564 }
565 @Override
566 public long millis() {
567 return Math.addExact(baseClock.millis(), offset.toMillis());
568 }
569 @Override
570 public Instant instant() {
571 return baseClock.instant().plus(offset);
572 }
573 @Override
574 public boolean equals(Object obj) {
575 if (obj instanceof OffsetClock) {
576 OffsetClock other = (OffsetClock) obj;
577 return baseClock.equals(other.baseClock) && offset.equals(other.offset);
578 }
579 return false;
580 }
581 @Override
582 public int hashCode() {
583 return baseClock.hashCode() ^ offset.hashCode();
584 }
585 @Override
586 public String toString() {
587 return "OffsetClock[" + baseClock + "," + offset + "]";
588 }
589 }
590
591 //-----------------------------------------------------------------------
592 /**
593 * Implementation of a clock that adds an offset to an underlying clock.
594 */
595 static final class TickClock extends Clock implements Serializable {
596 private static final long serialVersionUID = 6504659149906368850L;
597 private final Clock baseClock;
598 private final long tickNanos;
599
600 TickClock(Clock baseClock, long tickNanos) {
601 this.baseClock = baseClock;
602 this.tickNanos = tickNanos;
603 }
604 @Override
605 public ZoneId getZone() {
606 return baseClock.getZone();
607 }
608 @Override
609 public Clock withZone(ZoneId zone) {
610 if (zone.equals(baseClock.getZone())) { // intentional NPE
611 return this;
612 }
613 return new TickClock(baseClock.withZone(zone), tickNanos);
614 }
615 @Override
616 public long millis() {
617 long millis = baseClock.millis();
618 return millis - Math.floorMod(millis, tickNanos / 1000_000L);
619 }
620 @Override
621 public Instant instant() {
622 if ((tickNanos % 1000_000) == 0) {
623 long millis = baseClock.millis();
624 return Instant.ofEpochMilli(millis - Math.floorMod(millis, tickNanos / 1000_000L));
625 }
626 Instant instant = baseClock.instant();
627 long nanos = instant.getNano();
628 long adjust = Math.floorMod(nanos, tickNanos);
629 return instant.minusNanos(adjust);
630 }
631 @Override
632 public boolean equals(Object obj) {
633 if (obj instanceof TickClock) {
634 TickClock other = (TickClock) obj;
635 return baseClock.equals(other.baseClock) && tickNanos == other.tickNanos;
636 }
637 return false;
638 }
639 @Override
640 public int hashCode() {
641 return baseClock.hashCode() ^ ((int) (tickNanos ^ (tickNanos >>> 32)));
642 }
643 @Override
644 public String toString() {
645 return "TickClock[" + baseClock + "," + Duration.ofNanos(tickNanos) + "]";
646 }
647 }
648
649 }