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

См. также:

InstantSource

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

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

См. также:

ZoneId.systemDefault()

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().

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