net.jperf

Class LoggingStopWatch

java.lang.Object

net.jperf.StopWatch

net.jperf.LoggingStopWatch

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

CommonsLogStopWatch, JavaLogStopWatch, Log4JStopWatch, Slf4JStopWatch

public class LoggingStopWatch
extends StopWatch

A LoggingStopWatch prevents the need to explicitly send the StopWatch string to a Logger when stopping. Instead, all of the stop() and lap() methods themselves are responsible for persisting the StopWatch:

 LoggingStopWatch stopWatch = new LoggingStopWatch();
 ...some code
 stopWatch.stop("codeBlock1"); //calling stop writes the StopWatch string to std err.
 

This class just writes all StopWatch messages to the standard error stream, but subclasses will use Loggers from various logging frameworks to persist the StopWatch.

Author:

Alex Devine

See Also:

Serialized Form

Field Summary

Fields inherited from class net.jperf.StopWatch

DEFAULT_LOGGER_NAME

Constructor Summary

Constructors

Constructor and Description
LoggingStopWatch() Creates a LoggingStopWatch with a blank tag, no message and started at the instant of creation.
LoggingStopWatch(long startTime, long elapsedTime, String tag, String message) Creates a LoggingStopWatch with a specified start and elapsed time, tag, and message.
LoggingStopWatch(String tag) Creates a LoggingStopWatch with the specified tag, no message and started at the instant of creation.
LoggingStopWatch(String tag, String message) Creates a LoggingStopWatch with the specified tag and message, started an the instant of creation.

Method Summary

Modifier and Type	Method and Description
LoggingStopWatch	clone()
String	getNormalSuffix() The suffix to append to the tag if normalAndSlowSuffixesEnabled=true and elapsedTime < timeThreshold and timeThreshold > 0.
String	getSlowSuffix() The suffix to append to the tag if normalAndSlowSuffixesEnabled=true and elapsedTime >= timeThreshold and timeThreshold > 0.
String	getTag() Gets the tag used to group this StopWatch instance with other instances used to time the same code block.
long	getTimeThreshold() Gets a threshold level, in milliseconds, below which logging calls will not be made.
boolean	isLogging() Determines whether or not logging is currently enabled for normal log messages for this StopWatch.
boolean	isNormalAndSlowSuffixesEnabled() Determines whether or not to append normalSuffix or slowSuffix to every tag logged by this stopwatch.
String	lap(String tag, String message, Throwable exception) Identical to StopWatch.lap(String, String), but also allows you to specify an exception to be logged.
String	lap(String tag, Throwable exception) Identical to StopWatch.lap(String), but also allows you to specify an exception to be logged.
protected void	log(String stopWatchAsString, Throwable exception) This log method can be overridden by subclasses in order to persist the StopWatch, for example by using a log4j Logger.
LoggingStopWatch	setMessage(String message) Sends a message on this StopWatch instance to be printed when this instance is logged.
LoggingStopWatch	setNormalAndSlowSuffixesEnabled(boolean normalAndSlowSuffixesEnabled) Sets whether to append normalSuffix and slowSuffix when timeThreshold > 0 AND elapsedTime >= timeThreshold
LoggingStopWatch	setNormalSuffix(String normalSuffix) Sets the suffix to use when normalAndSlowSuffixesEnabled=true and timeThreshold > 0 and elapsedTime < timeThreshold.
LoggingStopWatch	setSlowSuffix(String slowSuffix) Sets the suffix to use when normalAndSlowSuffixesEnabled=true and timeThreshold > 0 and elapsedTime >= timeThreshold.
LoggingStopWatch	setTag(String tag) Sets the grouping tag for this StopWatch instance.
LoggingStopWatch	setTimeThreshold(long timeThreshold) Sets a threshold level, in milliseconds, below which logging calls will not be made.
String	stop() This stop method is overridden to perform the logging itself instead of needing to make a separate call to persist the timing information.
String	stop(String tag, String message, Throwable exception) Identical to StopWatch.stop(String, String), but also allows you to specify an exception to be logged.
String	stop(String tag, Throwable exception) Identical to StopWatch.stop(String), but also allows you to specify an exception to be logged.
String	stop(Throwable exception) In cases where a code block terminated by throwing an exception, you may wish to have the exception logged in addition to the time it took to execute the block, in which case this method will write out the exception's stack trace in addition to the StopWatch timing method.

Methods inherited from class net.jperf.StopWatch

equals, getElapsedTime, getMessage, getStartTime, hashCode, lap, lap, start, start, start, stop, stop, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

LoggingStopWatch

public LoggingStopWatch()

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

LoggingStopWatch

public LoggingStopWatch(String tag)

Creates a LoggingStopWatch 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.

LoggingStopWatch

public LoggingStopWatch(String tag,
                        String message)

Creates a LoggingStopWatch 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 LoggingStopWatch.

LoggingStopWatch

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

Creates a LoggingStopWatch 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

getTimeThreshold

public long getTimeThreshold()

Gets a threshold level, in milliseconds, below which logging calls will not be made. Defaults to 0, meaning that the log method is always called on stop or lap regardless of the elapsed time.

Returns:

The time threshold in milliseconds.

setTimeThreshold

public LoggingStopWatch setTimeThreshold(long timeThreshold)

Sets a threshold level, in milliseconds, below which logging calls will not be made. You can set this to a high positive value if you only want logging to occur for abnormally slow execution times. Note, though, that you may wish to leave the threshold at 0 and attach a JmxAttributeStatisticsAppender in the logging configuration to be notified when times are outside acceptable thresholds.

Parameters:

timeThreshold - The minimum elapsed time, in milliseconds, below which log calls will not be made.

Returns:

this instance, for use with method chaining if desired

See Also:

JmxAttributeStatisticsAppender.getNotificationThresholds()

