Interface ModelGraphResolver

All Known Implementing Classes:
DefaultModelRepository
public interface ModelGraphResolver
Optional repository capability for metadata-only Graph navigation. Queries return complete direct collections for the supplied identities at a shared boundary. A repository may additionally return complete ancestor collections when its protocol reads an ancestor closure; descendants are loaded one frontier at a time. Returned value suppliers must preserve that boundary and never skip replay errors. The historical mode denotes an explicitly historical read, not merely a pinned current boundary: pinning must not replace a Model's current document authority with event replay. Repositories without this capability retain their existing fully loaded Graph navigation.

  • Method Details

    • documentFallbackEnabled

      default boolean documentFallbackEnabled()
      Application default for current DOCUMENT-only fallback in historical Graph views.

    • historicalDocumentFallback

      default Object historicalDocumentFallback(String modelId, Class<?> modelType, ModelReadBoundary boundary, RuntimeException failure)
      Recovers only an unavailable historical document value. Implementations must preserve historical absence, resolve the exact canonical identity, and rethrow unrelated failures. The default preserves strict behavior.

    • allowsAliasFallback

      default boolean allowsAliasFallback(String requestedId, Class<?> modelType, ModelReadBoundary boundary)
      Checks whether a pending undecorated alias may supply a missing prefixed root at this boundary. An unrelated durable primary identity must retain precedence over the pending alias. Custom resolvers keep their existing overlay behavior by default; metadata-aware implementations can reject such collisions. Called only when a pending alias candidate exists, not on ordinary reads.

    • graphStagedValues

      ModelBatchScope.Snapshot graphStagedValues(ModelReadBoundary boundary)
      Captures this repository's message-batch overlay once for a new navigation view. Another application's pending writes must never enter this snapshot, even when its batch is active on the calling thread.

    • resolveBoundGraphIdentities

      default Map<String, ModelGraphResolver.Identity> resolveBoundGraphIdentities(Map<String,Class<?>> modelTypes)
      Resolves already bound handler references together without applying ID affixes again. Unlike exact canonical reads, these references may still be aliases. An empty map preserves existing eager parameter injection.

    • loadCurrentGraphValue

      ModelGraphResolver.Value loadCurrentGraphValue(Object modelId, Class<?> modelType)
      Loads deliberately current state with its namespace boundary, ignoring any active handler boundary.

    • loadGraphProjection

      Graph<?> loadGraphProjection(String rootId, Class<?> rootType, ModelReadBoundary boundary, boolean historical)
      Strictly materializes a full graph at the selected boundary without consulting later batch state.

    • loadGraphProjection

      default Graph<?> loadGraphProjection(String rootId, Class<?> rootType, ModelReadBoundary boundary, boolean historical, Entity<?> resolvedRoot)
      Materializes relationships while retaining a root value whose identity or absence was already resolved. A resolver opting into metadata-only identity resolution must implement this operation for absent roots; silently resolving the supplied identity again could bind it to a different model.

    • loadGraphValue

      ModelGraphResolver.Value loadGraphValue(Object modelId, boolean exact, Class<?> modelType, ModelReadBoundary boundary)
      Loads a source value and retains the coherent boundary that ordinary single-value APIs do not expose.

    • loadGraphValue

      default ModelGraphResolver.Value loadGraphValue(Object modelId, boolean exact, Class<?> modelType, ModelReadBoundary boundary, boolean historical)
      Loads at a pinned boundary without confusing transaction-current document authority with historical replay.

    • resolveGraphIdentity

      default ModelGraphResolver.Identity resolveGraphIdentity(Object modelId, Class<?> modelType, ModelReadBoundary boundary)
      Resolves an identity without requiring its value. The returned supplier must retain the resolved identity, absence and boundary even if the alias changes later. Returning null (the default) retains a custom repository's existing value-based identity lookup, without opting into metadata-only identity resolution.

    • resolveGraphIdentity

      default ModelGraphResolver.Identity resolveGraphIdentity(Object modelId, boolean exact, Class<?> modelType, ModelReadBoundary boundary)
      Resolves an exact persisted key without applying functional-ID affixes a second time.

    • resolveGraphIdentity

      default ModelGraphResolver.Identity resolveGraphIdentity(Object modelId, boolean exact, Class<?> modelType, ModelReadBoundary boundary, boolean historical)
      Resolves metadata at a pinned boundary with an explicit current versus historical value contract.

    • resolveCurrentGraphIdentity

      default ModelGraphResolver.Identity resolveCurrentGraphIdentity(Object modelId, Class<?> modelType)
      Optional metadata-first current root; the default retains the existing current-value route.

    • resolveCurrentGraphIdentity

      default ModelGraphResolver.Identity resolveCurrentGraphIdentity(Object modelId, boolean exact, Class<?> modelType)
      Resolves a deliberately current root, optionally using an exact repository key without functional-ID affixes or alias fallback. Must ignore the active handler boundary and pin a fresh storage boundary. Event-sourced roots need no value reconstruction; a DOCUMENT-only root may capture its current value with the head before exposing the identity, since later replacement cannot be reconstructed. The returned identity and supplier must never advance independently. Returning null declares this optional capability unsupported.

    • resolveCurrentGraphIdentity

      default ModelGraphResolver.Identity resolveCurrentGraphIdentity(Object modelId, boolean exact, Class<?> modelType, ModelBatchScope.Snapshot snapshot)
      Resolves a current root against the caller's captured batch overlay. Implementations that capture a durable document may omit that body read when the overlay wins. The default preserves custom resolver behavior.

    • resolveGraphIdentity

      default ModelGraphResolver.Identity resolveGraphIdentity(Object id, ModelIdResolution resolution, Class<?> type, ModelReadBoundary boundary)
      Resolves a root with independent normalization and alias policy.

    • resolveGraphIdentity

      default ModelGraphResolver.Identity resolveGraphIdentity(Object id, ModelIdResolution resolution, Class<?> type, ModelReadBoundary boundary, boolean historical)
      Resolves a root at a pinned boundary with independent normalization and alias policy.

    • loadGraphValue

      default ModelGraphResolver.Value loadGraphValue(Object id, ModelIdResolution resolution, Class<?> type, ModelReadBoundary boundary)
      Loads a source value with independent normalization and alias policy.

    • loadGraphValue

      default ModelGraphResolver.Value loadGraphValue(Object id, ModelIdResolution resolution, Class<?> type, ModelReadBoundary boundary, boolean historical)
      Loads a source value at a pinned boundary with independent normalization and alias policy.

    • resolveCurrentGraphIdentity

      default ModelGraphResolver.Identity resolveCurrentGraphIdentity(Object id, ModelIdResolution resolution, Class<?> type, ModelBatchScope.Snapshot snapshot)
      Resolves a deliberately current root with independent normalization and alias policy.

    • loadCurrentGraphValue

      default ModelGraphResolver.Value loadCurrentGraphValue(Object id, Class<?> type, boolean applyAffixes)
      Loads deliberately current state with optional ID conversion and affixes.

    • resolveUntypedGraphIdentity

      default ModelGraphResolver.Identity resolveUntypedGraphIdentity(Object modelId)
      Optional untyped root discovery; an implementation supplies its resolved class through ModelGraphResolver.HeadValue.

    • loadGraphValues

      Map<String, Entity<?>> loadGraphValues(Map<String,Class<?>> modelTypes, ModelReadBoundary boundary, Map<String, Entity<?>> staged, boolean historical)
      Reconstructs explicitly requested values together; unrelated metadata nodes must remain unloaded.

    • loadGraphRelations

      ModelGraphResolver.Relations loadGraphRelations(List<String> modelIds, ModelRelationshipRead.Direction direction, ModelReadBoundary boundary, Map<String, Entity<?>> staged, boolean historical)
      Reads direct relationships and heads without loading values. The supplied staged snapshot takes precedence over durable relationships and must also be used by returned value suppliers. No implicit later batch reads.