Package com.ultikits.ultitools.config.document
@Internal
package com.ultikits.ultitools.config.document
The config storage layer: a config file as a document over SnakeYAML's node tree, the plain-data
boundary every value crosses before it reaches a file, the configuration write gate
(
OperatorFileWriter) every write to an operator-editable configuration file goes through, and the
atomic writer that publishes what the gate verified.
The contract (maintainer rule of 2026-10-04): configuration an operator wrote is never overwritten automatically. Each write owns named keys (or the framework's own comment lines); after rendering, every byte outside them must equal the file as read and the file must still hold the bytes it was read from, otherwise nothing is written and one warning names the file, the keys and the reason (a line number for a layout the renderer cannot keep), never a value. No layout is normalized to make a write pass.
Framework-internal. Module authors use AbstractConfigEntity and the converter API; nothing
here is a module-facing contract.
- Since:
- 6.3.0
-
ClassDescriptionThe only way the config storage layer replaces a file.The file-system steps of a write and a load, as a seam for fault-injection tests.A backup this server run wrote, and the SHA-256 of the bytes it wrote there.Thrown when an in-place write failed after the target was opened and putting the target back from its framework backup failed too (#622): the target may hold part of the new content, and the backup holding its previous content is kept.A temporary file written beside its target and not yet moved over it.One config file as a document: SnakeYAML's own node tree (comments, quoting and layout as they are in the file) plus the plain-data view of its values, addressed by key arrays.One comment line to re-indent: where the reader found it, and what must be there for the move to apply.The two comment placements adjusted on read (see the class description).A section left with no value that a
ConfigDocument.set(java.util.List<java.lang.String>, java.lang.Object)made a section again, and the comment lines indented under it.ASafeConstructorthat constructs single nodes and flattens merge keys on request.Builds the plain-data view of a composed tree with Bukkit's key and value rules.Builds new nodes for plain values.What reading one config file found.The four outcomes of a load.Thrown byConfigDocument.parse(String)when a config file's text is not a document this layer reads: a YAML syntax error, a global tag such as!!java.util.UUID, a top level that is not a mapping, or nesting deeper than the limit.The layout facts of one config file that SnakeYAML's emitter needs to write the file the way it already looks.One pass over the composed tree, recording the first occurrence of each layout fact.The write gate for operator-editable config files: the one way the framework changes such a file automatically (maintainer decisions of 2026-10-04: "operator-written configuration is never overwritten automatically" and "what code may write, by file type").The owned paths the edit actually changed: values (inserted, set or removed) and comments.The sections an insert finds empty (#620, #610 item 2).What a write did.The outcome of one write, its one-phrase reason, and the document now on disk when there is one.One side of the comparison: its document, node tree, lines, nodes by line and owned-line marks.The file as the gate read it at write time, or why the write cannot start.A verified write whose content is staged and not yet published - or, when nothing needed staging, the write's settled result.The steps of a gated write that call into the YAML library, as the fault seam names them.What one write throughOperatorFileWritermay change in a config file: the value paths it sets, inserts or removes, the paths whose comment lines it rewrites, or - only when the file does not exist yet - the whole file.Collects owned paths; each path is copied, so later changes to the caller's list do not leak in.The plain-data boundary of the config storage layer.