org.perf4j.javalog
Class JavaLogStopWatch

java.lang.Object
  extended by org.perf4j.StopWatch
      extended by org.perf4j.LoggingStopWatch
          extended by org.perf4j.javalog.JavaLogStopWatch
All Implemented Interfaces:
Serializable, Cloneable

public class JavaLogStopWatch
extends LoggingStopWatch

This LoggingStopWatch uses a java.util.logging Logger to persist the StopWatch messages. The various constructors allow you to specify the Logger to use (defaults to org.perf4j.TimingLogger), the Level at which messages are normally logged (defaults to INFO) and the Level used for logging if one of the stop or lap methods that takes an exception is called (defaults to WARNING).

Author:
Alex Devine
See Also:
Serialized Form

Field Summary
 
Fields inherited from class org.perf4j.StopWatch
DEFAULT_LOGGER_NAME
 
Constructor Summary
JavaLogStopWatch()
          Creates a JavaLogStopWatch with a blank tag, no message and started at the instant of creation.
JavaLogStopWatch(Logger logger)
          Creates a JavaLogStopWatch with a blank tag, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the INFO level, or at the WARNING level if an exception is passed to one of the stop or lap methods.
JavaLogStopWatch(Logger logger, Level normalPriority)
          Creates a JavaLogStopWatch with a blank tag, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the WARNING level if an exception is passed to one of the stop or lap methods.
JavaLogStopWatch(Logger logger, Level normalPriority, Level exceptionPriority)
          Creates a JavaLogStopWatch with a blank tag, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the exceptionPriority level if an exception is passed to one of the stop or lap methods.
JavaLogStopWatch(long startTime, long elapsedTime, String tag, String message, Logger logger, Level normalPriority, Level exceptionPriority)
          This constructor is mainly used for creation of StopWatch instances from logs and for testing.
JavaLogStopWatch(String tag)
          Creates a JavaLogStopWatch with the tag specified, no message and started at the instant of creation.
JavaLogStopWatch(String tag, Logger logger)
          Creates a JavaLogStopWatch with the tag specified, no message and started at the instant of creation, using the specified Logger to log stop watch messages at INFO level, or at the WARNING level if an exception is passed to one of the stop or lap methods.
JavaLogStopWatch(String tag, Logger logger, Level normalPriority)
          Creates a JavaLogStopWatch with the tag specified, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the WARNING level if an exception is passed to one of the stop or lap methods.
JavaLogStopWatch(String tag, Logger logger, Level normalPriority, Level exceptionPriority)
          Creates a JavaLogStopWatch with the tag specified, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the exceptionPriority level if an exception is passed to one of the stop or lap methods.
JavaLogStopWatch(String tag, String message)
          Creates a JavaLogStopWatch with the tag and message specified and started at the instant of creation.
JavaLogStopWatch(String tag, String message, Logger logger)
          Creates a JavaLogStopWatch with the tag and message specified and started at the instant of creation, using the specified Logger to log stop watch messages at INFO level, or at WARNING level if an exception is passed to one of the stop or lap methods.
JavaLogStopWatch(String tag, String message, Logger logger, Level normalPriority)
          Creates a JavaLogStopWatch with the tag and message specified and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at WARNING level if an exception is passed to one of the stop or lap methods.
JavaLogStopWatch(String tag, String message, Logger logger, Level normalPriority, Level exceptionPriority)
          Creates a JavaLogStopWatch with the tag and message specified and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the exceptionPriority level if an exception is passed to one of the stop or lap methods.
 
Method Summary
 JavaLogStopWatch clone()
           
 Level getExceptionPriority()
          Gets the Level at which log statements will be made when one of the stop or lap methods that DOES take an exception is called.
 Logger getLogger()
          Gets the java.util.logging Logger that is used to persist logging statements when one of the stop or lap methods is called.
 Level getNormalPriority()
          Gets the Level at which log statements will be made when one of the stop or lap methods that does NOT take an exception is called.
 boolean isLogging()
          This method returns true if the logger it uses is enabled at the normalPriority level of this StopWatch.
protected  void log(String stopWatchAsString, Throwable exception)
          The log message is overridden to use the java.util.logging Logger to persist the stop watch.
