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