Add StopWatch.getStartInstant() and deprecate getStartTime()

src/changes/changes.xml

@@ -49,6 +49,7 @@ The <action> type attribute can be add,update,fix,remove.
       <!-- FIX -->
       <!-- ADD -->
       <action                 type="add" dev="ggregory" due-to="Gary Gregory">Add StopWatch.getSplitDuration() and deprecate getSplitTime().</action>
+      <action                 type="add" dev="ggregory" due-to="Gary Gregory">Add StopWatch.getStartInstant() and deprecate getStartTime().</action>
       <!-- UPDATE -->
   </release>
   <release version="3.15.0" date="2024-07-13" description="New features and bug fixes (Java 8 or above).">

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

@@ -18,6 +18,7 @@
 package org.apache.commons.lang3.time;
 
 import java.time.Duration;
+import java.time.Instant;
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 
@@ -357,13 +358,26 @@ public class StopWatch {
         return nanosToMillis(getSplitNanoTime());
     }
 
+    /**
+     * Gets the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
+     *
+     * @return the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
+     * @throws IllegalStateException if this StopWatch has not been started
+     * @since 3.16.0
+     */
+    public Instant getStartInstant() {
+        return Instant.ofEpochMilli(getStartTime());
+    }
+
     /**
      * Gets the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.
      *
      * @return the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.
      * @throws IllegalStateException if this StopWatch has not been started
      * @since 2.4
+     * @deprecated Use {@link #getStartInstant()}.
      */
+    @Deprecated
     public long getStartTime() {
         if (this.runningState == State.UNSTARTED) {
             throw new IllegalStateException("Stopwatch has not been started");

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

@@ -31,6 +31,7 @@ import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.time.Duration;
+import java.time.Instant;
 import java.util.concurrent.TimeUnit;
 
 import org.apache.commons.lang3.AbstractLangTest;
@@ -204,20 +205,33 @@ public class StopWatchTest extends AbstractLangTest {
         assertEquals(Duration.ofNanos(123456), watch.getSplitDuration());
     }
 
+    @Test
+    public void testGetStartInstant() {
+        final long beforeStopWatchMillis = System.currentTimeMillis();
+        final StopWatch watch = new StopWatch();
+        assertThrows(IllegalStateException.class, watch::getStartInstant, "Calling getStartInstant on an unstarted StopWatch should throw an exception");
+        watch.start();
+
+        watch.getStartInstant();
+        assertThat("getStartInstant", watch.getStartInstant(), greaterThanOrEqualTo(Instant.ofEpochMilli(beforeStopWatchMillis)));
+
+        watch.reset();
+        assertThrows(IllegalStateException.class, watch::getStartInstant,
+                "Calling getStartInstant on a reset, but unstarted StopWatch should throw an exception");
+    }
+
     @Test
     public void testGetStartTime() {
         final long beforeStopWatchMillis = System.currentTimeMillis();
         final StopWatch watch = new StopWatch();
-        assertThrows(IllegalStateException.class, watch::getStartTime,
+        assertThrows(IllegalStateException.class, watch::getStartTime, "Calling getStartTime on an unstarted StopWatch should throw an exception");
-            "Calling getStartTime on an unstarted StopWatch should throw an exception");
         watch.start();
 
         watch.getStartTime();
         assertThat("getStartTime", watch.getStartTime(), greaterThanOrEqualTo(beforeStopWatchMillis));
 
         watch.reset();
-        assertThrows(IllegalStateException.class, watch::getStartTime,
+        assertThrows(IllegalStateException.class, watch::getStartTime, "Calling getStartTime on a reset, but unstarted StopWatch should throw an exception");
-            "Calling getStartTime on a reset, but unstarted StopWatch should throw an exception");
     }
 
     @Test