Java : Clock with Examples

System.out.println(ZoneId.systemDefault()); // America/Los_Angeles

{
    final var now = ZonedDateTime.now();
    System.out.println(now); // 2023-10-10T00:22:38.499858400-07:00[America/Los_Angeles]
}
{
    final var clock = Clock.systemDefaultZone();

    final var now = ZonedDateTime.now(clock);
    System.out.println(now); // 2023-10-10T00:22:38.500856800-07:00[America/Los_Angeles]

    final var instant = clock.instant();
    System.out.println(instant); // 2023-10-10T07:22:38.500856800Z
}
{
    final var clock = Clock.systemUTC();

    final var now = ZonedDateTime.now(clock);
    System.out.println(now); // 2023-10-10T07:22:38.502856800Z

    final var instant = clock.instant();
    System.out.println(instant); // 2023-10-10T07:22:38.502856800Z
}
{
    final var dateTime = ZonedDateTime.of(1999, 12, 31, 0, 0, 0, 0, ZoneOffset.UTC);
    final var clock = Clock.fixed(dateTime.toInstant(), dateTime.getZone());

    final var now = ZonedDateTime.now(clock);
    System.out.println(now); // 1999-12-31T00:00Z

    final var instant = clock.instant();
    System.out.println(instant); // 1999-12-31T00:00:00Z
}

Clock ()

Constructor accessible by subclasses.

protected. I think it's rare to create a subclass of this class. Therefore, the code example is omitted.

boolean equals (Object obj)

Checks if this clock is equal to another clock.

final var clock1 = Clock.systemUTC();
final var clock2 = Clock.systemUTC();
final var clock3 = Clock.systemDefaultZone();

System.out.println(clock1.equals(clock2)); // true
System.out.println(clock1.equals(clock3)); // false

static Clock fixed (Instant fixedInstant, ZoneId zone)

Obtains a clock that always returns the same instant.

System.out.println(ZoneId.systemDefault()); // America/Los_Angeles

{
    final var now = ZonedDateTime.now();
    System.out.println(now); // 2023-10-10T00:22:38.499858400-07:00[America/Los_Angeles]
}
{
    final var clock = Clock.systemDefaultZone();

    final var now = ZonedDateTime.now(clock);
    System.out.println(now); // 2023-10-10T00:22:38.500856800-07:00[America/Los_Angeles]

    final var instant = clock.instant();
    System.out.println(instant); // 2023-10-10T07:22:38.500856800Z
}
{
    final var clock = Clock.systemUTC();

    final var now = ZonedDateTime.now(clock);
    System.out.println(now); // 2023-10-10T07:22:38.502856800Z

    final var instant = clock.instant();
    System.out.println(instant); // 2023-10-10T07:22:38.502856800Z
}
{
    final var dateTime = ZonedDateTime.of(1999, 12, 31, 0, 0, 0, 0, ZoneOffset.UTC);
    final var clock = Clock.fixed(dateTime.toInstant(), dateTime.getZone());

    final var now = ZonedDateTime.now(clock);
    System.out.println(now); // 1999-12-31T00:00Z

    final var instant = clock.instant();
    System.out.println(instant); // 1999-12-31T00:00:00Z
}

abstract ZoneId getZone ()

Gets the time-zone being used to create dates and times.

System.out.println(ZoneId.systemDefault()); // America/Los_Angeles

final var clock1 = Clock.systemDefaultZone();
System.out.println(clock1.getZone()); // America/Los_Angeles

final var clock2 = Clock.systemUTC();
System.out.println(clock2.getZone()); // Z

final var zone = ZoneId.of("Asia/Tokyo");
final var clock3 = Clock.system(zone);
System.out.println(clock3.getZone()); // Asia/Tokyo

int hashCode ()

A hash code for this clock.

final var clock1 = Clock.systemUTC();
System.out.println(clock1.hashCode()); // 1

final var clock2 = Clock.system(ZoneId.of("America/Los_Angeles"));
System.out.println(clock2.hashCode()); // -1536188512

final var clock3 = Clock.system(ZoneId.of("Asia/Tokyo"));
System.out.println(clock3.hashCode()); // -1660747038

abstract Instant instant ()

Gets the current instant of the clock.

final var clock = Clock.systemUTC();

for (int i = 0; i < 4; i++) {
    final var instant = clock.instant();
    final var millis = clock.millis();

    System.out.printf("%s (millis = %d)%n", instant, millis);

    TimeUnit.SECONDS.sleep(10);
}

// Result
// ↓
//2023-10-10T06:05:45.313682500Z (millis = 1696917945313)
//2023-10-10T06:05:55.327708500Z (millis = 1696917955327)
//2023-10-10T06:06:05.336554900Z (millis = 1696917965336)
//2023-10-10T06:06:15.340269400Z (millis = 1696917975340)

long millis ()

