Interface WalkConsumer

public interface WalkConsumer
The walk half of the two-route derived-metadata contract. A plugin keeps its derived state correct by exactly two routes, and a correct plugin implements both: live events (PublicationObserver's onPublished / onDeleted) for the steady state, and the full walk - this interface - for first-activation back-fill, periodic refresh and self-heal. A scheduled walk pass (RebuildPass) drives every discovered consumer from one enumeration, so N metadata rebuilders never mean N tree walks. The walk alone must be able to fully rebuild the plugin's derived state from the durable store wherever the truth model permits; where a surface genuinely cannot be re-derived (a human decision, a point-in-time observation), the plugin's documentation names it and the plugin degrades gracefully rather than serving a silently-incomplete view as if it were whole.

onRetained(ArtifactDescriptor, ArtifactStore) is called once per retained artifact per pass - and, across a crash-resume, at least once for the uncommitted stride tail - so it must be idempotent (upsert / re-judge semantics). A streaming consumer (a reconcile leg, a sidecar heal, a per-shard index) simply resumes mid-pass with the segment cursor; a snapshot rebuilder (one artifact committed at pass end) restarts its own accumulation after a crash and says so - degrade-and-say-so is recorded per consumer, never silent.

  • Method Summary

    Modifier and Type
    Method
    Description
    static List<WalkConsumer>
    discovered()
    Every enabled consumer discovered via ServiceLoader (a parallel SPI: a jenesis.repository.<name>=false skips one, Features), in discovery order - what the scheduled walk pass drives from its one enumeration.
    String
    name()
    The consumer's name - its signal and settings namespace, and its walks/<name>/ pass-state scope.
    default void
    onPassCompleted(WalkPass pass)
    The pass enumerated everything - the commit / compact / heal hook for a consumer that acts at pass end.
    default void
    onPassStarted(WalkPass pass)
    The pass is starting - the moment a snapshot rebuilder resets its accumulation.
    void
    onRetained(build.jenesis.repository.store.ArtifactDescriptor artifact, build.jenesis.repository.store.ArtifactStore store)
    One retained artifact, visited in total key order; must be idempotent per artifact (see the class contract for the exactly-once-per-pass / at-least-once-across-a-crash delivery semantics).

  • Method Details

    • name

      String name()
      The consumer's name - its signal and settings namespace, and its walks/<name>/ pass-state scope.

    • onRetained

      void onRetained(build.jenesis.repository.store.ArtifactDescriptor artifact, build.jenesis.repository.store.ArtifactStore store) throws IOException
      One retained artifact, visited in total key order; must be idempotent per artifact (see the class contract for the exactly-once-per-pass / at-least-once-across-a-crash delivery semantics).
      Throws:
      IOException

    • onPassStarted

      default void onPassStarted(WalkPass pass)
      The pass is starting - the moment a snapshot rebuilder resets its accumulation.

    • onPassCompleted

      default void onPassCompleted(WalkPass pass)
      The pass enumerated everything - the commit / compact / heal hook for a consumer that acts at pass end.

    • discovered

      static List<WalkConsumer> discovered()
      Every enabled consumer discovered via ServiceLoader (a parallel SPI: a jenesis.repository.<name>=false skips one, Features), in discovery order - what the scheduled walk pass drives from its one enumeration.