Meter (slf4j-toys 1.9.0 API)

java.lang.Object
- org.usefultoys.slf4j.internal.EventData
- - org.usefultoys.slf4j.internal.SystemData
  - - org.usefultoys.slf4j.meter.MeterData
    - - org.usefultoys.slf4j.meter.Meter

All Implemented Interfaces:

Closeable, Serializable, AutoCloseable
```
public class Meter
extends MeterData
implements Closeable
```
At beginning, termination of operations and on iterations, collects system status and reports it to logger. Call start() to produce a 1-line summary about operation start and current system status as debug message and an encoded event as trace message. Call ok() to produce a 1-line summary about operation successful end and current system status as information message and an encoded event as trace message. Call fail(Object) to produce a 1-line summary about operation failure and current system status as error message and an encoded event as trace message. Call progress() to produce a 1-line summary about operation progress and current system status as information message and an encoded event as trace message.

Author:

Daniel Felix Ferber

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Meter.IllegalMeterUsage

static class Meter.MeterThrowable

Nested Classes
Modifier and Type	Class and Description
`static class`	`Meter.IllegalMeterUsage`
`static class`	`Meter.MeterThrowable`

Field Summary

Fields
Modifier and Type Field and Description

static String CONTEXT_RESULT
- Fields inherited from class org.usefultoys.slf4j.meter.MeterData
  category, context, createTime, currentIteration, description, DETAILED_MESSAGE_PREFIX, EVENT_CATEGORY, EVENT_NAME, EVENT_PARENT, expectedIterations, failMessage, failPath, okPath, operation, parent, PROP_CONTEXT, PROP_CREATE_TIME, PROP_DESCRIPTION, PROP_EXPECTED_ITERATION, PROP_FAIL_ID, PROP_ITERATION, PROP_LIMIT_TIME, PROP_PATH_ID, PROP_REJECT_ID, PROP_START_TIME, PROP_STOP_TIME, rejectPath, startTime, stopTime, timeLimit
- Fields inherited from class org.usefultoys.slf4j.internal.SystemData
  classLoading_loaded, classLoading_total, classLoading_unloaded, compilationTime, garbageCollector_count, garbageCollector_time, heap_commited, heap_max, heap_used, nonHeap_commited, nonHeap_max, nonHeap_used, objectPendingFinalizationCount, PROP_CLASS_LOADING, PROP_COMPILATION_TIME, PROP_FINALIZATION_COUNT, PROP_GARBAGE_COLLECTOR, PROP_HEAP, PROP_MEMORY, PROP_NON_HEAP, PROP_SYSTEM_LOAD, runtime_maxMemory, runtime_totalMemory, runtime_usedMemory, systemLoad
- Fields inherited from class org.usefultoys.slf4j.internal.EventData
  EVENT_POSITION, EVENT_TIME, position, SESSION_UUID, sessionUuid, time

Fields
Modifier and Type	Field and Description
`static String`	`CONTEXT_RESULT`

Constructor Summary

