Adding labels to split StopWatch feature - refactor based on PR review

Author: edelgadoh

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

@@ -20,6 +20,7 @@
 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;
@@ -29,6 +30,7 @@
 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;
 
 /**
  * {@link StopWatch} provides a convenient API for timings.
@@ -251,9 +253,9 @@ public static StopWatch createStarted() {
     private long stopTimeNanos;
 
     /**
-     * The list of splits
+     * The list of recorded splits.
      */
-    private List<Split> splits;
+    private List<Split> recordedSplits;
 
     /**
      * Constructs a new instance.
@@ -333,6 +335,16 @@ public String getMessage() {
         return message;
     }
 
+    /**
+     * Gets the recorded splits.
+     *
+     * @return the list of splits.
+     * @since 3.19.0
+     */
+    public List<Split> getRecordedSplits() {
+        return Collections.unmodifiableList(recordedSplits);
+    }
+
     /**
      * Gets the <em>elapsed</em> time in nanoseconds.
      *
@@ -635,55 +647,20 @@ public void split() {
 
     /**
      * <p>
-     * Splits the time to track the elapsed time between two consecutive {@code split()} calls.
-     * The label specified is used to identify each split
+     * 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>
      *
-     * <p>
-     * After calling {@link #stop()}, we can call {@link #getReport()} to have a report with all time between each {@code split()} call, example:
-     * </p>
-     *
-     * <pre>
-     * 1 00:14:00.000
-     * 2 00:02:00.000
-     * 3 00:04:00.000
-     * </pre>
-     *
-     * @param label A number to identify this split
-     *
-     * @throws IllegalStateException
-     *             if the StopWatch is not running.
-     */
-    public void split(int label) {
-        split(String.valueOf(label));
-    }
-
-    /**
-     * <p>
-     * Splits the time to track the elapsed time between two consecutive {@code split()} calls.
-     * The label specified is used to identify each split
-     * </p>
-     *
-     * <p>
-     * After calling {@link #stop()}, we can call {@link #getReport()} to have a report with all time between each {@code split()} call, example:
-     * </p>
-     *
-     * <pre>
-     * Baking cookies  00:14:00.000
-     * Serving         00:02:00.000
-     * Eating          00:04:00.000
-     * </pre>
-     *
      * @param label A message for string presentation.
-     *
-     * @throws IllegalStateException
-     *             if the StopWatch is not running.
+     * @throws IllegalStateException if the StopWatch is not running.
+     * @since 3.19.0
      */
