Java 8 – Clock with method details and examples

In this article, we will discuss about newly introduced Clock class in Java 1.8 version for dealing with alternate clock when required

1. Clock :

  • The main usage of Clock is to provide alternate clock when required
  • The other usage is for testing where it can be used without altering current time/clock
  • Clock class provides 4 different implementation
    1. System Clock – Implementation of a clock that always returns the latest time from System
    2. Fixed Clock – Implementation of a clock that always returns the same instant which is typically used for testing
    3. Offset Clock – Implementation of a clock that adds an offset to an underlying clock
    4. Tick Clock – Implementation of a clock that reduces the tick frequency of an underlying clock
  • Java Clock is an abstract class which has several useful static methods as listed in the next section
  • The fully qualified package/class name of Clock is java.time.Clock i.e.; Clock is present under java.time package
  • Class declaration for Clock is as follows,
package java.time;

public abstract class Clock implements InstantSource {

}

2. Clock methods or APIs :

  • Important Clock method details,
    1. systemDefaultZone() – gets a clock that returns the current instant using the best available system clock, converting to date/time using the default time-zone
    2. systemUTC() – gets a clock that returns the current instant using the best available system clock, converting to date/time using the UTC time-zone
    3. system(ZoneId) – gets a clock that returns the current instant using best available system clock for the specified ZoneId
    4. instant() – gets the current instant of the clock which returns current date/time at UTC/GMT timezone
    5. getZone() – gets the time-zone being used to create dates/times
    6. fixed(Instant, ZoneId) – gets a clock that always returns the same instant
    7. offset(Clock, Duration) – gets a clock that returns instants from the specified clock with the specified duration added
    8. tick(Clock, Duration) – gets a clock that returns instants from the specified clock truncated to the nearest occurrence of the specified duration
    9. tickMinutes(ZoneId) – gets a clock that returns the current instant ticking in whole minutes using best available system clock
    10. tickSeconds(ZoneId) – gets a clock that returns the current instant ticking in whole seconds using best available system clock
    11. millis() – gets the current millisecond instant of the clock and this is very much same like System.currentTimeMillis()
    12. withZone(ZoneId) – returns a copy of this Clock with a different time-zone

3. Clock examples :

  1. Get System Clock for different time-zone
    • systemDefaultZone() – get a clock in default time-zone
    • systemUTC() – get a clock in UTC/GMT time-zone
    • system(ZoneId) – get a clock in the specified time-zone
  2. Get Fixed Clock
    • fixed() – gets a clock that always returns the same instant
    • instant() – gets the instant for the Fixed clock
    • getZone() – gets the time-zone being used to create dates/times
  3. Get Offset Clock with offset added to Default System Clock
    • offset(Clock, Duration) – get a clock with the specified duration added
  4. Get Tick Clock
    • tick(Clock, Duration) – get a clock truncated to the nearest occurrence of the specified duration
    • tickMinutes(ZoneId) – get a clock with whole minutes leaving seconds-of-Minutes & nano-of-Seconds to zero
    • tickSeconds(ZoneId) – get a clock with whole seconds leaving nanoseconds to zero
  5. Get Clock in millis
    • millis() – get current instant of Clock in milliseconds
  6. Get Clock in different Time-zone
    • withZone() – get a Clock in a different time-zone as per specified argument

3.1 System Clock for different time-zone

  • Below illustration prints Clock in different time-zone like
    1. Default
    2. UTC/GMT
    3. Specified time-zone
  • It also prints ZoneId information and their current instant with Z suffixed representing current date/time at UTC/GMT
  • Note:- Instant are time-zone unaware which means it prints current date/time up-to nanoseconds precision at UTC/GMT with suffix Z for all time-zones

SystemClockExample.java

package in.bench.resources.clock.methods;

import java.time.Clock;
import java.time.ZoneId;

public class SystemClockExample {

	public static void main(String[] args) {

		// 1. Clock.systemDefaultZone()
		System.out.println("1. Using Clock.systemDefaultZone() :- \n");
		Clock clock = Clock.systemDefaultZone();
		System.out.println("Clock :-\t" + clock);
		System.out.println("Zone :-\t\t" + clock.getZone());
		System.out.println("Instant :-\t" + clock.instant());


		// 2. Clock.systemUTC()
		System.out.println("\n\n2. Using Clock.systemUTC() :- \n");
		Clock clock2 = Clock.systemUTC();
		System.out.println("Clock :-\t" + clock2);
		System.out.println("Zone :-\t\t" + clock2.getZone());
		System.out.println("Instant :-\t" + clock2.instant());


		// 3. Clock.system(ZoneId.of("Europe/Paris"))
		System.out.println("\n\n3. Using Clock.system(ZoneId.of(\"Europe/Paris\")) :- \n");
		Clock clock3 = Clock.system(ZoneId.of("Europe/Paris"));
		System.out.println("Clock :-\t" + clock3);
		System.out.println("Zone :-\t\t" + clock3.getZone());
		System.out.println("Instant :-\t" + clock3.instant());
	}
}

