Пакет java.time

Основной API для дат, времён, мгновений и продолжительностей.

Классы, определённые здесь, представляют основные понятия даты и времени, включая мгновения, продолжительности, даты, времена, часовые пояса и периоды. Они основаны на системе календаря ISO, которая является фактическим мировым календарём, следуя пролептическим григорианским правилам. Все классы неизменяемы и потокобезопасны.

Каждый экземпляр даты и времени состоит из полей, которые удобно доступны через API. Для более низкоуровневого доступа к полям обратитесь к пакету java.time.temporal. Каждый класс включает поддержку печати и разбора различных дат и времён. Обратитесь к пакету java.time.format для параметров настройки.

Пакет java.time.chrono содержит календарно-нейтральный API ChronoLocalDate, ChronoLocalDateTime, ChronoZonedDateTime и Era. Это предназначено для использования приложениями, которым необходимо использовать локальные календари. Рекомендуется, чтобы приложения использовали классы дат и времени ISO-8601 из этого пакета при переходе через системные границы, такие как база данных или сеть. Календарно-нейтральный API следует резервировать для взаимодействия с пользователями.

Даты и времена

Instant по существу представляет собой числовой отметку времени. Текущий момент времени можно получить из Clock. Это полезно для ведения журнала и сохранения момента времени, и в прошлом было связано с сохранением результата из System.currentTimeMillis().

LocalDate хранит дату без времени. Он хранит дату, например, '2010-12-03', и может использоваться для хранения даты рождения.

LocalTime хранит время без даты. Он хранит время, например, '11:30', и может использоваться для хранения времени открытия или закрытия.

LocalDateTime хранит дату и время. Он хранит дату и время, например, '2010-12-03T11:30'.

ZonedDateTime хранит дату и время с часовым поясом. Это полезно, если вы хотите выполнить точные вычисления дат и времён с учётом ZoneId, например, 'Europe/Paris'. В случае возможности рекомендуется использовать более простой класс без часового пояса. Широкое использование часовых поясов, как правило, добавляет значительную сложность в приложение.

Продолжительность и период

Помимо дат и времён, API также позволяет хранить периоды и продолжительности времени. Duration представляет собой простое измерение времени вдоль временной линии в наносекундах. Period выражает количество времени в единицах, понятных людям, таких как годы или дни.

Дополнительные типы значений

Month хранит месяц сам по себе. Он хранит отдельный месяц года, например, 'ДЕКАБРЬ'.

DayOfWeek хранит день недели сам по себе. Он хранит отдельный день недели, например, 'ВТОРНИК'.

Year хранит год сам по себе. Он хранит отдельный год, например, '2010'.

YearMonth хранит год и месяц без дня или времени. Он хранит год и месяц, например, '2010-12', и может использоваться для срока действия кредитной карты.

MonthDay хранит месяц и день без года или времени. Он хранит месяц и день месяца, например, '--12-03', и может использоваться для хранения ежегодного события, такого как день рождения, без хранения года.

OffsetTime хранит время и смещение от UTC без даты. Он хранит время, например, '11:30+01:00'. ZoneOffset имеет вид '+01:00'.

OffsetDateTime хранит дату и время, и смещение от UTC. Он хранит дату и время, например, '2010-12-03T11:30+01:00'. Иногда он встречается в XML-сообщениях и других формах сохранения, но содержит меньше информации, чем полный часовой пояс.

Спецификация пакета

Если не указано иное, передача null-аргумента конструктору или методу в любом классе или интерфейсе в этом пакете вызовет NullPointerException. Определение Javadoc "@param" используется для обобщения поведения null. "@throws NullPointerException" не документируется явно в каждом методе.

Все вычисления должны проверять переполнение чисел и выбрасывать либо ArithmeticException, либо DateTimeException.

Примечания к проектированию (не нормативные)

API был разработан для отбрасывания null на ранних стадиях и для ясности этого поведения. Важным исключением является любой метод, принимающий объект и возвращающий boolean для проверки или валидации, который обычно возвращает false для null.

