Package org.apache.commons.lang3.time

Class StopWatch

java.lang.Object
org.apache.commons.lang3.time.StopWatch
public class StopWatch extends Object
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.

  1. split(), suspend(), or stop() cannot be invoked twice
  2. unsplit() may only be called if the watch has been split()
  3. resume() may only be called if the watch has been suspend()
  4. start() cannot be called twice without calling reset()

This class is not thread-safe

Since:
2.0
See Also:

  • Constructor Details

    • StopWatch

      public StopWatch()
      Constructs a new instance.

    • StopWatch

      public StopWatch(String message)
      Constructs a new instance.
      Parameters:
      message - A message for string presentation.
      Since:
      3.10

  • Method Details

    • 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 String formatSplitTime()
      Formats the split time with DurationFormatUtils.formatDurationHMS(long).
      Returns:
      the split time formatted by DurationFormatUtils.formatDurationHMS(long).
      Since:
      3.10

    • formatTime

      public String formatTime()
      Formats the time formatted with DurationFormatUtils.formatDurationHMS(long).
      Returns:
      the time formatted by DurationFormatUtils.formatDurationHMS(long).
      Since:
      3.10

    • getDuration

      public Duration 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

      public 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:

    • getSplitDuration

      public Duration 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 public long getSplitTime()
      Deprecated.
      Use getSplitDuration().
      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

      public 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:
      IllegalStateException - if this StopWatch has not been started
      Since:
      3.16.0

    • getStartTime

      @Deprecated public long getStartTime()
      Deprecated.
      Use getStartInstant().
      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

      public 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:
      IllegalStateException - if this StopWatch has not been started
      Since:
      3.16.0

    • getStopTime

      @Deprecated public long getStopTime()
      Deprecated.
      Use getStopInstant().
      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 public long getTime()
      Deprecated.
      Use getDuration().
      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

      public long getTime(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 the StopWatch time is 59 minutes, then the result returned will be 0.

      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

    • 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

      public String 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

      public String 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.

      Overrides:
      toString in class Object
      Returns:
      the time as a String
      Since:
      3.10 Returns the prefix "message " if the message is set.

    • 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.