Output:

1. Using Clock.systemDefaultZone() :- 

Clock :-	SystemClock[Asia/Calcutta]
Zone :-		Asia/Calcutta
Instant :-	2022-07-23T17:36:34.693291400Z


2. Using Clock.systemUTC() :- 

Clock :-	SystemClock[Z]
Zone :-		Z
Instant :-	2022-07-23T17:36:34.710365300Z


3. Using Clock.system(ZoneId.of("Europe/Paris")) :- 

Clock :-	SystemClock[Europe/Paris]
Zone :-		Europe/Paris
Instant :-	2022-07-23T17:36:34.711363800Z

3.2 Fixed Clock

  • Clock.fixed() method always returns same instant at any given point of time
  • fixed() method accepts 2 input-arguments
    1. First is the instant in any time-zone
    2. Second is the time-zone information i.e., ZoneId
  • This method is very helpful for testing purpose
  • Finally, it prints Fixed Clock, ZoneId information and current instant at UTC/GMT

FixedClockExample.java

package in.bench.resources.clock.methods;

import java.time.Clock;
import java.time.ZoneId;

public class FixedClockExample {

	public static void main(String[] args) {

		// 1. Clock in System default zone
		Clock clock = Clock.systemDefaultZone();


		// 2. Clock in Asia/Dubai zone
		Clock clock2 = Clock.fixed(clock.instant(), ZoneId.of("Asia/Dubai"));


		// 3. print to console
		System.out.println("Using Clock.fixed(clock.instant(), ZoneId.of(\"Asia/Dubai\")) :- \n");
		System.out.println("Clock :-\t" + clock2);
		System.out.println("Zone :-\t\t" + clock2.getZone());
		System.out.println("Instant :-\t" + clock2.instant());
	}
}

Output:

Using Clock.fixed(clock.instant(), ZoneId.of("Asia/Dubai")) :- 

Clock :-	FixedClock[2022-07-23T17:42:51.664070700Z,Asia/Dubai]
Zone :-		Asia/Dubai
Instant :-	2022-07-23T17:42:51.664070700Z

3.3 Offset Clock

  • This is very useful when current instant needs to be offset by some specified Duration
  • Clock.offset() method accepts 2 input-arguments
    1. First is the Clock
    2. Second is the Duration in seconds, minutes, hours, days, etc.,
  • offset() method returns instants from the specified clock with the specified duration added
  • Finally, it prints Offset Clock, ZoneId information and current instant at UTC/GMT

OffsetClockExample.java

package in.bench.resources.clock.methods;

import java.time.Clock;
import java.time.Duration;

public class OffsetClockExample {

	public static void main(String[] args) {

		// 1. Clock in System default zone
		Clock clock = Clock.systemDefaultZone();
		System.out.println("Instant at System default zone :- " + clock.instant());


		// 2. Clock with offset of 25 minutes
		Clock clock2 = Clock.offset(clock, Duration.ofMinutes(25));


		// 3. print to console
		System.out.println("\n\nUsing Clock.offset(clock, Duration.ofMinutes(25)) :- \n");
		System.out.println("Clock :-\t" + clock2);
		System.out.println("Zone :-\t\t" + clock2.getZone());
		System.out.println("Instant :-\t" + clock2.instant());
	}
}

Output:

Instant at System default zone :- 2022-07-23T17:48:20.876601500Z


Using Clock.offset(clock, Duration.ofMinutes(25)) :- 

Clock :-	OffsetClock[SystemClock[Asia/Calcutta],PT25M]
Zone :-		Asia/Calcutta
Instant :-	2022-07-23T18:13:20.894604700Z

3.4 Tick Clock

  • There are 3 methods related Tick Clock, those are
    • tick(Clock, Duration) – get a clock truncated to the nearest occurrence of the specified duration
    • tickMinutes(ZoneId) – get a clock with whole minutes leaving seconds-of-Minutes & nano-of-Seconds to zero
    • tickSeconds(ZoneId) – get a clock with whole seconds leaving nanoseconds to zero
  • Finally, it prints Tick Clock, ZoneId information and current instant at UTC/GMT for all 3 above mentioned Tick Clocks

TickClockExample.java

package in.bench.resources.clock.methods;

import java.time.Clock;
import java.time.Duration;
import java.time.ZoneId;

public class TickClockExample {

