Интерфейс 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 Time-Scale требует использования 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, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/time/InstantSource.html