Package com.ultikits.ultitools.config.document

Class OperatorFileWriter.Staged

java.lang.Object
com.ultikits.ultitools.config.document.OperatorFileWriter.Staged
Enclosing class:
OperatorFileWriter
public static final class OperatorFileWriter.Staged extends Object
A verified write whose content is staged and not yet published - or, when nothing needed staging, the write's settled result. Publishing re-reads the target under the lock every load and write holds, immediately before the replacement, and replaces it only while it still holds exactly the bytes the write was verified against (an edit saved while the content was being staged or while other files were being prepared is seen and kept: review round 1 IN-01, plan 17-65); a file the gate read absent is created exclusively, never replacing one that appeared.

A commit ends in one of three states, and restore() acts only on bytes the write still owns in that state (#673: a failed commit grants no permission to bypass the file-ownership check):

  • published - the target was replaced or created; the file holds this write's bytes until someone else writes it.
  • unpublished - nothing was replaced: the file changed or appeared before the commit, or the commit failed with any failure other than AtomicConfigWriter.RestoreFailedException. AtomicConfigWriter then leaves the target holding exactly what it held (a failed move, a failure before the target was opened, a failed in-place write that was put back from its backup) and a failed creation creates nothing, so no byte of this write is on disk and the file belongs to whoever writes it next - an operator's save included.
  • not put back - the in-place write failed after the target was opened and putting it back failed too (AtomicConfigWriter.RestoreFailedException): the target may hold part of this write, its backup is kept and one SEVERE names both. Only the operator decides what the file should hold; nothing here writes or deletes it again.

  • Field Details

    • settled

      private final OperatorFileWriter.Result settled

    • file

      private final Path file

    • absolute

      private final Path absolute

    • owned

      private final OwnedPaths owned

    • keys

      private final List<String> keys

    • rendered

      private final String rendered

    • candidate

      private final ConfigDocument candidate

    • read

      private final String read

    • readText

      private final String readText

    • temporary

      private final AtomicConfigWriter.StagedWrite temporary

    • finished

      private boolean finished

    • published

      private boolean published
      Whether this write replaced or created the target (the published state).

    • notPutBack

      private boolean notPutBack
      Whether the commit failed with AtomicConfigWriter.RestoreFailedException: the target may hold part of this write and its backup is kept (the not-put-back state). Set only from that exception; every other failure leaves the write unpublished with no byte of it on disk.

  • Constructor Details

  • Method Details

    • settled

      static OperatorFileWriter.Staged settled(OperatorFileWriter.Result result)

    • isPending

      public boolean isPending()
      Whether verified content is staged and waits for commit().
      Returns:
      false when the write was settled without staging (refused, file changed, or unchanged)

    • readText

      public String readText()
      The text the staged content was verified against - exactly what the file held when the gate read it - so a caller undoing a published write can put back precisely those bytes.
      Returns:
      the text read, or null when the file was absent or nothing is staged

    • settledResult

      public OperatorFileWriter.Result settledResult()
      The settled result of a write that needed no staging, or null while content is staged.
      Returns:
      the result or null

    • commit

      public OperatorFileWriter.Result commit() throws IOException
      Publishes the staged content when the target still holds exactly the bytes the write was verified against (or, for a file the gate read absent, while no file exists there); otherwise the staged file is released and the result is OperatorFileWriter.Outcome.FILE_CHANGED, logged once. A write that needed no staging returns its settled result. A staged write is committed at most once.

      The exception AtomicConfigWriter throws decides the state a failed commit leaves (class description): a AtomicConfigWriter.RestoreFailedException records that the target was not put back; any other failure leaves the write unpublished. The failure is rethrown unchanged either way.

      Returns:
      the outcome: OperatorFileWriter.Outcome.WRITTEN when published
      Throws:
      IOException - if the replacement or the creation fails (the target is then as AtomicConfigWriter leaves it)

    • restore

      public boolean restore() throws IOException
      Undoes this write after its batch failed, acting only on bytes the write still owns (class description, #673):
      • unpublished - nothing is read, written or deleted: no byte of this write is on disk, so whatever the file holds now, an operator's save made while the batch was failing included, is kept;
      • not put back - the file is read under the lock and never written or deleted: the SEVERE the failed put-back logged, the kept backup and the entity's "changed since it was read" protection until a reload stand, and the operator decides what the file holds;
      • published - the text the write was verified against is put back (or the file it created removed) through the same last-moment check as the commit, only while the file still holds exactly what this write put there. A file that changed after this write replaced it - an operator's save - is kept as it is, and one WARNING names it (17-65 review round 1 R65-I3).
      Returns:
      whether the file now holds what it held before this write (also when nothing needed undoing); after a failed put-back, true only when the file holds exactly those bytes again
      Throws:
      IOException - if reading the file or putting the text back fails

    • discard

      public boolean discard()
      Releases staged content that will not be committed; nothing on disk other than the staged temporary file is touched. Does nothing after commit() or for a settled write.
      Returns:
      whether no staged temporary file is left behind