org.javasimon.utils

Class SimonUtils

java.lang.Object

org.javasimon.utils.SimonUtils

public final class SimonUtils
extends Object

SimonUtils provides static utility methods.

Human readable outputs

Both Stopwatch and Counter provide human readable toString outputs. All nanosecond values are converted into few valid digits with proper unit (ns, us, ms, s) - this is done via method presentNanoTime(long). Max/min counter values are checked for undefined state (max/min long value is converted to string "undef") - via method presentMinMaxCount(long).

Aggregation utilities

It is possible to sum up (aggregate) values for a subtree for a particular Simon type using calculateCounterAggregate(org.javasimon.Simon) or calculateStopwatchAggregate(org.javasimon.Simon). Methods come also in versions allowing to filter by SimonFilter.

Simon tree operations

For various debug purposes there is a method that creates string displaying the whole Simon sub-tree. Here is example code that initializes two random Simons and prints the whole Simon hierarchy (note that the method can be used to obtain any sub-tree of the hierarchy):

 Split split = SimonManager.getStopwatch("com.my.other.stopwatch").start();
 SimonManager.getCounter("com.my.counter").setState(SimonState.DISABLED, false);
 split.stop();
 System.out.println(SimonUtils.simonTreeString(SimonManager.getRootSimon()));

And the output is:

 (+): Unknown Simon:  [ ENABLED]
   com(+): Unknown Simon:  [com INHERIT]
     my(+): Unknown Simon:  [com.my INHERIT]
       other(+): Unknown Simon:  [com.my.other INHERIT]
         stopwatch(+): Simon Stopwatch: total 24.2 ms, counter 1, max 24.2 ms, min 24.2 ms, mean 24.2 ms [com.my.other.stopwatch INHERIT]
       counter(-): Simon Counter: counter=0, max=undef, min=undef [com.my.counter DISABLED]

Notice +/- signs in parenthesis that displays effective Simon state (enabled/disabled), further details are printed via each Simon's toString method.

Other utilities

It is possible to obtain "local name" of the Simon (behind the last dot) via localName(String) or check if the name is valid Simon name via checkName(String).

Since:

1.0

Author:

Richard "Virgo" Richter, Radovan Sninsky

Field Summary

Fields

Modifier and Type	Field and Description
static String	ALLOWED_CHARS Allowed Simon name characters.
static String	MANAGER_SERVLET_CTX_ATTRIBUTE Name of the attribute where manager is searched for in an appropriate context - used for Spring/JavaEE/console integration.
static Pattern	NAME_PATTERN Regex pattern for Simon names.
static String	NAME_PATTERN_CHAR_CLASS_CONTENT Regex character class content for NAME_PATTERN.

Method Summary

Methods

Modifier and Type	Method and Description
static CounterAggregate	calculateCounterAggregate(Simon simon) Aggregate statistics from all counters in hierarchy of simons.
static CounterAggregate	calculateCounterAggregate(Simon simon, SimonFilter filter) Aggregate statistics from all counters in hierarchy that pass specified filter.
static StopwatchAggregate	calculateStopwatchAggregate(Simon simon) Aggregate statistics from all stopwatches in hierarchy of simons.
static StopwatchAggregate	calculateStopwatchAggregate(Simon simon, SimonFilter filter) Aggregate statistics from all stopwatches in hierarchy that pass specified filter.
static boolean	checkName(String name) Checks if the input string is correct Simon name.
static String	compact(String input, int limitTo) Shrinks the middle of the input string if it is too long, so it does not exceed limitTo.
static <T> T	doWithStopwatch(String name, Callable<T> callable) Calls a block of code with stopwatch around and returns result.
static void	doWithStopwatch(String name, Runnable runnable) Calls a block of code with stopwatch around, can not return any result or throw an exception (use doWithStopwatch(String, java.util.concurrent.Callable) instead).
static String	generateName() Autogenerates name for the Simon using the class name and the method name.
static String	generateNameForClass(String suffix) Autogenerates name for the Simon using the fully-qualified class name.
static String	generateNameForClassAndMethod(String suffix) Autogenerates name for the Simon using the fully qualified class name and the method name.
static String	localName(String name) Returns last part of Simon name - local name.
static String	presentMinMaxCount(long minmax) Returns min/max counter values in human readable form - if the value is max or min long value it is considered unused and string "undef" is returned.
static String	presentNanoTime(double nanos) Returns nano-time in human readable form with unit.
static String	presentNanoTime(long nanos) Returns nano-time in human readable form with unit.
static String	presentTimestamp(long timestamp) Returns timestamp in human readable (yet condensed) form "yyMMdd-HHmmss.SSS".
static String	simonTreeString(Simon simon) Returns multi-line string containing Simon tree starting with the specified Simon.
static void	validateSimonName(String name) Checks if the input string is correct Simon name and throws SimonException otherwise.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NAME_PATTERN_CHAR_CLASS_CONTENT