Constructors
Constructor and Description
`Meter(org.slf4j.Logger logger)` Creates a new meter for the category given by the logger's name.
`Meter(org.slf4j.Logger logger, String operation)` Creates a new Meter for the operation beloging to the category given by the logger's name.
`Meter(org.slf4j.Logger logger, String operation, String parent)` Creates a new Meter for the operation beloging to the category given by the logger's name, as child for an existing Meter.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`<T> T`	`call(Callable<T> callable)`
`<T> T`	`callOrReject(Callable<T> callable, Class<? extends Exception>... exceptionsToReject)`
`<T> T`	`callOrRejectChecked(Callable<T> callable)`
`void`	`close()` Compliance with `Closeable`.
`Meter`	`ctx(boolean condition, String trueName)` Adds an entry to the context map if conditions is true.
`Meter`	`ctx(boolean condition, String trueName, String falseName)` Adds an entry to the context map if conditions is true or false.
`Meter`	`ctx(String name)` Adds an entry to the context map.
`Meter`	`ctx(String name, boolean value)` Adds an entry to the context map.
`Meter`	`ctx(String name, Boolean value)` Adds an entry to the context map.
`Meter`	`ctx(String name, double value)` Adds an entry to the context map.
`Meter`	`ctx(String name, Double value)` Adds an entry to the context map.
`Meter`	`ctx(String name, float value)` Adds an entry to the context map.
`Meter`	`ctx(String name, Float value)` Adds an entry to the context map.
`Meter`	`ctx(String name, int value)` Adds an entry to the context map.
`Meter`	`ctx(String name, Integer value)` Adds an entry to the context map.
`Meter`	`ctx(String name, long value)` Adds an entry to the context map.
`Meter`	`ctx(String name, Long value)` Adds an entry to the context map.
`Meter`	`ctx(String name, Object object)` Adds an entry to the context map.
`Meter`	`ctx(String name, String value)` Adds an entry to the context map.
`Meter`	`ctx(String name, String format, Object... args)` Adds an entry to the context map.
`Meter`	`fail(Object cause)` Refuses the meter in order to claim incomplete or inconsistent execution of the task represented by the meter.
`protected void`	`finalize()` Checks if meters the meter has been forgotten to be confirmed or refused.
`static Meter`	`getCurrentInstance()`
`Meter`	`inc()` Notifies the meter that one more iteration or step completed that make up the task successfully.
`Meter`	`incBy(long increment)` Notifies the meter that more of iterations or steps that make up the task completed successfully.
`Meter`	`incTo(long currentIteration)` Notifies the meter that a number of iterations or steps that make up the task already completed successfully.
`Meter`	`iterations(long expectedIterations)` Configures the Meter for an operation made up of iterations or steps.
`Meter`	`limitMilliseconds(long timeLimit)` Configures the Meter with an threshold for reasonable, typical execution time for the operation.
`Meter`	`m(String message)` Configures the Meter with a human readable message that explains the operations's purpose.
`Meter`	`m(String format, Object... args)` Configures the Meter with a human readable message that explains the operations's purpose.
`Meter`	`ok()` Confirms the meter in order to claim successful completion of the task represented by the meter.
`Meter`	`ok(Object pathId)` Confirms the meter in order to claim successful completion of the task represented by the meter.
`Meter`	`path(Object pathId)`
`Meter`	`progress()` Allow informing about successful completion of iterations or steps making up the task represented by the meter.
`Meter`	`reject(Object cause)` Confirms the meter in order to claim unsuccessful completion of the task represented by the meter.
`void`	`run(Runnable runnable)`
`void`	`runOrReject(Runnable runnable, Class<? extends Exception>... exceptionsToReject)`
`<T> T`	`safeCall(Callable<T> callable)`
`<E extends RuntimeException,T> T`	`safeCall(Class<E> exceptionClass, Callable<T> callable)`
`Meter`	`start()` Notifies the meter in order to claim immediate execution start of the task represented by the meter.
`Meter`	`sub(String suboperationName)` Creates a new Meter for an operation that belongs to the opeartion of this Meter.
`Meter`	`unctx(String name)` Removes an entry from the context map.

Methods inherited from class org.usefultoys.slf4j.meter.MeterData
collectRuntimeStatus, equals, getContext, getExecutionTime, getFullID, getIterationsPerSecond, getPath, getWaitingTime, hashCode, isFail, isOK, isReject, isSlow, isStarted, isStopped, readableStringBuilder, resetImpl, writeJson5Impl

Methods inherited from class org.usefultoys.slf4j.internal.SystemData
collectManagedBeanStatus, collectPlatformStatus, readJson5

Methods inherited from class org.usefultoys.slf4j.internal.EventData
encodedMessage, json5Message, readableMessage, reset, writeJson5

Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CONTEXT_RESULT
```
public static final String CONTEXT_RESULT
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Meter
```
public Meter(org.slf4j.Logger logger)
```
    Creates a new meter for the category given by the logger's name.
    
    Parameters:
    
    logger - Logger that reports messages.
  - Meter
```
public Meter(org.slf4j.Logger logger,
             String operation)
```
    Creates a new Meter for the operation beloging to the category given by the logger's name.
    
    Parameters:
    
    logger - Logger that reports messages.
    
    operation - The operation name or null.
  - Meter
```
public Meter(org.slf4j.Logger logger,
             String operation,
             String parent)
