Class AbstractDefinitionResolver<N extends HistoricalNode & Comparable<? super N>>
java.lang.Object
com.inductiveautomation.historian.gateway.api.storage.AbstractDefinitionResolver<N>
- Type Parameters:
N- the node type the backend stores, ordered by created time ascending as required byHistoricalNodeVersionList.
- Direct Known Subclasses:
BatchedDefinitionResolver
public abstract class AbstractDefinitionResolver<N extends HistoricalNode & Comparable<? super N>>
extends Object
Base class for a storage engine's definition resolver. Maps an incoming point to the node version
it belongs to, creating, extending or retiring node versions and writing definition rows as
needed.
Subclasses implement writeDefinition(N, BatchContext); all other backend behavior is supplied through
the constructor functions.
Lookup order: the batch staging cache, then the node tree, then the node's version list, then the backend for an older version. Staging comes first so a batch sees versions that other in-flight batches created but have not yet published. A point resolves to:
- the matching node, unchanged;
- a node with its time range extended, when the timestamp falls outside the matched range;
- a new node version, when none matches or the point's data type differs from the node's (the old version is retired).
Not thread-safe: call under the storage engine's per-batch lock. The caches have their own locks, but the resolver relies on stable read-then-write sequences within a batch.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final recordResult oflookupMatchingNode(TemporalPoint).static final recordA normalized path and its staging-cache key.static final record -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final LoggerExprotected final Map<HistoricalNodeId, HistoricalNodeVersionList<N>> protected final HistoricalNodeTree<N> protected final QualifiedPathAdapterprotected final BatchScopedDefinitionCache<N> -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedAbstractDefinitionResolver(BatchScopedDefinitionCache<N> tempDefinitionCache, HistoricalNodeTree<N> nodeTree, Map<HistoricalNodeId, HistoricalNodeVersionList<N>> nodeIdCache, QualifiedPathAdapter pathAdapter, LoggerEx logger, BiFunction<HistoricalNodeId, Instant, Optional<@NonNull N>> priorNodeQuery, BiFunction<TemporalPoint<?, ?>, @Nullable N, N> newNodeBuilder, BiFunction<N, Instant, N> withCreatedTime, BiFunction<N, @Nullable Instant, N> withRetiredTime, BiFunction<N, DataType, N> withDataType, BiFunction<N, MetadataPoint, N> withMetadata, Function<TemporalPoint<?, ?>, Optional<DataType>> dataTypeExtractor, Consumer<N> cacheUpdater) -
Method Summary
Modifier and TypeMethodDescriptionprotected booleanReturns whether a point older than its node opens an earlier version of that node.lookupMatchingNode(TemporalPoint<?, ?> point) Finds the node version a point belongs to.protected AbstractDefinitionResolver.LookupResult<N> lookupMatchingNode(TemporalPoint<?, ?> point, AbstractDefinitionResolver.NormalizedPathBundle bundle) AslookupMatchingNode(TemporalPoint), for callers that already hold the normalized path.protected final AbstractDefinitionResolver.NormalizedPathBundlenormalizePath(QualifiedPath source) Normalizes a path and derives its staging-cache key, memoized per raw path string.publicNormalizePath(QualifiedPath source) Normalizes a path and derives its staging-cache key, for the engine's invalidation hooks.Returns the engine-scoped staging cache, for the engine's rollback, rename and retire hooks.validateMetadataPoint(MetadataPoint point, N node, BatchContext ctx) Applies a metadata point to its matched node, updating or replacing the node version when the point's data type is new or differs.protected <P extends TemporalPoint<?,?>>
AbstractDefinitionResolver.ValidationResult<N> validatePointType(P point, AbstractDefinitionResolver.NormalizedPathBundle bundle, BatchContext ctx) Resolves a point to its node version, creating or extending the node and writing definition rows as needed.protected abstract voidwriteDefinition(N node, BatchContext ctx) Persists a definition row for the node and stages it in the staging cache.
-
Field Details
-
tempDefinitionCache
protected final BatchScopedDefinitionCache<N extends HistoricalNode & Comparable<? super N>> tempDefinitionCache -
nodeTree
-
nodeIdCache
protected final Map<HistoricalNodeId, HistoricalNodeVersionList<N extends HistoricalNode & Comparable<? super N>>> nodeIdCache -
pathAdapter
-
logger
-
-
Constructor Details
-
AbstractDefinitionResolver
protected AbstractDefinitionResolver(BatchScopedDefinitionCache<N> tempDefinitionCache, HistoricalNodeTree<N> nodeTree, Map<HistoricalNodeId, HistoricalNodeVersionList<N>> nodeIdCache, QualifiedPathAdapter pathAdapter, LoggerEx logger, BiFunction<HistoricalNodeId, Instant, Optional<@NonNull N>> priorNodeQuery, BiFunction<TemporalPoint<?, ?>, @Nullable N, N> newNodeBuilder, BiFunction<N, Instant, N> withCreatedTime, BiFunction<N, @Nullable Instant, N> withRetiredTime, BiFunction<N, DataType, N> withDataType, BiFunction<N, MetadataPoint, N> withMetadata, Function<TemporalPoint<?, ?>, Optional<DataType>> dataTypeExtractor, Consumer<N> cacheUpdater)
-
-
Method Details
-
tempDefinitionCache
Returns the engine-scoped staging cache, for the engine's rollback, rename and retire hooks. -
publicNormalizePath
Normalizes a path and derives its staging-cache key, for the engine's invalidation hooks. -
writeDefinition
Persists a definition row for the node and stages it in the staging cache. Implementations must callBatchScopedDefinitionCache.stage(String, HistoricalNode, BatchContext)withctxso a rollback can find the keys this batch staged.- Parameters:
node- the node version to persist.ctx- the batch context that tracks staged keys.
-
backdatesVersions
protected boolean backdatesVersions()Returns whether a point older than its node opens an earlier version of that node. Whenfalse, the node's first version covers every earlier time. Defaults totrue. -
lookupMatchingNode
Finds the node version a point belongs to.- Parameters:
point- the point whose source and timestamp drive the lookup.- Returns:
- the match, or a result telling the caller to build a new node version.
-
lookupMatchingNode
protected AbstractDefinitionResolver.LookupResult<N> lookupMatchingNode(TemporalPoint<?, ?> point, AbstractDefinitionResolver.NormalizedPathBundle bundle) AslookupMatchingNode(TemporalPoint), for callers that already hold the normalized path.- Parameters:
point- the point whose timestamp drives the lookup.bundle- the result ofnormalizePath(QualifiedPath)forpoint.source(); a mismatched bundle silently corrupts the lookup.- Returns:
- the lookup result.
-
validatePointType
protected <P extends TemporalPoint<?,?>> AbstractDefinitionResolver.ValidationResult<N> validatePointType(P point, AbstractDefinitionResolver.NormalizedPathBundle bundle, BatchContext ctx) Resolves a point to its node version, creating or extending the node and writing definition rows as needed. Subclasses may override to add engine-specific lookups.- Parameters:
point- the point to validate.bundle- the result ofnormalizePath(QualifiedPath)forpoint.source().ctx- the batch context that tracks staged keys.- Returns:
- the node version, with a commit action if the engine's caches need updating.
-
validateMetadataPoint
public AbstractDefinitionResolver.ValidationResult<N> validateMetadataPoint(MetadataPoint point, N node, BatchContext ctx) Applies a metadata point to its matched node, updating or replacing the node version when the point's data type is new or differs.- Parameters:
point- the metadata point being stored.node- the existing node version that matched the point's source.ctx- the batch context that tracks staged keys.- Returns:
- the resulting node version, with a commit action if one is needed.
-
normalizePath
Normalizes a path and derives its staging-cache key, memoized per raw path string. Subclasses that key the staging cache themselves must use this method so readers and writers agree on the key.
-