public static final String NAME_PATTERN_CHAR_CLASS_CONTENT

Regex character class content for NAME_PATTERN.

See Also:

Constant Field Values

NAME_PATTERN

public static final Pattern NAME_PATTERN

Regex pattern for Simon names.

ALLOWED_CHARS

public static final String ALLOWED_CHARS

Allowed Simon name characters.

Since:

2.3

See Also:

Constant Field Values

MANAGER_SERVLET_CTX_ATTRIBUTE

public static final String MANAGER_SERVLET_CTX_ATTRIBUTE

Name of the attribute where manager is searched for in an appropriate context - used for Spring/JavaEE/console integration. While the name can be used in any context supporting named attributes, it is primarily aimed for ServletContext. Manager can be shared in ServletContext by SimonWebConfigurationBean (Spring module) and then picked up by SimonServletFilter (JavaEE module) and SimonConsoleFilter (Embeddable console). If no manager is found in the attribute of the context, it is expected that components will use default SimonManager instead.

Since:

3.2

See Also:

Constant Field Values

Method Detail

presentNanoTime

public static String presentNanoTime(long nanos)

Returns nano-time in human readable form with unit. Number is always from 10 to 9999 except for seconds that are the biggest unit used. In case of undefined value (Long.MAX_VALUE or Long.MIN_VALUE) string UNDEF_STRING is returned, so it can be used for min/max values as well.

Parameters:

nanos - time in nanoseconds

Returns:

human readable time string

presentNanoTime

public static String presentNanoTime(double nanos)

Returns nano-time in human readable form with unit. Number is always from 10 to 9999 except for seconds that are the biggest unit used.

Parameters:

nanos - time in nanoseconds

Returns:

human readable time string

presentTimestamp

public static String presentTimestamp(long timestamp)

Returns timestamp in human readable (yet condensed) form "yyMMdd-HHmmss.SSS".

Parameters:

timestamp - timestamp in millis

Returns:

timestamp as a human readable string

presentMinMaxCount

public static String presentMinMaxCount(long minmax)

Returns min/max counter values in human readable form - if the value is max or min long value it is considered unused and string "undef" is returned.

Parameters:

minmax - counter extreme value

Returns:

counter value or "undef" if counter contains Long.MIN_VALUE or Long.MAX_VALUE

simonTreeString

public static String simonTreeString(Simon simon)

Returns multi-line string containing Simon tree starting with the specified Simon. Root Simon can be used to obtain tree with all Simons. Returns null for input value of null or for NullSimon or any Simon with name equal to null (anonymous Simons) - this is also the case when the Manager is disabled and tree for its root Simon is requested.

Parameters:

simon - root Simon of the output tree

Returns:

string containing the tree or null if the Simon is null Simon

localName

public static String localName(String name)

Returns last part of Simon name - local name.

Parameters:

name - full Simon name

Returns:

string containing local name

checkName

public static boolean checkName(String name)

Checks if the input string is correct Simon name. Simon name is checked against public NAME_PATTERN.