static Level mapLevelName(String levelName)
          This utility method provides the standard mapping between log4j level names (which Perf4J uses as the standard set of possible levels) to the closest corresponding java.util.logging Level.
 JavaLogStopWatch setExceptionPriority(Level exceptionPriority)
          Sets the Level at which log statements will be made when one of the stop or lap methods that DOES take an exception is called.
 JavaLogStopWatch setLogger(Logger logger)
          Sets the java.util.logging Logger used to persist StopWatch instances.
 JavaLogStopWatch setMessage(String message)
          Sends a message on this StopWatch instance to be printed when this instance is logged.
 JavaLogStopWatch setNormalAndSlowSuffixesEnabled(boolean normalAndSlowSuffixesEnabled)
          Sets whether to append normalSuffix and slowSuffix when timeThreshold > 0 AND elapsedTime >= timeThreshold
 JavaLogStopWatch setNormalPriority(Level normalPriority)
          Sets the Level at which log statements will be made when one of the stop or lap methods that does NOT take an exception is called.
 JavaLogStopWatch setNormalSuffix(String normalSuffix)
          Sets the suffix to use when normalAndSlowSuffixesEnabled=true and timeThreshold > 0 and elapsedTime < timeThreshold.
 JavaLogStopWatch setSlowSuffix(String slowSuffix)
          Sets the suffix to use when normalAndSlowSuffixesEnabled=true and timeThreshold > 0 and elapsedTime >= timeThreshold.
 JavaLogStopWatch setTag(String tag)
          Sets the grouping tag for this StopWatch instance.
 JavaLogStopWatch setTimeThreshold(long timeThreshold)
          Sets a threshold level, in milliseconds, below which logging calls will not be made.
 
Methods inherited from class org.perf4j.LoggingStopWatch
getNormalSuffix, getSlowSuffix, getTag, getTimeThreshold, isNormalAndSlowSuffixesEnabled, lap, lap, stop, stop, stop, stop
 
Methods inherited from class org.perf4j.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

JavaLogStopWatch

public JavaLogStopWatch()
Creates a JavaLogStopWatch with a blank tag, no message and started at the instant of creation. The Logger with the name "org.perf4j.TimingLogger" is used to log stop watch messages at the INFO level, or at the WARNING level if an exception is passed to one of the stop or lap methods.


JavaLogStopWatch

public JavaLogStopWatch(Logger logger)
Creates a JavaLogStopWatch with a blank tag, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the INFO level, or at the WARNING level if an exception is passed to one of the stop or lap methods.

Parameters:
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.

JavaLogStopWatch

public JavaLogStopWatch(Logger logger,
                        Level normalPriority)
Creates a JavaLogStopWatch with a blank tag, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the WARNING level if an exception is passed to one of the stop or lap methods.

Parameters:
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.
normalPriority - The level at which this StopWatch is logged if one of the stop or lap methods that does NOT take an exception is called.

JavaLogStopWatch

public JavaLogStopWatch(Logger logger,
                        Level normalPriority,
                        Level exceptionPriority)
Creates a JavaLogStopWatch with a blank tag, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the exceptionPriority level if an exception is passed to one of the stop or lap methods.

Parameters:
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.
normalPriority - The level at which this StopWatch is logged if one of the stop or lap methods that does NOT take an exception is called.
exceptionPriority - The level at which this StopWatch is logged if one of the stop or lap methods that DOES take an exception is called.

JavaLogStopWatch

public JavaLogStopWatch(String tag)
Creates a JavaLogStopWatch with the tag specified, no message and started at the instant of creation. The Logger with the name "org.perf4j.TimingLogger" is used to log stop watch messages at the INFO level, or at the WARNING level if an exception is passed to one of the stop or lap methods.

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.

JavaLogStopWatch

public JavaLogStopWatch(String tag,
                        Logger logger)
Creates a JavaLogStopWatch with the tag specified, no message and started at the instant of creation, using the specified Logger to log stop watch messages at INFO level, or at the WARNING level if an exception is passed to one of the stop or lap methods.

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.
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.

JavaLogStopWatch

