Пакет 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 - неизменяемый эквивалент метода установки
• 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);
   }