Класс Clock

java.lang.Object
- java.time.Clock

public abstract class Clock
extends Object

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

Экземпляры этого класса используются для поиска текущего мгновения, которое можно интерпретировать, используя сохранённый часовой пояс, чтобы найти текущую дату и время. Таким образом, часы можно использовать вместо 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() или часы с более высокой точностью, если они доступны.

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

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

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

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

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

Примечание для реализации:

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

С момента:

1.8

Конструкторы

Модификатор	Конструктор и описание
`protected`	`Clock()` Конструктор, доступный подклассам.

Методы

Модификатор и тип	Метод и описание
`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`	`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

tickSeconds

public static Clock tickSeconds(ZoneId zone)

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

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

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

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

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

tickMinutes

public static Clock tickMinutes(ZoneId zone)

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

В этих часах поля nano-of-second и second-of-minute всегда будут равны нулю. Это гарантирует, что видимые отсчеты времени будут происходить в целых минутах. Базовые часы — лучшие доступные системные часы, эквивалентные использованию 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нс.

Длительность 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)

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

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

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

millis

public long millis()

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

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

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

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

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

instant

public abstract Instant instant()

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

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

Возвращает:: текущий момент времени от этих часов, не null
Исключения:: DateTimeException - если момент времени получить невозможно, не вызывается в большинстве реализаций

equals

public boolean equals(Object obj)

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

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

Переопределяет:: equals в классе Object
Параметры:: obj - объект для проверки, null возвращает false
Возвращает:: true, если часы равны другим часам
См. также:: Object.hashCode(), HashMap

hashCode

public int hashCode()

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

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

Переопределяет:: hashCode в классе Object
Возвращает:: подходящий хеш-код
См. также:: Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

© 1993, 2020, 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.