public JavaLogStopWatch(String tag,
                        Logger logger,
                        Level normalPriority)
Creates a JavaLogStopWatch with the tag specified, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the WARNING level if an exception is passed to one of the stop or lap methods.

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.
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.
normalPriority - The level at which this StopWatch is logged if one of the stop or lap methods that does NOT take an exception is called.

JavaLogStopWatch

public JavaLogStopWatch(String tag,
                        Logger logger,
                        Level normalPriority,
                        Level exceptionPriority)
Creates a JavaLogStopWatch with the tag specified, no message and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the exceptionPriority level if an exception is passed to one of the stop or lap methods.

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.
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.
normalPriority - The level at which this StopWatch is logged if one of the stop or lap methods that does NOT take an exception is called.
exceptionPriority - The level at which this StopWatch is logged if one of the stop or lap methods that DOES take an exception is called.

JavaLogStopWatch

public JavaLogStopWatch(String tag,
                        String message)
Creates a JavaLogStopWatch with the tag and message specified and started at the instant of creation. The Logger with the name "org.perf4j.TimingLogger" is used to log stop watch messages at the INFO level, or at the WARNING level if an exception is passed to one of the stop or lap methods.

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.

JavaLogStopWatch

public JavaLogStopWatch(String tag,
                        String message,
                        Logger logger)
Creates a JavaLogStopWatch with the tag and message specified and started at the instant of creation, using the specified Logger to log stop watch messages at INFO level, or at WARNING level if an exception is passed to one of the stop or lap methods.

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.
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.

JavaLogStopWatch

public JavaLogStopWatch(String tag,
                        String message,
                        Logger logger,
                        Level normalPriority)
Creates a JavaLogStopWatch with the tag and message specified and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at WARNING level if an exception is passed to one of the stop or lap methods.

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.
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.
normalPriority - The level at which this StopWatch is logged if one of the stop or lap methods that does NOT take an exception is called.

JavaLogStopWatch

public JavaLogStopWatch(String tag,
                        String message,
                        Logger logger,
                        Level normalPriority,
                        Level exceptionPriority)
Creates a JavaLogStopWatch with the tag and message specified and started at the instant of creation, using the specified Logger to log stop watch messages at the normalPriority level specified, or at the exceptionPriority level if an exception is passed to one of the stop or lap methods.

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.
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.
normalPriority - The level at which this StopWatch is logged if one of the stop or lap methods that does NOT take an exception is called.
exceptionPriority - The level at which this StopWatch is logged if one of the stop or lap methods that DOES take an exception is called.

JavaLogStopWatch

public JavaLogStopWatch(long startTime,
                        long elapsedTime,
                        String tag,
                        String message,
                        Logger logger,
                        Level normalPriority,
                        Level exceptionPriority)
This constructor is mainly used for creation of StopWatch instances from logs and for testing. Users should normally not call this constructor in client code.

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
logger - The Logger to use when persisting StopWatches in one of the stop or lap methods.
normalPriority - The level at which this StopWatch is logged if one of the stop or lap methods that does NOT take an exception is called.
exceptionPriority - The level at which this StopWatch is logged if one of the stop or lap methods that DOES take an exception is called.
Method Detail

getLogger

public Logger getLogger()
Gets the java.util.logging Logger that is used to persist logging statements when one of the stop or lap methods is called.

Returns:
The Logger used for StopWatch persistence.

setLogger

public JavaLogStopWatch setLogger(Logger logger)
Sets the java.util.logging Logger used to persist StopWatch instances.

Parameters:
logger - The Logger this instance should use for persistence. May not be null.
Returns:
this instance, for use with method chaining if desired

getNormalPriority

public Level getNormalPriority()
Gets the Level at which log statements will be made when one of the stop or lap methods that does NOT take an exception is called.

Returns:
The Level used when logging "normal" stop or lap calls.

setNormalPriority

public JavaLogStopWatch setNormalPriority(Level normalPriority)
Sets the Level at which log statements will be made when one of the stop or lap methods that does NOT take an exception is called.

Parameters:
normalPriority - The Level used when logging "normal" stop or lap calls. May not be null.
Returns:
this instance, for use with method chaining if desired

