Package org.apache.juneau.terminal.region

Class FileTerminalSource

java.lang.Object
org.apache.juneau.terminal.region.FileTerminalSource
All Implemented Interfaces:
AutoCloseable, TerminalSource
public final class FileTerminalSource extends Object implements TerminalSource, AutoCloseable
A TerminalSource that tails one growing log file of raw terminal bytes.

Size. The producer's cols×rows come from the sidecar <log>.size, which holds {"cols":C,"rows":R}. While it is missing or malformed the size is DEFAULT_COLS× DEFAULT_ROWS and one warning is logged; the first valid read is kept, since the sidecar is written once.

Done. The source is done when the terminal supplier says so and the reader has reached the end. Gone. A log that existed and then disappears answers a gone, done, empty chunk whose next and end are the requested offset.

Nudges. nudges(String, TerminalNudgePublisher) starts a daemon watcher that publishes when the file grows. A source has no process exit, so it never publishes a done nudge: the page's polling already sees done through the terminal supplier. Call close() to stop the watcher.

Path safety. The application supplies the Path; nothing in a request ever becomes a path.

Example:

FileTerminalSource src = FileTerminalSource.create(dir.resolve("run.log")) .terminal(() -> run.isFinished()) .build();

  • Field Details

  • Method Details

    • create

      public static FileTerminalSource.Builder create(Path file)
      Creates a builder.
      Parameters:
      file - The log file, supplied by the application.
      Returns:
      A new builder.

    • file

      public Path file()
      The log file.
      Returns:
      The path given to create(Path).

    • nudges

      public FileTerminalSource nudges(String terminalId, TerminalNudgePublisher publisher)
      Reports growth of the file to a publisher.

      Starts a daemon thread named juneau-terminal-nudge-file-<name> that checks the file size every 100 ms and calls the publisher with the new end when it has grown. A file that is missing or has shrunk publishes nothing and the watcher keeps going. A RuntimeException thrown by the publisher is logged at FINE and otherwise ignored. No done nudge is ever published, since the source does not know when the producer finishes; polling covers it. close() stops the thread.

      Parameters:
      terminalId - The terminal id passed to the publisher; must be a valid run id.
      publisher - The publisher.
      Returns:
      This object.
      Throws:
      NullPointerException - If an argument is null.
      IllegalArgumentException - If the id is not a valid run id.
      IllegalStateException - If a publisher is already set, or this source has been closed.

    • close

      public void close()
      Stops the nudge thread, if any, and waits up to 1000 ms for it.

      Reads keep working after this; only nudges(String, TerminalNudgePublisher) is refused.

      Specified by:
      close in interface AutoCloseable

    • read

      public TerminalChunk read(long fromOffset, int maxBytes) throws IOException
      Description copied from interface: TerminalSource
      Reads up to maxBytes bytes starting at fromOffset.

      When fromOffset equals the end, the chunk is empty. When it is past the end, the chunk is empty, its next is its end, and that is below fromOffset, which the endpoint answers with 416. When it is no longer held, the chunk is truncated and starts at the oldest offset held. When the backing store has disappeared, the chunk is empty and gone, with next and end equal to fromOffset.

      Specified by:
      read in interface TerminalSource
      Parameters:
      fromOffset - The offset to read from, at least 0.
      maxBytes - The most bytes to return, clamped to 0-TerminalSource.MAX_READ_BYTES.
      Returns:
      The chunk.
      Throws:
      IOException - If the backing store could not be read.