version 0.15

 added new IntervalUnits Day and Hours

Author: cwensel

.gitignore

@@ -1,4 +1,5 @@
 .gradle
+.kotlin
 out
 build
 workspace

README.md

@@ -25,9 +25,15 @@ The Label class is for making labels, String for use in different contexts.
 ```java
 Label id = Label.of("project").with("version");
 
-id.camelCase(); // projectVersion
-id.lowerHyphen(); // project-version
-id.lowerColonPath(); // project:version
+id.
+
+camelCase(); // projectVersion
+id.
+
+lowerHyphen(); // project-version
+id.
+
+lowerColonPath(); // project:version
 ```
 
 There are a few flavors of Label:
@@ -65,15 +71,20 @@ class provides a way to create Refs for child resources of the construct.
 Provides [IntervalUnit](clusterless-commons-core/src/main/java/clusterless/commons/temporal/IntervalUnit.java)
 implementations of:
 
-- Fourths - 15 minute intervals
-- Sixths - 10 minute intervals
-- Twelfths - 5 minute intervals
-
-These intervals are used by Clusterless to label lots.
+- Day - the day interval - `20230206PT24H`
+- Hours - 60 minute intervals within a day (24 intervals) - `20230206PT1H23`
+- Fourths - 15 minute intervals within a day (96 intervals) - `20230206PT15M92`
+- Sixths - 10 minute intervals within a day (144 intervals) - `20230206PT10M138`
+- Twelfths - 5 minute intervals within a day (288 intervals) - `20230206PT5M276`
 
 There is also a
 [IntervalDateTimeFormatter](clusterless-commons-core/src/main/java/clusterless/commons/temporal/IntervalDateTimeFormatter.java)
-for formatting dates and times of these intervals.
+for formatting and parsing of the dates and times these intervals represent. See above for examples.
+
+These intervals are used by Clusterless to label the execution of a batch job (or lot).
+
+For continuously arriving data, the lexical order of the jobs by the formatted interval string makes it trivial to
+identify gaps and reason about how long the batch accumulated data before execution.
 
 ### Collection
 

build-logic/src/main/kotlin/clusterless.commons.java-common-properties.gradle.kts

@@ -7,7 +7,8 @@
  */
 
 extra["group"] = "io.clusterless"
-extra["version"] = "0.14"
+//extra["version"] = "0.15-wip-"+System.getProperty("build.number","dev")
+extra["version"] = "0.15"
 
 extra["repoUserName"] = System.getProperty("publish.repo.userName")
 extra["repoPassword"] = System.getProperty("publish.repo.password")

clusterless-commons-core/src/main/java/clusterless/commons/temporal/IntervalDateTimeFormatter.java

@@ -14,26 +14,56 @@
 import java.time.temporal.TemporalUnit;
 
 import static clusterless.commons.temporal.IntervalField.*;
