Java Clock Class Methods with Examples

This article is the series of Java Date Time API TutorialIn this article, we will discuss important methods or APIs of the Java Clock class from the java.time package.

The Clock class was added in Java 8 and provides access to an instant in time using the best available system clock, and to be used as a time provider which can be effectively stubbed for testing purposes.
Instances of this class are used to find the current instant, which can be interpreted using the stored time-zone to find the current date and time. As such, a clock can be used instead of System.currentTimeMillis() and TimeZone.getDefault().

Clock Class Diagram

The below class diagram shows a list of methods that the Clock class provides.

Java Clock Class Methods/APIs with Examples

Let's explore a few important and commonly used Clock methods with examples.

instant()

This method is used to get the current instant of the clock
Clock clock = Clock.systemDefaultZone();
Clock clock1 = Clock.systemUTC();
System.out.println("Clock 1 Instant: " + clock.instant());
System.out.println("Clock 2 Instant: " + clock1.instant());
Output:
Clock 1 Instant: 2018-12-22T07:20:26.681Z
Clock 2 Instant: 2018-12-22T07:20:26.704Z

fixed()

This method returns a clock that always returns the same instant. The main use case for this method is in testing, where the fixed clock ensures that tests are not dependent on the current clock.
Clock clock = Clock.fixed(Instant.ofEpochSecond(3600), ZoneId.systemDefault());
Clock clock1 = Clock.fixed(Instant.ofEpochSecond(3600), ZoneId.systemDefault());

System.out.println("Clock 1: " + clock.toString());
System.out.println("Clock 2: " + clock1.toString());
Output:
Clock 1: FixedClock[1970-01-01T01:00:00Z,Asia/Calcutta]
Clock 2: FixedClock[1970-01-01T01:00:00Z,Asia/Calcutta]

withZone()

This method returns a copy of this clock with a different time-zone.
Example: Below example demonstrates the usage of withZone() method with default zone.
Clock clock = Clock.systemUTC();
Clock clock1 = clock.withZone(ZoneId.systemDefault());
System.out.println("Clock : " + clock.instant());
System.out.println("Clock1 : " + clock1.instant());
Output:
Clock : 2018-12-22T07:06:19.348Z
Clock1 : 2018-12-22T07:06:19.370Z

tickSeconds()

This static method returns the current instant ticking in whole seconds for the given time zone. This clock will always have the nano-of-second field set to zero:
Clock clock = Clock.systemDefaultZone();
Clock clock1 = Clock.tickSeconds(ZoneId.systemDefault());
System.out.println("Clock : " + clock.instant());
System.out.println("Clock1 : " + clock1.instant());
Output:
Clock : 2018-12-22T07:08:50.202Z
Clock1 : 2018-12-22T07:08:50Z

tickMinutes()

This method used to obtain a clock that returns the current instant ticking in whole minutes using best available system clock.
Example:
Clock clock = Clock.systemDefaultZone();
Clock clock1 = Clock.tickMinutes(ZoneId.systemDefault());
System.out.println("Clock : " + clock.instant());
System.out.println("Clock1 : " + clock1.instant());
Output:
Clock : 2018-12-22T07:11:18.229Z
Clock1 : 2018-12-22T07:11:00Z

tick()

This static method returns instants from the specified clock rounded to the nearest occurrence of the specified duration. The specified clock duration must be positive:
Clock clock = Clock.systemUTC();

Duration tickDuration = Duration.ofNanos(250000);
Clock clock1 = Clock.tick(clock, tickDuration);
System.out.println("Clock : " + clock.instant());
System.out.println("Clock1 : " + clock1.instant());
Output:
Clock : 2018-12-22T07:11:52.714Z
Clock1 : 2018-12-22T07:11:52.819Z

systemUTC()

This method returns a Clock object representing the current instant in the UTC zone:
Clock clock = Clock.systemUTC();
System.out.println("Clock : " + clock.instant());
Output:
Clock : 2018-12-22T07:14:04.040Z

systemDefaultZone()

This static method returns a Clock object representing the current instant and using the default time zone of the system it’s running on:
Clock clock = Clock.systemDefaultZone();
System.out.println("Clock : " + clock.toString());
Output:
Clock : SystemClock[Asia/Calcutta]

system()

Obtains a clock that returns the current instant using best available system clock.
Clock clock = Clock.system(ZoneId.systemDefault());
System.out.println("Clock : " + clock.instant());
Output:
Clock : 2018-12-22T07:17:37.418Z

offset()

Obtains a clock that returns instants from the specified clock with the specified duration added
Clock clock = Clock.systemUTC();
Duration duration = Duration.ofHours(5);
Clock clock1 = Clock.offset(clock, duration);
System.out.println("Clock 1: " + clock.instant());
System.out.println("Clock 2: " + clock1.instant());
Output:
Clock 1: 2018-12-22T07:18:36.695Z
Clock 2: 2018-12-22T12:18:36.800Z

millis()

This method is used to get the current millisecond instant of the clock.
Clock clock = Clock.systemDefaultZone();
Clock clock1 = Clock.systemUTC();
System.out.println("Clock 1 millis: " + clock.millis());
System.out.println("Clock 2 millis: " + clock1.millis());
Output:
Clock 1 millis: 1545463167415
Clock 2 millis: 1545463167415

getZone()

Gets the time-zone being used to create dates and times.
Clock clock = Clock.systemDefaultZone();
Clock clock1 = Clock.systemUTC();
System.out.println("Clock 1 Zone: " + clock.getZone());
System.out.println("Clock 2 Zone: " + clock1.getZone());
Output:
Clock 1 Zone: Asia/Calcutta
Clock 2 Zone: Z

Related Java 8 Date & Time API Guide

References



Comments