diff --git a/src/changes/changes.xml b/src/changes/changes.xml index ab34f5567..e1cdae1ef 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -49,6 +49,7 @@ The type attribute can be add,update,fix,remove. Add StopWatch.getSplitDuration() and deprecate getSplitTime(). + Add StopWatch.getStartInstant() and deprecate getStartTime(). diff --git a/src/main/java/org/apache/commons/lang3/time/StopWatch.java b/src/main/java/org/apache/commons/lang3/time/StopWatch.java index a811862fc..5cc28143c 100644 --- a/src/main/java/org/apache/commons/lang3/time/StopWatch.java +++ b/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"); diff --git a/src/test/java/org/apache/commons/lang3/time/StopWatchTest.java b/src/test/java/org/apache/commons/lang3/time/StopWatchTest.java index 295ff1261..60ce1f872 100644 --- a/src/test/java/org/apache/commons/lang3/time/StopWatchTest.java +++ b/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, - "Calling getStartTime on an unstarted StopWatch should throw an exception"); + assertThrows(IllegalStateException.class, watch::getStartTime, "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, - "Calling getStartTime on a reset, but unstarted StopWatch should throw an exception"); + assertThrows(IllegalStateException.class, watch::getStartTime, "Calling getStartTime on a reset, but unstarted StopWatch should throw an exception"); } @Test