Gets the current millisecond instant of the clock.

Please see instant().

static Clock offset (Clock baseClock, Duration offsetDuration)

Obtains a clock that returns instants from the specified clock with the specified duration added.

final var instant = Instant.ofEpochSecond(4102444800L);
System.out.println(instant); // 2100-01-01T00:00:00Z

final var baseClock = Clock.fixed(instant, ZoneOffset.UTC);
System.out.println(baseClock.instant()); // 2100-01-01T00:00:00Z

final var clock1 = Clock.offset(baseClock, Duration.ofDays(-1));
System.out.println(clock1.instant()); // 2099-12-31T00:00:00Z

final var clock2 = Clock.offset(baseClock, Duration.ofHours(14).plusMinutes(30));
System.out.println(clock2.instant()); // 2100-01-01T14:30:00Z

static Clock system (ZoneId zone)

Obtains a clock that returns the current instant using the best available system clock.

Please see getZone().

static Clock systemDefaultZone ()

Obtains a clock that returns the current instant using the best available system clock, converting to date and time using the default time-zone.

Please see fixed(Instant fixedInstant, ZoneId zone).

static Clock systemUTC ()

Obtains a clock that returns the current instant using the best available system clock, converting to date and time using the UTC time-zone.

Please see fixed(Instant fixedInstant, ZoneId zone).

static Clock tick (Clock baseClock, Duration tickDuration)

Obtains a clock that returns instants from the specified clock truncated to the nearest occurrence of the specified duration.

final var baseClock = Clock.systemUTC();
final var clock = Clock.tick(baseClock, Duration.ofSeconds(2));

for (int i = 0; i < 8; i++) {
    final var instant = clock.instant();
    System.out.println(instant);

    TimeUnit.SECONDS.sleep(1);
}

// Result
// ↓
//2023-10-05T07:41:30Z
//2023-10-05T07:41:30Z
//2023-10-05T07:41:32Z
//2023-10-05T07:41:32Z
//2023-10-05T07:41:34Z
//2023-10-05T07:41:34Z
//2023-10-05T07:41:36Z
//2023-10-05T07:41:36Z

static Clock tickMillis (ZoneId zone)

Obtains a clock that returns the current instant ticking in whole milliseconds using the best available system clock.

final var clock = Clock.tickMillis(ZoneOffset.UTC);

for (int i = 0; i < 8; i++) {
    final var instant = clock.instant();
    System.out.println(instant);

    TimeUnit.MILLISECONDS.sleep(1);
}

// Result
// ↓
//2023-10-05T07:54:49.828Z
//2023-10-05T07:54:49.835Z
//2023-10-05T07:54:49.838Z
//2023-10-05T07:54:49.840Z
//2023-10-05T07:54:49.842Z
//2023-10-05T07:54:49.844Z
//2023-10-05T07:54:49.846Z
//2023-10-05T07:54:49.847Z

static Clock tickMinutes (ZoneId zone)

Obtains a clock that returns the current instant ticking in whole minutes using the best available system clock.

final var clock = Clock.tickMinutes(ZoneOffset.UTC);

for (int i = 0; i < 4; i++) {
    final var instant = clock.instant();
    System.out.println(instant);

    TimeUnit.SECONDS.sleep(30);
}

// Result
// ↓
//2023-10-05T07:50:00Z
//2023-10-05T07:50:00Z
//2023-10-05T07:51:00Z
//2023-10-05T07:51:00Z

static Clock tickSeconds (ZoneId zone)

Obtains a clock that returns the current instant ticking in whole seconds using the best available system clock.

final var clock = Clock.tickSeconds(ZoneOffset.UTC);

for (int i = 0; i < 8; i++) {
    final var instant = clock.instant();
    System.out.println(instant);

    TimeUnit.MILLISECONDS.sleep(500);
}

// Result
// ↓
//2023-10-05T07:53:43Z
//2023-10-05T07:53:43Z
//2023-10-05T07:53:44Z
//2023-10-05T07:53:44Z
//2023-10-05T07:53:45Z
//2023-10-05T07:53:45Z
//2023-10-05T07:53:46Z
//2023-10-05T07:53:46Z

abstract Clock withZone (ZoneId zone)

Returns a copy of this clock with a different time-zone.

final var clock1 = Clock.systemUTC();
System.out.println(clock1); // SystemClock[Z]

final var zone = ZoneId.of("America/Los_Angeles");
final var clock2 = clock1.withZone(zone);
System.out.println(clock2); // SystemClock[America/Los_Angeles]

final var clock1 = Clock.tickSeconds(ZoneOffset.UTC);
System.out.println(clock1); // TickClock[SystemClock[Z],PT1S]

final var zone = ZoneId.of("Asia/Tokyo");
final var clock2 = clock1.withZone(zone);
System.out.println(clock2); // TickClock[SystemClock[Asia/Tokyo],PT1S]