Package org.machanism.machai.gw.tools

Class LogBuilder

java.lang.Object
org.machanism.machai.gw.tools.LogBuilder
public class LogBuilder extends Object
A StringBuilder-like helper that retains only the last maxSize characters.

This utility is typically used when capturing potentially unbounded output (for example, process stdout/stderr) while keeping a deterministic upper bound on memory usage. It also supports optional persistence of appended content to a log file on disk.

The log buffer is truncated from the beginning if the maximum size is exceeded, and a flag is set to indicate truncation. The class also tracks the total number of characters ever appended and the elapsed time since instantiation.

Since:
1.2.0
Author:
Viktor Tovstyi

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    LOG_EXTENSION
    Standard file extension for log files.

  • Constructor Summary

    Constructors
    Constructor
    Description
    LogBuilder(String folder, int maxSize, String logId, File projectDir)
    Creates a builder that keeps at most maxSize characters.

  • Method Summary

    Modifier and Type
    Method
    Description
    LogBuilder
    append(String text)
    Appends the specified text to the internal log buffer and optionally persists it to disk.
    void
    clear()
    Clears the retained content and resets the truncation flag.
    static Path
    getCommandLogPath(String folder, String logId)
    Returns the path to the log file for the given log identifier.
    Map<String,Object>
    getReport()
    Returns a report of the log state, including log ID, retained tail, total length, truncation status, and elapsed process time in milliseconds.
    String
    getTail()
    Returns the retained content.
    int
    getTotalLength()
    Returns the total number of characters ever appended to this builder.
    int
    length()
    Returns the number of characters currently retained.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • LOG_EXTENSION

      public static final String LOG_EXTENSION
      Standard file extension for log files.

      All log files created by this component or related utilities should use this extension.

      See Also:

  • Constructor Details

    • LogBuilder

      public LogBuilder(String folder, int maxSize, String logId, File projectDir)
      Creates a builder that keeps at most maxSize characters.
      Parameters:
      folder - TODO
      maxSize - maximum number of characters to retain; must be positive
      logId - optional log identifier for file persistence
      projectDir - optional project directory for log file location
      Throws:
      IllegalArgumentException - if maxSize is not positive

  • Method Details

    • append

      public LogBuilder append(String text)
      Appends the specified text to the internal log buffer and optionally persists it to disk.

      This method updates the internal buffer by adding the provided text. If the buffer exceeds the configured maximum size (maxSize), the oldest content is truncated to maintain the limit. The truncated flag is set if truncation occurs.

      If both projectDir and logId are set, the appended text is also written to a log file on disk. The log file is created if it does not exist, or appended to if it does. Parent directories are created as needed.

      Parameters:
      text - the text to append to the log buffer; if null, no action is taken
      Returns:
      this LogBuilder instance for method chaining
      Throws:
      IllegalArgumentException - if an I/O error occurs while writing to the log file

    • getCommandLogPath

      public static Path getCommandLogPath(String folder, String logId)
      Returns the path to the log file for the given log identifier.

      The log file is located in the system temporary directory under gw-command-logs. Parent directories are created if necessary.

      Parameters:
      folder -
      logId - the log identifier
      Returns:
      the path to the log file
      Throws:
      RuntimeException - if the log directory cannot be created

    • getTail

      public String getTail()
      Returns the retained content.

      If truncation occurred, a prefix is added to indicate that earlier content was discarded.

      Returns:
      retained text (possibly with a truncation prefix)

    • length

      public int length()
      Returns the number of characters currently retained.
      Returns:
      retained length

    • clear

      public void clear()
      Clears the retained content and resets the truncation flag.

    • getTotalLength

      public int getTotalLength()
      Returns the total number of characters ever appended to this builder.
      Returns:
      the total length of all appended content

    • getReport

      public Map<String,Object> getReport()
      Returns a report of the log state, including log ID, retained tail, total length, truncation status, and elapsed process time in milliseconds.
      Returns:
      a map containing log state information