Интерфейс 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, 2021, 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/17/docs/api/java.base/java/time/InstantSource.html