Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Date and Time

The Clock class

Reference for java.time.Clock: pass a clock instead of calling now() so code is testable. Covers systemUTC, fixed, offset and tick clocks, with examples.

Clock is a source of the current instant plus a time zone. Every now() method in java.time has an overload that accepts a Clock: LocalDate.now(clock), Instant.now(clock), ZonedDateTime.now(clock). In production you pass the system clock; in tests you pass a clock whose time you control.

The point is design. Code that calls LocalDate.now() directly is hard to test, because its answer changes every day. Code that receives a Clock (through a constructor, for example) can be checked for any date you like, including awkward ones such as a leap day or the midnight a daylight saving change happens.

Java
Clock fixed = Clock.fixed(Instant.parse("2026-03-01T10:00:00Z"), ZoneOffset.UTC);
LocalDate today = LocalDate.now(fixed);   // 2026-03-01

Try it

Java A fixed clock and a service that uses it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Offset, tick and zone variants

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
abstract Instant instant()
abstract ZoneId getZone()
abstract Clock withZone(ZoneId zone)
long millis()
Factory Description
Clock.systemUTC() The system clock in UTC.
Clock.systemDefaultZone() The system clock in the JVM's default zone.
Clock.system(ZoneId) The system clock in a given zone.
Clock.fixed(Instant, ZoneId) A clock that always returns the same instant.
Clock.offset(Clock, Duration) A clock shifted forward or back by a duration.
Clock.tick(Clock, Duration) A clock that returns the instant truncated to a multiple of the duration.
Clock.tickSeconds(ZoneId), tickMinutes(ZoneId), tickMillis(ZoneId) Shortcuts for system clocks that tick in whole units.

Usage notes

  • Inject the clock. Take a Clock as a constructor parameter; use Clock.systemUTC() in main and Clock.fixed(...) in tests. This avoids static mocking.
  • Prefer UTC for stored values. Take Instant.now(clock) for timestamps and convert to local time only for display.
  • A fixed clock never advances. Two calls to instant() return the same value, so elapsed-time logic sees zero. Use Clock.offset or a hand-written mutable Clock subclass to simulate progress.
  • Writing your own clock. Subclass Clock and implement instant(), getZone() and withZone(...). A test clock with a plus(Duration) method is a popular helper.
  • Not for measuring durations. The system clock can jump when the machine's time is adjusted. Use System.nanoTime() to measure how long something takes.
  • systemDefaultZone() makes tests machine-dependent. Fix the zone explicitly where output matters.
  • Immutable and thread-safe for the standard implementations.