Class BatchScopedDefinitionCache<N extends HistoricalNode>

java.lang.Object
com.inductiveautomation.historian.gateway.api.storage.BatchScopedDefinitionCache<N>
Type Parameters:
N - the historical-node type
All Implemented Interfaces:
AutoCloseable

public final class BatchScopedDefinitionCache<N extends HistoricalNode> extends Object implements AutoCloseable
Engine-scoped staging cache for newly created HistoricalNode definitions whose batch has not yet committed: the union of the staged definitions of all in-flight batches.

A staged entry is evicted when its batch commits (the node is published to the node tree and the entry invalidated), when it rolls back (every key staged by the batch's BatchContext is invalidated), when a rename or retire invalidates the affected paths, or by a failsafe TTL sweep that backstops hung batches. After a rollback the definition row stays in the database, so later batches rediscover it.

Definition resolvers must seed the cache only through stage(String, HistoricalNode, BatchContext); there is no public put, so entries always have a lifecycle owner.

Thread-safe: stage, getNullable and invalidate may be called concurrently.

  • Field Details

    • DEFAULT_TTL

      public static final Duration DEFAULT_TTL
      Default failsafe TTL: the longest an in-flight batch is expected to take.
  • Constructor Details

    • BatchScopedDefinitionCache

      public BatchScopedDefinitionCache()
    • BatchScopedDefinitionCache

      public BatchScopedDefinitionCache(Duration ttl)
  • Method Details

    • stage

      public void stage(String key, N value, BatchContext ctx)
      Stages a node under key and records the key in ctx so commit or rollback can invalidate it.
    • getNullable

      public @Nullable N getNullable(String key)
      Returns the staged node for key, or null if none.
    • invalidate

      public void invalidate(String key)
      Removes the entry for key; does nothing if absent.
    • clear

      public void clear()
      Drops every staged entry, for invalidations no per-key hook can express, such as a gateway system rename.

      Not free: an in-flight batch that would have found a staged node resolves its key as absent and writes the definition again. Idempotent backends absorb that as a duplicate upsert; a backend with an append-only definitions table gains a duplicate row and must not call this while batches are in flight.

      Safe with respect to BatchContext: invalidating an already-absent key at commit or rollback does nothing.

    • size

      public int size()
      Returns the approximate number of staged entries.
    • close

      public void close()
      Specified by:
      close in interface AutoCloseable