Package com.inductiveautomation.historian.gateway.api.storage
Who owns what
StorageEngine is the interface a
backend satisfies. AbstractStorageEngine is the base to
extend: it owns the handler registry, the normalized-path memo, and the lifecycle that must
behave identically on every backend. AbstractDefinitionResolver answers whether
a path already has a node, and which one. BatchScopedDefinitionCache stages nodes
written but not yet published, so a batch does not resolve the same new tag twice.
Path normalization depends on the gateway name
Every path entering a backend is normalized through the owning historian's QualifiedPathAdapter. A path with no
sys: component gets the gateway's current system name, so the same input normalizes differently
before and after the gateway is renamed. The storage engine's normalized-path cache, the
definition resolver's normalized-path cache and the batch-scoped cache all hold such values and
are dropped on rename.
Rename handling
AbstractHistorian's system-properties listener observes the new name, advances the path adapter, and calls the package-privateAbstractStorageEngine.onSystemNameUpdate. It contains any exception so later listeners still receive the event.onSystemNameUpdateenters the engine's rename exclusion, drops the caches, and delegates tohandleSystemNameUpdate.- The backend's
handleSystemNameUpdatedoes the stored-node work. The default walks the active nodes under the old system path and issues a source change per node; a backend that stores the system name outside the node path overrides it and does not callsuper.
onSystemNameUpdate is package-private on purpose: a backend in another package that
declares the same signature adds a new method instead of overriding it, so the cache invalidation
cannot be skipped. Do not widen it.
Extending this package
Override handleSystemNameUpdate, never onSystemNameUpdate. Override
runWithRenameExclusion if node identity is a path carrying the system name, so a concurrent
flush cannot mint a second node for a tag mid-walk. Return a resolver from
definitionResolver() only if it outlives a single operation and its definition write is
idempotent: the rename hook clears its staging cache, which can cost one duplicate definition
write per batch in flight.
Thread-safety
Rename hooks run on the gateway's system-properties dispatch thread; point storage runs on threads from the historian's execution manager. The two are concurrent unless a backend supplies an exclusion. Other types in this package document their own guarantees.
-
ClassDescriptionBase class for a storage engine's definition resolver.A normalized path and its staging-cache key.AbstractHistorian<S extends HistorianSettings>Base class for historian implementations.Base class for storage engines.Per-batch state carried through the definition-resolver call chain, tracking the staging-cache keys the batch has staged.Batching layer over
AbstractDefinitionResolver.Thread-safe accumulator of one flush's pending definition writes, deduplicated by path.The resolver could not produce a usable node (implicit id).The outcome of a definition flush.A write was buffered; the node's id is known after the flush.The accumulated definition work for one path in one flush: a retire, an upsert, or both.The node already carries a real id.Capability of a storage engine that accepts pre-coalesced batches of temporal points and writes them directly, bypassing the debounce or coalesce queue used for realtime arrivals.BatchScopedDefinitionCache<N extends HistoricalNode>Engine-scoped staging cache for newly createdHistoricalNodedefinitions whose batch has not yet committed: the union of the staged definitions of all in-flight batches.Per-engine registry that maps eachChangePointTypeto the handler accepting a homogeneous batch of change points of that type.Builder used inAbstractStorageEngine.registerHandlers(ComplexPointRegistry.Builder, ChangePointRegistry.Builder);ChangePointRegistry.Builder.build()produces the immutable registry.Per-engine registry that maps eachComplexPointTypeto the handler accepting a homogeneous batch of points of that type.Builder used inAbstractStorageEngine.registerHandlers(ComplexPointRegistry.Builder, ChangePointRegistry.Builder);ComplexPointRegistry.Builder.build()produces the immutable registry.What a running historian's ingest has been doing: the rate points are stored at, joined with the shape of the flushes storing them.A metered rate over the 1, 5 and 15 minute exponentially weighted windows.The case fold for every in-memory tag-path and gateway-name key: each code point goes throughCharacter.toUpperCase(int)thenCharacter.toLowerCase(int), independent of the JVM's locale.What aTemporalPointBatchmay assume about the ordering of the points it is given, relative toTemporalPoint's natural ordering (timestamp ascending).Backing storage for atomic, complex and change points, written byDataCollectorsessions and by pre-batched writers.A batch of points of one type, with the future that completes with their storage result.