Class AbstractStorageEngine

java.lang.Object
com.inductiveautomation.historian.gateway.api.storage.AbstractStorageEngine
All Implemented Interfaces:
BatchedStorageWriter, StorageEngine
Direct Known Subclasses:
TagHistoryStorageEngineBridge

public abstract class AbstractStorageEngine extends Object implements StorageEngine, BatchedStorageWriter
Base class for storage engines. Validates availability and point types, routes points through the PointStorageStrategy, and dispatches each point family to the backend's doStore* and apply* methods.

Backends implement doStoreAtomic(List, Set), applySourceChanges(List, Set) and getActiveNodesForSystemRename(String), and may register handlers for further complex and change point types in registerHandlers(ComplexPointRegistry.Builder, ChangePointRegistry.Builder).

  • Field Details

  • Constructor Details

  • Method Details

    • storeAtomic

      public final CompletionStage<StorageResult<AtomicPoint<?>>> storeAtomic(List<AtomicPoint<?>> atomicPoints)
      Description copied from interface: StorageEngine
      Stores atomic points asynchronously.
      Specified by:
      storeAtomic in interface StorageEngine
      Parameters:
      atomicPoints - the points to store
      Returns:
      a stage completing with the per-point outcome
    • applyChanges

      public final <C extends ChangePoint<?>> CompletionStage<StorageResult<C>> applyChanges(List<C> changePoints)
      Description copied from interface: StorageEngine
      Applies change points asynchronously.
      Specified by:
      applyChanges in interface StorageEngine
      Type Parameters:
      C - the change point type
      Parameters:
      changePoints - the changes to apply, not null
      Returns:
      a stage completing with the per-point outcome
    • storeComplex

      public final <C extends ComplexPoint<?>> CompletionStage<StorageResult<C>> storeComplex(List<C> complexPoints)
      Description copied from interface: StorageEngine
      Stores complex points asynchronously.
      Specified by:
      storeComplex in interface StorageEngine
      Type Parameters:
      C - the complex point type
      Parameters:
      complexPoints - the points to store, not null
      Returns:
      a stage completing with the per-point outcome
    • writeBatch

      public <P extends TemporalPoint<?,?>> CompletionStage<StorageResult<P>> writeBatch(TemporalPointBatch<P> batch)
      Writes a pre-coalesced batch directly, bypassing the PointStorageStrategy queue; for pre-batched callers such as bulk ingest. Availability checks and metrics apply, but per-point type validation is skipped because a TemporalPointBatch holds a single point type. Split mixed input with TemporalPointBatch.partition(List, SortHint).

      The returned stage carries every outcome, including an unchecked backend exception; only an Error propagates out of the call.

      Specified by:
      writeBatch in interface BatchedStorageWriter
      Type Parameters:
      P - the temporal-point subtype of the batch
      Parameters:
      batch - the batch to write; non-null and non-empty
      Returns:
      a stage resolving to the outcome for this batch
    • storeBatchNow

      protected final StorageResult<?> storeBatchNow(TemporalPointBatch<?> batch)
      Stores batch on the calling thread through the same dispatch as writeBatch(TemporalPointBatch), timed and metered, without the availability gate; does not complete batch.result().
    • batchWriter

      public Optional<BatchedStorageWriter> batchWriter()
      Description copied from interface: StorageEngine
      Returns this engine's batched write path, which bypasses the debounce queue. Callers that have already coalesced their points (bulk ingest, replays) should prefer it over StorageEngine.storeAtomic(List), StorageEngine.storeComplex(List) and StorageEngine.applyChanges(List), which may re-enter the debounce queue. Callers fall back to those methods when it is empty.
      Specified by:
      batchWriter in interface StorageEngine
      Returns:
      the batched writer, or empty if this engine has none
    • supportedComplexTypes

      public Set<? extends ComplexPointType> supportedComplexTypes()
      Returns the complex point types this engine can store.
    • registerHandlers

      protected void registerHandlers(ComplexPointRegistry.Builder complex, ChangePointRegistry.Builder change)
      Registers handlers for the complex and change point types this engine accepts. Called once from the constructor; the registries are immutable afterwards. The default registers annotation and metadata (complex) and source-change and annotation-change (change) handlers, so overrides should call super first:
      protected void registerHandlers(ComplexPointRegistry.Builder complex,
          ChangePointRegistry.Builder change) {
        super.registerHandlers(complex, change);
        complex.register(MyType, points -> myDoStoreMyType(points));
      }
      
    • doStoreComplex

      protected final <C extends ComplexPoint<?>> StorageResult<C> doStoreComplex(List<C> complexPoints)
    • doApplyChanges

      protected final <C extends ChangePoint<?>> StorageResult<C> doApplyChanges(List<C> changePoints)
    • stopProcessor

      protected void stopProcessor()
    • pauseProcessor

      protected void pauseProcessor()
    • resumeProcessor

      protected void resumeProcessor()
    • doStoreAnnotations

      protected StorageResult<AnnotationPoint> doStoreAnnotations(List<AnnotationPoint> annotationPoints, Set<AdaptedQualifiedPath> normalizedSources)
      Parameters:
      normalizedSources - source paths, pre-normalized to AdaptedQualifiedPath
    • doStoreMetadata

      protected StorageResult<MetadataPoint> doStoreMetadata(List<MetadataPoint> metadataPoints, Set<AdaptedQualifiedPath> normalizedSources)
      Parameters:
      normalizedSources - source paths, pre-normalized to AdaptedQualifiedPath
    • applyAnnotationChanges

      protected StorageResult<AnnotationChangePoint> applyAnnotationChanges(List<AnnotationChangePoint> annotationChangePoints, Set<AdaptedQualifiedPath> normalizedSources)
      Parameters:
      normalizedSources - source paths, pre-normalized to AdaptedQualifiedPath
    • getActiveNodesForSystemRename

      protected abstract Iterable<? extends HistoricalNode> getActiveNodesForSystemRename(String oldSystemName)
      Returns the active, non-implicit nodes parented under the old system name, for onSystemNameUpdate(String, String). Backends without rename support return List.of() with a comment saying so. Called on the gateway's system-properties dispatch thread, so implementations must synchronize internally.
      Parameters:
      oldSystemName - the previous gateway system name (lowercased).
      Returns:
      the nodes under sys:<oldSystemName>; never null.
    • runWithRenameExclusion

      protected void runWithRenameExclusion(Runnable renameAction)
      Runs the rename work with this engine's point-storage path excluded. The default runs it inline. Engines whose node identity is a path carrying the system name must override this, or a flush mid-rename can mint a second node for a tag that already has one. Points flushed between the new name being written and this hook being dispatched are not covered; quiesce ingest first if that matters.
      Parameters:
      renameAction - the cache invalidation and rename work to run.
    • definitionResolver

      protected @Nullable AbstractDefinitionResolver<?> definitionResolver()
      Returns this engine's long-lived definition resolver so a rename can clear its caches, or null (the default) if the engine builds one per operation. An engine whose definition write is not idempotent must return null, because the clear can make an in-flight batch write a second definition row.
      Returns:
      the resolver, or null.
    • handleSystemNameUpdate

      protected void handleSystemNameUpdate(String oldSystemName, String newSystemName)
      Applies a system-name change to the stored nodes. The default issues a SourceChangePoint per active node under the old name, one round trip each. Engines that store the system apart from the node path, or do not support rename, override this without calling super.
      Parameters:
      oldSystemName - the previous gateway system name (lowercased).
      newSystemName - the new gateway system name (lowercased).
    • applySourceChanges

      protected abstract StorageResult<SourceChangePoint> applySourceChanges(List<SourceChangePoint> sourceChangePoints, Set<AdaptedQualifiedPath> normalizedSources)
      Parameters:
      normalizedSources - source paths, pre-normalized to AdaptedQualifiedPath
    • doStoreAtomic

      protected abstract StorageResult<AtomicPoint<?>> doStoreAtomic(List<AtomicPoint<?>> atomicPoints, Set<AdaptedQualifiedPath> normalizedSources)
      Parameters:
      normalizedSources - source paths, pre-normalized to AdaptedQualifiedPath
    • normalizePath

      protected AdaptedQualifiedPath normalizePath(QualifiedPath path)
      Normalizes a path to an AdaptedQualifiedPath, caching the result per source path.
    • isEngineUnavailable

      protected final boolean isEngineUnavailable()
      Returns whether the owning historian is unavailable; DEGRADED does not count.
      Returns:
      true if storage should not be attempted.
    • acceptsWhileUnavailable

      protected boolean acceptsWhileUnavailable()
      Returns whether points submitted while unavailable still go to the storage strategy rather than being refused; override to true when the strategy can absorb them. writeBatch(TemporalPointBatch) is always refused while unavailable.
      Returns:
      true to accept points while unavailable.
    • ingestTelemetry

      public Optional<IngestTelemetry> ingestTelemetry()
      Returns the observed ingest rate joined with the storage strategy's flush shape; empty if the strategy does not flush in batches.
      Returns:
      the observed ingest, or empty if there is none to report
    • onHistorianRename

      protected void onHistorianRename(String oldName, String newName)
    • shutdownStorageMetrics

      protected void shutdownStorageMetrics(String name)