SimonUtils (Java Simon 4.2.0 API)

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

All Methods Static Methods Concrete 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

Class SimonUtils

Human readable outputs

Aggregation utilities

Simon tree operations

Other utilities

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NAME_PATTERN_CHAR_CLASS_CONTENT

NAME_PATTERN

ALLOWED_CHARS

MANAGER_SERVLET_CTX_ATTRIBUTE

Method Detail

presentNanoTime

presentNanoTime

presentTimestamp

presentMinMaxCount

simonTreeString

localName

checkName

validateSimonName

generateNameForClass

generateNameForClassAndMethod

generateName

doWithStopwatch

doWithStopwatch

compact

calculateStopwatchAggregate

calculateStopwatchAggregate

calculateCounterAggregate

calculateCounterAggregate