Класс 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

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

Часы

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нс, 250000нс и 500000нс.

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

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

Возвращаемая реализация неизменяема, потокобезопасна и 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)

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

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

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

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

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

instant

public abstract Instant instant()

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

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

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

equals

public boolean equals(Object obj)

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

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

Overrides:

equals в классе Object

Parameters:

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

Returns:

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

See Also:

hashCode

public int hashCode()

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

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

Overrides:

hashCode в классе Object

Returns:

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

See Also:

© 1993, 2023, 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/21/docs/api/java.base/java/time/Clock.html