Class PerfLogUtils.PerformanceTrackerHolder

java.lang.Object

org.tquadrat.foundation.perflog.PerfLogUtils.PerformanceTrackerHolder

All Implemented Interfaces:

AutoCloseable, PerformanceTracker

Enclosing class:

PerfLogUtils

@ClassVersion(sourceVersion="$Id: PerfLogUtils.java 1258 2026-06-04 18:33:06Z tquadrat $")
@API(status=STABLE,
     since="0.25.0")
public static final class PerfLogUtils.PerformanceTrackerHolder
extends Object
implements AutoCloseable, PerformanceTracker

A holder for PerformanceTracker that allows to use it with try-with-resources.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

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

Since:

0.25.0

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.perflog.PerfLogUtils.PerformanceTrackerHolder"

⁠

Nested Class Summary

Nested classes/interfaces inherited from interface PerformanceTracker

PerformanceTracker.TrackerStatus

Field Summary

Fields

Modifier and Type	Field	Description
private boolean	m_IsClosed	The flag that indicates whether close() was already called on this instance.
private PerfLogManager	m_Manager	The reference to a volatile instance of PerfLogManager.
private final PerformanceTracker	m_Tracker	The wrapped instance of PerformanceTracker.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	PerformanceTrackerHolder()	Creates a new instance of PerformanceTrackerHolder that does not hold an instance of PerformanceTracker.
private	PerformanceTrackerHolder(PerformanceTrackerImpl tracker)	Creates a new instance of PerformanceTrackerHolder that holds an instance of PerformanceTracker.
private	PerformanceTrackerHolder(PerfLogManager manager, PerformanceSectionName name)	Creates a new instance of PerformanceTrackerHolder that holds an instance of PerformanceTracker, created by calling PerfLogManager.createPerformanceTracker(PerformanceSectionName) on the given PerfLogManager instance with the given PerformanceSectionName.

Method Summary

Modifier and Type	Method	Description
final 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.
final PerformanceTracker	addContext(String name, String value)	Adds context information to this tracker.
final <T> PerformanceTracker	addContext(String name, T value, StringConverter<T> stringConverter)	Adds context information to this tracker.
final void	close()
final PerformanceTracker.TrackerStatus	getStatus()	Returns the status of this tracker instance.
final PerformanceTracker	reset(boolean resetContext)	Resets the instance.
final void	start()	Resets the instance and starts the performance timer.
final void	stop()	Stops the performance timer and transfers the elapsed time to the PerfLogMBean for further processing.

Methods inherited from class Object

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

Methods inherited from interface PerformanceTracker

isActive

Field Details

m_IsClosed

private boolean m_IsClosed

The flag that indicates whether close() was already called on this instance.

m_Manager

private PerfLogManager m_Manager

The reference to a volatile instance of PerfLogManager.

It is kept here to prevent it from prematurely being garbage collected.

m_Tracker

private final PerformanceTracker m_Tracker

The wrapped instance of PerformanceTracker.

It can be null.

Constructor Details

PerformanceTrackerHolder

private PerformanceTrackerHolder(PerformanceTrackerImpl tracker)

Creates a new instance of PerformanceTrackerHolder that holds an instance of PerformanceTracker.

Parameters:

tracker - The tracker instance to wrap.

Throws:

ClassCastException - If called with an instance of Holder.

PerformanceTrackerHolder

private PerformanceTrackerHolder(PerfLogManager manager,
 PerformanceSectionName name)

Creates a new instance of PerformanceTrackerHolder that holds an instance of PerformanceTracker, created by calling PerfLogManager.createPerformanceTracker(PerformanceSectionName) on the given PerfLogManager instance with the given PerformanceSectionName.

Parameters:

manager - The Performance Logging manager.

name - The performance section name.

PerformanceTrackerHolder

private PerformanceTrackerHolder()

Creates a new instance of PerformanceTrackerHolder that does not hold an instance of PerformanceTracker.

Method Details

abort

public final void abort()

Stops the performance timer.

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

Specified by:

abort in interface PerformanceTracker

abort

public 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.

Specified by:

abort in interface PerformanceTracker

Parameters:

message - The message describing the reason for the abort.

abort

public 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.

Specified by:

abort in interface PerformanceTracker

Parameters:

message - The message describing the reason for the abort.

cause - The exception that caused the abort.

addContext

public final 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 PerformanceTracker.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!!
    …
}

Specified by:

addContext in interface PerformanceTracker

Parameters:

name - The name of the context value.

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

Returns:

This instance.

addContext

public final <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 PerformanceTracker.start() will not reset the context.

Specified by:

addContext in interface PerformanceTracker

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:

• PerformanceTracker.addContext(String,String)

close

public final void close()

Specified by:

close in interface AutoCloseable

getStatus

public final PerformanceTracker.TrackerStatus getStatus()

Returns the status of this tracker instance.

Specified by:

getStatus in interface PerformanceTracker

Returns:

The tracker status.

reset

public final PerformanceTracker reset(boolean resetContext)
                               throws IllegalArgumentException

Resets the instance.

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

Throws also an IllegalStateException if this instance of PerformanceTrackerHolder was already closed.

Specified by:

reset in interface PerformanceTracker

Parameters:

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

Returns:

This instance.

Throws:

IllegalArgumentException

start

public final void start()
                 throws IllegalArgumentException

Resets the instance and starts the performance timer.

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

Specified by:

start in interface PerformanceTracker

Throws:

IllegalArgumentException

stop

public final void stop()
                throws IllegalArgumentException

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.

Specified by:

stop in interface PerformanceTracker

Throws:

IllegalArgumentException