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 –
- System Clock – Implementation of a clock that always returns the latest time from System
- Fixed Clock – Implementation of a clock that always returns the same instant which is typically used for testing
- Offset Clock – Implementation of a clock that adds an offset to an underlying clock
- 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,
- systemDefaultZone() – gets a clock that returns the current instant using the best available system clock, converting to date/time using the default time-zone
- systemUTC() – gets a clock that returns the current instant using the best available system clock, converting to date/time using the UTC time-zone
- system(ZoneId) – gets a clock that returns the current instant using best available system clock for the specified ZoneId
- instant() – gets the current instant of the clock which returns current date/time at UTC/GMT timezone
- getZone() – gets the time-zone being used to create dates/times
- fixed(Instant, ZoneId) – gets a clock that always returns the same instant
- offset(Clock, Duration) – gets a clock that returns instants from the specified clock with the specified duration added
- tick(Clock, Duration) – gets a clock that returns instants from the specified clock truncated to the nearest occurrence of the specified duration
- tickMinutes(ZoneId) – gets a clock that returns the current instant ticking in whole minutes using best available system clock
- tickSeconds(ZoneId) – gets a clock that returns the current instant ticking in whole seconds using best available system clock
- millis() – gets the current millisecond instant of the clock and this is very much same like System.currentTimeMillis()
- withZone(ZoneId) – returns a copy of this Clock with a different time-zone
3. Clock examples :
- 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
- 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
- Get Offset Clock with offset added to Default System Clock
- offset(Clock, Duration) – get a clock with the specified duration added
- 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
- Get Clock in millis
- millis() – get current instant of Clock in milliseconds
- 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
- Default
- UTC/GMT
- 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 –
- First is the instant in any time-zone
- 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 –
- First is the Clock
- 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:
- Java 8 – LocalDate with method details and examples
- Java 8 – LocalTime with method details and examples
- Java 8 – LocalDateTime with method details and examples
- Java 8 – ZonedDateTime with method details and examples
- Java 8 – Display all Zones and its Offset using ZoneId and ZoneOffset
- Java 8 – OffsetDateTime with method details and examples
- Java 8 – Instant with method details and examples
- Java 8 – How to display Zones for particular Offset ?
- Java 8 – Clock with method details and examples
- Java 8 – How to sort List by java.util.Date in different ways
- Java 8 – How to sort List by java.time.LocalDate in different ways
- Java 8 – How to sort List by java.time.LocalDateTime in different ways
References:
- https://docs.oracle.com/javase/7/docs/api/java/util/Date.html
- https://docs.oracle.com/javase/7/docs/api/java/util/Calendar.html
- https://docs.oracle.com/javase/7/docs/api/java/sql/Timestamp.html
- https://docs.oracle.com/javase/7/docs/api/java/sql/Time.html
- https://docs.oracle.com/javase/8/docs/api/java/time/LocalDate.html
- https://docs.oracle.com/javase/8/docs/api/java/time/LocalTime.html
- https://docs.oracle.com/javase/8/docs/api/java/time/LocalDateTime.html
- https://docs.oracle.com/javase/8/docs/api/java/time/ZonedDateTime.html
- https://docs.oracle.com/javase/8/docs/api/java/time/OffsetDateTime.html
- https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html
- https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html
- https://docs.oracle.com/javase/8/docs/api/java/time/ZoneOffset.html
- https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html
- https://docs.oracle.com/javase/8/docs/api/java/time/Clock.html
Happy Coding !!
Happy Learning !!