Класс Clock

java.lang.Object

java.time.Clock

Все реализованные интерфейсы:: InstantSource

public abstract class Clock extends Object implements InstantSource

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

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

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

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

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

  public class MyBean {
    private Clock clock;  // dependency inject
    ...
    public void process(LocalDate eventDate) {
      if (eventDate.isBefore(LocalDate.now(clock)) {
        ...
      }
    }
  }

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

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

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

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

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

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

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

С:

1.8

См. также:

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

Clock()

Модификатор	Конструктор	Описание
`protected`	Конструктор, доступный для подклассов.

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

Модификатор и тип	Метод	Описание
`boolean`	`equals(Object obj)`	Проверяет, равны ли эти часы другим часам.
`static Clock`	`fixed(Instant fixedInstant, ZoneId zone)`	Получает часы, которые всегда возвращают одно и то же мгновение.
`abstract ZoneId`	`getZone()`	Получает часовой пояс, используемый для создания дат и времени.
`int`	`hashCode()`	Хеш-код для этих часов.
`abstract Instant`	`instant()`	Получает текущее мгновение часов.
`long`	`millis()`	Получает текущее мгновение часов в миллисекундах.
`static Clock`	`offset(Clock baseClock, Duration offsetDuration)`	Получает часы, возвращающие мгновения из указанных часов с добавленным указанным интервалом.
`static Clock`	`system(ZoneId zone)`	Получает часы, возвращающие текущее мгновение с использованием лучших доступных системных часов.
`static Clock`	`systemDefaultZone()`	Получает часы, возвращающие текущее мгновение с использованием лучших доступных системных часов, преобразуя дату и время в соответствии с часовым поясом по умолчанию.
`static Clock`	`systemUTC()`	Получает часы, возвращающие текущее мгновение с использованием лучших доступных системных часов, преобразуя дату и время в соответствии с часовым поясом UTC.
`static Clock`	`tick(Clock baseClock, Duration tickDuration)`	Получает часы, возвращающие мгновения из указанных часов, усечённые до ближайшего значения указанного интервала.
`static Clock`	`tickMillis(ZoneId zone)`	Получает часы, возвращающие текущее мгновение, отсчитываемое в целых миллисекундах, с использованием лучших доступных системных часов.
`static Clock`	`tickMinutes(ZoneId zone)`	Получает часы, возвращающие текущее мгновение, отсчитываемое в целых минутах, с использованием лучших доступных системных часов.
`static Clock`	`tickSeconds(ZoneId zone)`	Получает часы, возвращающие текущее мгновение, отсчитываемое в целых секундах, с использованием лучших доступных системных часов.
`abstract Clock`	`withZone(ZoneId zone)`	Возвращает копию этих часов с другим часовым поясом.

Методы, объявленные в классе java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

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

Clock

protected Clock()

Конструктор, доступный подклассам.

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

systemUTC

public static Clock systemUTC()

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

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

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

Преобразование момента во дату или время использует часовой пояс UTC.

Возвращаемая реализация неизменяема, потокобезопасна и Serializable. Она эквивалентна system(ZoneOffset.UTC).

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

systemDefaultZone

public static Clock systemDefaultZone()

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

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

Возвращаемая реализация неизменяема, потокобезопасна и Serializable. Она эквивалентна system(ZoneId.systemDefault()).

Возвращает:

часы, использующие лучшие доступные системные часы в часовом поясе по умолчанию, не null

См. также:

system

public static Clock system(ZoneId zone)

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

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

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

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

tickMillis

public static Clock tickMillis(ZoneId zone)

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

Эти часы всегда будут иметь поле наносекунд, усечённое до миллисекунд. Это гарантирует, что видимые отсчёты времени происходят в целых миллисекундах. Базовые часы — лучшие доступные системные часы, эквивалентно использованию system(ZoneId).

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

Возвращаемая реализация неизменяема, потокобезопасна и Serializable. Она эквивалентна tick(system(zone), Duration.ofMillis(1)).

Параметры:: zone - часовой пояс, используемый для преобразования момента во дату и время, не null
Возвращает:: часы, отсчитывающие в целых миллисекундах, используя указанный часовой пояс, не null
С:: 9

tickSeconds

public static Clock tickSeconds(ZoneId zone)

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

Эти часы всегда будут иметь поле наносекунд, установленное в ноль. Это гарантирует, что видимые отсчёты времени происходят в целых секундах. Базовые часы — лучшие доступные системные часы, эквивалентно использованию system(ZoneId).

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

Возвращаемая реализация неизменяема, потокобезопасна и Serializable. Она эквивалентна tick(system(zone), Duration.ofSeconds(1)).

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

tickMinutes

public static Clock tickMinutes(ZoneId zone)

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

Эти часы всегда будут иметь поля наносекунд и секунд минуты, установленные в ноль. Это гарантирует, что видимые отсчёты времени происходят в целых минутах. Базовые часы — лучшие доступные системные часы, эквивалентно использованию system(ZoneId).

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

Возвращаемая реализация неизменяема, потокобезопасна и Serializable. Она эквивалентна tick(system(zone), Duration.ofMinutes(1)).

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

tick

public static Clock tick(Clock baseClock, Duration tickDuration)

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

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

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

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

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

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

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

fixed

public static Clock fixed(Instant fixedInstant, ZoneId zone)

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

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

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

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

offset

public static Clock offset(Clock baseClock, Duration offsetDuration)

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

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

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

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

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

getZone

public abstract ZoneId getZone()

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

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

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

withZone

public abstract Clock withZone(ZoneId zone)

Возвращает копию этого таймера с другим часовым поясом.

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

Specified by:: withZone in interface InstantSource
Parameters:: zone - часовой пояс для изменения, не null
Returns:: таймер, основанный на этом таймере с указанным часовым поясом, не null

millis

public long millis()

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

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

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

Текущая реализация по умолчанию вызывает instant().

Specified by:: millis in interface InstantSource
Returns:: текущий момент в миллисекундах от этого таймера, измеренный с эпохи Java 1970-01-01T00:00Z (UTC), не null
Throws:: DateTimeException - если момент получить невозможно, не выбрасывается в большинстве реализаций

instant

public abstract Instant instant()

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

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

Specified by:: instant in interface InstantSource
Returns:: текущий момент времени от этого таймера, не null
Throws:: DateTimeException - если момент получить невозможно, не выбрасывается в большинстве реализаций

equals

public boolean equals(Object obj)

Проверяет, равен ли этот таймер другому таймеру.

Таймеры должны переопределять этот метод для сравнения равенства на основе своего состояния и для соблюдения контракта Object.equals(java.lang.Object). Если не переопределен, поведение определяется Object.equals(java.lang.Object)

Overrides:

equals in class Object

Parameters:

obj - объект для проверки, null возвращает false

Returns:

true, если этот таймер равен другому таймеру

See Also:

hashCode

public int hashCode()

Хеш-код этого таймера.

Таймеры должны переопределять этот метод, основываясь на их состоянии, и для выполнения контракта Object.hashCode(). Если не переопределен, поведение определяется Object.hashCode()

Overrides:

hashCode in class Object

Returns:

подходящий хеш-код

See Also:

© 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/Clock.html