-    public void split(String label) {
+    public void recordSplit(final String label) {
         if (this.runningState != State.RUNNING) {
             throw new IllegalStateException("Stopwatch is not running.");
         }
-        splits.add(new Split(label));
+        final long duration = System.nanoTime() - recordedSplits.get(recordedSplits.size() - 1).getNanoTime();
+        recordedSplits.add(new Split(label, duration));
     }
 
     /**
@@ -705,7 +682,8 @@ public void start() {
         startTimeNanos = System.nanoTime();
         startInstant = Instant.now();
         runningState = State.RUNNING;
-        splits = new ArrayList<>();
+        recordedSplits = new ArrayList<>();
+        recordedSplits.add(new Split(StringUtils.EMPTY, NumberUtils.LONG_ZERO));
     }
 
     /**
@@ -735,20 +713,11 @@ public void stop() {
         if (runningState == State.RUNNING) {
             stopTimeNanos = System.nanoTime();
             stopInstant = Instant.now();
-            split(StringUtils.EMPTY);
+            recordSplit(StringUtils.EMPTY);
         }
         runningState = State.STOPPED;
     }
 
-    /**
-     * Stops the watch if necessary
-     */
-    private void stopIfNecessary() {
-        if (this.runningState == State.RUNNING || this.runningState == State.SUSPENDED) {
-            stop();
-        }
-    }
-
     /**
      * Suspends this StopWatch for later resumption.
      *
@@ -818,180 +787,67 @@ public void unsplit() {
     }
 
     /**
-     * Stops the watch and returns the list of splits with duration on each split (using milliseconds)
-     * @return list of splits
+     * Class to store details of each split.
+     * @since 3.19.0
      */
-    public List<Split> getProcessedSplits() {
-        return getProcessedSplits(TimeUnit.MILLISECONDS);
-    }
-
-    /**
-     * Stops the watch and returns the list of splits with duration on each split (using nanoseconds)
-     * @return list of splits
-     */
-    public List<Split> getNanoProcessedSplits() {
-        return getProcessedSplits(TimeUnit.NANOSECONDS);
-    }
-
-    /**
-     * Stops the watch and returns the list of splits with duration on each split
-     *
-     * @param timeUnit the unit of time, not null. Any value will calculate with milliseconds precision unless
-     * {@code TimeUnit.NANOSECONDS} is specified.
-     * @return list of splits
-     */
-    public List<Split> getProcessedSplits(TimeUnit timeUnit) {
-        stopIfNecessary();
-        processSplits(timeUnit);
-        final List<Split> result = new ArrayList<>(splits);
-
-        // we remove the last split because it's an internal and automatic split
-        result.remove(result.size() - 1);
-
-        return result;
-    }
-
-    /**
-     * Fill durations (time took) on each split
-     *
-     * @param timeUnit the unit of time, not null. Any value will calculate with milliseconds precision unless
-     * {@code TimeUnit.NANOSECONDS} is specified.
-     */
-    private void processSplits(TimeUnit timeUnit) {
-        // we need at least 2 splits to calculate the elapsed time
-        if (splits.size() < 2) {
-            return;
-        }
-
-        for (int i = 0; i < splits.size() - 1; i++) {
-            final long durationNanos = splits.get(i + 1).getStartNanoTime() - splits.get(i).getStartNanoTime();
-            final long duration = (timeUnit == TimeUnit.NANOSECONDS)
-                    ? durationNanos
-                    : TimeUnit.MILLISECONDS.convert(durationNanos, TimeUnit.NANOSECONDS);
-            splits.get(i).setDuration(duration);
-        }
-
-    }
-
-    /**
-     * <p>
-     * Stops the watch and returns the splits report.
-     * This report contains the elapsed time (on milliseconds) between each split
-     * </p>
-     *
-     * @return the splits report
-     */
-    public String getReport() {
-        return getReport(TimeUnit.MILLISECONDS);
-    }
-
-    /**
-     * <p>
-     * Stops the watch and returns the splits report.
-     * This report contains the elapsed time (on nanoseconds) between each split
-     * </p>
-     *
-     * @return the splits report
-     */
-    public String getNanoReport() {
-        return getReport(TimeUnit.NANOSECONDS);
-    }
-
-    /**
-     * <p>
-     * Stops the watch and returns the splits report.
-     * This report contains the elapsed time between each split
-     * </p>
-     *
-     * @param timeUnit the unit of time, not null. Any value will calculate with milliseconds precision unless
-     * {@code TimeUnit.NANOSECONDS} is specified.
-     * @return the splits report
-     */
-    private String getReport(TimeUnit timeUnit) {
-        final StringBuilder report = new StringBuilder();
-
-        String duration;
-        for (final Split split : getProcessedSplits(timeUnit)) {
-            report.append(System.lineSeparator());
-            report.append(split.getLabel()).append(StringUtils.SPACE);
-
-            if (timeUnit == TimeUnit.NANOSECONDS) {
-                duration = String.valueOf(split.getDuration());
-            } else {
-                duration = DurationFormatUtils.formatDurationHMS(split.getDuration());
-            }
-
-            report.append(duration);
-        }
-
-        return report.toString();
-    }
-
-    /**
-     * Class to store details of each split
-     */
-    protected static class Split {
+    public static final class Split {
 
         /**
-         * The start nano time of this split
+         * The nano time of this split.
          */
-        private long startNanoTime = System.nanoTime();
+        private long nanoTime = System.nanoTime();
 
         /**
-         * The duration (time took) on this split
-         * This field is filled when user calls getSplits() or tries to print the splits report
+         * The duration (time took) on this split.
          */
         private long duration;
 
-        /*
-         * The label for this split
+        /**
+         * The label for this split.
          */
         private String label;
 
         /**
-         * Constructor with label
-         * @param label Label for this split
+         * Constructor with label and duration.
+         * @param label Label for this split.
+         * @param duration time on nano.
          */
-        public Split(String label) {
+        public Split(String label, long duration) {
             this.label = label;
+            this.duration = duration;
         }
 
         /**
-         * <p>
-         * Get the timestamp when this split was created
-         * </p>
-         *
-         * @return startNanoTime
+         * Get the nano time of this split.
+         * @return nano time.
          */
-        public long getStartNanoTime() {
-            return startNanoTime;
+        public long getNanoTime() {
+            return nanoTime;
         }
 
         /**
-         * <p>
-         * Get the label of this split
-         * </p>
-         *
-         * @return label
+         * Get the label of this split.
+         * @return label.
          */
         public String getLabel() {
             return label;
         }
 
         /**
-         * Duration of this split
-         * @return duration (time on ms or nano)
+         * Duration of this split.
+         * @return duration time on nano.
          */
         public long getDuration() {
             return duration;
         }
 
         /**
-         * Set the duration of this split
-         * @param duration time (on ms or nano)
+         * Converts this instance to a handy string.
+         * @return this instance as a string.
          */
-        private void setDuration(long duration) {
-            this.duration = duration;
+        @Override
+        public String toString() {
+            return String.format("Split [label=%s, duration=%d])", getLabel(), getDuration());
         }
     }