API разработан для обеспечения типобезопасности, где это возможно, в основном высокоуровневом API. Таким образом, существуют отдельные классы для различных понятий даты, времени и даты-времени, плюс варианты для смещения и часового пояса. Это может показаться большим количеством классов, но большинство приложений могут начать с всего пяти типов дат/времени.

• Instant - отметка времени
• LocalDate - дата без времени или любой ссылки на смещение или часовой пояс
• LocalTime - время без даты или любой ссылки на смещение или часовой пояс
• LocalDateTime - объединяет дату и время, но всё ещё без смещения или часового пояса
• ZonedDateTime - "полное" время и дата с часовым поясом и вычисленным смещением от UTC/Гринвича

Instant — это ближайший эквивалентный класс к java.util.Date. ZonedDateTime — это ближайший эквивалентный класс к java.util.GregorianCalendar.

По возможности, приложения должны использовать LocalDate, LocalTime и LocalDateTime для лучшего моделирования предметной области. Например, день рождения следует хранить в коде LocalDate. Имейте в виду, что любое использование часового пояса, например, 'Europe/Paris', добавляет значительную сложность вычислению. Многие приложения могут быть написаны только с использованием LocalDate, LocalTime и Instant, с добавлением часового пояса на уровне пользовательского интерфейса (UI).

Типы дат и времени, основанные на смещении, OffsetTime и OffsetDateTime, предназначены в первую очередь для использования с сетевыми протоколами и доступом к базам данных. Например, большинство баз данных не могут автоматически хранить часовой пояс, такой как 'Europe/Paris', но они могут хранить смещение, такое как '+02:00'.

Также предоставляются классы для наиболее важных подэлементов даты, включая Month, DayOfWeek, Year, YearMonth и MonthDay. Они могут использоваться для моделирования более сложных концепций даты и времени. Например, YearMonth полезен для представления срока действия кредитной карты.

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

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

API имеет относительно большую поверхность в плане количества методов. Это облегчается использованием согласованных префиксов методов.

• of - статический фабричный метод
• parse - статический фабричный метод, ориентированный на разбор
• get - получает значение чего-либо
• is - проверяет, верно ли что-либо
• with - неизменяемый аналог метода установки
• plus - добавляет величину к объекту
• minus - вычитает величину из объекта
• to - преобразует этот объект в другой тип
• at - объединяет этот объект с другим, например, date.atTime(time)

Множественные системы календарей являются неудобным дополнением к проблемам проектирования. Первый принцип заключается в том, что большинство пользователей хотят стандартную систему календаря ISO. Поэтому основные классы — только ISO. Второй принцип заключается в том, что большинство тех, кто хочет не-ISO систему календарей, хотят её для взаимодействия с пользователем, поэтому это проблема локализации UI. Таким образом, объекты даты и времени должны храниться в виде ISO-объектов в модели данных и в постоянном хранилище, преобразуясь только в и из локального календаря для отображения. Система календаря будет храниться отдельно в пользовательских настройках.

Однако существуют некоторые ограниченные случаи использования, когда пользователи считают, что им необходимо хранить и использовать даты в произвольных системах календарей на всём протяжении приложения. Это поддерживается ChronoLocalDate, однако крайне важно прочитать все соответствующие предупреждения в Javadoc этого интерфейса перед его использованием. Подводя итог, приложения, которым требуется общая работа с несколькими системами календарей, обычно требуют написания кода совершенно другим образом, чем те, которые используют только календарь ISO, поэтому большинство приложений должны использовать только ISO и избегать ChronoLocalDate.

API также разработан с учётом возможности расширения пользователями, так как существует множество способов вычисления времени. API полей и единиц, доступные через TemporalAccessor и Temporal, обеспечивают значительную гибкость для приложений. Кроме того, интерфейсы TemporalQuery и TemporalAdjuster обеспечивают повседневную функциональность, позволяя коду работать в соответствии с бизнес-требованиями:

   LocalDate customerBirthday = customer.loadBirthdayFromDatabase();
   LocalDate today = LocalDate.now();
   if (customerBirthday.equals(today)) {
     LocalDate specialOfferExpiryDate = today.plusWeeks(2).with(next(FRIDAY));
     customer.sendBirthdaySpecialOffer(specialOfferExpiryDate);
   }