Package io.jenkins.plugins.batchcontrol.ops

Class SnapshotSeeding

java.lang.Object
io.jenkins.plugins.batchcontrol.ops.SnapshotSeeding
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public final class SnapshotSeeding extends Object
Keeps the configuration snapshots (the CONFIGURE diff baselines, ARCHITECTURE section 5) in step with the items when change recording becomes active (SPEC item 9).
  • A switch turns recording on (no switch was on before): nothing kept the snapshots current while recording was off, so the snapshot of every item is refreshed to its current configuration, not only the missing ones. Otherwise a change made while recording was off would appear in the diff of whoever saves the item first, and an item created at a deleted item's name would be compared with the deleted item's configuration. The first 1000 items are refreshed on the calling thread, so the items of a usual instance are current when the switch change returns, the rest in the background. Until the refresh reaches an item, a save that changed it is recorded without a diff (ConfigSnapshotListener.Refresh).
  • Startup, after every item is loaded (InitMilestone.JOB_CONFIG_ADAPTED) and only while recording is active, in the background so startup is not delayed: the snapshots that are missing are seeded; existing ones are kept, because recording was on when Jenkins stopped. When a switch turned recording on while Jenkins started (JCasC applies its configuration before the items are loaded), recording was off in the configuration the previous run saved, so every snapshot is refreshed instead, as for a switch-on. Recording turned on by editing the saved configuration while Jenkins was stopped cannot be told apart from recording that stayed on: it gets the missing snapshots only.

Bounded work: a pass visits every item once. Seeding looks up whether an item's snapshot exists (one file system lookup) and reads the configuration only of an item that has none; a refresh reads the configuration and the snapshot of each item still waiting for it and writes only a snapshot that differs. There is no periodic scan: passes run only at startup and when recording becomes active, at most one runs in the background and at most one more waits for it (requests in between are folded into the one waiting, which works on the latest refresh). A pass stops when recording is switched off or a newer refresh starts. Each pass logs one summary line.

A save that comes before the seeding reached its item, or whose item could not be seeded, is recorded without a diff (ConfigSnapshotListener), so no change is lost meanwhile.

  • Method Details

    • atStartup

      @Initializer(after=JOB_CONFIG_ADAPTED) public static void atStartup()
      Startup: every item is loaded. Seeds the missing snapshots in the background when recording is active, or refreshes every snapshot when a switch turned recording on while Jenkins started. Switch changes made before this point (JCasC applies its configuration earlier) are covered by this pass.

    • recordingTurnedOn

      public static void recordingTurnedOn()
      A switch turned recording on (no switch was on before). Refreshes the snapshot of every item: on the calling thread up to 1000 items, the rest in the background. Before the startup pass of this session was decided it only notes the switch-on, and that pass refreshes. Never throws.