isNormalAndSlowSuffixesEnabled

public boolean isNormalAndSlowSuffixesEnabled()

Determines whether or not to append normalSuffix or slowSuffix to every tag logged by this stopwatch.

Returns:

whether or not to append normalSuffix or slowSuffix to every tag logged by this stopwatch.

setNormalAndSlowSuffixesEnabled

public LoggingStopWatch setNormalAndSlowSuffixesEnabled(boolean normalAndSlowSuffixesEnabled)

Sets whether to append normalSuffix and slowSuffix when timeThreshold > 0 AND elapsedTime >= timeThreshold

Parameters:

normalAndSlowSuffixesEnabled - true enables logging extra suffixes to normal and slow events; false (default) suppresses the suffixes

getNormalSuffix

public String getNormalSuffix()

The suffix to append to the tag if normalAndSlowSuffixesEnabled=true and elapsedTime < timeThreshold and timeThreshold > 0. Default is ".normal".

Returns:

the suffix to append if normalAndSlowSuffixesEnabled=true and the event was normal and under the threshold

setNormalSuffix

public LoggingStopWatch setNormalSuffix(String normalSuffix)

Sets the suffix to use when normalAndSlowSuffixesEnabled=true and timeThreshold > 0 and elapsedTime < timeThreshold. Setting this to "" is equivalent to setting to null.

Parameters:

normalSuffix - the suffix to append if normalAndSlowSuffixesEnabled and the elapsedtime is under the threshold

getSlowSuffix

public String getSlowSuffix()

The suffix to append to the tag if normalAndSlowSuffixesEnabled=true and elapsedTime >= timeThreshold and timeThreshold > 0. Default is ".slow"

Returns:

the suffix to append if normalAndSlowSuffixesEnabled=true and the event was slow and over the threshold.

setSlowSuffix

public LoggingStopWatch setSlowSuffix(String slowSuffix)

Sets the suffix to use when normalAndSlowSuffixesEnabled=true and timeThreshold > 0 and elapsedTime >= timeThreshold. Setting this to "" is equivalent to setting to null.

Parameters:

slowSuffix - the suffix to append if normalAndSlowSuffixesEnabled and the elapsedtime is under the threshold

getTag

public String getTag()

Description copied from class: StopWatch

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

Overrides:

getTag in class StopWatch

Returns:

The grouping tag.

setTag

public LoggingStopWatch setTag(String tag)

Description copied from class: StopWatch

Sets the grouping tag for this StopWatch instance.

Overrides:

setTag in class StopWatch

Parameters:

tag - The grouping tag.

Returns:

this instance, for method chaining if desired

setMessage

public LoggingStopWatch setMessage(String message)

Description copied from class: StopWatch

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

Overrides:

setMessage in class StopWatch

Parameters:

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

Returns:

this instance, for method chaining if desired.

stop

public String stop()

This stop method is overridden to perform the logging itself instead of needing to make a separate call to persist the timing information.

Overrides:

stop in class StopWatch

Returns:

this.toString(), however, this should not be passed to a logger as it will have already been logged.

stop

public String stop(Throwable exception)

In cases where a code block terminated by throwing an exception, you may wish to have the exception logged in addition to the time it took to execute the block, in which case this method will write out the exception's stack trace in addition to the StopWatch timing method.

Parameters:

exception - The exception that was thrown by the timed code block

Returns:

this.toString(), however, this should not be passed to a logger as it will have already been logged.

stop

public String stop(String tag,
                   Throwable exception)

Identical to StopWatch.stop(String), but also allows you to specify an exception to be logged.

Parameters:

tag - The grouping tag for this StopWatch

exception - The exception that was thrown by the timed code block

Returns:

this.toString(), however, this should not be passed to a logger as it will have already been logged.

stop

public String stop(String tag,
                   String message,
                   Throwable exception)

Identical to StopWatch.stop(String, String), but also allows you to specify an exception to be logged.

Parameters:

tag - The grouping tag for this StopWatch

message - A descriptive message about the timed block

exception - The exception that was thrown by the timed code block

Returns:

this.toString(), however, this should not be passed to a logger as it will have already been logged.

lap

public String lap(String tag,
                  Throwable exception)

Identical to StopWatch.lap(String), but also allows you to specify an exception to be logged.

Parameters:

tag - The grouping tag for the PREVIOUS code block that was timed.

exception - The exception that was thrown by the timed code block.

Returns:

this.toString(), however, this should not be passed to a logger as it will have already been logged.

lap

public String lap(String tag,
                  String message,
                  Throwable exception)

Identical to StopWatch.lap(String, String), but also allows you to specify an exception to be logged.

Parameters:

tag - The grouping tag for the PREVIOUS code block that was timed.

message - A descriptive message about the timed block

exception - The exception that was thrown by the timed code block

Returns:

this.toString(), however, this should not be passed to a logger as it will have already been logged.

isLogging

public boolean isLogging()

Determines whether or not logging is currently enabled for normal log messages for this StopWatch. This implementation always returns true, but subclasses should override this method if logging can be disabled. For example, a StopWatch that uses log4j Loggers will return false if the Logger is not currently enabled for the Level at which the log method is called.

Returns:

true if calls to one of the stop() or lap() methods that do NOT take an exception will result in the StopWatch being written to a persisting log.

log

protected void log(String stopWatchAsString,
                   Throwable exception)

This log method can be overridden by subclasses in order to persist the StopWatch, for example by using a log4j Logger. The default implementation here just writes the StopWatch to the standard error stream.

Parameters:

stopWatchAsString - The serialized StopWatch string

exception - An exception, if any, that was also passed to the stop() or lap() methods - may be null.

clone

public LoggingStopWatch clone()

Overrides:

clone in class StopWatch