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).
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static final record -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final GatewayContextprotected Stringprotected final LoggerExprotected AbstractStorageEngine.StorageMetricsprotected final QualifiedPathAdapter -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedAbstractStorageEngine(GatewayContext gatewayContext, String historianName, LoggerEx logger, QualifiedPathAdapter pathAdapter, PointStorageStrategy storageStrategy, Supplier<AvailabilityState> availability) protectedAbstractStorageEngine(GatewayContext gatewayContext, String historianName, LoggerEx logger, QualifiedPathAdapter pathAdapter, Supplier<AvailabilityState> availability) protectedAbstractStorageEngine(GatewayContext gatewayContext, String historianName, LoggerEx logger, Supplier<AvailabilityState> availability) -
Method Summary
Modifier and TypeMethodDescriptionprotected booleanReturns whether points submitted while unavailable still go to the storage strategy rather than being refused; override totruewhen the strategy can absorb them.protected StorageResult<AnnotationChangePoint> applyAnnotationChanges(List<AnnotationChangePoint> annotationChangePoints, Set<AdaptedQualifiedPath> normalizedSources) final <C extends ChangePoint<?>>
CompletionStage<StorageResult<C>> applyChanges(List<C> changePoints) Applies change points asynchronously.protected abstract StorageResult<SourceChangePoint> applySourceChanges(List<SourceChangePoint> sourceChangePoints, Set<AdaptedQualifiedPath> normalizedSources) Returns this engine's batched write path, which bypasses the debounce queue.protected @Nullable AbstractDefinitionResolver<?> Returns this engine's long-lived definition resolver so a rename can clear its caches, ornull(the default) if the engine builds one per operation.protected final <C extends ChangePoint<?>>
StorageResult<C> doApplyChanges(List<C> changePoints) protected StorageResult<AnnotationPoint> doStoreAnnotations(List<AnnotationPoint> annotationPoints, Set<AdaptedQualifiedPath> normalizedSources) protected abstract StorageResult<AtomicPoint<?>> doStoreAtomic(List<AtomicPoint<?>> atomicPoints, Set<AdaptedQualifiedPath> normalizedSources) protected final <C extends ComplexPoint<?>>
StorageResult<C> doStoreComplex(List<C> complexPoints) protected StorageResult<MetadataPoint> doStoreMetadata(List<MetadataPoint> metadataPoints, Set<AdaptedQualifiedPath> normalizedSources) protected abstract Iterable<? extends HistoricalNode> getActiveNodesForSystemRename(String oldSystemName) Returns the active, non-implicit nodes parented under the old system name, foronSystemNameUpdate(String, String).protected voidhandleSystemNameUpdate(String oldSystemName, String newSystemName) Applies a system-name change to the stored nodes.Returns the observed ingest rate joined with the storage strategy's flush shape; empty if the strategy does not flush in batches.protected final booleanReturns whether the owning historian is unavailable;DEGRADEDdoes not count.protected AdaptedQualifiedPathnormalizePath(QualifiedPath path) Normalizes a path to anAdaptedQualifiedPath, caching the result per source path.protected voidonHistorianRename(String oldName, String newName) protected voidprotected voidregisterHandlers(ComplexPointRegistry.Builder complex, ChangePointRegistry.Builder change) Registers handlers for the complex and change point types this engine accepts.protected voidprotected voidrunWithRenameExclusion(Runnable renameAction) Runs the rename work with this engine's point-storage path excluded.protected voidshutdownStorageMetrics(String name) protected voidfinal CompletionStage<StorageResult<AtomicPoint<?>>> storeAtomic(List<AtomicPoint<?>> atomicPoints) Stores atomic points asynchronously.protected final StorageResult<?> storeBatchNow(TemporalPointBatch<?> batch) Storesbatchon the calling thread through the same dispatch aswriteBatch(TemporalPointBatch), timed and metered, without the availability gate; does not completebatch.result().final <C extends ComplexPoint<?>>
CompletionStage<StorageResult<C>> storeComplex(List<C> complexPoints) Stores complex points asynchronously.Set<? extends ComplexPointType> Returns the complex point types this engine can store.<P extends TemporalPoint<?,?>>
CompletionStage<StorageResult<P>> writeBatch(TemporalPointBatch<P> batch) Writes a pre-coalesced batch directly, bypassing thePointStorageStrategyqueue; for pre-batched callers such as bulk ingest.Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface StorageEngine
getOrCreateDataCollector
-
Field Details
-
logger
-
gatewayContext
-
historianName
-
pathAdapter
-
metrics
-
-
Constructor Details
-
AbstractStorageEngine
protected AbstractStorageEngine(GatewayContext gatewayContext, String historianName, LoggerEx logger, Supplier<AvailabilityState> availability) -
AbstractStorageEngine
protected AbstractStorageEngine(GatewayContext gatewayContext, String historianName, LoggerEx logger, QualifiedPathAdapter pathAdapter, Supplier<AvailabilityState> availability) -
AbstractStorageEngine
protected AbstractStorageEngine(GatewayContext gatewayContext, String historianName, LoggerEx logger, QualifiedPathAdapter pathAdapter, PointStorageStrategy storageStrategy, Supplier<AvailabilityState> availability)
-
-
Method Details
-
storeAtomic
public final CompletionStage<StorageResult<AtomicPoint<?>>> storeAtomic(List<AtomicPoint<?>> atomicPoints) Description copied from interface:StorageEngineStores atomic points asynchronously.- Specified by:
storeAtomicin interfaceStorageEngine- 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:StorageEngineApplies change points asynchronously.- Specified by:
applyChangesin interfaceStorageEngine- 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:StorageEngineStores complex points asynchronously.- Specified by:
storeComplexin interfaceStorageEngine- 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 thePointStorageStrategyqueue; for pre-batched callers such as bulk ingest. Availability checks and metrics apply, but per-point type validation is skipped because aTemporalPointBatchholds a single point type. Split mixed input withTemporalPointBatch.partition(List, SortHint).The returned stage carries every outcome, including an unchecked backend exception; only an
Errorpropagates out of the call.- Specified by:
writeBatchin interfaceBatchedStorageWriter- 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
Storesbatchon the calling thread through the same dispatch aswriteBatch(TemporalPointBatch), timed and metered, without the availability gate; does not completebatch.result(). -
batchWriter
Description copied from interface:StorageEngineReturns this engine's batched write path, which bypasses the debounce queue. Callers that have already coalesced their points (bulk ingest, replays) should prefer it overStorageEngine.storeAtomic(List),StorageEngine.storeComplex(List)andStorageEngine.applyChanges(List), which may re-enter the debounce queue. Callers fall back to those methods when it is empty.- Specified by:
batchWriterin interfaceStorageEngine- Returns:
- the batched writer, or empty if this engine has none
-
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 callsuperfirst:protected void registerHandlers(ComplexPointRegistry.Builder complex, ChangePointRegistry.Builder change) { super.registerHandlers(complex, change); complex.register(MyType, points -> myDoStoreMyType(points)); } -
doStoreComplex
-
doApplyChanges
-
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 toAdaptedQualifiedPath
-
doStoreMetadata
protected StorageResult<MetadataPoint> doStoreMetadata(List<MetadataPoint> metadataPoints, Set<AdaptedQualifiedPath> normalizedSources) - Parameters:
normalizedSources- source paths, pre-normalized toAdaptedQualifiedPath
-
applyAnnotationChanges
protected StorageResult<AnnotationChangePoint> applyAnnotationChanges(List<AnnotationChangePoint> annotationChangePoints, Set<AdaptedQualifiedPath> normalizedSources) - Parameters:
normalizedSources- source paths, pre-normalized toAdaptedQualifiedPath
-
getActiveNodesForSystemRename
protected abstract Iterable<? extends HistoricalNode> getActiveNodesForSystemRename(String oldSystemName) Returns the active, non-implicit nodes parented under the old system name, foronSystemNameUpdate(String, String). Backends without rename support returnList.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
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
Returns this engine's long-lived definition resolver so a rename can clear its caches, ornull(the default) if the engine builds one per operation. An engine whose definition write is not idempotent must returnnull, because the clear can make an in-flight batch write a second definition row.- Returns:
- the resolver, or
null.
-
handleSystemNameUpdate
Applies a system-name change to the stored nodes. The default issues aSourceChangePointper 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 callingsuper.- 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 toAdaptedQualifiedPath
-
doStoreAtomic
protected abstract StorageResult<AtomicPoint<?>> doStoreAtomic(List<AtomicPoint<?>> atomicPoints, Set<AdaptedQualifiedPath> normalizedSources) - Parameters:
normalizedSources- source paths, pre-normalized toAdaptedQualifiedPath
-
normalizePath
Normalizes a path to anAdaptedQualifiedPath, caching the result per source path. -
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
-
shutdownStorageMetrics
-