+import static clusterless.commons.temporal.IntervalField.HOUR_OF_DAY;
 import static java.time.temporal.ChronoField.*;
 
 /**
  * IntervalDateTimeFormatter provided formatters for the {@link IntervalUnit} units.
- *
+ * <p>
  * See {@link IntervalUnits#formatter(TemporalUnit)} for looking up an appropriate formatter.
  */
 public class IntervalDateTimeFormatter {
+    public static final DateTimeFormatter DAY_FORMATTER;
+    public static final DateTimeFormatter HOUR_FORMATTER;
     public static final DateTimeFormatter FOURTH_FORMATTER;
     public static final DateTimeFormatter SIXTH_FORMATTER;
     public static final DateTimeFormatter TWELFTH_FORMATTER;
 
+    static {
+        DAY_FORMATTER = new DateTimeFormatterBuilder()
+                .parseStrict()
+                .appendValue(YEAR, 4)
+                .appendValue(MONTH_OF_YEAR, 2)
+                .appendValue(DAY_OF_MONTH, 2)
+                .appendLiteral(DAY.getBaseUnit().getDuration().toString())
+                // ensure that the TemporalAccessor is set to midnight
+                .parseDefaulting(HOUR_OF_DAY, 0)
+                .parseDefaulting(MINUTE_OF_HOUR, 0)
+                .parseDefaulting(SECOND_OF_MINUTE, 0)
+                .toFormatter()
+                .withZone(ZoneOffset.UTC);
+    }
+
+    static {
+        HOUR_FORMATTER = new DateTimeFormatterBuilder()
+                .parseStrict()
+                .appendValue(YEAR, 4)
+                .appendValue(MONTH_OF_YEAR, 2)
+                .appendValue(DAY_OF_MONTH, 2)
+                .appendLiteral(HOUR_OF_DAY.getBaseUnit().getDuration().toString())
+                .appendValue(HOUR_OF_DAY, 2)
+                .toFormatter()
+                .withZone(ZoneOffset.UTC);
+    }
+
     static {
         FOURTH_FORMATTER = new DateTimeFormatterBuilder()
                 .parseStrict()
                 .appendValue(YEAR, 4)
                 .appendValue(MONTH_OF_YEAR, 2)
                 .appendValue(DAY_OF_MONTH, 2)
                 .appendLiteral(FOURTH_OF_DAY.getBaseUnit().getDuration().toString())
-                .appendValue(FOURTH_OF_DAY, 3)
+                .appendValue(FOURTH_OF_DAY, 2) // max 96
                 .toFormatter()
                 .withZone(ZoneOffset.UTC);
     }

clusterless-commons-core/src/main/java/clusterless/commons/temporal/IntervalField.java

@@ -19,11 +19,26 @@
 import java.util.Objects;
 
 import static java.time.temporal.ChronoUnit.DAYS;
+import static java.time.temporal.ChronoUnit.YEARS;
 
 /**
  * Mostly copied from {@link ChronoField} adding support for new IntervalUnits.
  */
 public enum IntervalField implements TemporalField {
+    /**
+     * The day.
+     * <p>
+     * This represents the actual day only.
+     */
+    DAY("Day", IntervalUnit.DAY, YEARS, ValueRange.of(0, 365)),
+
+    /**
+     * The hour-of-day.
+     * <p>
+     * This counts the full hour within the day, from 0 to 24 * 60.
+     */
+    HOUR_OF_DAY("HourOfDay", IntervalUnit.HOURS, DAYS, ValueRange.of(0, 24 * 60)),
+
     /**
      * The fourth-of-day.
      * <p>

clusterless-commons-core/src/main/java/clusterless/commons/temporal/IntervalUnit.java

@@ -9,14 +9,16 @@
 package clusterless.commons.temporal;
 
 import java.time.Duration;
+import java.time.temporal.ChronoUnit;
 import java.time.temporal.Temporal;
 import java.time.temporal.TemporalUnit;
 
 import static java.time.temporal.ChronoField.MINUTE_OF_DAY;
-import static java.time.temporal.ChronoUnit.MINUTES;
 
 /**
  * Breaks a day into the number of intervals requested.
+ * <p>
+ * Day is the actual day as an interval where the day component is of the month.
  * <p/>
  * Fourths is a 15-minute duration, there are 4 Fourths in an hour, and 96 Fourths in a day.
  * <p/>
@@ -25,6 +27,8 @@
  * Twelfths is a 5-minute duration, there are 12 Twelfths in an hour, and 288 Twelfth in a day.
  */
 public enum IntervalUnit implements TemporalUnit {
+    DAY("Day", Duration.ofDays(1)),
+    HOURS("Hours", Duration.ofHours(1)),
     FOURTHS("Fourths", Duration.ofMinutes(15)),
     SIXTHS("Sixths", Duration.ofMinutes(10)),
     TWELFTHS("Twelfths", Duration.ofMinutes(5));
@@ -66,12 +70,16 @@ public boolean isSupportedBy(Temporal temporal) {
     @Override
     public <R extends Temporal> R addTo(R temporal, long amount) {
         switch (this) {
+            case DAY:
+                return (R) temporal.plus(amount, ChronoUnit.DAYS);
+            case HOURS:
+                return (R) temporal.plus(amount, ChronoUnit.HOURS);
             case FOURTHS:
-                return (R) temporal.plus(15 * amount, MINUTES);
+                return (R) temporal.plus(15 * amount, ChronoUnit.MINUTES);
             case SIXTHS:
-                return (R) temporal.plus(10 * amount, MINUTES);
+                return (R) temporal.plus(10 * amount, ChronoUnit.MINUTES);
             case TWELFTHS:
-                return (R) temporal.plus(5 * amount, MINUTES);
+                return (R) temporal.plus(5 * amount, ChronoUnit.MINUTES);
             default:
                 throw new IllegalArgumentException();
         }
@@ -83,12 +91,16 @@ public long between(Temporal temporal1Inclusive, Temporal temporal2Exclusive) {
             return temporal1Inclusive.until(temporal2Exclusive, this);
         }
         switch (this) {
+            case DAY:
+                return temporal1Inclusive.until(temporal2Exclusive, ChronoUnit.DAYS);
+            case HOURS:
+                return temporal1Inclusive.until(temporal2Exclusive, ChronoUnit.HOURS);
             case FOURTHS:
-                return temporal1Inclusive.until(temporal2Exclusive, MINUTES) / 15;
+                return temporal1Inclusive.until(temporal2Exclusive, ChronoUnit.MINUTES) / 15;
             case SIXTHS:
-                return temporal1Inclusive.until(temporal2Exclusive, MINUTES) / 10;
+                return temporal1Inclusive.until(temporal2Exclusive, ChronoUnit.MINUTES) / 10;
             case TWELFTHS:
-                return temporal1Inclusive.until(temporal2Exclusive, MINUTES) / 5;
+                return temporal1Inclusive.until(temporal2Exclusive, ChronoUnit.MINUTES) / 5;
             default:
                 throw new IllegalArgumentException();
         }

clusterless-commons-core/src/main/java/clusterless/commons/temporal/IntervalUnits.java

@@ -39,6 +39,12 @@ public static void verifyHasFormatter(TemporalUnit unit) {
      * @throws IllegalArgumentException if the given unit does not have an associated formatter
      */
     public static DateTimeFormatter formatter(TemporalUnit unit) {
+        if (unit == IntervalUnit.DAY) {
+            return IntervalDateTimeFormatter.DAY_FORMATTER;
+        }
+        if (unit == IntervalUnit.HOURS) {
+            return IntervalDateTimeFormatter.HOUR_FORMATTER;
+        }
         if (unit == IntervalUnit.FOURTHS) {
             return IntervalDateTimeFormatter.FOURTH_FORMATTER;
         }
@@ -63,9 +69,9 @@ public static TemporalUnit find(String name) {
         Objects.requireNonNull(name, "name");
 
         try {
-            return ChronoUnit.valueOf(name.toUpperCase(Locale.ROOT));
-        } catch (IllegalArgumentException e) {
             return IntervalUnit.valueOf(name.toUpperCase(Locale.ROOT));
+        } catch (IllegalArgumentException e) {
+            return ChronoUnit.valueOf(name.toUpperCase(Locale.ROOT));
         }
     }
 

clusterless-commons-core/src/test/java/clusterless/commons/temporal/TemporalTest.java

@@ -17,6 +17,7 @@
 import java.time.ZoneId;
 import java.time.format.DateTimeFormatter;
 import java.time.temporal.TemporalAccessor;
+import java.time.temporal.TemporalField;
 import java.time.temporal.TemporalUnit;
 import java.util.stream.Stream;
 
@@ -35,19 +36,26 @@ public class TemporalTest {
     private static Stream<Arguments> arguments() {
         return Stream.of(
                 // Mon Feb 06 2023 23:52:06 GMT+0000
-                Arguments.of(1675727526500L, 1675727100000L, 95, IntervalField.FOURTH_OF_DAY, "PT15M"),
-                Arguments.of(1675727526500L, 1675727400000L, 143, IntervalField.SIXTH_OF_DAY, "PT10M"),
-                Arguments.of(1675727526500L, 1675727400000L, 286, IntervalField.TWELFTH_OF_DAY, "PT5M"),
+                Arguments.of(1675727526500L, 1675727100000L, 95, IntervalField.FOURTH_OF_DAY, "PT15M", "20230206%s%02d"),
+                Arguments.of(1675727526500L, 1675727400000L, 143, IntervalField.SIXTH_OF_DAY, "PT10M", "20230206%s%03d"),
+                Arguments.of(1675727526500L, 1675727400000L, 286, IntervalField.TWELFTH_OF_DAY, "PT5M", "20230206%s%03d"),
                 // Mon Feb 06 2023 23:00:21 GMT+0000
-                Arguments.of(1675724421500L, 1675724400000L, 96 - 4, IntervalField.FOURTH_OF_DAY, "PT15M"),
-                Arguments.of(1675724421500L, 1675724400000L, 144 - 6, IntervalField.SIXTH_OF_DAY, "PT10M"),
-                Arguments.of(1675724421500L, 1675724400000L, 288 - 12, IntervalField.TWELFTH_OF_DAY, "PT5M")
+                Arguments.of(1675724421500L, 1675724400000L, 96 - 4, IntervalField.FOURTH_OF_DAY, "PT15M", "20230206%s%02d"),
+                Arguments.of(1675724421500L, 1675724400000L, 144 - 6, IntervalField.SIXTH_OF_DAY, "PT10M", "20230206%s%03d"),
+                Arguments.of(1675724421500L, 1675724400000L, 288 - 12, IntervalField.TWELFTH_OF_DAY, "PT5M", "20230206%s%03d"),
+
+                Arguments.of(1675724421500L, 1675724400000L, 23, IntervalField.HOUR_OF_DAY, "PT1H", "20230206%s%02d"),
+                Arguments.of(1675724421500L, 1675641600000L, 0, IntervalField.DAY, "PT24H", "20230206%s")
+
+                // unsupported by java.time so we made our own above
+                // Arguments.of(1675724421500L, 1675724400000L, 23, ChronoField.HOUR_OF_DAY, "PT1H", "20230206%s%02d"),
+                // Arguments.of(1675724421500L, 1675641600000L, 0, ChronoField.DAY_OF_MONTH, "PT24H", "20230206%s")
         );
     }
 
     @ParameterizedTest
     @MethodSource("arguments")
-    public void test(long epochMilli, long truncatedMilli, int expected, IntervalField intervalField, String durationFragment) {
+    public void test(long epochMilli, long truncatedMilli, int expected, TemporalField intervalField, String durationFragment, String stringFormat) {
         TemporalUnit durationUnit = intervalField.getBaseUnit();
         DateTimeFormatter formatter = IntervalUnits.formatter(durationUnit);
         Instant instant = Instant.ofEpochMilli(epochMilli);
@@ -60,7 +68,7 @@ public void test(long epochMilli, long truncatedMilli, int expected, IntervalFie
 
         String format = formatter.format(instant);
 
-        assertEquals(String.format("20230206%s%03d", durationFragment, i), format);
+        assertEquals(String.format(stringFormat, durationFragment, i), format);
 
         TemporalAccessor temporalAccessor = formatter.parse(format);