Пакет 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 хранит месяц сам по себе. Это хранит отдельный месяц года, например, 'DECEMBER'.

DayOfWeek хранит день недели сам по себе. Это хранит отдельный день недели, например, 'TUESDAY'.

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 - неизменяемый аналог метода setter
• 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);
   }