Пакет 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 используется для всех точности времени, причём нули используются для подразумевания меньшей точности.

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

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

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

Несколько календарных систем представляют собой неудобное дополнение к проблемам проектирования. Первое правило — большинство пользователей хотят стандартной календарной системы ISO. Таким образом, основные классы — только ISO. Второе правило — большинство тех, кто хочет не-ISO календарную систему, хотят это для взаимодействия с пользователем, таким образом, это проблема локализации пользовательского интерфейса. Таким образом, объекты дат и времён должны храниться как объекты 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);
   }