Уголок сельского джависта

JSR 310: Источники времени

Alexander Kosarev·9 Jul at 3:08 pm
JSR 310: Источники времени, image #1

Прежде чем переходить к более подробному описанию классов, описывающих метки времени, неплохо было бы упомянуть источники времени, хотя на практике они используются не так часто. Источники времени представлены интерфейсом InstantSource и его основной реализацией — Clock.

InstantSource используется для получения количества миллисекунд, прошедших с начала эпохи UNIX в UTC. Кроме этого InstantSource может быть использован для создания экземпляров классов Instant и Clock. Экземпляр InstantSource может быть получен при помощи одного из четырёх статических методов:

  • system — возвращает источник времени, использующий системные часы.
  • fixed — возвращает фиксированный источник времени на основе переданного экземпляра Instant. Такой источник времени всегда будет возвращать одно и то же время.
  • offset — возвращает источник времени, возвращающий время с указанным смещением.
  • tick — возвращает источник времени, который обновляет время с указанной периодичностью
// Получение системного источника времени
var systemInstantSource = InstantSource.system();

// Получение фиксированного источника времени
var fixedInstantSource = InstantSource.fixed(Instant.now());

// Получение источника времени, который будет возвращать время на 10 секунд больше системного
var offsetInstantSource = InstantSource.offset(systemInstantSource, Duration.ofSeconds(10));

// Получение источника времени, который будет обновлять время раз в десять секунд
var tickInstantSource = InstantSource.tick(systemInstantSource, Duration.ofSeconds(10));

Стандартные реализации InstantSource опираются на системное время, однако существуют и сторонние реализации, использующие серверы точного времени (NTP).

InstantSource предоставляет 3 метода:

  • instant — для получения Instant с текущей для источника меткой времени
  • millis — для получения количества миллисекунд с начала эпохи UNIX текущей для источника метки времени
  • clock — для получения экземпляра Clock для указанного часового пояса
// Получение Instant от InstantSource
Instant instant = systemInstantSource.instant();

// Получения количества миллисекунд с начала эпохи UNIX
long millis = systemInstantSource.millis();

// Получение Clock с часовым поясом Asia/Yekaterinburg
Clock clock = systemInstantSource.withZone(ZoneId.of("Asia/Yekaterinburg"));

Clock аналогичен InstantSource, но учитывает часовой пояс и может быть использован для создания экземпляров любых классов, описывающих метки времени, при помощи метода now(Clock clock). Часовой пояс, указанный при создании экземпляра Clock никак не влияет на значение создаваемых экземпляров Instant, так как последний всегда работает в UTC.

Получить экземпляр Clock можно при помощи статических методов:

  • systemDefaultZone — получение системных часов с системным часовым поясом
  • systemUTC — получение системных часов с UTC
  • system — получение системных часов с указанным часовым поясом
  • fixed — получение фиксированных часов
  • offset — получение часов с указанным сдвигом
  • tick — получение часов с указанной периодичностью обновления
  • tickMillis — получение часов с обновлением раз в n миллисекунд
  • tickSeconds — получение часов с обновлением раз в n секунд
  • tickMinutes — получение часов с обновлением ра в n минут
// Получение системных часов с системным часовым поясом
var systemDefaultZoneClock = Clock.systemDefaultZone();

// Получение системных часов в UTC
var systemUTCClock = Clock.systemUTC();

// Получение системных часов с часовым поясом Asia/Yekaterinburg
var systemClock = Clock.system(ZoneId.of("Asia/Yekaterinburg"));

// Получение фиксированных часов с часовым поясом Asia/Yekaterinburg
var fixedClock = Clock.fixed(Instant.now(), ZoneId.of("Asia/Yekaterinburg"));

// Получение часов, которые возвращают время на 10 секунд впереди текущего
var offsetClock = Clock.offset(systemDefaultZoneClock, Duration.ofSeconds(10));

// Получение часов с обновлением раз в 10 секунд
var tickClock = Clock.tick(systemUTCClock, Duration.ofSeconds(10));

// Получение часов с обновлением раз в миллисекунду с часовым поясом Asia/Yekaterinburg
var tickMillisClock = Clock.tickMillis(ZoneId.of("Asia/Yekaterinburg"));

// Получение часов с обновлением раз в секунду с часовым поясом Asia/Yekaterinburg
var tickSecondsClock = Clock.tickSeconds(ZoneId.of("Asia/Yekaterinburg"));

// Получение часов с обновлением раз в минуту с часовым поясом Asia/Yekaterinburg
var tickMinutesClock = Clock.tickMinutes(ZoneId.of("Asia/Yekaterinburg"));

Аналогично InstantSource класс Clock предоставляет доступ к Instant и количеству миллисекунд с начала эпохи UNIX текущей для часов метки времени. Кроме этого предоставляются методы getZone и withZone для получения часового пояса часов и создания копии часов с указанным часовым поясом соответственно.

// Получение Instant
Instant instant = systemDefaultZoneClock.instant();

// Получения количества миллисекунд с начала эпохи UNIX
long millis = systemDefaultZoneClock.millis();

// Получение копии Clock с часовым поясом Asia/Novosibirsk
Clock clock = systemDefaultZoneClock.withZone(ZoneId.of("Asia/Novosibirsk"));

// Получение часового пояса часов
ZoneId zone = sytemDefaultZoneClock.getZone();

Источники времени могут быть полезны, если вы хотите больше контроля над кодом. Например, такой код сложно тестировать точно:

record SomeEntity(Instant createdAt) {
}

class SomeService {

    SomeEntity createEntity() {
        return new SomeEntity(Instant.now());
    }
}

Максимум вы сможете написать такой тест:

class SomeTest {

    SomeService service = new SomeService();

    @Test
    void createEntity_ReturnValidEntity() {
        var entity = someService.createEntity();

        // Вы не можете проверить значение timestamp,
        // так как не имеете доступа к механизму создания Instant
        assertNotNull(entity.createdAt());
    }
}

Однако используя источники времени вы можете получить более контролируемый код:

class SomeService {

    private final Clock clock;

    SomeService(Clock clock) {
        this.clock = clock;
    }

    SomeEntity createEntity() {
        return new SomeEntity(Instant.now(this.clock));
    }
}

И этот код можно покрыть более точными тестами:

class SomeTest {

    static final Instant INSTANT = Instant.parse("2026-06-15T14:07:00Z");

    SomeService service = new SomeService(Clock.fixed(Instant, ZoneOffset.UTC));

    @Test
    void createEntity_ReturnValidEntity() {
        var entity = someService.createEntity();

        // Теперь вы можете проверить значение свойства createdAt
        assertEquals(INSTANT, entity.createdAt());
    } 
}
17 views·2 shares
17 views