Интерфейс InstantSource

Все известные реализующие классы:: Clock

public interface InstantSource

Предоставляет доступ к текущему мгновению времени.

Экземпляры этого интерфейса используются для доступа к подключаемому представлению текущего момента времени. Например, InstantSource можно использовать вместо System.currentTimeMillis().

Основная цель этой абстракции — позволить подключать альтернативные источники мгновений времени по мере необходимости. Приложения используют объект для получения текущего времени вместо статического метода. Это может упростить тестирование.

Таким образом, этот интерфейс не гарантирует, что результат фактически представляет текущий момент на временной шкале. Вместо этого он позволяет приложению предоставить контролируемый вид текущего момента времени.

Лучшая практика для приложений — передавать InstantSource в любой метод, который требует текущего момента времени. Фреймворк для инъекции зависимостей — один из способов достижения этого:

  public class MyBean {
    private InstantSource source;  // dependency inject
    ...
    public void process(Instant endInstant) {
      if (source.instant().isAfter(endInstant) {
        ...
      }
    }
  }

Этот подход позволяет использовать альтернативный источник, такой как fixed или offset во время тестирования.

Фабричный метод system предоставляет источник, основанный на лучшем доступном системном часе. Это может использовать System.currentTimeMillis(), или более точный час, если он доступен.

Требования к реализации:

Этот интерфейс должен быть реализован с осторожностью, чтобы обеспечить правильную работу других классов. Все реализации должны быть потокобезопасными — один экземпляр должен быть способен вызываться из нескольких потоков без негативных последствий, таких как гонки.

Основные методы определены для возможности выброса исключения. В обычном использовании исключения не будут выброшены, однако одной возможной реализацией было бы получение времени с центрального сервера времени через сеть. Очевидно, что в этом случае поиск может завершиться неудачей, и поэтому метод может выбросить исключение.

Возвращаемые мгновения времени из InstantSource работают на временной шкале, игнорирующей високосные секунды, как описано в Instant. Если реализация оборачивает источник, который предоставляет информацию о високосных секундах, то должен быть использован механизм для «сглаживания» високосной секунды. Временная шкала Java требует использования UTC-SLS, однако реализации могут выбирать, насколько точными они будут с временной шкалой, при условии, что они документируют, как они работают. Поэтому реализации не обязаны фактически выполнять сдвиг UTC-SLS или каким-либо иным образом быть осведомлёнными о високосных секундах.

Реализации должны реализовывать Serializable по возможности и должны документировать, поддерживают ли они сериализацию.

Примечание к реализации:

Представленная здесь реализация основана на том же базовом системном часе, что и System.currentTimeMillis(), но может иметь точность, более тонкую, чем миллисекунды, если доступна. Однако о точности базового системного часа не гарантируется ничего. Приложениям, требующим более точного системного часов, необходимо реализовать этот абстрактный класс самостоятельно, используя другой внешний системный час, такой как сервер NTP.

С:

Краткое описание методов

Модификатор и тип	Метод	Описание
`static InstantSource`	`fixed(Instant fixedInstant)`	Получает источник, который всегда возвращает одно и то же мгновение времени.
`Instant`	`instant()`	Получает текущее мгновение времени источника.
`default long`	`millis()`	Получает текущее мгновение времени источника в миллисекундах.
`static InstantSource`	`offset(InstantSource baseSource, Duration offsetDuration)`	Получает источник, который возвращает мгновения времени из указанного источника с добавленной продолжительностью.
`static InstantSource`	`system()`	Получает источник, возвращающий текущее мгновение времени, используя лучшие доступные системные часы.
`static InstantSource`	`tick(InstantSource baseSource, Duration tickDuration)`	Получает источник, который возвращает мгновения времени из указанного источника, усечённые до ближайшего значения указанной продолжительности.
`default Clock`	`withZone(ZoneId zone)`	Возвращает часы с указанной часовой зоной.

Подробное описание методов

system

static InstantSource system()

Получает источник, возвращающий текущий момент времени, используя лучшие доступные системные часы.

Этот источник основан на лучших доступных системных часах. Он может использовать System.currentTimeMillis(), или часы с более высокой точностью, если они доступны.

Возвращаемая реализация неизменяема, потокобезопасна и Serializable.

Возвращает:: источник, использующий лучшие доступные системные часы, не null

tick

static InstantSource tick(InstantSource baseSource, Duration tickDuration)

Получает источник, возвращающий моменты времени из указанного источника, усечённые до ближайшего кратного указанной продолжительности.

Этот источник будет тикать только согласно указанной продолжительности. Таким образом, если продолжительность составляет полсекунды, источник будет возвращать моменты времени, усечённые до ближайшей полсекунды.

Продолжительность тика должна быть положительной. Если она имеет дробную часть, меньшую целого миллисекунда, то продолжительность должна делиться на одну секунду без остатка. Все обычные продолжительности тиков будут соответствовать этим критериям, включая любые кратные часы, минуты, секунды и миллисекунды, а также разумные наносекундные продолжительности, такие как 20нс, 250 000нс и 500 000нс.

Продолжительность в ноль или одну наносекунду не будет оказывать никакого эффекта усечения. Передача одного из этих значений вернёт исходный источник.

Реализации могут использовать стратегию кэширования для повышения производительности. В связи с этим, возможно, что начало запрошенной продолжительности, наблюдаемой через этот источник, будет позже, чем наблюдаемое непосредственно через базовый источник.

Возвращаемая реализация неизменяема, потокобезопасна и Serializable при условии, что базовый источник таковым является.

Параметры:: baseSource - базовый источник для построения источника тиков, не null; tickDuration - продолжительность каждого видимого тика, не отрицательная, не null
Возвращает:: источник, тикающий целыми единицами продолжительности, не null
Исключения:: IllegalArgumentException - если продолжительность отрицательная или имеет дробную часть, меньшую целого миллисекунда, так что продолжительность не делится на одну секунду без остатка; ArithmeticException - если продолжительность слишком велика для представления в наносекундах

fixed

static InstantSource fixed(Instant fixedInstant)

Получает источник, который всегда возвращает тот же момент времени.

Этот источник просто возвращает указанный момент времени. Таким образом, он не является источником, представляющим текущий момент времени. Основной случай использования этого - в тестировании, где фиксированный источник гарантирует, что тесты не зависят от текущего источника.

Возвращаемая реализация неизменяема, потокобезопасна и Serializable.

Параметры:: fixedInstant - используемый момент времени, не null
Возвращает:: источник, который всегда возвращает тот же момент времени, не null

offset

static InstantSource offset(InstantSource baseSource, Duration offsetDuration)

Получает источник, возвращающий моменты времени из указанного источника с добавлением указанной продолжительности.

Этот источник оборачивает другой источник, возвращая моменты времени, которые позже на указанную продолжительность. Если продолжительность отрицательная, моменты времени будут раньше текущей даты и времени. Основной случай использования этого - моделирование выполнения в будущем или прошлом.

Продолжительность в ноль не будет иметь эффекта смещения. Передача нуля вернёт базовый источник.

Параметры:: baseSource - базовый источник, к которому нужно добавить продолжительность, не null; offsetDuration - продолжительность для добавления, не null
Возвращает:: источник, основанный на базовом источнике с добавленной продолжительностью, не null

instant

Instant instant()

Получает текущий момент времени источника.

Это возвращает момент времени, представляющий текущий момент времени, как определено источником.

Возвращает:: текущий момент времени из этого источника, не null
Исключения:: DateTimeException - если момент времени получить невозможно, не выбрасывается большинством реализаций

millis

default long millis()

Получает текущий момент времени в миллисекундах источника.

Это возвращает момент времени, основанный на миллисекундах, измеренный с 1970-01-01T00:00Z (UTC). Это эквивалентно определению System.currentTimeMillis().

Большинство приложений должны избегать этого метода и использовать Instant для представления момента времени на временной шкале, а не значения в миллисекундах. Этот метод предоставляется, чтобы позволить использование источника в высокопроизводительных случаях, когда создание объекта было бы неприемлемым.

Требования к реализации:: Основная реализация вызывает instant().
Возвращает:: текущий момент времени в миллисекундах из этого источника, измеренный с эпохи Java 1970-01-01T00:00Z (UTC), не null
Исключения:: DateTimeException - если момент времени получить невозможно, не выбрасывается большинством реализаций

withZone

default Clock withZone(ZoneId zone)

Возвращает часы с указанной часовой зоной.

Это возвращает Clock, который является расширением этого интерфейса, объединяющим этот источник и указанную часовую зону.

Возвращаемая реализация неизменяема, потокобезопасна и Serializable при условии, что этот источник таковым является.

Требования к реализации:: Основная реализация возвращает неизменяемый, потокобезопасный и Serializable подкласс Clock, который объединяет этот источник и указанную зону.
Параметры:: zone - используемая часовая зона, не null
Возвращает:: часы, основанные на этом источнике с указанной часовой зоной, не null

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/InstantSource.html