Package com.arc_e_tect.gradle.apionly.subscriber

Class Lockfile

java.lang.Object
com.arc_e_tect.gradle.apionly.subscriber.Lockfile
public final class Lockfile extends Object
apionly.lock -- what this project is actually building against. Committed, and recording per target the resolved version, the channel it came from, and the SHA-256 of every fetched file. That is the verbatim guarantee: `verifyApiSpec` re-hashes and fails when anything drifted, whether because a generated file was hand-edited or because a tag was moved under the build's feet. Run it in CI and contract drift becomes a build failure rather than a production surprise. The format is deliberately a small, sorted, line-oriented text file rather than JSON: it is read by people in review far more often than by machines, and a one-line diff should mean one thing changed.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    Lockfile.Entry
    What is locked for one target.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    FORMAT_VERSION
    The format this class reads and writes.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Lockfile()
    Creates an empty lockfile.

  • Method Summary

    Modifier and Type
    Method
    Description
    Lockfile.Entry
    get(String target)
    The entry for one target.
    void
    put(Lockfile.Entry entry)
    Adds or replaces the entry for a target.
    static Lockfile
    read(File file)
    Reads a lockfile, or returns an empty one if it does not exist.
    static String
    sha256(File file)
    The SHA-256 of a file, lowercase hexadecimal.
    List<String>
    targets()
    Every target with an entry, in sorted order.
    void
    write(File file)
    Writes the lockfile, with targets and their files in sorted order.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • FORMAT_VERSION

      public static final int FORMAT_VERSION
      The format this class reads and writes. Bumped only when the format changes.
      See Also:

  • Constructor Details

    • Lockfile

      public Lockfile()
      Creates an empty lockfile.

  • Method Details

    • read

      public static Lockfile read(File file)
      Reads a lockfile, or returns an empty one if it does not exist.

      A missing file is an ordinary first-run state, not an error: a project that has never fetched anything has nothing locked yet.

      Parameters:
      file - the lockfile to read
      Returns:
      the parsed lockfile, empty if the file is absent
      Throws:
      UncheckedIOException - if the file exists but cannot be read

    • write

      public void write(File file)
      Writes the lockfile, with targets and their files in sorted order.

      The ordering matters: this file is read in review far more often than by a machine, and a one-line diff should mean one thing changed rather than a reordering.

      Parameters:
      file - where to write
      Throws:
      UncheckedIOException - if it cannot be written

    • get

      public Lockfile.Entry get(String target)
      The entry for one target.
      Parameters:
      target - the contract to look up
      Returns:
      its entry, or null if nothing is locked for it

    • put

      public void put(Lockfile.Entry entry)
      Adds or replaces the entry for a target.
      Parameters:
      entry - what to record

    • targets

      public List<String> targets()
      Every target with an entry, in sorted order.
      Returns:
      the locked target names

    • sha256

      public static String sha256(File file)
      The SHA-256 of a file, lowercase hexadecimal.
      Parameters:
      file - the file to hash
      Returns:
      its digest as 64 hexadecimal characters
      Throws:
      UncheckedIOException - if the file cannot be read