Interface ModelRepository

All Superinterfaces:
Namespaced<ModelRepository>
All Known Implementing Classes:
DefaultModelRepository
public interface ModelRepository extends Namespaced<ModelRepository>
Repository for loading independently stored models.

Model identity combines the repository representation of its @EntityId value with any explicit prefix and postfix. Loads first match that primary identity and then, when no such model exists, a current value declared with @Alias.

  • Method Details

    • forNamespace

      default ModelRepository forNamespace(String namespace)
      Returns this repository scoped to the requested namespace.

      Custom repositories that are not namespace-aware retain their behavior by returning the same instance.

      Specified by:
      forNamespace in interface Namespaced<ModelRepository>
      Parameters:
      namespace - the namespace to which the returned resource is scoped, or null for the application namespace
      Returns:
      the resource associated with the specified namespace

    • reindex

      default void reindex(@NonNull @NonNull String modelId, @NonNull @NonNull Class<?> modelType)
      Reindexes the current durable state of exactly one Model. Custom repositories must implement the guarded capability explicitly. See Graph.reindex() for cutoff and completion semantics.

    • diagnostics

      default ModelDiagnostics diagnostics()
      Returns an explicit bounded dev/CI catalog inspector for this repository's namespace. Custom repositories may expose their own inspector; the default declines rather than inspecting a different store or namespace.

    • load

      default <T> Entity<T> load(@NonNull @NonNull Id<T> modelId)
      Loads a model using the type carried by a typed identifier.

    • load

      default <T> Entity<T> load(@NotNull @NotNull Object modelId)
      Loads a model by ID, inferring its requested type when the ID is typed.

      An untyped ID requests Object. Its concrete type is resolved from the durable model head. If no model exists, an empty Entity of type Object is returned.

    • load

      default <T> Entity<T> load(@NonNull @NonNull Object modelId, boolean applyAffixes)
      Loads a possibly typed ID with optional affixes; untyped IDs remain literal in either mode.

    • load

      default <T> Entity<T> load(@NonNull @NonNull Object modelId, @NonNull @NonNull Class<T> modelType)
      Loads a model using the string representation of the supplied ID, resolving a current model alias when no primary model has that identity. An undecorated fallback ignores primary Models of unrelated types (for example the parent of an absent companion). Genuine aliases and compatible primary identities remain valid; explicit wrong-type reads fail.

    • load

      default <T> Entity<T> load(@NonNull @NonNull Object modelId, @NonNull @NonNull Class<T> modelType, boolean applyAffixes)
      Loads by functional ID when applyAffixes is true, or by the supplied string representation when false. False skips typed-ID conversion and EntityId affixes (including parent scope); supply the full key or alias. Both modes retain primary-ID precedence and alias resolution. Existing overloads keep their own defaults.

    • load

      default <T> Entity<T> load(@NonNull @NonNull Id<T> modelId, boolean applyAffixes)
      Loads a typed ID with optional model affixes; false uses its existing string representation unchanged.

    • loadCurrent

      default <T> Entity<T> loadCurrent(@NonNull @NonNull Object modelId, @NonNull @NonNull Class<T> modelType)
      Loads the latest model state without inheriting an event or notification handler's historical read boundary.

      Use this when deliberately inspecting current intent, for example after a synchronous nested Model write or when reconciling schedules triggered by an older event. Ordinary event-bound reads should use load(Object, Class) so they remain coherent with the message being handled.

    • loadCurrent

      default <T> Entity<T> loadCurrent(@NonNull @NonNull Object modelId, @NonNull @NonNull Class<T> modelType, boolean applyAffixes)
      Current counterpart of load(Object, Class, boolean), retaining aliases in either mode.

    • loadCurrent

      default <T> Entity<T> loadCurrent(@NonNull @NonNull String modelId, @NonNull @NonNull Class<T> modelType)
      Loads the latest model state by literal primary key or alias, without adding affixes. Custom repositories without contextual historical reads retain their normal behavior by delegating to load(String, Class).

    • loadCurrentState

      default <T> ModelState<T> loadCurrentState(@NonNull @NonNull String modelId, @NonNull @NonNull Class<T> modelType)
      Reads a current document-backed Model value without replaying historical events. The returned state is read-only, independently current (not handler-historical), and not an implicit commit dependency. A missing/deleted Model has no value; a live Model with an unavailable, stale or unversioned document fails explicitly. No automatic replay, event skipping or ordinary Model-cache update takes place. The Runtime must attest a body/head proof captured with trusted Model materialization/adoption; older unproven documents require a new eligible trusted write and are never retroactively certified by a read. Custom repositories must implement the verified document capability; the default never emulates it by replay. This overload uses the exact persisted identity, not an alias.

    • loadCurrentState

      default <T> ModelState<T> loadCurrentState(@NonNull @NonNull Id<T> modelId)
      Reads a current document-backed Model using its typed identity, including its prefix/postfix.

    • load

      default <T> Entity<T> load(@NonNull @NonNull Object parentId, @NonNull @NonNull Class<?> parentType, @NonNull @NonNull Object modelId, @NonNull @NonNull Class<T> modelType)
      Loads a parent-scoped model by its functional child ID and explicit parent type.

      Ordinary model types ignore the parent and retain their normal identity. A parent-scoped model uses the same collision-safe persisted identity as automatic apply handling.

    • load

      <T> Entity<T> load(@NonNull @NonNull String modelId, @NonNull @NonNull Class<T> modelType)
      Loads a model by primary ID or current alias and expected type. A primary model ID always takes precedence over an alias with the same value.
      Parameters:
      modelId - persisted model key or current alias; never decorated with model type metadata
      modelType - expected model type, or Object when it should be resolved from storage

    • loadAll

      default <T> List<Entity<T>> loadAll(@NonNull @NonNull List<?> modelIds, @NonNull @NonNull Class<T> modelType)
      Loads several models at one coherent state boundary, preserving input order.

      Repositories without coherent multi-model reconstruction reject this capability instead of emulating it with independent reads at different boundaries.

    • loadAll

      default <T> List<Entity<T>> loadAll(@NonNull @NonNull List<?> modelIds, @NonNull @NonNull Class<T> modelType, boolean applyAffixes)
      Loads models at one coherent boundary with optional ID conversion and affixes, retaining alias resolution. False uses each supplied string representation unchanged. Custom repositories must support literal batch reads explicitly; the default never substitutes independent reads at different boundaries.

    • loadContext

      default CommitAttempt loadContext(@NonNull MutationPlan.Resolution resolution)
      Loads all model parameters for one selected message handler at one repository boundary.

      Event and notification handlers carrying model-commit metadata must be reconstructed at that exact commit boundary. Other handlers use one current load context. Implementations should batch direct targets and ancestor traversal rather than loading each parameter independently. Resolved ancestors must preserve their planned access: reading a parent does not authorize a write, while a planned parent write must not be silently downgraded to read-only. Implementations unable to preserve the requested access and boundary must reject that capability.

    • planDeletion

      default ModelDeletionPlan planDeletion(@NonNull @NonNull Object modelId, @NonNull @NonNull ModelDeletionCascade cascade)
      Creates a bounded, non-mutating plan for an explicit model hard deletion.

      A descendant cascade must be planned and confirmed before execution. The returned published-event count makes clear that globally published events are outside the model-stream erasure boundary. Descendants include retained deleted-parent lineage after nested logical cascades, but not earlier ordinary detachments or moves. Inspect the plan before confirming it: upgrading cannot reconstruct missing lineage markers written by older store implementations.

    • deleteModel

      default CompletableFuture<ModelDeletionResult> deleteModel(@NonNull @NonNull Object modelId, @NonNull @NonNull ModelDeletionCascade cascade)
      Hard-deletes exactly one model.

      Passing ModelDeletionCascade.DESCENDANTS without a confirmed plan is rejected. Use deleteModel(ModelDeletionPlan) for descendant cascades.

    • deleteModel

      default CompletableFuture<ModelDeletionResult> deleteModel(@NonNull @NonNull String deletionId, @NonNull @NonNull Object modelId, @NonNull @NonNull ModelDeletionCascade cascade)
      Executes or resumes an exact-model hard deletion using an explicit durable idempotency key. Descendant deletion still requires a confirmed plan.

    • deleteModel

      default CompletableFuture<ModelDeletionResult> deleteModel(@NonNull @NonNull ModelDeletionPlan plan)
      Executes a previously confirmed hard-deletion plan with a new durable idempotency key.

    • deleteModel

      default CompletableFuture<ModelDeletionResult> deleteModel(@NonNull @NonNull String deletionId, @NonNull @NonNull ModelDeletionPlan plan)
      Executes or resumes a confirmed plan using an explicit durable idempotency key.

    • adoptModelMigrations

      default CompletableFuture<Integer> adoptModelMigrations()
      Verifies and adopts every staged direct Model migration known to this application. Materialized Graph projections declared by the application are rebuilt after every staged document has been adopted. The accepted normalized source remains isolated from later staging until the first ordinary Model write, so another legacy boundary can be re-adopted without exposing unverified state. Repeating the operation is also a safe way to resume projection rebuilds after a failure.
      Returns:
      the number of staged Model documents adopted by this invocation
      See Also:

    • followPublishedEventMigration

      default ModelRepository followPublishedEventMigration(@NonNull @NonNull String migrationName)
      Coordinates legacy-event Model and Graph reads with a published-event migration consumer.

      A mapped event remains a single ordinary Model read. Only when an event boundary had to fall back to current state does the repository wait for the durable migration-consumer position and retry the exact same read. If the consumer has processed the event but no mapping becomes visible, the read fails instead of exposing stale or future state.

      Parameters:
      migrationName - stable consumer name used by PublishedEventModelMigration
      Returns:
      this repository

    • followPublishedEventMigration

      default ModelRepository followPublishedEventMigration(@NonNull @NonNull String migrationName, @NonNull @NonNull Duration maxWait)
      Coordinates legacy-event reads with a migration consumer using a bounded wait before normal handler retry takes over.
      Parameters:
      migrationName - stable durable migration-consumer name
      maxWait - maximum time one read waits for the migration consumer to reach its event
      Returns:
      this repository

    • registerGraphProjection

      default CompletableFuture<ModelGraphProjectionStatus> registerGraphProjection(@NonNull @NonNull Class<?> modelType, boolean rebuild)
      Registers the graph projection declared by the supplied model type.
      Parameters:
      modelType - model carrying an enabled graph projection
      rebuild - whether all current roots should be scanned even if the definition is unchanged

    • registerGraphProjection

      default CompletableFuture<ModelGraphProjectionStatus> registerGraphProjection(@NonNull @NonNull Class<?> modelType)
      Registers a changed graph definition and rebuilds all current roots.

    • graphProjectionStatus

      default ModelGraphProjectionStatus graphProjectionStatus(@NonNull @NonNull Class<?> modelType)
      Returns current graph-projection freshness for the supplied model type.

    • loadGraph

      default <T> Graph<T> loadGraph(@NonNull @NonNull Id<T> rootId)
      Reconstructs a model and every related descendant at one state boundary. Pathless relationships participate in typed traversal but remain absent from serialized graph documents. Pending changes from earlier messages in the same ordered tracking segment are included. Use loadGraphAt(Id, long) when an exact durable historical boundary is required.

    • loadGraphAt

      default <T> Graph<T> loadGraphAt(@NonNull @NonNull Id<T> rootId, long stateIndex)
      Reconstructs a model graph at an inclusive historical model-state boundary.

    • loadGraphAt

      default <T> Graph<T> loadGraphAt(@NonNull @NonNull Id<T> rootId, long stateIndex, @NonNull Graph.Options options)
      Reconstructs a model graph at an inclusive historical model-state boundary with optional caller-imposed limits.

    • loadGraph

      default <T> Graph<T> loadGraph(@NonNull @NonNull String rootId, @NonNull @NonNull Class<T> rootType, @NonNull Graph.Options options)
      Reconstructs a model graph using exact persisted identity, root type, and optional caller-imposed limits. Pending changes from earlier messages in the same ordered tracking segment are included.

    • loadGraph

      default <T> Graph<T> loadGraph(@NonNull @NonNull String rootId, @NonNull @NonNull Class<T> rootType, @NonNull @NonNull ModelReadBoundary boundary, @NonNull Graph.Options options)
      Reconstructs one model graph at the supplied current, state, commit, event, or before boundary.

    • loadGraphAt

      default <T> Graph<T> loadGraphAt(@NonNull @NonNull String rootId, @NonNull @NonNull Class<T> rootType, long stateIndex, @NonNull Graph.Options options)
      Reconstructs a model graph using exact persisted identity, root type, an inclusive historical boundary, and optional caller-imposed limits.

    • loadGraphBefore

      default <T> Graph<T> loadGraphBefore(@NonNull @NonNull String rootId, @NonNull @NonNull Class<T> rootType, long stateIndex, @NonNull Graph.Options options)
      Reconstructs the model graph that was current immediately before an opaque state boundary.