Интерфейс 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, 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://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/InstantSource.html