Класс 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)`	Возвращает копию этих часов с другим часовым поясом.

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

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API подлежит удалению в будущей версии. Финализация устарела и будет удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Приостанавливает текущий поток до его пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Приостанавливает текущий поток до его пробуждения, обычно в результате вызова notify или interrupt, либо до истечения указанного времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Приостанавливает текущий поток до его пробуждения, обычно в результате вызова notify или interrupt, либо до истечения указанного времени.

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

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)

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

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

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

Параметры:: 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.