Пакет java.time

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

См.: Описание

Сводка класса

Класс	Описание
Часы	Доступ обеспечения часов к текущему моменту, дате и время, используя часовой пояс.
Продолжительность	Основанное на времени количество времени, такое как '34.5 секунды.
Момент	Мгновенная точка на временной шкале.
LocalDate	Дата без часового пояса в календарной системе ISO 8601, такой как 2007-12-03.
LocalDateTime	Разовое датой без часового пояса в календарной системе ISO 8601, такой как 2007-12-03T10:15:30.
LocalTime	Время без часового пояса в календарной системе ISO 8601, такой как 10:15:30.
MonthDay	Дневное месяцем в календарной системе ISO 8601, такой как --12-03.
OffsetDateTime	Разовое датой со смещением от UTC/Гринвича в календарной системе ISO 8601, такой как 2007-12-03T10:15:30+01:00.
OffsetTime	Время со смещением от UTC/Гринвича в календарной системе ISO 8601, такой как 10:15:30+01:00.
Период	Основанное на дате количество времени, такое как '2 года, 3 месяца и 4 дня.
Год	Год в календарной системе ISO 8601, такой как 2007.
YearMonth	Месячное годом в календарной системе ISO 8601, такой как 2007-12.
ZonedDateTime	Разовое датой с часовым поясом в календарной системе ISO 8601, такой как 2007-12-03T10:15:30+01:00 Europe/Paris.
ZoneId	ID часового пояса, такой как Europe/Paris.
ZoneOffset	Смещение часового пояса из Гринвича/UTC, такой как +02:00.

Перечислимая Сводка

Перечисление	Описание
DayOfWeek	День-недельного, такой как в 'вторник'.
Месяц	Месяц-летнего, такой как 'июль'.

Сводка исключения

Исключение	Описание
DateTimeException	Исключение, используемое, чтобы указать на проблему, вычисляя разовое датой.

Пакет java.time Описание

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

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

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

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

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

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

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

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

LocalDateTime хранит дату и время. Это хранит разовое датой как '2010-12-03T11:30'.

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

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

Вне дат и времена, API также позволяет хранение периода и продолжительности времени. A Duration простая мера времени вдоль временной шкалы в наносекундах. A 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 и других формах персистентности, но содержит меньше информации чем весь часовой пояс.

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

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

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

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

API был разработан, чтобы отклонить нуль рано и согласиться с этим поведением. Ключевое исключение является любым методом, который берет объект и возвращает булево, с целью проверки или проверки допустимости, обычно возвратит false для нуля.

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

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

Instant самый близкий эквивалентный class к java.util.Date. ZonedDateTime самый близкий эквивалентный class к java.util.GregorianCalendar.

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

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

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

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

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

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

• of - статический метод фабрики
• parse - статический метод фабрики фокусировался на парсинге
• get - получает значение чего-то
• is - проверки, если что-то - истина
• with - неизменный эквивалент метода set
• 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);
   }

 

С тех пор:

JDK1.8