Java : InstantSource - API使用例

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

概要

現在のインスタントにアクセスできます。

クラス構成

InstantSource は、現在時刻を示す Instant を取得するためのインタフェースです。
Instant.now メソッドの代わりにこのインタフェースを使うと、ユニットテストなどでダミーの現在時刻が作りやすくなります。

メソッド

static InstantSource fixed (Instant fixedInstant)

常に同じインスタントを返すソースを取得します。

final var now = Instant.now();
System.out.println(now); // 2024-07-07T07:07:35.229440100Z

final var source = InstantSource.system();

final var instant = source.instant();
System.out.println(instant); // 2024-07-07T07:07:35.237433600Z

final var dateTime = ZonedDateTime.of(2100, 12, 31, 0, 0, 0, 0, ZoneOffset.UTC);
final var source = InstantSource.fixed(dateTime.toInstant());

// 固定で 2100-12-31T00:00:00Z を返します。
final var instant = source.instant();
System.out.println(instant); // 2100-12-31T00:00:00Z

Instant instant ()

ソースの現在のインスタントを取得します。

final var source = InstantSource.system();

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

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

    TimeUnit.SECONDS.sleep(10);
}

// 結果
// ↓
//2024-07-07T07:07:53.895113100Z (millis = 1720336073895)
//2024-07-07T07:08:03.905051300Z (millis = 1720336083905)
//2024-07-07T07:08:13.919694300Z (millis = 1720336093919)
//2024-07-07T07:08:23.930906500Z (millis = 1720336103930)

default long millis ()

ソースの現在のミリ秒のインスタントを取得します。

final var source = InstantSource.system();

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

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

    TimeUnit.SECONDS.sleep(10);
}

// 結果
// ↓
//2024-07-07T07:07:53.895113100Z (millis = 1720336073895)
//2024-07-07T07:08:03.905051300Z (millis = 1720336083905)
//2024-07-07T07:08:13.919694300Z (millis = 1720336093919)
//2024-07-07T07:08:23.930906500Z (millis = 1720336103930)

static InstantSource offset (InstantSource baseSource, Duration offsetDuration)

指定された継続時間が追加された、指定されたソースから瞬間を返すソースを取得します。

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

final var baseSource = InstantSource.fixed(instant);
System.out.println(baseSource.instant()); // 2100-01-01T00:00:00Z

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

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

static InstantSource system ()

使用可能な最高のシステム・クロックを使用して現在のインスタントを返すソースを取得します。

final var now = Instant.now();
System.out.println(now); // 2024-07-07T07:07:35.229440100Z

final var source = InstantSource.system();

final var instant = source.instant();
System.out.println(instant); // 2024-07-07T07:07:35.237433600Z

final var dateTime = ZonedDateTime.of(2100, 12, 31, 0, 0, 0, 0, ZoneOffset.UTC);
final var source = InstantSource.fixed(dateTime.toInstant());

// 固定で 2100-12-31T00:00:00Z を返します。
final var instant = source.instant();
System.out.println(instant); // 2100-12-31T00:00:00Z

static InstantSource tick (InstantSource baseSource, Duration tickDuration)

指定されたソースから、指定した期間の最も近い出現まで切り捨てられるソースを取得します。

final var baseSource = InstantSource.system();
final var source = InstantSource.tick(baseSource, Duration.ofSeconds(2));

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

    TimeUnit.SECONDS.sleep(1);
}

// 結果
// ↓
//2024-07-07T07:09:18Z
//2024-07-07T07:09:20Z
//2024-07-07T07:09:20Z
//2024-07-07T07:09:22Z
//2024-07-07T07:09:22Z
//2024-07-07T07:09:24Z
//2024-07-07T07:09:24Z
//2024-07-07T07:09:26Z

default Clock withZone (ZoneId zone)

指定されたタイムゾーンの時計を返します。

final var source = InstantSource.system();
System.out.println(source); // SystemInstantSource

{
    final var zone = ZoneId.of("America/Los_Angeles");
    final var clock = source.withZone(zone);
    System.out.println(clock); // SystemClock[America/Los_Angeles]
}
{
    final var zone = ZoneId.of("Asia/Tokyo");
    final var clock = source.withZone(zone);
    System.out.println(clock); // SystemClock[Asia/Tokyo]
}

API 使用例