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 String
    folder
    Name of the directory where log files are stored.
    static final String
    LOG_EXTENSION
    Standard file extension for log files.
    private final String
    logId
    Optional log identifier for file persistence.
    private final int
    maxSize
    Maximum number of characters to retain in the buffer.
    private File
    projectDir
    Optional project directory for log file location.
    private final StringBuilder
    sb
    Internal buffer for retained log content.
    private long
    startTime
    Start time in milliseconds since epoch.
    private int
    totalLength
    Total number of characters ever appended.
    private boolean
    truncated
    Flag indicating whether truncation has occurred.

  • 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 String folder
      Name of the directory where log files are stored.

      This directory is typically used as the parent location for all log files.

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

    • maxSize

      private final int maxSize
      Maximum number of characters to retain in the buffer.

    • sb

      private final StringBuilder sb
      Internal buffer for retained log content.

    • truncated

      private boolean truncated
      Flag indicating whether truncation has occurred.

    • logId

      private final String logId
      Optional log identifier for file persistence.

    • projectDir

      private File projectDir
      Optional project directory for log file location.

    • totalLength

      private int totalLength
      Total number of characters ever appended.

    • startTime

      private long startTime
      Start time in milliseconds since epoch.

  • 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 log file
      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 - the directory beneath the runtime temporary directory
      logId - the log identifier used as the file name
      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