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 Summary

    Modifier and Type
    Method
    Description
    default CompletableFuture<Integer>
    adoptModelMigrations()
    Verifies and adopts every staged direct Model migration known to this application.
    default CompletableFuture<io.fluxzero.common.api.modeling.ModelDeletionResult>
    deleteModel(@NonNull io.fluxzero.common.api.modeling.ModelDeletionPlan plan)
    Executes a previously confirmed hard-deletion plan with a new durable idempotency key.
    default CompletableFuture<io.fluxzero.common.api.modeling.ModelDeletionResult>
    deleteModel(@NonNull Object modelId, @NonNull io.fluxzero.common.api.modeling.ModelDeletionCascade cascade)
    Hard-deletes exactly one model.
    default CompletableFuture<io.fluxzero.common.api.modeling.ModelDeletionResult>
    deleteModel(@NonNull String deletionId, @NonNull io.fluxzero.common.api.modeling.ModelDeletionPlan plan)
    Executes or resumes a confirmed plan using an explicit durable idempotency key.
    default CompletableFuture<io.fluxzero.common.api.modeling.ModelDeletionResult>
    deleteModel(@NonNull String deletionId, @NonNull Object modelId, @NonNull io.fluxzero.common.api.modeling.ModelDeletionCascade cascade)
    Executes or resumes an exact-model hard deletion using an explicit durable idempotency key.
    default ModelRepository
    followPublishedEventMigration(@NonNull String migrationName)
    Coordinates legacy-event Model and Graph reads with a published-event migration consumer.
    default ModelRepository
    followPublishedEventMigration(@NonNull String migrationName, @NonNull Duration maxWait)
    Coordinates legacy-event reads with a migration consumer using a bounded wait before normal handler retry takes over.
    default ModelRepository
    forNamespace(String namespace)
    Returns this repository scoped to the requested namespace.
    default io.fluxzero.common.api.modeling.ModelGraphProjectionStatus
    graphProjectionStatus(@NonNull Class<?> modelType)
    Returns current graph-projection freshness for the supplied model type.
    default <T> Entity<T>
    load(@NonNull Id<T> modelId)
    Loads a model using the type carried by a typed identifier.
    default <T> Entity<T>
    load(@NotNull Object modelId)
    Loads a model by ID, inferring its requested type when the ID is typed.
    default <T> Entity<T>
    load(@NonNull Object parentId, @NonNull Class<?> parentType, @NonNull Object modelId, @NonNull Class<T> modelType)
    Loads a parent-scoped model by its functional child ID and explicit parent type.
    default <T> Entity<T>
    load(@NonNull Object modelId, @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.
    <T> Entity<T>
    load(@NonNull String modelId, @NonNull Class<T> modelType)
    Loads a model by primary ID or current alias and expected type.
    default <T> List<Entity<T>>
    loadAll(@NonNull List<?> modelIds, @NonNull Class<T> modelType)
    Loads several models at one coherent state boundary, preserving input order.
    default CommitAttempt
    loadContext(MutationPlan.Resolution resolution)
    Loads all model parameters for one selected message handler at one repository boundary.
    default <T> Entity<T>
    loadCurrent(@NonNull Object modelId, @NonNull Class<T> modelType)
    Loads the latest model state without inheriting an event or notification handler's historical read boundary.
    default <T> Entity<T>
    loadCurrent(@NonNull String modelId, @NonNull Class<T> modelType)
    Loads the latest model state by exact persisted identity.
    default <T> ModelState<T>
    loadCurrentState(@NonNull Id<T> modelId)
    Reads a current document-backed Model using its typed identity, including its prefix/postfix.
    default <T> ModelState<T>
    loadCurrentState(@NonNull String modelId, @NonNull Class<T> modelType)
    Reads a current document-backed Model value without replaying historical events.
    default <T> Graph<T>
    loadGraph(@NonNull Id<T> rootId)
    Reconstructs a model and every related descendant at one state boundary.
    default <T> Graph<T>
    loadGraph(@NonNull String rootId, @NonNull Class<T> rootType, @NonNull io.fluxzero.common.api.modeling.ModelReadBoundary boundary, Graph.Options options)
    Reconstructs one model graph at the supplied current, state, commit, event, or before boundary.
    default <T> Graph<T>
    loadGraph(@NonNull String rootId, @NonNull Class<T> rootType, Graph.Options options)
    Reconstructs a model graph using exact persisted identity, root type, and optional caller-imposed limits.
    default <T> Graph<T>
    loadGraphAt(@NonNull Id<T> rootId, long stateIndex)
    Reconstructs a model graph at an inclusive historical model-state boundary.
    default <T> Graph<T>
    loadGraphAt(@NonNull Id<T> rootId, long stateIndex, Graph.Options options)
    Reconstructs a model graph at an inclusive historical model-state boundary with optional caller-imposed limits.
    default <T> Graph<T>
    loadGraphAt(@NonNull String rootId, @NonNull Class<T> rootType, long stateIndex, Graph.Options options)
    Reconstructs a model graph using exact persisted identity, root type, an inclusive historical boundary, and optional caller-imposed limits.
    default <T> Graph<T>
    loadGraphBefore(@NonNull String rootId, @NonNull Class<T> rootType, long stateIndex, Graph.Options options)
    Reconstructs the model graph that was current immediately before an opaque state boundary.
    default io.fluxzero.common.api.modeling.ModelDeletionPlan
    planDeletion(@NonNull Object modelId, @NonNull io.fluxzero.common.api.modeling.ModelDeletionCascade cascade)
    Creates a bounded, non-mutating plan for an explicit model hard deletion.
    default CompletableFuture<io.fluxzero.common.api.modeling.ModelGraphProjectionStatus>
    registerGraphProjection(@NonNull Class<?> modelType)
    Registers a changed graph definition and rebuilds all current roots.
    default CompletableFuture<io.fluxzero.common.api.modeling.ModelGraphProjectionStatus>
    registerGraphProjection(@NonNull Class<?> modelType, boolean rebuild)
    Registers the graph projection declared by the supplied model type.

    Methods inherited from interface Namespaced

    forApplicationNamespace, forDefaultNamespace

  • 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

    • 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, @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.

    • 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.

      This is intended for flows that synchronously perform another Model write and then deliberately need its updated state. Ordinary handler reads should use load(Object, Class) so they remain coherent with the message being handled.

    • loadCurrent

      default <T> Entity<T> loadCurrent(@NonNull @NonNull String modelId, @NonNull @NonNull Class<T> modelType)
      Loads the latest model state by exact persisted identity. 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.

    • 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 io.fluxzero.common.api.modeling.ModelDeletionPlan planDeletion(@NonNull @NonNull Object modelId, @NonNull @NonNull io.fluxzero.common.api.modeling.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.

    • deleteModel

      default CompletableFuture<io.fluxzero.common.api.modeling.ModelDeletionResult> deleteModel(@NonNull @NonNull Object modelId, @NonNull @NonNull io.fluxzero.common.api.modeling.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<io.fluxzero.common.api.modeling.ModelDeletionResult> deleteModel(@NonNull @NonNull String deletionId, @NonNull @NonNull Object modelId, @NonNull @NonNull io.fluxzero.common.api.modeling.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<io.fluxzero.common.api.modeling.ModelDeletionResult> deleteModel(@NonNull @NonNull io.fluxzero.common.api.modeling.ModelDeletionPlan plan)
      Executes a previously confirmed hard-deletion plan with a new durable idempotency key.

    • deleteModel

      default CompletableFuture<io.fluxzero.common.api.modeling.ModelDeletionResult> deleteModel(@NonNull @NonNull String deletionId, @NonNull @NonNull io.fluxzero.common.api.modeling.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<io.fluxzero.common.api.modeling.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<io.fluxzero.common.api.modeling.ModelGraphProjectionStatus> registerGraphProjection(@NonNull @NonNull Class<?> modelType)
      Registers a changed graph definition and rebuilds all current roots.

    • graphProjectionStatus

      default io.fluxzero.common.api.modeling.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 io.fluxzero.common.api.modeling.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.