Class StopWatch
- java.lang.Object
-
- org.apache.commons.lang3.time.StopWatch
-
public class StopWatch extends java.lang.Object
StopWatch
provides a convenient API for timings.To start the watch, call
start()
orcreateStarted()
. At this point you can:split()
the watch to get the time whilst the watch continues in the background.unsplit()
will remove the effect of the split. At this point, these three options are available again.suspend()
the watch to pause it.resume()
allows the watch to continue. Any time between the suspend and resume will not be counted in the total. At this point, these three options are available again.stop()
the watch to complete the timing session.
It is intended that the output methods
toString()
andgetTime()
should only be called after stop, split or suspend, however a suitable result will be returned at other points.NOTE: As from v2.1, the methods protect against inappropriate calls. Thus you cannot now call stop before start, resume before suspend or unsplit before split.
split()
,suspend()
, orstop()
cannot be invoked twiceunsplit()
may only be called if the watch has beensplit()
resume()
may only be called if the watch has beensuspend()
start()
cannot be called twice without callingreset()
This class is not thread-safe
- Since:
- 2.0
- See Also:
DurationUtils.of(FailableRunnable)
,DurationUtils.of(FailableConsumer)
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static StopWatch
create()
Creates a StopWatch.static StopWatch
createStarted()
Creates and starts a StopWatch.java.lang.String
formatSplitTime()
Formats the split time withDurationFormatUtils.formatDurationHMS(long)
.java.lang.String
formatTime()
Formats the time formatted withDurationFormatUtils.formatDurationHMS(long)
.<T> T
get(java.util.function.Supplier<T> supplier)
Delegates toSupplier.get()
while recording the duration of the call.java.time.Duration
getDuration()
Gets the Duration on this StopWatch.java.lang.String
getMessage()
Gets the message for string presentation.long
getNanoTime()
Gets the elapsed time in nanoseconds.java.time.Duration
getSplitDuration()
Gets the split Duration on this StopWatch.long
getSplitNanoTime()
Gets the split time in nanoseconds.long
getSplitTime()
Deprecated.UsegetSplitDuration()
.java.time.Instant
getStartInstant()
Gets the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.long
getStartTime()
Deprecated.UsegetStartInstant()
.java.time.Instant
getStopInstant()
Gets the Instant this StopWatch was stopped, between the current time and midnight, January 1, 1970 UTC.long
getStopTime()
Deprecated.UsegetStopInstant()
.<T,E extends java.lang.Throwable>
TgetT(FailableSupplier<T,E> supplier)
Delegates toFailableSupplier.get()
while recording the duration of the call.long
getTime()
Gets the time on this StopWatch.long
getTime(java.util.concurrent.TimeUnit timeUnit)
Gets the time in the specified TimeUnit.boolean
isStarted()
Tests whether this StopWatch is started.boolean
isStopped()
Tests whether StopWatch is stopped.boolean
isSuspended()
Tests whether this StopWatch is suspended.void
reset()
Resets this StopWatch.void
resume()
Resumes this StopWatch after a suspend.void
run(java.lang.Runnable runnable)
Delegates toRunnable.run()
while recording the duration of the call.<E extends java.lang.Throwable>
voidrunT(FailableRunnable<E> runnable)
Delegates toFailableRunnable.run()
while recording the duration of the call.void
split()
Splits the time.void
start()
Starts this StopWatch.void
stop()
Stops this StopWatch.void
suspend()
Suspends this StopWatch for later resumption.java.lang.String
toSplitString()
Gets a summary of the split time that this StopWatch recorded as a string.java.lang.String
toString()
Gets a summary of the time that this StopWatch recorded as a string.void
unsplit()
Removes the split.
-
-
-
Method Detail
-
create
public static StopWatch create()
Creates a StopWatch.- Returns:
- StopWatch a StopWatch.
- Since:
- 3.10
-
createStarted
public static StopWatch createStarted()
Creates and starts a StopWatch.- Returns:
- StopWatch a started StopWatch.
- Since:
- 3.5
-
formatSplitTime
public java.lang.String formatSplitTime()
Formats the split time withDurationFormatUtils.formatDurationHMS(long)
.- Returns:
- the split time formatted by
DurationFormatUtils.formatDurationHMS(long)
. - Since:
- 3.10
-
formatTime
public java.lang.String formatTime()
Formats the time formatted withDurationFormatUtils.formatDurationHMS(long)
.- Returns:
- the time formatted by
DurationFormatUtils.formatDurationHMS(long)
. - Since:
- 3.10
-
get
public <T> T get(java.util.function.Supplier<T> supplier)
Delegates toSupplier.get()
while recording the duration of the call.- Type Parameters:
T
- the type of results supplied by this supplier.- Parameters:
supplier
- The supplier toSupplier.get()
.- Returns:
- a result from the given Supplier.
- Since:
- 3.18.0
-
getDuration
public java.time.Duration getDuration()
Gets the Duration on this StopWatch.This is either the Duration between the start and the moment this method is called, or the Duration between start and stop.
- Returns:
- the Duration.
- Since:
- 3.16.0
-
getMessage
public java.lang.String getMessage()
Gets the message for string presentation.- Returns:
- the message for string presentation.
- Since:
- 3.10
-
getNanoTime
public long getNanoTime()
Gets the elapsed time in nanoseconds.This is either the time between the start and the moment this method is called, or the amount of time between start and stop.
- Returns:
- the elapsed time in nanoseconds.
- Since:
- 3.0
- See Also:
System.nanoTime()
-
getSplitDuration
public java.time.Duration getSplitDuration()
Gets the split Duration on this StopWatch.This is the Duration between start and latest split.
- Returns:
- the split Duration
- Throws:
java.lang.IllegalStateException
- if this StopWatch has not yet been split.- Since:
- 3.16.0
-
getSplitNanoTime
public long getSplitNanoTime()
Gets the split time in nanoseconds.This is the time between start and latest split.
- Returns:
- the split time in nanoseconds
- Throws:
java.lang.IllegalStateException
- if this StopWatch has not yet been split.- Since:
- 3.0
-
getSplitTime
@Deprecated public long getSplitTime()
Deprecated.UsegetSplitDuration()
.Gets the split time on this StopWatch.This is the time between start and latest split.
- Returns:
- the split time in milliseconds
- Throws:
java.lang.IllegalStateException
- if this StopWatch has not yet been split.- Since:
- 2.1
-
getStartInstant
public java.time.Instant getStartInstant()
Gets the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.- Returns:
- the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
- Throws:
java.lang.IllegalStateException
- if this StopWatch has not been started- Since:
- 3.16.0
-
getStartTime
@Deprecated public long getStartTime()
Deprecated.UsegetStartInstant()
.Gets the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.- Returns:
- the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.
- Throws:
java.lang.IllegalStateException
- if this StopWatch has not been started- Since:
- 2.4
-
getStopInstant
public java.time.Instant getStopInstant()
Gets the Instant this StopWatch was stopped, between the current time and midnight, January 1, 1970 UTC.- Returns:
- the Instant this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
- Throws:
java.lang.IllegalStateException
- if this StopWatch has not been started- Since:
- 3.16.0
-
getStopTime
@Deprecated public long getStopTime()
Deprecated.UsegetStopInstant()
.Gets the time this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.- Returns:
- the time this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
- Throws:
java.lang.IllegalStateException
- if this StopWatch has not been started- Since:
- 3.12.0
-
getT
public <T,E extends java.lang.Throwable> T getT(FailableSupplier<T,E> supplier) throws java.lang.Throwable
Delegates toFailableSupplier.get()
while recording the duration of the call.- Type Parameters:
T
- the type of results supplied by this supplier.E
- The kind of thrown exception or error.- Parameters:
supplier
- The supplier toSupplier.get()
.- Returns:
- a result from the given Supplier.
- Throws:
java.lang.Throwable
- if the supplier fails.- Since:
- 3.18.0
-
getTime
public long getTime()
Gets the time on this StopWatch.This is either the time between the start and the moment this method is called, or the amount of time between start and stop.
- Returns:
- the time in milliseconds
- See Also:
getDuration()
-
getTime
public long getTime(java.util.concurrent.TimeUnit timeUnit)
Gets the time in the specified TimeUnit.This is either the time between the start and the moment this method is called, or the amount of time between start and stop. The resulting time will be expressed in the desired TimeUnit with any remainder rounded down. For example, if the specified unit is
TimeUnit.HOURS
and this StopWatch time is 59 minutes, then the result returned will be0
.- Parameters:
timeUnit
- the unit of time, not null- Returns:
- the time in the specified TimeUnit, rounded down
- Since:
- 3.5
-
isStarted
public boolean isStarted()
Tests whether this StopWatch is started. A suspended StopWatch is also started watch.- Returns:
- boolean If this StopWatch is started.
- Since:
- 3.2
-
isStopped
public boolean isStopped()
Tests whether StopWatch is stopped. this StopWatch which's not yet started and explicitly stopped StopWatch is considered as stopped.- Returns:
- boolean If this StopWatch is stopped.
- Since:
- 3.2
-
isSuspended
public boolean isSuspended()
Tests whether this StopWatch is suspended.- Returns:
- boolean If this StopWatch is suspended.
- Since:
- 3.2
-
reset
public void reset()
Resets this StopWatch. Stops it if need be.This method clears the internal values to allow the object to be reused.
-
resume
public void resume()
Resumes this StopWatch after a suspend.This method resumes the watch after it was suspended. The watch will not include time between the suspend and resume calls in the total time.
- Throws:
java.lang.IllegalStateException
- if this StopWatch has not been suspended.
-
run
public void run(java.lang.Runnable runnable)
Delegates toRunnable.run()
while recording the duration of the call.- Parameters:
runnable
- The runnable toRunnable.run()
.- Since:
- 3.18.0
-
runT
public <E extends java.lang.Throwable> void runT(FailableRunnable<E> runnable) throws java.lang.Throwable
Delegates toFailableRunnable.run()
while recording the duration of the call.- Type Parameters:
E
- The kind ofThrowable
.- Parameters:
runnable
- The runnable toFailableRunnable.run()
.- Throws:
java.lang.Throwable
- Thrown byFailableRunnable.run()
.- Since:
- 3.18.0
-
split
public void split()
Splits the time.This method sets the stop time of the watch to allow a time to be extracted. The start time is unaffected, enabling
unsplit()
to continue the timing from the original start point.- Throws:
java.lang.IllegalStateException
- if this StopWatch is not running.
-
start
public void start()
Starts this StopWatch.This method starts a new timing session, clearing any previous values.
- Throws:
java.lang.IllegalStateException
- if this StopWatch is already running.
-
stop
public void stop()
Stops this StopWatch.This method ends a new timing session, allowing the time to be retrieved.
- Throws:
java.lang.IllegalStateException
- if this StopWatch is not running.
-
suspend
public void suspend()
Suspends this StopWatch for later resumption.This method suspends the watch until it is resumed. The watch will not include time between the suspend and resume calls in the total time.
- Throws:
java.lang.IllegalStateException
- if this StopWatch is not currently running.
-
toSplitString
public java.lang.String toSplitString()
Gets a summary of the split time that this StopWatch recorded as a string.The format used is ISO 8601-like, [message ]hours:minutes:seconds.milliseconds.
- Returns:
- the split time as a String
- Since:
- 2.1, 3.10 Returns the prefix
"message "
if the message is set.
-
toString
public java.lang.String toString()
Gets a summary of the time that this StopWatch recorded as a string.The format used is ISO 8601-like, [message ]hours:minutes:seconds.milliseconds.
- Overrides:
toString
in classjava.lang.Object
- Returns:
- the time as a String
- Since:
- 3.10 Returns the prefix
"message "
if the message is set.
-
unsplit
public void unsplit()
Removes the split.This method clears the stop time. The start time is unaffected, enabling timing from the original start point to continue.
- Throws:
java.lang.IllegalStateException
- if this StopWatch has not been split.
-
-