org.perf4j
Class StopWatch

java.lang.Object
  org.perf4j.StopWatch

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

LoggingStopWatch

public class StopWatch
extends Object
implements Serializable, Cloneable

The StopWatch class is used to time code blocks in Perf4J. The general usage pattern is to create a StopWatch before a section of code that is to be timed and then stop it before it is passed to a logging method:

 StopWatch stopWatch = new StopWatch();
 try {
     ...code being timed...
     log.info(stopWatch.stop("methodBeingTimed.success"));
 } catch (Exception e) {
     log.error(stopWatch.stop("methodBeingTimed.fail"), e);
 }
 

Note that a StopWatch is reusable. That is, you can call start() and stop() in succession and the getElapsedTime() method will refer to the time since the most recent start() call.

In general, most clients will find it simpler and cleaner to use the LoggingStopWatch class or one of its subclasses in preference to this class.

Author:

Alex Devine

See Also:

Serialized Form

Field Summary

static String

DEFAULT_LOGGER_NAME

Constructor Summary

StopWatch()
Creates a StopWatch with a blank tag, no message and started at the instant of creation.

StopWatch(long startTime, long elapsedTime, String tag, String message)
Creates a StopWatch with a specified start and elapsed time, tag, and message.

StopWatch(String tag)
Creates a StopWatch with the specified tag, no message and started at the instant of creation.

StopWatch(String tag, String message)
Creates a StopWatch with the specified tag and message, started an the instant of creation.

Method Summary

StopWatch	clone()
boolean	equals(Object o)
long	getElapsedTime() Gets the time in milliseconds between when this StopWatch was last started and stopped.
String	getMessage() Gets any additional message that was set on this StopWatch instance.
long	getStartTime() Gets the time when this instance was created, or when one of the start() messages was last called.
String	getTag() Gets the tag used to group this StopWatch instance with other instances used to time the same code block.
int	hashCode()
String	lap(String tag) The lap method is useful when using a single StopWatch to time multiple consecutive blocks.
String	lap(String tag, String message) The lap method is useful when using a single StopWatch to time multiple consecutive blocks.
void	setMessage(String message) Sends a message on this StopWatch instance to be printed when this instance is logged.
void	setTag(String tag) Sets the grouping tag for this StopWatch instance.
void	start() Starts this StopWatch, which sets its startTime property to the current time and resets the elapsedTime property.
void	start(String tag) Starts this StopWatch and sets its tag to the specified value.
void	start(String tag, String message) Starts this StopWatch and sets its tag and message to the specified values.
String	stop() Stops this StopWatch, which "freezes" its elapsed time.
String	stop(String tag) Stops this StopWatch and sets its grouping tag.
String	stop(String tag, String message) Stops this StopWatch and sets its grouping tag and message.
String	toString()

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_LOGGER_NAME

public static final String DEFAULT_LOGGER_NAME

See Also:

Constant Field Values

Constructor Detail

StopWatch

public StopWatch()

Creates a StopWatch with a blank tag, no message and started at the instant of creation.

StopWatch

public StopWatch(String tag)

Creates a StopWatch with the specified tag, no message and started at the instant of creation.

Parameters:

tag - The tag name for this timing call. Tags are used to group timing logs, thus each block of code being timed should have a unique tag. Note that tags can take a hierarchical format using dot notation.

StopWatch

public StopWatch(String tag,
                 String message)

Creates a StopWatch with the specified tag and message, started an the instant of creation.

Parameters:

tag - The tag name for this timing call. Tags are used to group timing logs, thus each block of code being timed should have a unique tag. Note that tags can take a hierarchical format using dot notation.

message - Additional text to be printed with the logging statement of this StopWatch.

StopWatch

public StopWatch(long startTime,
                 long elapsedTime,
                 String tag,
                 String message)

Creates a StopWatch with a specified start and elapsed time, tag, and message. This constructor should normally not be called by third party code; it is intended to allow for deserialization of StopWatch logs.

