Package com.inductiveautomation.historian.gateway.api.storage


package com.inductiveautomation.historian.gateway.api.storage
The storage half of the historian SPI: how a backend turns incoming points into stored nodes, and the base classes that hold behaviour every backend shares.

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

  1. AbstractHistorian's system-properties listener observes the new name, advances the path adapter, and calls the package-private AbstractStorageEngine.onSystemNameUpdate. It contains any exception so later listeners still receive the event.
  2. onSystemNameUpdate enters the engine's rename exclusion, drops the caches, and delegates to handleSystemNameUpdate.
  3. The backend's handleSystemNameUpdate does 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 call super.

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.