Class RetirementAwareNodeTree<N extends HistoricalNode>

Type Parameters:
N - the node type.
All Implemented Interfaces:
Serializable

public abstract class RetirementAwareNodeTree<N extends HistoricalNode> extends HistoricalNodeTree<N>
A HistoricalNodeTree that propagates retirement up the path hierarchy. When a leaf is registered or its retirement state changes, it retires every implicit-folder ancestor whose children are all retired, and un-retires every retired implicit-folder ancestor that has an active child.

Backends supply isImplicit(HistoricalNode) (default false), retireMutation(HistoricalNode) and unretireMutation(HistoricalNode).

Thread-safe: mutations serialize through the tree's write lock and reads through its read lock. Methods ending in Unlocked require the caller to hold the write lock.

See Also:
  • Constructor Details

  • Method Details

    • registerNode

      public void registerNode(N node)
      Registers a leaf node at its source path and refreshes retirement state on its ancestors, as one atomic operation.
      Parameters:
      node - the node to register.
    • registerNodeUnlocked

      public final void registerNodeUnlocked(N node)
      As registerNode(HistoricalNode); the caller must hold the write lock.
    • recursiveRetireWithParent

      public void recursiveRetireWithParent(N node)
      Retires a node and propagates retirement up the parent chain. The node must already carry a retirement timestamp and is not mutated. No propagation occurs if its parent is the root.
      Parameters:
      node - the retired node whose ancestors should be re-evaluated.
    • recursiveRetireWithParentUnlocked

      public final void recursiveRetireWithParentUnlocked(N node)
      As recursiveRetireWithParent(HistoricalNode); the caller must hold the write lock.
    • recursiveRetireWithParent

      public void recursiveRetireWithParent(QualifiedPath path)
      Retires each ancestor of path whose children are all retired, up to the root.
      Parameters:
      path - the path whose ancestors should be re-evaluated.
    • recursiveRetireWithParentUnlocked

      public final void recursiveRetireWithParentUnlocked(QualifiedPath path)
      As recursiveRetireWithParent(QualifiedPath); the caller must hold the write lock.
    • updateParentRetirementState

      public void updateParentRetirementState(N node)
      Re-evaluates retirement state up the node's parent chain: retiring ancestors if the node is retired, un-retiring them otherwise.
      Parameters:
      node - the leaf node whose retirement state may have changed.
    • updateParentRetirementStateUnlocked

      public final void updateParentRetirementStateUnlocked(N node)
      As updateParentRetirementState(HistoricalNode); the caller must hold the write lock.
    • recursiveUnretireWithParent

      public void recursiveUnretireWithParent(QualifiedPath path)
      Un-retires each retired implicit-folder ancestor of path that has an active child, up to the root.
      Parameters:
      path - the path whose ancestors should be re-evaluated.
    • recursiveUnretireWithParentUnlocked

      public final void recursiveUnretireWithParentUnlocked(QualifiedPath path)
      As recursiveUnretireWithParent(QualifiedPath); the caller must hold the write lock.
    • isImplicit

      protected boolean isImplicit(N node)
      Returns whether a node is a synthetic implicit-folder placeholder. false by default; backends that synthesize folder nodes override.
      Parameters:
      node - the candidate node; never null.
      Returns:
      true for an implicit-folder node.
    • retireMutation

      protected abstract N retireMutation(N node)
      Returns a retired copy of the node, without mutating it.
      Parameters:
      node - the node to retire; never null.
      Returns:
      the retired copy.
    • unretireMutation

      protected abstract N unretireMutation(N node)
      Returns an un-retired copy of the node, without mutating it.
      Parameters:
      node - the node to un-retire; never null.
      Returns:
      the un-retired copy.