Java : Clock (時計) - API使用例

Clock (Java SE 20 & JDK 20) の使用例まとめです。
だいたいのメソッドを網羅済みです。
API仕様のおともにどうぞ。

概要

タイムゾーンを使用して現在の時点、日付および時間へのアクセスを提供するクロックです。

クラス構成

Clock クラスは、現在時刻を取得するために利用するクラスです。

単純に現在時刻を返すだけでなく、

固定の時刻を返す
現在時刻の xx 時間後を返す

といったことも可能です。

ユニットテストなどで

現在時刻を特定の時刻にして実行したい

というケースで便利ですね。

System.out.println(ZoneId.systemDefault()); // Asia/Tokyo

{
    final var now = ZonedDateTime.now();
    System.out.println(now); // 2023-10-08T16:54:38.751605600+09:00[Asia/Tokyo]
}
{
    final var clock = Clock.systemDefaultZone();

    final var now = ZonedDateTime.now(clock);
    System.out.println(now); // 2023-10-08T16:54:38.751605600+09:00[Asia/Tokyo]

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

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

    final var instant = clock.instant();
    System.out.println(instant); // 2023-10-08T07:54:38.754603500Z
}
{
    // 固定で 1999-12-31 00:00 を返します。
    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 ()

サブクラスでアクセスできるコンストラクタです。

protectedです。
独自にサブクラスを作ることは少ないと思いますので、コード例は割愛します。

メソッド

boolean equals (Object obj)

このクロックがもう一方のクロックと等しいかどうかを確認します。

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)

常に同じインスタントを返すクロックを取得します。

System.out.println(ZoneId.systemDefault()); // Asia/Tokyo

{
    final var now = ZonedDateTime.now();
    System.out.println(now); // 2023-10-08T16:54:38.751605600+09:00[Asia/Tokyo]
}
{
    final var clock = Clock.systemDefaultZone();

    final var now = ZonedDateTime.now(clock);
    System.out.println(now); // 2023-10-08T16:54:38.751605600+09:00[Asia/Tokyo]

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

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

    final var instant = clock.instant();
    System.out.println(instant); // 2023-10-08T07:54:38.754603500Z
}
{
    // 固定で 1999-12-31 00:00 を返します。
    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 ()

日付と時間を作成するために使用されるタイムゾーンを取得します。

System.out.println(ZoneId.systemDefault()); // Asia/Tokyo

final var clock1 = Clock.systemDefaultZone();
System.out.println(clock1.getZone()); // Asia/Tokyo

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

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

int hashCode ()

このクロックのハッシュ・コード。

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 ()

クロックの現在の時点を取得します。

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);
}

// 結果
// ↓
//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 ()

クロックの現在の時点をミリ秒で取得します。

このメソッドの使用例は、instant() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

static Clock offset (Clock baseClock, Duration offsetDuration)

指定されたデュレーションを加算して指定されたクロックからインスタントを返すクロックを取得します

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)

最高の利用可能なシステム・クロックを使用して現在の瞬間を返すクロックを取得します。

このメソッドの使用例は、getZone() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

static Clock systemDefaultZone ()

利用できる最適なシステム・クロックを使用し、デフォルト・タイムゾーンを使って日付と時間に変換した現在のインスタントを返すクロックを取得します。

このメソッドの使用例は、fixed(Instant fixedInstant, ZoneId zone) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

static Clock systemUTC ()

利用できる最適なシステム・クロックを使用し、UTCタイムゾーンを使って日付と時間に変換した現在のインスタントを返すクロックを取得します。

このメソッドの使用例は、fixed(Instant fixedInstant, ZoneId zone) にまとめて記載しました。
そちらのAPI使用例をご参照ください。

static Clock tick (Clock baseClock, Duration tickDuration)

指定されたデュレーションの直近値に切り捨てられたインスタントを指定されたクロックから返すクロックを取得します。

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);
}

// 結果
// ↓
//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)

最高の利用可能なシステム・クロックを使用して、ミリ秒単位で現在の時刻を返すクロックを取得します。

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);
}

// 結果
// ↓
//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)

最高の利用可能なシステム・クロックを使用して、分単位で現在の時刻を返す時計を取得します。

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);
}

// 結果
// ↓
//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)

最高の利用可能なシステム・クロックを使用して、秒単位で現在のチックを返すクロックを取得します。

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);
}

// 結果
// ↓
//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)

別のタイムゾーンを使って、このクロックのコピーを返します。

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]

API 使用例