Как KivaKit упрощает java.time

API времени Java (java.time) обеспечивает надежную, надежную и достаточно полную модель времени для платформы Java. Измерение времени сложно, так что это немаловажно. Однако связанное с платформой требование существенной полноты java.time привело к довольно сложному API. Именно из-за этой сложности КиваКит 1.6 (будет выпущен в ближайшее время) предоставляет упрощенный API для повседневных задач, который легче понять и использовать. Мини-фреймворк com.telenav.kivakit.core.time также отлично сочетается с другими мини-фреймворками KivaKit.

<dependency>
    <groupId>com.telenav.kivakit</groupId>
    <artifactId>kivakit-core</artifactId>
    <version>1.6.0</version>
</dependency>

Сравнение Java и KivaKit

Java представляет время несколькими темпоральными классами:

Мгновенное: представляет точку на временной шкале.
Длительность – представляет продолжительность времени.
LocalDate — представляет дату без часового пояса.
LocalTime — представляет время без часового пояса.
LocalDateTime — представляет дату и время без часового пояса.
ZonedDateTime — дата и время с указанием часового пояса.

KivaKit предоставляет следующие временные классы:

Время —момент времени: ДеньНедели, ЧасНедели
Продолжительность —продолжительность: год, месяц, неделя, день, час, минута, секунда.
ZonedTime — момент времени с часовым поясом.

Следующие примеры кода дают представление о разнице между API времени KivaKit и Java. Код, написанный с использованием java.time,отображается первым в виде простого текста, за которым следует kivakit.core.timeэквивалент жирным шрифтом.

Создание

var now = DateTime.now();  // java.time
var now = now();           // com.telenav.kivakit.core.time
var five = Duration.ofMinutes(5)
var five = minutes(5);
var dateOfBirth = LocalDate.of(2012, Month.MAY, 14);
var dateOfBirth = localTime(year(2012), MAY, dayOfMonth(14));
var sixThirty = LocalTime.parse("06:30")
var sixThirty = parseIsoLocalTime(this, "6:30");

Здесь мы видим, что KivaKit обеспечивает лучшую безопасность типов (все аргументы являются объектами, а не примитивами), а также улучшенную читабельность. Такие методы, как LocalDate.of(), требуют понимания класса. Эквивалентный метод ZonedTime.localTime() в KivaKit может быть статически импортирован как localTime(…).

Все статические методы KivaKit названы так, чтобы их было легко импортировать.

Пройденное время

var start = Instant.now();
var elapsed = Duration.between(start, Instant.now());
var start = now()
var elapsed = start.elapsedSince();

В этом примере мы видим разницу между негибким служебным методом Duration.between() static и плавным, легко обнаруживаемым методом elapsedSince().

Потоки

Thread.sleep(Duration.ofMinutes(7).toMillis();
minutes(7).sleep();
var timer = new Timer();
timer.scheduleAtFixedRate(this::doit, 0, 
    Duration.ofMinutes(7).toMillis();
minutes(7).every(this::doit());
var wake = Instant.now().plus(1, ChronoUnit.HOURS);
Thread.sleep(Duration.between(Instant.now(), wake)
    .toMillis());
var wake = now().plus(hours(1));
now().until(wake).sleep();

Здесь мы видим, что KivaKit предоставляет общие операции с потоками, которые легко обнаружить и использовать, и которые устраняют шаблоны.

Арифметика

var anHourFromNow = Instant.now().plus(1, ChronoUnit.HOURS);
var anHourFromNow = now().plus(hours(1));
var todayLastMonth = LocalDate.now().minus(1, ChronoUnit.MONTHS);
var todayLastMonth = nowLocal().minus(months(1));
var date = LocalDate.parse("2016-06-12")
var sunday = date.getDayOfWeek();
var theFirst = date.with(TemporalAdjusters.firstDayOfMonth())
var date = parseIsoLocalTime(this, "2016.06.12");
var sunday = date.dayOfWeek();
var theFirst = date.withDay(dayOfMonth(1));

Показанные здесь арифметические операции очень похожи, хотя, возможно, KivaKit выглядит несколько чище. Метод parseIsoLocalTime() также интегрируется с дизайном обмена сообщениями KivaKit, где this является Listener:

var date = parseIsoLocalTime(this, "2016.06.12");

Реализация parseIsoLocalTime() возвращает null и передает сообщение Problem, если данный текст не может быть проанализирован. Но параметр Listener делает его более гибким API. На самом деле, мы можем легко изменить его поведение, чтобы вместо этого он выдавал исключение:

var date = parseIsoLocalTime(throwingListener(), "2016.06.12");

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

Конверсии

var duration = Duration.ofMinutes(5)
    .plus(Duration.ofSeconds(15))
    .toString();
var duration = minutes(5).plus(seconds(15)).asString(FILESYSTEM);
var minutes = Duration.ofWeeks(5).toMinutes();
var minutes = weeks(5).asMinutes();

Здесь мы конвертируем 5 минут и 15 секунд в строковое представление, совместимое с файловой системой. Затем мы конвертируем 5 недель в минуты.