Package io.jenkins.plugins.configsplice.engine

Class SourceDocument

java.lang.Object
io.jenkins.plugins.configsplice.engine.SourceDocument
public final class SourceDocument extends Object
An immutable in-memory view of one configuration file: its original bytes, its BOM state, and its decoded text.

This class owns the only byte/character boundary in the engine. Locators work purely in char offsets against text(); render(String) turns spliced text back into bytes with the original BOM restored.

Decoding is strict on purpose. The default new String(bytes, UTF_8) silently replaces malformed sequences with U+FFFD, which would mean writing back a file whose untouched bytes had changed — a direct violation of the exact-preservation guarantee (SRS section 10.4) and a plausible way to corrupt a config file the plugin was only supposed to read.

  • Method Details

    • of

      public static SourceDocument of(byte[] bytes) throws SpliceException
      Detects the encoding, admits only UTF-8, and decodes strictly.
      Throws:
      SpliceException - ErrorCode.UNSUPPORTED_ENCODING for a non-UTF-8 BOM or malformed UTF-8

    • text

      public String text()
      The decoded document text, excluding any BOM.

    • bom

      public EncodingSupport.Bom bom()

    • originalBytes

      public byte[] originalBytes()
      The original file bytes exactly as read, including any BOM.

    • render

      public byte[] render(String newText)
      Re-encodes newText to bytes, restoring the original BOM.

      Rendering the unmodified text() must reproduce originalBytes() exactly; rendersIdentically() asserts that round-trip and is exercised by every fixture.

    • rendersIdentically

      public boolean rendersIdentically()
      True when decoding and re-encoding the document is byte-exact.

      Strict decoding should make this unconditionally true for every document we accept; it is asserted rather than assumed because it underpins the exact-preservation oracle.