Class SlotLogFile

java.lang.Object
com.iizix.log.SlotLogFile

public final class SlotLogFile extends Object
A log file of a running program in a numbered slot of a directory: <prefix>-1.log to <prefix>-<slots>.log, UTF-8 without a byte order mark.

The slot. When a file is opened, the slot whose file is the oldest by last write, or does not exist, is created or overwritten. The running program holds an exclusive lock on its file, so a slot another running program holds is skipped; when every numbered slot is held, <slots>+1, <slots>+2, ... are tried until one can be created or overwritten.

The lock. The lock covers ONE byte at LOCK_POSITION, far past any content: on Windows a file lock is mandatory and another process cannot read a locked range, so a lock over the content would keep the user's text editor out of the file. A second program that tries the same byte gets no lock (tryLock answers null, or OverlappingFileLockException in the same JVM) and skips the slot.

One open file per process. The open file is held in a static: open(File, String, int, long, List) closes the file open at the time before it opens the new one, so two are never open at once, and getCurrent() answers the file of the process. The file is otherwise closed by the end of the process; its user flushes after every batch, so the file is complete at any time, and the operating system releases the lock.

The size limit. The user checks isOverSize() after a flush and calls continueInNextSlot(List): the file ends with a line saying that the log continues in the next slot file, is closed, and the next slot (the same rules, this file excluded) is opened with a header line naming the file it continues.

The methods of an instance are called by the one thread that writes the log; the statics are safe to call from any thread.

Author:
Christopher Mindus
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    The line written at the end of a file that reached its size limit.
    static final long
    The position of the one byte the exclusive lock covers.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Closes the file: flushes the writer, releases the lock and closes the channel.
    Ends this file with the line CONTINUES, closes it and opens the next slot (the same rules, this file excluded) with the same prefix, slot count and size limit.
    void
    Flushes the writer to the file.
    Gets the log file open in this process.
    Gets the file.
    boolean
    Checks if the file is open.
    boolean
    Checks if the file has reached its size limit (what is flushed counts).
    open(File dir, String prefix, int slots, long maxSize, List<String> header)
    Opens a log file in a slot of the directory, closing the file open in this process first.
    void
    write(String text)
    Writes a text as it is: no line separator is added.
  • Field Details

    • LOCK_POSITION

      public static final long LOCK_POSITION
      The position of the one byte the exclusive lock covers.
      See Also:
    • CONTINUES

      public static final String CONTINUES
      The line written at the end of a file that reached its size limit.
      See Also:
  • Method Details

    • open

      public static SlotLogFile open(File dir, String prefix, int slots, long maxSize, List<String> header) throws IOException
      Opens a log file in a slot of the directory, closing the file open in this process first. The file starts with a header: its own path, the start time in UTC and local time, then the lines given, then an empty line.
      Parameters:
      dir - The directory, created if missing.
      prefix - The file name prefix, e.g. iiziGo-console for iiziGo-console-1.log.
      slots - The count of numbered slots, at least 1.
      maxSize - The size limit in bytes for isOverSize(), zero for none.
      header - The header lines written after the path and the time, may be empty.
      Returns:
      The open file, also answered by getCurrent().
      Throws:
      IOException - If the directory cannot be created, no slot can be opened or the header cannot be written; the file open before is closed in every case.
    • getCurrent

      public static SlotLogFile getCurrent()
      Gets the log file open in this process.
      Returns:
      The open file, or null for none.
    • getFile

      public File getFile()
      Gets the file.
      Returns:
      The file, absolute.
    • isOpen

      public boolean isOpen()
      Checks if the file is open.
      Returns:
      true while open, false once closed.
    • write

      public void write(String text) throws IOException
      Writes a text as it is: no line separator is added.
      Parameters:
      text - The text.
      Throws:
      IOException - For write errors, or if the file is closed.
    • flush

      public void flush() throws IOException
      Flushes the writer to the file.
      Throws:
      IOException - For write errors, or if the file is closed.
    • isOverSize

      public boolean isOverSize()
      Checks if the file has reached its size limit (what is flushed counts).
      Returns:
      true when the limit is set and the file is at or past it.
    • continueInNextSlot

      public SlotLogFile continueInNextSlot(List<String> header) throws IOException
      Ends this file with the line CONTINUES, closes it and opens the next slot (the same rules, this file excluded) with the same prefix, slot count and size limit.
      Parameters:
      header - The header lines of the new file, written after the path, the time and the line naming this file.
      Returns:
      The new open file, also answered by getCurrent().
      Throws:
      IOException - If this file cannot be ended or the next cannot be opened; this file is closed in every case.
    • close

      public void close()
      Closes the file: flushes the writer, releases the lock and closes the channel. A closed file stays closed; closing it again does nothing. When this is the file of the process, getCurrent() answers null afterwards.