8071919: Add java.time.Clock.tickMillis(ZoneId zone) method

Reviewed-by: dfuchs, rriggs, scolebourne

jdk/src/java.base/share/classes/java/time/Clock.java

@@ -65,7 +65,7 @@ import java.io.IOException;
 import java.io.ObjectInputStream;
 import static java.time.LocalTime.NANOS_PER_MINUTE;
 import static java.time.LocalTime.NANOS_PER_SECOND;
-
+import static java.time.LocalTime.NANOS_PER_MILLI;
 import java.io.Serializable;
 import java.util.Objects;
 import java.util.TimeZone;
@@ -182,7 +182,7 @@ public abstract class Clock {
     }
 
     /**
-     * Obtains a clock that returns the current instant using best available
+     * Obtains a clock that returns the current instant using the best available
      * system clock.
      * <p>
      * This clock is based on the best available system clock.
@@ -204,10 +204,34 @@ public abstract class Clock {
         return new SystemClock(zone);
     }
 
+    //-------------------------------------------------------------------------
+    /**
+     * Obtains a clock that returns the current instant ticking in whole milliseconds
+     * using the best available system clock.
+     * <p>
+     * This clock will always have the nano-of-second field truncated to milliseconds.
+     * This ensures that the visible time ticks in whole milliseconds.
+     * The underlying clock is the best available system clock, equivalent to
+     * using {@link #system(ZoneId)}.
+     * <p>
+     * Implementations may use a caching strategy for performance reasons.
+     * As such, it is possible that the start of the millisecond observed via this
+     * clock will be later than that observed directly via the underlying clock.
+     * <p>
+     * The returned implementation is immutable, thread-safe and {@code Serializable}.
+     * It is equivalent to {@code tick(system(zone), Duration.ofMillis(1))}.
+     *
+     * @param zone  the time-zone to use to convert the instant to date-time, not null
+     * @return a clock that ticks in whole milliseconds using the specified zone, not null
+     */
+    public static Clock tickMillis(ZoneId zone) {
+        return new TickClock(system(zone), NANOS_PER_MILLI);
+    }
+
     //-------------------------------------------------------------------------
     /**
      * Obtains a clock that returns the current instant ticking in whole seconds
-     * using best available system clock.
+     * using the best available system clock.
      * <p>
      * This clock will always have the nano-of-second field set to zero.
      * This ensures that the visible time ticks in whole seconds.
@@ -230,7 +254,7 @@ public abstract class Clock {
 
     /**
      * Obtains a clock that returns the current instant ticking in whole minutes
-     * using best available system clock.
+     * using the best available system clock.
      * <p>
      * This clock will always have the nano-of-second and second-of-minute fields set to zero.
      * This ensures that the visible time ticks in whole minutes.

jdk/src/java.base/share/classes/java/time/LocalTime.java

@@ -189,6 +189,10 @@ public final class LocalTime
      * Microseconds per day.
      */
     static final long MICROS_PER_DAY = SECONDS_PER_DAY * 1000_000L;
+    /**
+     * Nanos per millisecond.
+     */
+    static final long NANOS_PER_MILLI = 1000_000L;
     /**
      * Nanos per second.
      */

jdk/test/java/time/tck/java/time/TCKClock_Tick.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -159,6 +159,17 @@ public class TCKClock_Tick extends AbstractTCKTest {
         Clock.tick(Clock.systemUTC(), null);
     }
 
+    //-----------------------------------------------------------------------
+    public void test_tickMillis_ZoneId() throws Exception {
+        Clock test = Clock.tickMillis(PARIS);
+        assertEquals(test.getZone(), PARIS);
+        assertEquals(test.instant().getNano() % 1000_000, 0);
+    }
+
+    @Test(expectedExceptions = NullPointerException.class)
+    public void test_tickMillis_ZoneId_nullZoneId() {
+        Clock.tickMillis(null);
+    }
     //-----------------------------------------------------------------------
     public void test_tickSeconds_ZoneId() throws Exception {
         Clock test = Clock.tickSeconds(PARIS);