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
    private final String
    folder
    Name of the directory beneath the runtime temporary directory where this builder stores its persisted log file.
    static final String
    LOG_EXTENSION
    Standard filename extension assigned to persisted command log files.
    private final String
    logId
    Optional identifier used as the base name of the persisted log file.
    private final int
    maxSize
    Maximum number of characters retained in sb after each append.
    private final File
    projectDir
    Optional project directory marker indicating that appended content should also be persisted.
    private final StringBuilder
    sb
    Mutable buffer containing the most recently appended, retained log content.
    private final long
    startTime
    Epoch time in milliseconds at which this builder was created.
    private int
    totalLength
    Total number of characters accepted by append(String) since this instance was created, including content no longer retained in sb.
    private boolean
    truncated
    Whether content has been removed from the beginning of the buffer since the last call to clear().

  • 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

    • folder

      private final String folder
      Name of the directory beneath the runtime temporary directory where this builder stores its persisted log file.

      This directory is combined with ProjectLayout.getTempDir() when a log path is requested.

    • LOG_EXTENSION

      public static final String LOG_EXTENSION
      Standard filename extension assigned to persisted command log files.

      All log files created by this class use this extension after their log identifier.

      See Also:

    • maxSize

      private final int maxSize
      Maximum number of characters retained in sb after each append.

    • sb

      private final StringBuilder sb
      Mutable buffer containing the most recently appended, retained log content.

    • truncated

      private boolean truncated
      Whether content has been removed from the beginning of the buffer since the last call to clear().

    • logId

      private final String logId
      Optional identifier used as the base name of the persisted log file.

    • projectDir

      private final File projectDir
      Optional project directory marker indicating that appended content should also be persisted. The directory itself is not used to construct the log path; persistence is enabled only when this value and logId are non-null.

    • totalLength

      private int totalLength
      Total number of characters accepted by append(String) since this instance was created, including content no longer retained in sb.

    • startTime

      private final long startTime
      Epoch time in milliseconds at which this builder was created.

  • Constructor Details

    • LogBuilder

      public LogBuilder(String folder, int maxSize, String logId, File projectDir)
      Creates a builder that keeps at most maxSize characters.
      Parameters:
      folder - directory beneath the runtime temporary directory for the persisted log file
      maxSize - maximum number of characters to retain; must be positive
      logId - optional log identifier for file persistence
      projectDir - optional non-null marker enabling file persistence when logId is also non-null
      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:
      UncheckedIOException - 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 beneath the runtime temporary directory in the supplied folder. Parent directories are created if necessary.

      Parameters:
      folder - the directory beneath the runtime temporary directory
      logId - the log identifier used as the file name
      Returns:
      the path to the log file
      Throws:
      UncheckedIOException - if the log directory cannot be created

    • getTail

      public String getTail()
      Returns the retained content.

      Earlier content is omitted when the configured maximum size was exceeded; callers can inspect getReport() for the truncation status.

      Returns:
      retained text; when truncation occurred, the returned value omits the discarded leading content

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

      This operation does not reset the total appended length, the start time, or any persisted log file.

    • 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