Interface PerformanceTracker

All Known Implementing Classes:

PerfLogUtils.PerformanceTrackerHolder, PerformanceTrackerImpl

@ClassVersion(sourceVersion="$Id: PerformanceTracker.java 1258 2026-06-04 18:33:06Z tquadrat $")
@API(status=STABLE,
     since="0.25.0")
public sealed interface PerformanceTracker
permits PerfLogUtils.PerformanceTrackerHolder, PerformanceTrackerImpl

This interface describes a performance tracker for the Foundation Performance Logging and Monitoring.

This is basically collecting the time that is spent within a performance section.

Obviously, an instance of the implementation of this interface is not thread-safe, but it can be reused multiple times.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: PerformanceTracker.java 1258 2026-06-04 18:33:06Z tquadrat $

Since:

0.25.0

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.perflog.PerformanceTracker"

⁠

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	PerformanceTracker.TrackerStatus	The status of a PerformanceTracker.

Method Summary

Modifier and Type	Method	Description
void	abort()	Stops the performance timer.
void	abort(String message)	Stops the performance timer and takes a message describing the reason for the abort.
void	abort(String message, Throwable cause)	Stops the performance timer and takes a message describing the reason for the abort, plus the exception that caused it.
PerformanceTracker	addContext(String name, String value)	Adds context information to this tracker.
default <T> PerformanceTracker	addContext(String name, T value, StringConverter<T> stringConverter)	Adds context information to this tracker.
PerformanceTracker.TrackerStatus	getStatus()	Returns the status of this tracker instance.
default boolean	isActive()	Checks whether the tracker is active.
PerformanceTracker	reset(boolean resetContext)	Resets the instance.
void	start()	Resets the instance and starts the performance timer.
void	stop()	Stops the performance timer and transfers the elapsed time to the PerfLogMBean for further processing.

Method Details

abort

void abort()

Stops the performance timer.

If the tracker has been aborted or stopped already, nothing happens. Same if it was never started.

abort

void abort(String message)

Stops the performance timer and takes a message describing the reason for the abort.

If the tracker has been aborted or stopped already, nothing happens. Same if it was never started.

Parameters:

message - The message describing the reason for the abort.

abort

void abort(String message,
 Throwable cause)

Stops the performance timer and takes a message describing the reason for the abort, plus the exception that caused it.

If the tracker has been aborted or stopped already, nothing happens. Same if it was never started.

Parameters:

message - The message describing the reason for the abort.

cause - The exception that caused the abort.

addContext

PerformanceTracker addContext(String name,
 String value)

Adds context information to this tracker. This is also transferred to the PerfLogMBean when the tracker is stopped or aborted.

The given name must conform a valid JSON name and may not start with an underscore ("_"/#x005f).

The given name is unique; if a value is added with an already known name, it will overwrite the existing value.

A call to start() will not reset the context.

An example on how to use the context may look like this:

//---* Load Data *-------------------------------------------------------------
try( final var tracker = PerfLogUtils.holdAndStart( PS1 ) )
{
    tracker.setContext( "Source", … );

    // Do something here!!
    …
}

Parameters:

name - The name of the context value.

value - The context value; null removes the entry with the given name.

Returns:

This instance.

addContext

default <T> PerformanceTracker addContext(String name,
 T value,
 StringConverter<T> stringConverter)

Adds context information to this tracker. This is also transferred to the PerfLogMBean when the tracker is stopped.

The given name is unique; if a value is added with an already known name, it will overwrite the existing value.

A call to start() will not reset the context.

Type Parameters:

T - The type of the context value.

Parameters:

name - The name of the context value.

value - The context value; null removes the entry with the given name.

stringConverter - The instance of StringConverter that is used to translate the value into a String.

Returns:

This instance.

See Also:

• addContext(String,String)

getStatus

PerformanceTracker.TrackerStatus getStatus()

Returns the status of this tracker instance.

Returns:

The tracker status.

isActive

default boolean isActive()

Checks whether the tracker is active.

Returns:

true if the tracker was started, but not yet aborted or stopped, false otherwise.

reset

PerformanceTracker reset(boolean resetContext)
                  throws IllegalStateException

Resets the instance.

If the tracker was already started, but never stopped or aborted, an IllegalStateException is thrown.

Parameters:

resetContext - true if also the context should be reset, false to keep the current context.

Returns:

This instance.

Throws:

IllegalStateException - The tracker was already started but not stopped or aborted.

start

void start()
    throws IllegalStateException

Resets the instance and starts the performance timer.

If the tracker was already started, but never stopped or aborted, an IllegalStateException is thrown.

Throws:

IllegalStateException - The tracker was already started but not stopped or aborted.

stop

void stop()
   throws IllegalStateException

Stops the performance timer and transfers the elapsed time to the PerfLogMBean for further processing.

If the tracker has been aborted already, nothing happens. Same if it was never started.

Throws:

IllegalStateException - The tracker was already stopped previously.