	public static void main(String[] args) {

		// 1. Clock in System default zone
		Clock clock = Clock.systemDefaultZone();
		System.out.println("1. Instant at System default zone :- \n" + clock.instant());


		// 2. Clock.tick(clock, Duration.ofMinutes(15))
		System.out.println("\n\n2. Using Clock.tick(clock, Duration.ofMinutes(15)) :- \n");
		Clock clock2 = Clock.tick(clock, Duration.ofMinutes(15));
		System.out.println("Clock :-\t" + clock2);
		System.out.println("Zone :-\t\t" + clock2.getZone());
		System.out.println("Instant :-\t" + clock2.instant());


		// 3. Clock.tickMinutes(ZoneId.of("Europe/Paris"))
		System.out.println("\n\n3. Using Clock.tickMinutes(ZoneId.of(\"Europe/Paris\")) :- \n");
		Clock clock3 = Clock.tickMinutes(ZoneId.of("Europe/Paris"));
		System.out.println("Clock :-\t" + clock3);
		System.out.println("Zone :-\t\t" + clock3.getZone());
		System.out.println("Instant :-\t" + clock3.instant());


		// 4. Clock.tickSeconds(ZoneId.of("Europe/Paris"))
		System.out.println("\n\n4. Using Clock.tickSeconds(ZoneId.of(\"Europe/Paris\")) :- \n");
		Clock clock4 = Clock.tickSeconds(ZoneId.of("Europe/Paris"));
		System.out.println("Clock :-\t" + clock4);
		System.out.println("Zone :-\t\t" + clock4.getZone());
		System.out.println("Instant :-\t" + clock4.instant());
	}
}

Output:

1. Instant at System default zone :- 
2022-07-23T17:50:24.703306100Z


2. Using Clock.tick(clock, Duration.ofMinutes(15)) :- 

Clock :-	TickClock[SystemClock[Asia/Calcutta],PT15M]
Zone :-		Asia/Calcutta
Instant :-	2022-07-23T17:45:00Z


3. Using Clock.tickMinutes(ZoneId.of("Europe/Paris")) :- 

Clock :-	TickClock[SystemClock[Europe/Paris],PT1M]
Zone :-		Europe/Paris
Instant :-	2022-07-23T17:50:00Z


4. Using Clock.tickSeconds(ZoneId.of("Europe/Paris")) :- 

Clock :-	TickClock[SystemClock[Europe/Paris],PT1S]
Zone :-		Europe/Paris
Instant :-	2022-07-23T17:50:24Z

3.5 Get Clock in milliseconds

  • millis() method Clock returns instant in milliseconds
  • This is very much same like System.currentTimeMillis() method which returns current date/time information in milliseconds
  • In short, clock.millis() = System.currentTimeMillis()

ClockMillisExample.java

package in.bench.resources.clock.methods;

import java.time.Clock;

public class ClockMillisExample {

	public static void main(String[] args) {

		System.out.println("Comparison of Clock.millis() and System.currentTimeMillis() :- \n");

		// 1. Clock in System default zone
		Clock clock = Clock.systemDefaultZone();
		System.out.println("clock.millis() in default zone :- " + clock.millis());


		// 2. System.currentTimeMillis() 
		System.out.println("System.currentTimeMillis() :- " + System.currentTimeMillis());
	}
}

Output:

Comparison of Clock.millis() and System.currentTimeMillis() :- 

clock.millis() in default zone :- 1658598645396
System.currentTimeMillis() :- 1658598645396

3.6 Get Clock in different Time Zone

  • withZone() method of Clock helps to get any Clock in different time-zone passing ZoneId information as method-argument

SystemClockInDifferentTimeZone.java

package in.bench.resources.clock.methods;

import java.time.Clock;
import java.time.ZoneId;

public class SystemClockInDifferentTimeZone {

	public static void main(String[] args) {

		// 1. Get Clock in system default time-zone
		System.out.println("1. System Clock in System Default Time-zone :- \n");
		Clock clock = Clock.systemDefaultZone();
		System.out.println("Clock :-\t" + clock);
		System.out.println("Zone :-\t\t" + clock.getZone());
		System.out.println("Instant :-\t" + clock.instant());


		// 2. Get same Clock in different time-zone
		System.out.println("\n\n2. Clock in Different Time-zone :- \n");
		Clock clock2 = clock.withZone(ZoneId.of("Europe/Paris"));
		System.out.println("Clock :-\t" + clock2);
		System.out.println("Zone :-\t\t" + clock2.getZone());
		System.out.println("Instant :-\t" + clock2.instant());
	}
}

Output:

1. System Clock in System Default Time-zone :- 

Clock :-	SystemClock[Asia/Calcutta]
Zone :-		Asia/Calcutta
Instant :-	2022-07-23T17:55:04.926183500Z


2. Clock in Different Time-zone :- 

Clock :-	SystemClock[Europe/Paris]
Zone :-		Europe/Paris
Instant :-	2022-07-23T17:55:04.943157700Z

Related Articles:

References:

Happy Coding !!
Happy Learning !!

Java 8 - OffsetTime with method details and examples
Java 8 - How to merge/concatenate/join two lists into single list ?