This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-lang.git
commit 263026823515618b42f9549b491e57065cb69c58 Author: Gary Gregory <[email protected]> AuthorDate: Thu Jul 18 16:26:28 2024 -0400 Add StopWatch.getDuration() and deprecate getTime() --- src/changes/changes.xml | 1 + .../org/apache/commons/lang3/time/StopWatch.java | 18 ++- .../apache/commons/lang3/time/StopWatchTest.java | 149 ++++++++++++--------- 3 files changed, 106 insertions(+), 62 deletions(-) diff --git a/src/changes/changes.xml b/src/changes/changes.xml index 255de4ae1..fc8bcb221 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -51,6 +51,7 @@ The <action> type attribute can be add,update,fix,remove. <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> <action type="add" dev="ggregory" due-to="Gary Gregory">Add StopWatch.getStopInstant() and deprecate getStopTime().</action> + <action type="add" dev="ggregory" due-to="Gary Gregory">Add StopWatch.getDuration() and deprecate getTime().</action> <!-- UPDATE --> </release> <release version="3.15.0" date="2024-07-13" description="New features and bug fixes (Java 8 or above)."> 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 433a54b08..57eac032f 100644 --- a/src/main/java/org/apache/commons/lang3/time/StopWatch.java +++ b/src/main/java/org/apache/commons/lang3/time/StopWatch.java @@ -271,6 +271,20 @@ public class StopWatch { return DurationFormatUtils.formatDurationHMS(getTime()); } + /** + * Gets the Duration on the StopWatch. + * + * <p> + * This is either the Duration between the start and the moment this method is called, or the Duration between start and stop. + * </p> + * + * @return the Duration. + * @since 3.16.0 + */ + public Duration getDuration() { + return Duration.ofNanos(getNanoTime()); + } + /** * Gets the message for string presentation. * @@ -394,7 +408,7 @@ public class StopWatch { * @since 3.16.0 */ public Instant getStopInstant() { - return Instant.ofEpochMilli(getStartTime()); + return Instant.ofEpochMilli(getStopTime()); } /** @@ -422,7 +436,9 @@ public class StopWatch { * </p> * * @return the time in milliseconds + * @deprecated Use {@link #getDuration()}. */ + @Deprecated public long getTime() { return nanosToMillis(getNanoTime()); } 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 dab6eccbb..fddf9fcc7 100644 --- a/src/test/java/org/apache/commons/lang3/time/StopWatchTest.java +++ b/src/test/java/org/apache/commons/lang3/time/StopWatchTest.java @@ -194,6 +194,16 @@ public class StopWatchTest extends AbstractLangTest { assertThat("formatTime", formatTime, not(startsWith(MESSAGE))); } + @Test + public void testGetDuration() throws InterruptedException { + final StopWatch watch = new StopWatch(); + assertEquals(Duration.ZERO, watch.getDuration()); + assertEquals(ZERO_TIME_ELAPSED, watch.toString()); + watch.start(); + sleep(MILLIS_550); + assertThat("watch.getDuration()", watch.getDuration().toMillis(), lessThan(2000L)); + } + @Test public void testGetSplitDuration() { // Create a mock StopWatch with a time of 2:59:01.999 @@ -234,16 +244,45 @@ public class StopWatchTest extends AbstractLangTest { assertThrows(IllegalStateException.class, watch::getStartTime, "Calling getStartTime on a reset, but unstarted StopWatch should throw an exception"); } + @Test + public void testGetTime() throws InterruptedException { + final StopWatch watch = new StopWatch(); + assertEquals(0, watch.getTime()); + assertEquals(ZERO_TIME_ELAPSED, watch.toString()); + watch.start(); + sleep(MILLIS_550); + assertThat("watch.getTime()", watch.getTime(), lessThan(2000L)); + } + + @Test + public void testGetWithTimeUnit() { + // Create a mock StopWatch with a time of 2:59:01.999 + // @formatter:off + final StopWatch watch = createMockStopWatch( + TimeUnit.HOURS.toNanos(2) + + TimeUnit.MINUTES.toNanos(59) + + TimeUnit.SECONDS.toNanos(1) + + TimeUnit.MILLISECONDS.toNanos(999)); + // @formatter:on + assertEquals(2L, watch.getTime(TimeUnit.HOURS)); + assertEquals(179L, watch.getTime(TimeUnit.MINUTES)); + assertEquals(10741L, watch.getTime(TimeUnit.SECONDS)); + assertEquals(10741999L, watch.getTime(TimeUnit.MILLISECONDS)); + } + @Test public void testLang315() throws InterruptedException { final StopWatch watch = StopWatch.createStarted(); sleep(MILLIS_200); watch.suspend(); final long suspendTime = watch.getTime(); + final Duration suspendDuration = watch.getDuration(); sleep(MILLIS_200); watch.stop(); final long totalTime = watch.getTime(); + final Duration totalDuration = watch.getDuration(); assertEquals(suspendTime, totalTime); + assertEquals(suspendDuration, totalDuration); } @Test @@ -258,80 +297,31 @@ public class StopWatchTest extends AbstractLangTest { } @Test - public void testStopInstantSimple() throws InterruptedException { - final StopWatch watch = StopWatch.createStarted(); - final long testStartMillis = System.currentTimeMillis(); - sleep(MILLIS_550); - watch.stop(); - final long testEndMillis = System.currentTimeMillis(); - final Instant stopTime = watch.getStopInstant(); - assertEquals(stopTime, watch.getStopInstant()); - assertThat("stopTime", stopTime, - allOf(greaterThanOrEqualTo(Instant.ofEpochMilli(testStartMillis)), lessThanOrEqualTo(Instant.ofEpochMilli(testEndMillis)))); - } - - @Test - public void testStopTimeSimple() throws InterruptedException { - final StopWatch watch = StopWatch.createStarted(); - final long testStartMillis = System.currentTimeMillis(); - sleep(MILLIS_550); - watch.stop(); - final long testEndMillis = System.currentTimeMillis(); - final long stopTime = watch.getStopTime(); - assertEquals(stopTime, watch.getStopTime()); - assertThat("stopTime", stopTime, allOf(greaterThanOrEqualTo(testStartMillis), lessThanOrEqualTo(testEndMillis))); - } - - @Test - public void testStopWatchGetWithTimeUnit() { - // Create a mock StopWatch with a time of 2:59:01.999 - // @formatter:off - final StopWatch watch = createMockStopWatch( - TimeUnit.HOURS.toNanos(2) - + TimeUnit.MINUTES.toNanos(59) - + TimeUnit.SECONDS.toNanos(1) - + TimeUnit.MILLISECONDS.toNanos(999)); - // @formatter:on - assertEquals(2L, watch.getTime(TimeUnit.HOURS)); - assertEquals(179L, watch.getTime(TimeUnit.MINUTES)); - assertEquals(10741L, watch.getTime(TimeUnit.SECONDS)); - assertEquals(10741999L, watch.getTime(TimeUnit.MILLISECONDS)); - } - - @Test - public void testStopWatchSimple() throws InterruptedException { + public void testSimple() throws InterruptedException { final StopWatch watch = StopWatch.createStarted(); sleep(MILLIS_550); watch.stop(); final long time = watch.getTime(); + final Duration duration = watch.getDuration(); assertEquals(time, watch.getTime()); - + assertEquals(duration, watch.getDuration()); assertThat("time", time, allOf(greaterThanOrEqualTo(500L), lessThan(2000L))); - + assertThat("duration", duration.toMillis(), allOf(greaterThanOrEqualTo(500L), lessThan(2000L))); watch.reset(); assertEquals(0, watch.getTime()); + assertEquals(Duration.ZERO, watch.getDuration()); } @Test - public void testStopWatchSimpleGet() throws InterruptedException { - final StopWatch watch = new StopWatch(); - assertEquals(0, watch.getTime()); - assertEquals(ZERO_TIME_ELAPSED, watch.toString()); - - watch.start(); - sleep(MILLIS_550); - assertThat("watch.getTime()", watch.getTime(), lessThan(2000L)); - } - - @Test - public void testStopWatchSplit() throws InterruptedException { + public void testSplit() throws InterruptedException { final StopWatch watch = StopWatch.createStarted(); sleep(MILLIS_550); // slept ~550 millis watch.split(); final long splitTime = watch.getSplitTime(); + final Duration splitDuration = watch.getSplitDuration(); assertEquals(splitTime, watch.getSplitDuration().toMillis()); - final String splitStr = watch.toSplitString(); + assertEquals(12, watch.toSplitString().length(), "Formatted split string not the correct length"); sleep(MILLIS_550); // slept ~1100 millis watch.unsplit(); @@ -339,46 +329,83 @@ public class StopWatchTest extends AbstractLangTest { // slept ~1650 millis watch.stop(); final long totalTime = watch.getTime(); - - assertEquals(12, splitStr.length(), "Formatted split string not the correct length"); + final Duration totalDuration = watch.getDuration(); assertThat("splitTime", splitTime, allOf(greaterThanOrEqualTo(500L), lessThan(1000L))); + assertThat("splitDuration", splitDuration.toMillis(), allOf(greaterThanOrEqualTo(500L), lessThan(1000L))); assertThat("totalTime", totalTime, allOf(greaterThanOrEqualTo(1500L), lessThan(2100L))); + assertThat("totalDuration", totalDuration.toMillis(), allOf(greaterThanOrEqualTo(1500L), lessThan(2100L))); } @Test - public void testStopWatchStatic() { + public void testStatic() { final StopWatch watch = StopWatch.createStarted(); assertTrue(watch.isStarted()); } @Test - public void testStopWatchSuspend() throws InterruptedException { + public void testStopInstantSimple() throws InterruptedException { + final StopWatch watch = StopWatch.createStarted(); + final long testStartMillis = System.currentTimeMillis(); + sleep(MILLIS_550); + watch.stop(); + final long testEndMillis = System.currentTimeMillis(); + final Instant stopTime = watch.getStopInstant(); + assertEquals(stopTime, watch.getStopInstant()); + assertThat("stopTime", stopTime, + allOf(greaterThanOrEqualTo(Instant.ofEpochMilli(testStartMillis)), lessThanOrEqualTo(Instant.ofEpochMilli(testEndMillis)))); + } + + @Test + public void testStopTimeSimple() throws InterruptedException { + final StopWatch watch = StopWatch.createStarted(); + final long testStartMillis = System.currentTimeMillis(); + sleep(MILLIS_550); + watch.stop(); + final long testEndMillis = System.currentTimeMillis(); + final long stopTime = watch.getStopTime(); + assertEquals(stopTime, watch.getStopTime()); + assertThat("stopTime", stopTime, allOf(greaterThanOrEqualTo(testStartMillis), lessThanOrEqualTo(testEndMillis))); + } + + @Test + public void testSuspend() throws InterruptedException { // Watch out comparing measurements from System.currentTimeMillis() vs. System.nanoTime() final StopWatch watch = StopWatch.createStarted(); final long testStartMillis = System.currentTimeMillis(); final long testStartNanos = System.nanoTime(); + final Instant testStartInstant = Instant.ofEpochMilli(testStartMillis); sleep(MILLIS_550); watch.suspend(); final long testSuspendMillis = System.currentTimeMillis(); final long testSuspendNanos = System.nanoTime(); final long testSuspendTimeNanos = testSuspendNanos - testStartNanos; + final Duration testSuspendDuration = Duration.ofNanos(testSuspendTimeNanos); final long suspendTimeFromNanos = watch.getTime(); + final Duration suspendDuration = watch.getDuration(); final long stopTimeMillis = watch.getStopTime(); + final Instant stopInstant = watch.getStopInstant(); assertThat("testStartMillis <= stopTimeMillis", testStartMillis, lessThanOrEqualTo(stopTimeMillis)); + assertThat("testStartInstant <= stopInstant", testStartInstant, lessThanOrEqualTo(stopInstant)); assertThat("testSuspendMillis <= stopTimeMillis", testSuspendMillis, lessThanOrEqualTo(stopTimeMillis)); + assertThat("testSuspendMillis <= stopInstant", testSuspendMillis, lessThanOrEqualTo(stopInstant.toEpochMilli())); sleep(MILLIS_550); watch.resume(); sleep(MILLIS_550); watch.stop(); final long totalTimeFromNanos = watch.getTime(); + final Duration totalDuration = watch.getDuration(); assertThat("suspendTimeFromNanos", suspendTimeFromNanos, greaterThanOrEqualTo(500L)); + assertThat("suspendDuration", suspendDuration, greaterThanOrEqualTo(Duration.ofMillis(500L))); assertThat("suspendTimeFromNanos <= testSuspendTimeNanos", suspendTimeFromNanos, lessThanOrEqualTo(testSuspendTimeNanos)); + assertThat("suspendDuration <= testSuspendDuration", suspendDuration, lessThanOrEqualTo(testSuspendDuration)); assertThat("totalTimeFromNanos", totalTimeFromNanos, greaterThanOrEqualTo(1000L)); + assertThat("totalDuration", totalDuration, greaterThanOrEqualTo(Duration.ofMillis(1000L))); // Be lenient for slow running builds assertThat("totalTimeFromNanos", totalTimeFromNanos, lessThan(2500L)); + assertThat("totalDuration", totalDuration, lessThan(Duration.ofMillis(2500L))); } @Test
