org.usefultoys.slf4j.meter

Class Meter

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:

java.io.Closeable, java.io.Serializable, java.lang.AutoCloseable

public class Meter
extends MeterData
implements java.io.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(Throwable) 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.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Meter.IllegalMeterUsage
static class	Meter.MeterThrowable
static class	Meter.TryWithResourcesFailed

Field Summary

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

context, createTime, description, DETAILED_MESSAGE_PREFIX, expectedIterations, failClass, failMessage, iteration, pathId, 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, PROP_THREAD, rejectId, startTime, stopTime, timeLimitNanoseconds

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, runtime_maxMemory, runtime_totalMemory, runtime_usedMemory, systemLoad

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

EVENT_CATEGORY, EVENT_NAME, EVENT_POSITION, eventCategory, eventName, eventPosition, SESSION_UUID, sessionUuid, time

Constructor Summary

Constructors

Constructor and Description
Meter(org.slf4j.Logger logger) Creates a new meter.
Meter(org.slf4j.Logger logger, java.lang.String operationName) Creates a new meter.

Method Summary

Modifier and Type	Method and Description
<T> T	call(java.util.concurrent.Callable<T> callable)
boolean	checkCurrentInstance()
void	close() Compliance with Closeable.
Meter	ctx(boolean condition, java.lang.String trueName) Adds an entry to the context map if conditions is true.
Meter	ctx(boolean condition, java.lang.String trueName, java.lang.String falseName) Adds an entry to the context map if conditions is true or false.
Meter	ctx(java.lang.String name) Adds an entry to the context map.
Meter	ctx(java.lang.String name, boolean value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, java.lang.Boolean value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, double value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, java.lang.Double value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, float value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, java.lang.Float value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, int value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, java.lang.Integer value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, long value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, java.lang.Long value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, java.lang.Object object) Adds an entry to the context map.
Meter	ctx(java.lang.String name, java.lang.String value) Adds an entry to the context map.
Meter	ctx(java.lang.String name, java.lang.String format, java.lang.Object... args) Adds an entry to the context map.
Meter	fail(java.lang.Throwable 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.
Meter	flow(java.lang.Object flow) Deprecated.
static Meter	getCurrentInstance()
org.slf4j.Logger	getLogger()
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 as representing a task made up of iterations or steps.
Meter	limitMilliseconds(long timeLimitMilliseconds) Configures the meter with an threshold for reasonable, typical execution time for the task represented by the meter.
Meter	m(java.lang.String message) Configures the meter with a human readable message that explains the task's purpose.
Meter	m(java.lang.String format, java.lang.Object... args) Configures the meter with a human readable message that explains the task's purpose.
Meter	ok() Confirms the meter in order to claim successful completion of the task represented by the meter.
Meter	ok(java.lang.Object pathId) Confirms the meter in order to claim successful completion of the task represented by the meter.
Meter	path(java.lang.Object pathId)
Meter	progress() Allow informing about successful completion of iterations or steps making up the task represented by the meter.
Meter	reject(java.lang.Object cause) Confirms the meter in order to claim unsuccessful completion of the task represented by the meter.
void	run(java.lang.Runnable runnable)
<T> T	safeCall(java.util.concurrent.Callable<T> callable)
<E extends java.lang.RuntimeException,T> T	safeCall(java.lang.Class<E> exceptionClass, java.util.concurrent.Callable<T> callable)
Meter	start() Notifies the meter in order to claim immediate execution start of the task represented by the meter.
Meter	sub(java.lang.String suboperationName) Creates a new Meter whose name is under the hierarchy of this meter.
Meter	unctx(java.lang.String name) Removes an entry from the context map.

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

getContext, getCreateTime, getCurrentIteration, getDescription, getExceptionClass, getExceptionMessage, getExecutionTime, getExpectedIterations, getIterationsPerSecond, getPathId, getRejectId, getStartTime, getStopTime, getTimeLimitNanoseconds, getWaitingTime, isCompletelyEqualsImpl, isFail, isOK, isReject, isSlow, isStarted, isStopped, read, readableString, readableWrite, readPropertyImpl, resetImpl, write, writePropertiesImpl

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

collectManagedBeanStatus, collectPlatformStatus, collectRuntimeStatus

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

equals, getEventCategory, getEventName, getEventPosition, getFullID, getSessionUuid, getTime, hashCode, isCompletelyEqualsTo, isSameAs, read, reset, toString, write

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Meter

public Meter(org.slf4j.Logger logger)

Creates a new meter. Events produced by this meter will use the logger name as event category.

Parameters:

logger - Logger that reports messages.

Meter

public Meter(org.slf4j.Logger logger,
             java.lang.String operationName)

Creates a new meter. Events produced by this meter will use the logger name as event category.

Parameters:

logger - Logger that reports messages.

operationName - Additional identification to distinguish operations reported on the same logger.

Method Detail

getCurrentInstance

public static Meter getCurrentInstance()

Returns:

The meter most recently started on the current thread.

getLogger

public org.slf4j.Logger getLogger()

Returns:

Logger that reports current system status as information messages.

sub

public Meter sub(java.lang.String suboperationName)

Creates a new Meter whose name is under the hierarchy of this meter. Useful if a large task may be subdivided into smaller task and reported individually. The new meter uses the name of this meter appended by dot and its own name, similar as logger do.

Parameters:

suboperationName - Additional identification appended to this logger name.

Returns:

The new Meter

m

public Meter m(java.lang.String message)

Configures the meter with a human readable message that explains the task's purpose.

Parameters:

message - fixed message

Returns:

reference to the meter itself.

m

public Meter m(java.lang.String format,
               java.lang.Object... args)

Configures the meter with a human readable message that explains the task'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 timeLimitMilliseconds)

Configures the meter with an threshold for reasonable, typical execution time for the task represented by the meter.

Parameters:

timeLimitMilliseconds - time threshold

Returns:

reference to the meter itself.

iterations

public Meter iterations(long expectedIterations)

Configures the meter as representing a task made up of iterations or steps. Such meters are allows to call progress() an arbitrarily number of times between start() and ok()/fail(java.lang.Throwable) 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(java.lang.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,
                 java.lang.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,
                 java.lang.String trueName,
                 java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String name,
                 java.lang.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(java.lang.String name,
                 java.lang.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(java.lang.String name,
                 java.lang.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(java.lang.String name,
                 java.lang.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(java.lang.String name,
                 java.lang.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(java.lang.String name,
                 java.lang.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(java.lang.String name,
                 java.lang.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(java.lang.String name,
                 java.lang.String format,
                 java.lang.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(java.lang.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.

flow

@Deprecated
public Meter flow(java.lang.Object flow)

Deprecated.

path

public Meter path(java.lang.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.

checkCurrentInstance

public boolean checkCurrentInstance()

ok

public Meter ok(java.lang.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(java.lang.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(java.lang.Throwable 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 java.lang.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

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.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 java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

run

public void run(java.lang.Runnable runnable)

call

public <T> T call(java.util.concurrent.Callable<T> callable)
           throws java.lang.Exception

Throws:

java.lang.Exception

safeCall

public <T> T safeCall(java.util.concurrent.Callable<T> callable)

safeCall

public <E extends java.lang.RuntimeException,T> T safeCall(java.lang.Class<E> exceptionClass,
                                                           java.util.concurrent.Callable<T> callable)