Class StopWatch
StopWatch
provides a convenient API for timings.
To start the watch, call start()
or createStarted()
. 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()
and getTime()
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:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static enum
Enumeration type which indicates the split status of a StopWatch.private static enum
Enumeration type which indicates the status of a StopWatch. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final String
A message for string presentation.private static final long
private StopWatch.State
The current running state of the StopWatch.private StopWatch.SplitState
Whether the StopWatch has a split time recorded.private Instant
The start Instant.private long
The start time in nanoseconds.private Instant
The end Instant.private long
The stop time in nanoseconds. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic StopWatch
create()
Creates a StopWatch.static StopWatch
Creates and starts a StopWatch.Formats the split time withDurationFormatUtils.formatDurationHMS(long)
.Formats the time formatted withDurationFormatUtils.formatDurationHMS(long)
.Gets the Duration on the StopWatch.Gets the message for string presentation.long
Gets the elapsed time in nanoseconds.Gets the split Duration on the StopWatch.long
Gets the split time in nanoseconds.long
Deprecated.Gets the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.long
Deprecated.UsegetStartInstant()
.Gets the Instant this StopWatch was stopped, between the current time and midnight, January 1, 1970 UTC.long
Deprecated.UsegetStopInstant()
.long
getTime()
Deprecated.UsegetDuration()
.long
Gets the time in the specified TimeUnit.boolean
Tests whether the StopWatch is started.boolean
Tests whether StopWatch is stopped.boolean
Tests whether the StopWatch is suspended.private long
nanosToMillis
(long nanos) Converts nanoseconds to milliseconds.void
reset()
Resets the StopWatch.void
resume()
Resumes the StopWatch after a suspend.void
split()
Splits the time.void
start()
Starts the StopWatch.void
stop()
Stops the StopWatch.void
suspend()
Suspends the StopWatch for later resumption.Gets a summary of the split time that the StopWatch recorded as a string.toString()
Gets a summary of the time that the StopWatch recorded as a string.void
unsplit()
Removes a split.
-
Field Details
-
NANO_2_MILLIS
private static final long NANO_2_MILLIS- See Also:
-
message
A message for string presentation.- Since:
- 3.10
-
runningState
The current running state of the StopWatch. -
splitState
Whether the StopWatch has a split time recorded. -
startTimeNanos
private long startTimeNanosThe start time in nanoseconds. This field can be removed once we move off of Java 8. -
startInstant
The start Instant.nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.
On Java 8, Instant has millisecond precision, only later versions use nanoseconds.
-
stopInstant
The end Instant.nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.
On Java 8, Instant has millisecond precision, only later versions use nanoseconds.
-
stopTimeNanos
private long stopTimeNanosThe stop time in nanoseconds. This field can be removed once we move off of Java 8.
-
-
Constructor Details
-
StopWatch
public StopWatch()Constructs a new instance. -
StopWatch
Constructs a new instance.- Parameters:
message
- A message for string presentation.- Since:
- 3.10
-
-
Method Details
-
create
Creates a StopWatch.- Returns:
- StopWatch a StopWatch.
- Since:
- 3.10
-
createStarted
Creates and starts a StopWatch.- Returns:
- StopWatch a started StopWatch.
- Since:
- 3.5
-
formatSplitTime
Formats the split time withDurationFormatUtils.formatDurationHMS(long)
.- Returns:
- the split time formatted by
DurationFormatUtils.formatDurationHMS(long)
. - Since:
- 3.10
-
formatTime
Formats the time formatted withDurationFormatUtils.formatDurationHMS(long)
.- Returns:
- the time formatted by
DurationFormatUtils.formatDurationHMS(long)
. - Since:
- 3.10
-
getDuration
Gets the Duration on the 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
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:
-
getSplitDuration
Gets the split Duration on the StopWatch.This is the Duration between start and latest split.
- Returns:
- the split Duration
- Throws:
IllegalStateException
- if the 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:
IllegalStateException
- if the StopWatch has not yet been split.- Since:
- 3.0
-
getSplitTime
Deprecated.UsegetSplitDuration()
.Gets the split time on the StopWatch.This is the time between start and latest split.
- Returns:
- the split time in milliseconds
- Throws:
IllegalStateException
- if the StopWatch has not yet been split.- Since:
- 2.1
-
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:
IllegalStateException
- if this StopWatch has not been started- Since:
- 3.16.0
-
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:
IllegalStateException
- if this StopWatch has not been started- Since:
- 2.4
-
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:
IllegalStateException
- if this StopWatch has not been started- Since:
- 3.16.0
-
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:
IllegalStateException
- if this StopWatch has not been started- Since:
- 3.12.0
-
getTime
Deprecated.UsegetDuration()
.Gets the time on the 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
-
getTime
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 the 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 the StopWatch is started. A suspended StopWatch is also started watch.- Returns:
- boolean If the StopWatch is started.
- Since:
- 3.2
-
isStopped
public boolean isStopped()Tests whether StopWatch is stopped. The StopWatch which's not yet started and explicitly stopped StopWatch is considered as stopped.- Returns:
- boolean If the StopWatch is stopped.
- Since:
- 3.2
-
isSuspended
public boolean isSuspended()Tests whether the StopWatch is suspended.- Returns:
- boolean If the StopWatch is suspended.
- Since:
- 3.2
-
nanosToMillis
private long nanosToMillis(long nanos) Converts nanoseconds to milliseconds.- Parameters:
nanos
- nanoseconds to convert.- Returns:
- milliseconds conversion result.
-
reset
public void reset()Resets the StopWatch. Stops it if need be.This method clears the internal values to allow the object to be reused.
-
resume
public void resume()Resumes the 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:
IllegalStateException
- if the StopWatch has not been suspended.
-
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:
IllegalStateException
- if the StopWatch is not running.
-
start
public void start()Starts the StopWatch.This method starts a new timing session, clearing any previous values.
- Throws:
IllegalStateException
- if the StopWatch is already running.
-
stop
public void stop()Stops the StopWatch.This method ends a new timing session, allowing the time to be retrieved.
- Throws:
IllegalStateException
- if the StopWatch is not running.
-
suspend
public void suspend()Suspends the 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:
IllegalStateException
- if the StopWatch is not currently running.
-
toSplitString
Gets a summary of the split time that the 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
Gets a summary of the time that the StopWatch recorded as a string.The format used is ISO 8601-like, [message ]hours:minutes:seconds.milliseconds.
-
unsplit
public void unsplit()Removes a split.This method clears the stop time. The start time is unaffected, enabling timing from the original start point to continue.
- Throws:
IllegalStateException
- if the StopWatch has not been split.
-
getSplitDuration()
.