```
    Creates a new Meter for the operation beloging to the category given by the logger's name, as child for an existing Meter.
    
    Parameters:
    
    logger - Logger that reports messages.
    
    operation - The operation name or null.
    
    parent - ID of the parent Meter or null.
- Method Detail
  - getCurrentInstance
```
public static Meter getCurrentInstance()
```
    Returns:
    
    The Meter most recently started on the current thread.
  - sub
```
public Meter sub(String suboperationName)
```
    Creates a new Meter for an operation that belongs to the opeartion of this Meter. Useful if a large operation may be subdivided into smaller operations and reported individually. The new Meter uses the same category of this Meter.
    
    Parameters:
    
    suboperationName - Additional identification appended to this logger name.
    
    Returns:
    
    The new Meter
  - m
```
public Meter m(String message)
```
    Configures the Meter with a human readable message that explains the operations's purpose.
    
    Parameters:
    
    message - fixed message
    
    Returns:
    
    reference to the meter itself.
  - m
```
public Meter m(String format,
               Object... args)
```
    Configures the Meter with a human readable message that explains the operations's purpose.
    
    Parameters:
    
    format - message format (String.format(java.lang.String, java.lang.Object...))
    
    args - message arguments
    
    Returns:
    
    reference to the meter itself.
  - limitMilliseconds
```
public Meter limitMilliseconds(long timeLimit)
```
    Configures the Meter with an threshold for reasonable, typical execution time for the operation.
    
    Parameters:
    
    timeLimit - time threshold
    
    Returns:
    
    reference to the meter itself.
  - iterations
```
public Meter iterations(long expectedIterations)
```
    Configures the Meter for an operation made up of iterations or steps. Such Meter is allows to call progress() an arbitrarily number of Such Meter should call inc(), incBy(long) or incTo(long) to advance the current iteration. times between start() and ok()/reject(Object)/fail(Object) method calls.
    
    Parameters:
    
    expectedIterations - Number of expected iterations or steps that make up the task
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name)
```
    Adds an entry to the context map. The entry has no value and is interpreted as a marker.
    
    Parameters:
    
    name - key of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(boolean condition,
                 String trueName)
```
    Adds an entry to the context map if conditions is true. The entry has no value and is interpreted as a marker.
    
    Parameters:
    
    condition - the condition
    
    trueName - key of the entry to add if conditions is true
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(boolean condition,
                 String trueName,
                 String falseName)
```
    Adds an entry to the context map if conditions is true or false. The entry has no value and is interpreted as a marker.
    
    Parameters:
    
    condition - the condition
    
    trueName - key of the entry to add if conditions is true
    
    falseName - key of the entry to add if conditions is true
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 int value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 long value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 boolean value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 float value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 double value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 Integer value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 Long value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 Boolean value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 Float value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 Double value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 Object object)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    object - object which string representation is used for the value of the entry to add
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 String value)
```
    Adds an entry to the context map.
    
    Parameters:
    
    name - key of the entry to add.
    
    value - value of the entry to add.
    
    Returns:
    
    reference to the meter itself.
  - ctx
```
public Meter ctx(String name,
                 String format,
                 Object... args)