Parameters:

startTime - The start time in milliseconds

elapsedTime - The elapsed time in milliseconds

tag - The tag used to group timing logs of the same code block

message - Additional message text

Method Detail

getStartTime

public long getStartTime()

Gets the time when this instance was created, or when one of the start() messages was last called.

Returns:

The start time in milliseconds since the epoch.

getElapsedTime

public long getElapsedTime()

Gets the time in milliseconds between when this StopWatch was last started and stopped. Is stop() was not called, then the time returned is the time since the StopWatch was started.

Returns:

The elapsed time in milliseconds.

getTag

public String getTag()

Gets the tag used to group this StopWatch instance with other instances used to time the same code block.

Returns:

The grouping tag.

setTag

public void setTag(String tag)

Sets the grouping tag for this StopWatch instance.

Parameters:

tag - The grouping tag.

getMessage

public String getMessage()

Gets any additional message that was set on this StopWatch instance.

Returns:

The message associated with this StopWatch, which may be null.

setMessage

public void setMessage(String message)

Sends a message on this StopWatch instance to be printed when this instance is logged.

Parameters:

message - The message associated with this StopWatch, which may be null.

start

public void start()

Starts this StopWatch, which sets its startTime property to the current time and resets the elapsedTime property. For single-use StopWatch instance you should not need to call this method as a StopWatch is automatically started when it is created. Note any existing tag and message are not changed.

start

public void start(String tag)

Starts this StopWatch and sets its tag to the specified value. For single-use StopWatch instance you should not need to call this method as a StopWatch is automatically started when it is created. Note any existing message on this StopWatch is not changed.

Parameters:

tag - The grouping tag for this StopWatch

start

public void start(String tag,
                  String message)

Starts this StopWatch and sets its tag and message to the specified values. For single-use StopWatch instance you should not need to call this method as a StopWatch is automatically started when it is created.

Parameters:

tag - The grouping tag for this StopWatch

message - A descriptive message about the code being timed, may be null

stop

public String stop()

Stops this StopWatch, which "freezes" its elapsed time. You should normally call this method (or one of the other stop methods) before passing this instance to a logger.

Returns:

this.toString(), which is a message suitable for logging

stop

public String stop(String tag)

Stops this StopWatch and sets its grouping tag.

Parameters:

tag - The grouping tag for this StopWatch

Returns:

this.toString(), which is a message suitable for logging

stop

public String stop(String tag,
                   String message)

Stops this StopWatch and sets its grouping tag and message.

Parameters:

tag - The grouping tag for this StopWatch

message - A descriptive message about the code being timed, may be null

Returns:

this.toString(), which is a message suitable for logging

lap

public String lap(String tag)

The lap method is useful when using a single StopWatch to time multiple consecutive blocks. It calls stop() and then immediately calls start(), e.g.:

 StopWatch stopWatch = new StopWatch();
 ...some code
 log.info(stopWatch.lap("block1"));
 ...some more code
 log.info(stopWatch.lap("block2"));
 ...even more code
 log.info(stopWatch.stop("block3"));
 

Parameters:

tag - The grouping tag to use for the execution block that was just stopped.

Returns:

A message suitable for logging the previous execution block's execution time.

lap

public String lap(String tag,
                  String message)

The lap method is useful when using a single StopWatch to time multiple consecutive blocks. It calls stop() and then immediately calls start(), e.g.:

 StopWatch stopWatch = new StopWatch();
 ...some code
 log.info(stopWatch.lap("block1", "message about block 1"));
 ...some more code
 log.info(stopWatch.lap("block2", "message about block 2"));
 ...even more code
 log.info(stopWatch.stop("block3", "message about block 3"));
 

Parameters:

tag - The grouping tag to use for the execution block that was just stopped.

message - A descriptive message about the code being timed, may be null

Returns:

A message suitable for logging the previous execution block's execution time.

toString

public String toString()

Overrides:

toString in class Object

clone

public StopWatch clone()

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object