getExceptionPriority

public Level getExceptionPriority()
Gets the Level at which log statements will be made when one of the stop or lap methods that DOES take an exception is called.

Returns:
The Level used when logging "exception" stop or lap calls.

setExceptionPriority

public JavaLogStopWatch setExceptionPriority(Level exceptionPriority)
Sets the Level at which log statements will be made when one of the stop or lap methods that DOES take an exception is called. This should usually be at a level equal to or higher than the normal priority.

Parameters:
exceptionPriority - The Level used when logging "exceptional" stop or lap calls. May not be null.
Returns:
this instance, for use with method chaining if desired

setTimeThreshold

public JavaLogStopWatch setTimeThreshold(long timeThreshold)
Description copied from class: LoggingStopWatch
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.

Overrides:
setTimeThreshold in class LoggingStopWatch
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()

setTag

public JavaLogStopWatch setTag(String tag)
Description copied from class: StopWatch
Sets the grouping tag for this StopWatch instance.

Overrides:
setTag in class LoggingStopWatch
Parameters:
tag - The grouping tag.
Returns:
this instance, for method chaining if desired

setMessage

public JavaLogStopWatch 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 LoggingStopWatch
Parameters:
message - The message associated with this StopWatch, which may be null.
Returns:
this instance, for method chaining if desired.

setNormalAndSlowSuffixesEnabled

public JavaLogStopWatch setNormalAndSlowSuffixesEnabled(boolean normalAndSlowSuffixesEnabled)
Description copied from class: LoggingStopWatch
Sets whether to append normalSuffix and slowSuffix when timeThreshold > 0 AND elapsedTime >= timeThreshold

Overrides:
setNormalAndSlowSuffixesEnabled in class LoggingStopWatch
Parameters:
normalAndSlowSuffixesEnabled - true enables logging extra suffixes to normal and slow events; false (default) suppresses the suffixes

setNormalSuffix

public JavaLogStopWatch setNormalSuffix(String normalSuffix)
Description copied from class: LoggingStopWatch
Sets the suffix to use when normalAndSlowSuffixesEnabled=true and timeThreshold > 0 and elapsedTime < timeThreshold. Setting this to "" is equivalent to setting to null.

Overrides:
setNormalSuffix in class LoggingStopWatch
Parameters:
normalSuffix - the suffix to append if normalAndSlowSuffixesEnabled and the elapsedtime is under the threshold

setSlowSuffix

public JavaLogStopWatch setSlowSuffix(String slowSuffix)
Description copied from class: LoggingStopWatch
Sets the suffix to use when normalAndSlowSuffixesEnabled=true and timeThreshold > 0 and elapsedTime >= timeThreshold. Setting this to "" is equivalent to setting to null.

Overrides:
setSlowSuffix in class LoggingStopWatch
Parameters:
slowSuffix - the suffix to append if normalAndSlowSuffixesEnabled and the elapsedtime is under the threshold

isLogging

public boolean isLogging()
This method returns true if the logger it uses is enabled at the normalPriority level of this StopWatch.

Overrides:
isLogging in class LoggingStopWatch
Returns:
true if this StopWatch will output log messages when one of the stop or lap messages that does NOT take an exception is called.

log

protected void log(String stopWatchAsString,
                   Throwable exception)
The log message is overridden to use the java.util.logging Logger to persist the stop watch.

Overrides:
log in class LoggingStopWatch
Parameters:
stopWatchAsString - The stringified view of the stop watch for logging.
exception - An exception, if any, that was passed to the stop or lap method. If this is null then logging will occur at normalPriority, if non-null it will occur at exceptionPriority.

mapLevelName

public static Level mapLevelName(String levelName)
This utility method provides the standard mapping between log4j level names (which Perf4J uses as the standard set of possible levels) to the closest corresponding java.util.logging Level.

Parameters:
levelName - The name of the logging level, should be one of TRACE, DEBUG, INFO, WARN, ERROR or FATAL.
Returns:
The java.util.logging Level that is the closest match to the log4j Level name.

clone

public JavaLogStopWatch clone()
Overrides:
clone in class LoggingStopWatch


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