Parameters:

name - checked Simon name

Returns:

true if the string is proper Simon name

validateSimonName

public static void validateSimonName(String name)

Checks if the input string is correct Simon name and throws SimonException otherwise.

Parameters:

name - checked Simon name

Throws:

SimonException - if the string is not proper Simon name

generateNameForClass

public static String generateNameForClass(String suffix)

Autogenerates name for the Simon using the fully-qualified class name. This method has inherent performance penalty (getting the stack-trace) so it is recommended to store pre-generated name. (Whole get-start-stop cycle is roughly 30-times slower with this method included.)

Parameters:

suffix - name suffix for eventual Simon discrimination

Returns:

autogenerated name for Simon

Since:

3.1

generateNameForClassAndMethod

public static String generateNameForClassAndMethod(String suffix)

Autogenerates name for the Simon using the fully qualified class name and the method name. This method has inherent performance penalty (getting the stack-trace) so it is recommended to store pre-generated name. (Whole get-start-stop cycle is roughly 30-times slower with this method included.)

Parameters:

suffix - name suffix for eventual Simon discrimination

Returns:

autogenerated name for Simon

Since:

3.1

generateName

public static String generateName()

Autogenerates name for the Simon using the class name and the method name.

Returns:

autogenerated name for Simon

See Also:

generateNameForClassAndMethod(String)

doWithStopwatch

public static <T> T doWithStopwatch(String name,
                    Callable<T> callable)
                         throws Exception

Calls a block of code with stopwatch around and returns result.

Type Parameters:

T - return type

Parameters:

name - name of the Stopwatch

callable - callable block of code

Returns:

whatever block of code returns

Throws:

Exception - whatever block of code throws

Since:

3.0

doWithStopwatch

public static void doWithStopwatch(String name,
                   Runnable runnable)

Calls a block of code with stopwatch around, can not return any result or throw an exception (use doWithStopwatch(String, java.util.concurrent.Callable) instead).

Parameters:

name - name of the Stopwatch

runnable - wrapped block of code

Since:

3.0

compact

public static String compact(String input,
             int limitTo)

Shrinks the middle of the input string if it is too long, so it does not exceed limitTo.

Since:

3.2

calculateStopwatchAggregate

public static StopwatchAggregate calculateStopwatchAggregate(Simon simon)

Aggregate statistics from all stopwatches in hierarchy of simons.

Parameters:

simon - root of the hierarchy of simons for which statistics will be aggregated

Returns:

aggregated statistics

Since:

3.5

calculateStopwatchAggregate

public static StopwatchAggregate calculateStopwatchAggregate(Simon simon,
                                             SimonFilter filter)

Aggregate statistics from all stopwatches in hierarchy that pass specified filter. Filter is applied to all simons in the hierarchy of all types. If a simon is rejected by filter its children are not considered. Simons are aggregated in the top-bottom fashion, i.e. parent simons are aggregated before children.

Parameters:

simon - root of the hierarchy of simons for which statistics will be aggregated

filter - filter to select subsets of simons to aggregate

Returns:

aggregates statistics

Since:

3.5

calculateCounterAggregate

public static CounterAggregate calculateCounterAggregate(Simon simon)

Aggregate statistics from all counters in hierarchy of simons.

Parameters:

simon - root of the hierarchy of simons for which statistics will be aggregated

Returns:

aggregated statistics

Since:

3.5

calculateCounterAggregate

public static CounterAggregate calculateCounterAggregate(Simon simon,
                                         SimonFilter filter)

Aggregate statistics from all counters in hierarchy that pass specified filter. Filter is applied to all simons in the hierarchy of all types. If a simon is rejected by filter its children are not considered. Simons are aggregated in the top-bottom fashion, i.e. parent simons are aggregated before children.

Parameters:

simon - root of the hierarchy of simons for which statistics will be aggregated

filter - filter to select subsets of simons to aggregate

Returns:

aggregates statistics

Since:

3.5