```
    Adds an entry to the context map. The entry value is made up of a formatted message with arguments.
    
    Parameters:
    
    name - key of the entry to add.
    
    format - message format (String.format(java.lang.String, java.lang.Object...))
    
    args - message arguments
    
    Returns:
    
    reference to the meter itself.
  - unctx
```
public Meter unctx(String name)
```
    Removes an entry from the context map.
    
    Parameters:
    
    name - key of the entry to remove.
    
    Returns:
    
    reference to the meter itself.
  - start
```
public Meter start()
```
    Notifies the meter in order to claim immediate execution start of the task represented by the meter. Sends a message to logger using debug level. Sends a message with system status and partial context to log using trace level.
    
    Returns:
    
    reference to the meter itself.
  - inc
```
public Meter inc()
```
    Notifies the meter that one more iteration or step completed that make up the task successfully.
    
    Returns:
    
    reference to the meter itself.
  - incBy
```
public Meter incBy(long increment)
```
    Notifies the meter that more of iterations or steps that make up the task completed successfully.
    
    Parameters:
    
    increment - the number of iterations or steps
    
    Returns:
    
    reference to the meter itself.
  - incTo
```
public Meter incTo(long currentIteration)
```
    Notifies the meter that a number of iterations or steps that make up the task already completed successfully.
    
    Parameters:
    
    currentIteration - the number of iterations or steps
    
    Returns:
    
    reference to the meter itself.
  - progress
```
public Meter progress()
```
    Allow informing about successful completion of iterations or steps making up the task represented by the meter. Only applicable for meters that called iterations(long i) before calling start(). Sends a message to logger using info level, only periodically and if progress was observed, to minimize performance degradation.
    
    Returns:
    
    reference to the meter itself.
  - path
```
public Meter path(Object pathId)
```
  - ok
```
public Meter ok()
```
    Confirms the meter in order to claim successful completion of the task represented by the meter. Sends a message to logger using info level. If a time limit was given and execution exceeded this limit, sends a message using warn level instead. Sends a message with system status and partial context to log using trace level.
    
    Returns:
    
    reference to the meter itself.
  - ok
```
public Meter ok(Object pathId)
```
    Confirms the meter in order to claim successful completion of the task represented by the meter. Sends a message to logger using info level. If a time limit was given and execution exceeded this limit, sends a message using warn level instead. Sends a message with system status and partial context to log using trace level.
    
    Parameters:
    
    pathId - A token, enum or exception that describes the successful pathId.
    
    Returns:
    
    reference to the meter itself.
  - reject
```
public Meter reject(Object cause)
```
    Confirms the meter in order to claim unsuccessful completion of the task represented by the meter. Sends a message to logger using info level. If a time limit was given and execution exceeded this limit, sends a message using warn level instead. Sends a message with system status and partial context to log using trace level.
    
    Parameters:
    
    cause - A token, enum or exception that describes the cause of rejection.
    
    Returns:
    
    reference to the meter itself.
  - fail
```
public Meter fail(Object cause)
```
    Refuses the meter in order to claim incomplete or inconsistent execution of the task represented by the meter. Sends a message with the the exception to logger using warn level. Sends a message with system status, statistics and complete context to log using trace level.
    
    Parameters:
    
    cause - Exception that represents the failure. May be null if no exception applies.
    
    Returns:
    
    reference to the meter itself.
  - finalize
```
protected void finalize()
                 throws Throwable
```
    Checks if meters the meter has been forgotten to be confirmed or refused. Useful to track those meters that do not follow the start(), ok()/fail() idiom for all execution flows. Meters created to represent unknown instance in checkCurrentInstance() are not considered for check.
    
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable
  - close
```
public void close()
```
    Compliance with Closeable. Assumes failure and refuses the meter if the meter has not yet been marked as confirmed.
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
  - run
```
public void run(Runnable runnable)
```
  - runOrReject
```
public void runOrReject(Runnable runnable,
                        Class<? extends Exception>... exceptionsToReject)
```
  - call
```
public <T> T call(Callable<T> callable)
           throws Exception
```
    Throws:
    
    Exception
  - callOrRejectChecked
```
public <T> T callOrRejectChecked(Callable<T> callable)
```
  - callOrReject
```
public <T> T callOrReject(Callable<T> callable,
                          Class<? extends Exception>... exceptionsToReject)
```
  - safeCall
```
public <T> T safeCall(Callable<T> callable)
```
  - safeCall
```
public <E extends RuntimeException,T> T safeCall(Class<E> exceptionClass,
                                                 Callable<T> callable)
```

Class Meter

Nested Class Summary

Field Summary

Fields inherited from class org.usefultoys.slf4j.meter.MeterData

Fields inherited from class org.usefultoys.slf4j.internal.SystemData

Fields inherited from class org.usefultoys.slf4j.internal.EventData

Constructor Summary

Method Summary

Methods inherited from class org.usefultoys.slf4j.meter.MeterData

Methods inherited from class org.usefultoys.slf4j.internal.SystemData

Methods inherited from class org.usefultoys.slf4j.internal.EventData

Methods inherited from class java.lang.Object

Field Detail

CONTEXT_RESULT

Constructor Detail

Meter

Meter

Meter

Method Detail

getCurrentInstance

sub

m

m

limitMilliseconds

iterations

ctx

ctx

ctx

ctx

ctx

ctx

ctx

ctx

ctx

ctx

ctx

ctx

ctx

ctx

ctx

ctx

unctx

start

inc

incBy

incTo

progress

path

ok

ok

reject

fail

finalize

close

run

runOrReject

call

callOrRejectChecked

callOrReject

safeCall

safeCall