org.perf4j
Class LoggingStopWatch

java.lang.Object
  extended by org.perf4j.StopWatch
      extended by org.perf4j.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 org.perf4j.StopWatch
DEFAULT_LOGGER_NAME
 
Constructor Summary
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
 LoggingStopWatch clone()
           
 boolean isLogging()
          Determines whether or not logging is currently enabled for normal log messages for 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.
 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 org.perf4j.StopWatch
equals, getElapsedTime, getMessage, getStartTime, getTag, hashCode, lap, lap, setMessage, setTag, 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

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


Copyright © 2008-2009 perf4j.org. All Rights Reserved.