Класс 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() или часы с более высоким разрешением, если таковые доступны.

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

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

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

Возвращаемые значения типа instant из Clock используют временную шкалу, игнорирующую високосные секунды, как описано в Instant. Если реализация оборачивает источник, предоставляющий сведения о високосных секундах, следует использовать механизм «сглаживания» високосной секунды. Шкала Java Time-Scale предписывает использовать 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)`	Возвращает копию этих часов с другим часовым поясом.

Методы, объявленные в классе 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)

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

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

Определено в:: withZone в интерфейсе InstantSource
Параметры:: zone — новый часовой пояс; не null
Возвращает:: часы, основанные на этих часах и использующие указанный часовой пояс; не null

millis

public long millis()

Возвращает текущий момент по этим часам в миллисекундах.

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

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

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

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

instant

public abstract Instant instant()

Возвращает текущий момент по этим часам.

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

Определено в:: instant в интерфейсе InstantSource
Возвращает:: текущий момент по этим часам; не null
Выбрасывает:: DateTimeException — если невозможно получить момент; большинство реализаций не выбрасывают это исключение

equals

public boolean equals(Object obj)

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

Часы должны переопределять этот метод, чтобы сравнивать равенство на основе своего состояния и соответствовать контракту Object.equals(Object). Если метод не переопределен, его поведение определяется методом Object.equals(Object)

Переопределяет:

equals в классе Object

Параметры:

obj — объект для проверки; для null возвращается false

Возвращает:

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

См. также:

hashCode

public int hashCode()

Хеш-код этих часов.

Часы должны переопределять этот метод с учетом своего состояния и для соответствия контракту Object.hashCode(). Если метод не переопределен, его поведение определяется методом Object.hashCode()

Переопределяет:

hashCode в классе Object

Возвращает:

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

См. также:

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