Adding labels to split StopWatch feature

Author: edelgadoh

src/main/java/org/apache/commons/lang3/time/StopWatch.java

@@ -19,6 +19,9 @@
 
 import java.time.Duration;
 import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;
@@ -27,6 +30,8 @@
 import org.apache.commons.lang3.function.FailableConsumer;
 import org.apache.commons.lang3.function.FailableRunnable;
 import org.apache.commons.lang3.function.FailableSupplier;
+import org.apache.commons.lang3.math.NumberUtils;
+import org.apache.commons.lang3.tuple.ImmutablePair;
 
 /**
  * {@link StopWatch} provides a convenient API for timings.
@@ -248,6 +253,11 @@ public static StopWatch createStarted() {
      */
     private long stopTimeNanos;
 
+    /**
+     * The split history list.
+     */
+    private List<Split> splitHistory;
+
     /**
      * Constructs a new instance.
      */
@@ -326,6 +336,16 @@ public String getMessage() {
         return message;
     }
 
+    /**
+     * Gets the split history list.
+     *
+     * @return the list of splits.
+     * @since 3.19.0
+     */
+    public List<Split> getSplitHistory() {
+        return Collections.unmodifiableList(splitHistory);
+    }
+
     /**
      * Gets the <em>elapsed</em> time in nanoseconds.
      *
@@ -557,6 +577,7 @@ private long nanosToMillis(final long nanos) {
     public void reset() {
         runningState = State.UNSTARTED;
         splitState = SplitState.UNSPLIT;
+        splitHistory = new ArrayList<>();
     }
 
     /**
@@ -626,6 +647,22 @@ public void split() {
         splitState = SplitState.SPLIT;
     }
 
+    /**
+     * <p>
+     * Captures the duration (elapsed time of this split vs the last split) and is recorded in a list.
+     * The label specified is used to identify the current split.
+     * </p>
+     *
+     * @param label A message for string presentation.
+     * @throws IllegalStateException if the StopWatch is not running.
+     * @since 3.19.0
+     */
+    public void addSplitHistory(final String label) {
+        split();
+        final long duration = System.nanoTime() - splitHistory.get(splitHistory.size() - 1).getDuration().getNano();
+        splitHistory.add(new Split(label, Duration.ofNanos(duration)));
+    }
+
     /**
      * Starts this StopWatch.
      *
@@ -645,6 +682,8 @@ public void start() {
         startTimeNanos = System.nanoTime();
         startInstant = Instant.now();
         runningState = State.RUNNING;
+        splitHistory = new ArrayList<>();
+        splitHistory.add(new Split(StringUtils.EMPTY, Duration.ofNanos(NumberUtils.LONG_ZERO)));
     }
 
     /**
@@ -674,6 +713,7 @@ public void stop() {
         if (runningState == State.RUNNING) {
             stopTimeNanos = System.nanoTime();
             stopInstant = Instant.now();
+            addSplitHistory(StringUtils.EMPTY);
         }
         runningState = State.STOPPED;
     }
@@ -746,4 +786,45 @@ public void unsplit() {
         splitState = SplitState.UNSPLIT;
     }
 
+    /**
+     * Class to store details of each split.
+     * @since 3.19.0
+     */
+    public static final class Split extends ImmutablePair<String, Duration> {
+
+        /**
+         * Constructor with label and duration.
+         * @param label Label for this split.
+         * @param duration Duration of the split.
+         */
+        public Split(String label, Duration duration) {
+            super(label, duration);
+        }
+
+        /**
+         * Get the label of this split.
+         * @return label.
+         */
+        public String getLabel() {
+            return getLeft();
+        }
+
+        /**
+         * Duration of this split.
+         * @return duration.
+         */
+        public Duration getDuration() {
+            return getRight();
+        }
+
+        /**
+         * Converts this instance to a handy string.
+         * @return this instance as a string.
+         */
+        @Override
+        public String toString() {
+            return String.format("Split [label=%s, duration=%s])", getLabel(), getDuration());
+        }
+    }
+
 }

src/test/java/org/apache/commons/lang3/time/StopWatchTest.java

@@ -26,11 +26,14 @@
 import java.io.IOException;
 import java.time.Duration;
 import java.time.Instant;
+import java.util.List;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
 
 import org.apache.commons.lang3.AbstractLangTest;
+import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.ThreadUtils;
+import org.apache.commons.lang3.math.NumberUtils;
 import org.apache.commons.lang3.reflect.FieldUtils;
 import org.junit.jupiter.api.RepeatedTest;
 import org.junit.jupiter.api.Test;
@@ -500,6 +503,36 @@ void testToStringWithMessage() throws InterruptedException {
         assertEquals(SPLIT_CLOCK_STR_LEN + MESSAGE.length() + 1, splitStr.length(), "Formatted split string not the correct length");
     }
 
+    @Test
+    void testSplitsWithStringLabels() {
+        final StopWatch watch = new StopWatch();
+        final String firstLabel = "one";
+        final String secondLabel = "two";
+        final String thirdLabel = "three";
+        watch.start();
+        // starting splits
+        watch.addSplitHistory(firstLabel);
+        watch.addSplitHistory(secondLabel);
+        watch.addSplitHistory(thirdLabel);
+        watch.stop();
+        // getting splits
+        final List<StopWatch.Split> splits = watch.getSplitHistory();
+        // check sizes
+        assertEquals(5, splits.size());
+        // check labels
+        assertEquals(StringUtils.EMPTY, splits.get(0).getLabel());
+        assertEquals(firstLabel, splits.get(1).getLabel());
+        assertEquals(secondLabel, splits.get(2).getLabel());
+        assertEquals(thirdLabel, splits.get(3).getLabel());
+        assertEquals(StringUtils.EMPTY, splits.get(4).getLabel());
+        // check duration
+        assertEquals(NumberUtils.LONG_ZERO, splits.get(0).getDuration().getNano());
+        assertTrue(splits.get(1).getDuration().getNano() > 0);
+        assertTrue(splits.get(2).getDuration().getNano() > 0);
+        assertTrue(splits.get(3).getDuration().getNano() > 0);
+        assertTrue(splits.get(4).getDuration().getNano() > 0);
+    }
+
     private int throwIOException() throws IOException {
         throw new IOException("A");
     }