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.
Clock fixed = Clock.fixed(Instant.parse("2026-03-01T10:00:00Z"), ZoneOffset.UTC); LocalDate today = LocalDate.now(fixed); // 2026-03-01
Try 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.
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
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
Clockas a constructor parameter; useClock.systemUTC()inmainandClock.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. UseClock.offsetor a hand-written mutableClocksubclass to simulate progress. - Writing your own clock. Subclass
Clockand implementinstant(),getZone()andwithZone(...). A test clock with aplus(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.
Related
Instant,ZoneIdandZoneOffset,LocalDate,Duration- Lessons: Dates and times