Package io.jenkins.plugins.batchcontrol.security

Class ItemIdentity

java.lang.Object
io.jenkins.plugins.batchcontrol.security.ItemIdentity
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public final class ItemIdentity extends Object
security-13 S-13-09, D-80: the identity of an item's directory, recorded with an activation state so that a state left behind by a deleted item is not taken for a new item of the same name.

The identity is a random id kept in a marker file, ".batch-control-activation-id", inside the item's root directory. It is written the first time an activation state is stored or seeded for the item (ensure(java.io.File)) and read on every check (of(java.io.File)). Because it is part of the directory's content:

  • copying, restoring or remounting $JENKINS_HOME (new inodes, same content) keeps it, so activations survive a backup restore or a move to another volume;
  • a rename or move keeps it: core moves the directory, and its fallback copy (Ant's Copy with default excludes) does not exclude this name;
  • a job re-created under a deleted job's name, or created with Jenkins' copy (core copies only config.xml), has no marker until its own state is stored, with a new id.
A missing, unreadable or malformed marker gives no identity, and the caller counts the item as not activated (fail closed). Permission windows do not use it: they follow their item through item events (D-74, WindowItemListener).

The marker name starts with a dot and names the plugin, so it cannot collide with a file core or a job type keeps in an item directory (config.xml, nextBuildNumber, builds/, jobs/, configurations/, modules/, branches/, the atomic writer's atomic*.tmp); it is never read as configuration and never shown.

Reads are cached per marker path and revalidated with one stat (file key, modification time, size) and a readability check, so a check does not read the file again unless it changed; a marker that went missing or became unreadable is noticed on the next check.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    MARKER_FILE
    The marker file in an item's root directory (D-80).

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    ensure(File rootDir)
    The identity of rootDir, writing a marker with a new random id first when there is no readable one (a missing or malformed marker is replaced).
    static String
    of(File rootDir)
    The identity held by the marker in rootDir, or null when the directory or the marker does not exist, cannot be read, or does not hold an id.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • MARKER_FILE

      public static final String MARKER_FILE
      The marker file in an item's root directory (D-80).
      See Also:

  • Method Details

    • of

      @CheckForNull public static String of(@CheckForNull File rootDir)
      The identity held by the marker in rootDir, or null when the directory or the marker does not exist, cannot be read, or does not hold an id.

    • ensure

      @CheckForNull public static String ensure(@CheckForNull File rootDir)
      The identity of rootDir, writing a marker with a new random id first when there is no readable one (a missing or malformed marker is replaced). Called when an activation state is stored or seeded. null when the marker cannot be written or read back; the state stored with it then counts as not activated.