Package 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

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method 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