io.toro.martini.tracker

Interface Tracker

public interface Tracker

Tracker serves as the centralized abstraction for logging and tracing changes that may occur within an arbitrary invocation. Similar to how a typical logger is used within the context of a class, one may pass Tracker objects possibly to a pipeline to track states as the each processor processes the the data. Similar to a finite-state machine, the tracker records maintain a set of states, at which callers can arbitrarily set the current state at that specific point in time. A common use-case of a tracker is for tracing method invocation, such as:

  Tracker tracker = ...

  tracker.moveTo("Started);
  someObject.invokeMethod();
  tracker.moveTo("Finished");
 

The above code tells the tracker to move to the "Start" state, invoke the method, and finally move to the "Finished" state.

                       invoke method
  |   Start   |   -------------------->   |  Finished   |

 

Not all invocations may succeed - so callers may catch the exception thrown in their code, and move the tracker to a different state such as:

  Tracker tracker = ...

  tracker.moveTo("Started);
  try {
     someObject.invokeMethod();
  } catch ( SomeException ex ) {
     tracker.moveTo("Failed");
     throw ex;
  }
  tracker.moveTo("Finished");
 

The above code treats the exception as fatal - so the last transition is not called. Data collected by the tracker are retrievable and may serve as an audit trail for observing execution flow.

Method Summary

Modifier and Type	Method and Description
void	addChild(String trackerId) Register a child to the document associated with the tracker
void	addParent(String trackerId) Register a parent to the document associated with the tracker
default void	debug(String message) Logs message as DEBUG
default void	error(String message) Logs message as ERROR
default String	get(String key)
String	getOrDefault(String key, String defaultValue)
String	id()
default void	info(String message) Logs message as INFO
void	log(String type, String message) Logs the message under the type as level
void	moveTo(Document.State state, byte[] content) Tells the tracker to move to the state, using state as name, and then associates the content to it.
void	moveTo(Document.State state, Throwable throwable) Tells the tracker to move to state, and associates the stacktrace of the throwable
default void	moveTo(String state) Tells the tracker to move the state
default void	moveTo(String stateName, byte[] content) Tells the tracker to move to the state, using state as name, and then associates the content to it.
default void	moveTo(String stateName, Throwable throwable) Tells the tracker to move to state, and associates the stacktrace of the throwable
void	put(String key, String value) Puts the value in this context, associated with the key
String	remove(String key) Removes the value associated with key
boolean	removeChild(String trackerId) Unregister a child from the document associated with the tracker
boolean	removeParent(String trackerId) Unregister a parent from the document associated with the tracker
default void	warn(String message) Logs message as WARN

Method Detail

id

String id()

Returns:

the identifier for this tracker

moveTo

default void moveTo(String state)

Tells the tracker to move the state

moveTo

default void moveTo(String stateName,
                    byte[] content)

Tells the tracker to move to the state, using state as name, and then associates the content to it.

moveTo

void moveTo(Document.State state,
            byte[] content)

Tells the tracker to move to the state, using state as name, and then associates the content to it.

moveTo

default void moveTo(String stateName,
                    Throwable throwable)

Tells the tracker to move to state, and associates the stacktrace of the throwable

moveTo

void moveTo(Document.State state,
            Throwable throwable)

Tells the tracker to move to state, and associates the stacktrace of the throwable

log

void log(String type,
         String message)

Logs the message under the type as level

info

default void info(String message)

Logs message as INFO

warn

default void warn(String message)

Logs message as WARN

error

default void error(String message)

Logs message as ERROR

debug

default void debug(String message)

Logs message as DEBUG

get

default String get(String key)

Returns:

the value associated with key, or null

getOrDefault

String getOrDefault(String key,
                    String defaultValue)

Returns:

the value associated with key, or defaultValue

put

void put(String key,
         String value)

Puts the value in this context, associated with the key

remove

String remove(String key)

Removes the value associated with key

Returns:

The previous value associated with key, or null

addParent

void addParent(String trackerId)

Register a parent to the document associated with the tracker

Parameters:

trackerId - The id of the tracker to be set as a parent

removeParent

boolean removeParent(String trackerId)

Unregister a parent from the document associated with the tracker

Parameters:

trackerId - The id of the parent to be unregistered

Returns:

whether an association was removed

addChild

void addChild(String trackerId)

Register a child to the document associated with the tracker

Parameters:

trackerId - The id of the tracker to be set as a child

removeChild

boolean removeChild(String trackerId)

Unregister a child from the document associated with the tracker

Parameters:

trackerId - The id of the child to be unregistered

Returns:

whether an association was removed