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