Interface Graph<T>

Type Parameters:
T - model value type at the current graph placement
public interface Graph<T>
A typed view of one independently stored model and its lazily available relationship context.

Merely resolving a detached graph by ID does not load its model value. A typed ancestor can be resolved directly from relationship identities without loading either the source or intermediate parents. The source value, children, history and update context are loaded only when requested, at one pinned model-state boundary. Every returned child is itself a graph view, so root, parent, history and update operations remain available without exposing the persistence-only Entity wrapper.

As the sole parameter of an event or notification handler, a graph subscribes to durable changes of that root and any descendant. The handler runs once per affected root. previous() then returns the complete graph directly before the change; a child move therefore invokes the handler once for the old root and once for the new root. One handler object may declare separate sole-parameter methods for different Graph<T> root types; each changed root is routed to its matching typed method.

A materialized graph retains the serialized type and revision of every root and descendant placement. The ordinary serializer upcasts each node independently and lazily when its value is accessed; there is no graph-wide revision or separate graph-upcaster contract. Returning a complete materialized graph from a @HandleDocument(modelGraph = ...) handler can persist those evolved node schemas into the derived projection without changing the authoritative Models or relationships.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Graph.Options
    Optional caller-imposed graph reconstruction limits.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Collection<?>
    aliases()
    Returns the model aliases without loading relationship context.
    <A> Optional<Graph<A>>
    ancestor(Class<A> ancestorType)
    Returns the closest ancestor, including the current graph, assignable to the requested type.
    default <A> Optional<A>
    ancestorModel(Class<A> ancestorType)
    Returns the value of the closest ancestor, including the current model, assignable to the requested type.
    Graph<T>
    apply(Message update)
    Applies a complete message.
    Graph<T>
    apply(DeserializingMessage update)
    Applies a deserializing message.
    Graph<T>
    apply(Object update)
    Applies one update to this graph's current model and returns the staged resulting graph.
    Graph<T>
    apply(Object... updates)
    Applies the supplied updates in order.
    Graph<T>
    apply(Object update, io.fluxzero.common.api.Metadata metadata)
    Applies one update with explicit metadata.
    Graph<T>
    apply(Collection<?> updates)
    Applies the supplied updates in order.
    Graph<T>
    assertAndApply(Object update)
    Verifies and applies the supplied update.
    default Graph<T>
    assertAndApply(Object... updates)
    Verifies and applies the supplied updates in order.
    Graph<T>
    assertAndApply(Object update, io.fluxzero.common.api.Metadata metadata)
    Verifies and applies the supplied update with explicit metadata.
    default Graph<T>
    assertAndApply(Collection<?> updates)
    Verifies and applies the supplied updates in order.
    <E extends Exception>
    Graph<T>
    assertLegal(Object update)
    Verifies that the supplied update is legal and returns this graph.
    Graph<T>
    atStateIndex(long stateIndex)
    Returns the same model graph reconstructed at the requested durable state boundary.
    default <C> List<C>
    childModels(Class<C> childType)
    Returns direct child values of the requested type.
    default <C> List<C>
    childModels(String path, Class<C> childType)
    Returns direct child values placed at the requested explicit relationship path.
    default List<String>
    childPaths()
    Returns the declared serialized child paths in deterministic order, including paths that currently have no children.
    List<Graph<?>>
    children()
    Returns all direct children in deterministic relationship-path order.
    <C> List<Graph<C>>
    children(Class<C> childType)
    Returns direct children of the requested type.
    <C> List<Graph<C>>
    children(String path, Class<C> childType)
    Returns direct children placed at the requested explicit relationship path.
    Graph<T>
    commit()
    Explicitly commits staged changes.
    default <C> Optional<C>
    context(Class<C> contextType)
    Returns response context assignable to the requested type, if attached to this graph view.
    default Graph<T>
    delete()
    Marks this model as deleted and returns the staged resulting graph.
    default <D> List<D>
    descendantModels(Class<D> descendantType)
    Returns all descendant values assignable to the requested type.
    default <D> List<D>
    descendantModels(String path, Class<D> descendantType)
    Returns descendant values reached through the requested relationship path.
    <D> List<Graph<D>>
    descendants(Class<D> descendantType)
    Returns all descendants assignable to the requested type in deterministic graph order.
    <D> List<Graph<D>>
    descendants(String path, Class<D> descendantType)
    Returns descendants reached through the requested relationship path.
    default Graph<T>
    filterBranches(Predicate<? super Graph<?>> predicate)
    Returns an immutable response view containing every matching placement, its complete descendant branch and the ancestors needed to preserve its serialized path.
    default Optional<Graph<T>>
    filterGraph(Predicate<? super Graph<T>> predicate)
    Returns this graph when it matches the supplied condition.
    default Graph<T>
    filterNodes(Predicate<? super Graph<?>> predicate)
    Returns an immutable, lazy view whose model values are retained only when the supplied predicate accepts their graph placement.
    default Optional<Graph<T>>
    filterPresent()
    Returns this graph only when its current model value is present.
    default Optional<Graph<?>>
    find(Object idOrAlias)
    Finds a graph by exact persisted identity or alias.
    default <M> Optional<Graph<M>>
    find(Object idOrAlias, Class<M> modelType)
    Finds a graph by functional identity or alias and expected model type.
    default <M> Optional<Graph<M>>
    find(Object idOrAlias, Class<M> modelType, GraphLookupPolicy lookupPolicy)
    Finds a graph by functional identity or alias and expected model type using the supplied ambiguity policy.
    default Optional<Graph<?>>
    find(Predicate<? super Graph<?>> predicate)
    Finds the first graph in deterministic graph order matching the supplied condition.
    default String
    functionalId()
    Returns the public functional identity from the current model value or, for a deleted model, its latest available historical value.
    T
    get()
    Returns the current model value, or null for a missing or deleted model.
    default boolean
    hasChanged(Function<? super T, ?> selector)
    Returns whether the selected value differs from the preceding revision.
    default Long
    highestEventIndex()
    Returns the newest event index retained by this graph's revision history.
    Object
    id()
    Returns the exact collision-safe repository identity of this model.
    default Graph<T>
    ifPresent(UnaryOperator<Graph<T>> operation)
    Applies a graph operation only when a current model value is present.
    default boolean
    isEmpty()
    Returns whether this graph currently represents a missing or deleted model.
    default boolean
    isPresent()
    Returns whether this graph currently contains a model value.
    default boolean
    isRoot()
    Returns whether this graph is the outer root of its current graph view.
    String
    lastEventId()
    Returns the last globally published event identifier visible to this model revision.
    Long
    lastEventIndex()
    Returns the last globally published event index visible to this model revision.
    default <R> Optional<R>
    map(Function<? super T, ? extends R> mapper)
    Maps the current model value when present without loading relationship context.
    default <R> Optional<R>
    mapGraph(Function<? super Graph<T>, ? extends R> mapper)
    Maps this graph itself without loading relationship context.
    default <R> Optional<R>
    mapIfPresent(Function<? super Graph<T>, ? extends R> mapper)
    Maps this graph only when its current model value is present.
    default Optional<T>
    optional()
    Returns the current model value as an optional without loading relationship context.
    default T
    orElse(T fallback)
    Returns the current model value or the supplied fallback.
    default T
    orElseGet(Supplier<? extends T> fallback)
    Returns the current model value or obtains a fallback lazily.
    default T
    orElseThrow()
    Returns the current model value or throws when this graph is empty.
    default <X extends Throwable>
    T
    orElseThrow(Supplier<? extends X> exceptionSupplier)
    Returns the current model value or throws the supplied exception when this graph is empty.
    Optional<Graph<?>>
    parent()
    Returns the parent of this concrete graph placement, if one exists.
    <P> Optional<Graph<P>>
    parent(Class<P> parentType)
    Returns the closest parent assignable to the requested type.
    default <P> Optional<P>
    parentModel(Class<P> parentType)
    Returns the value of the closest parent assignable to the requested type.
    default List<Graph<?>>
    parents()
    Returns all direct parents of this model.
    Optional<Graph<T>>
    playBackToCondition(Predicate<Graph<T>> condition)
    Plays back to the first retained revision matching the supplied condition.
    Optional<Graph<T>>
    playBackToEvent(Long eventIndex, String eventId)
    Plays back to the first retained revision matching the supplied event boundary.
    Graph<T>
    previous()
    Returns the preceding model revision as a lazy graph, or null when none is retained.
    default <V> V
    previousValue(Function<? super T, V> selector)
    Returns the selected value from the preceding revision, or null when unavailable.
    String
    relationshipPath()
    Returns the parent-relative relationship path, or null for a pathless, standalone, or root view.
    default Stream<Graph<T>>
    revisions()
    Returns current and retained preceding revisions, newest first.
    default long
    revisionStateIndex()
    Returns the namespace-wide state boundary at which this concrete model revision became current.
    Graph<?>
    root()
    Returns the outer graph root.
    default Graph<T>
    selectPaths(String... paths)
    Returns an immutable graph view containing only the selected serialized relationship paths and their ancestors.
    default Graph<T>
    selectPaths(Collection<String> paths)
    See selectPaths(String...).
    long
    sequenceNumber()
    Returns the model-local sequence number.
    long
    stateIndex()
    Returns the pinned namespace-wide model-state boundary.
    default Stream<Graph<?>>
    stream()
    Lazily traverses this graph in deterministic pre-order, including this graph itself.
    Instant
    timestamp()
    Returns the timestamp of this model revision.
    Class<T>
    type()
    Returns the concrete model type.
    Graph<T>
    update(UnaryOperator<T> update)
    Updates the current value directly.
    default Graph<T>
    withContext(Object... values)
    Returns an immutable graph view carrying typed response context for graph-derived properties.

  • Method Details

    • get

      @Nullable T get()
      Returns the current model value, or null for a missing or deleted model.

    • isPresent

      default boolean isPresent()
      Returns whether this graph currently contains a model value.

    • isEmpty

      default boolean isEmpty()
      Returns whether this graph currently represents a missing or deleted model.

    • optional

      default Optional<T> optional()
      Returns the current model value as an optional without loading relationship context.

    • mapGraph

      default <R> Optional<R> mapGraph(Function<? super Graph<T>, ? extends R> mapper)
      Maps this graph itself without loading relationship context.

    • filterGraph

      default Optional<Graph<T>> filterGraph(Predicate<? super Graph<T>> predicate)
      Returns this graph when it matches the supplied condition.

    • filterPresent

      default Optional<Graph<T>> filterPresent()
      Returns this graph only when its current model value is present.

    • withContext

      default Graph<T> withContext(Object... values)
      Returns an immutable graph view carrying typed response context for graph-derived properties.

      Context is shared by the complete graph view, including its parents, children and historical revisions. It does not become part of model state and is not loaded or persisted by the SDK. This makes it suitable for one response-wide, already-batched lookup that several @GraphProperty methods consume without introducing per-node I/O.

    • context

      default <C> Optional<C> context(Class<C> contextType)
      Returns response context assignable to the requested type, if attached to this graph view.

    • mapIfPresent

      default <R> Optional<R> mapIfPresent(Function<? super Graph<T>, ? extends R> mapper)
      Maps this graph only when its current model value is present.

    • map

      default <R> Optional<R> map(Function<? super T, ? extends R> mapper)
      Maps the current model value when present without loading relationship context.

    • orElse

      default T orElse(T fallback)
      Returns the current model value or the supplied fallback.

    • orElseGet

      default T orElseGet(Supplier<? extends T> fallback)
      Returns the current model value or obtains a fallback lazily.

    • orElseThrow

      default T orElseThrow()
      Returns the current model value or throws when this graph is empty.

    • orElseThrow

      default <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X
      Returns the current model value or throws the supplied exception when this graph is empty.
      Throws:
      X

    • ifPresent

      default Graph<T> ifPresent(UnaryOperator<Graph<T>> operation)
      Applies a graph operation only when a current model value is present.

    • id

      Object id()
      Returns the exact collision-safe repository identity of this model.

    • functionalId

      @Nullable default String functionalId()
      Returns the public functional identity from the current model value or, for a deleted model, its latest available historical value.

      This deliberately differs from id(), which can contain an EntityId prefix, postfix or parent scope used only for durable repository identity. A model that has never existed has no functional identity and returns null.

    • type

      Class<T> type()
      Returns the concrete model type.

    • aliases

      default Collection<?> aliases()
      Returns the model aliases without loading relationship context.

    • relationshipPath

      @Nullable String relationshipPath()
      Returns the parent-relative relationship path, or null for a pathless, standalone, or root view.

    • stateIndex

      long stateIndex()
      Returns the pinned namespace-wide model-state boundary.

    • revisionStateIndex

      default long revisionStateIndex()
      Returns the namespace-wide state boundary at which this concrete model revision became current.

      Unlike stateIndex(), which describes the pinned boundary shared by the complete graph, this value can differ between nodes and therefore provides a stable ordering for otherwise ambiguous functional-ID lookups.

    • lastEventId

      @Nullable String lastEventId()
      Returns the last globally published event identifier visible to this model revision.

    • lastEventIndex

      @Nullable Long lastEventIndex()
      Returns the last globally published event index visible to this model revision.

    • sequenceNumber

      long sequenceNumber()
      Returns the model-local sequence number.

    • timestamp

      Instant timestamp()
      Returns the timestamp of this model revision.

    • root

      Graph<?> root()
      Returns the outer graph root. On a root graph this returns this.

    • isRoot

      default boolean isRoot()
      Returns whether this graph is the outer root of its current graph view.

    • parent

      Optional<Graph<?>> parent()
      Returns the parent of this concrete graph placement, if one exists.

    • parents

      default List<Graph<?>> parents()
      Returns all direct parents of this model. A concrete placement normally has one parent, while a directly loaded model may expose multiple declared Parent relationships.

    • parent

      <P> Optional<Graph<P>> parent(Class<P> parentType)
      Returns the closest parent assignable to the requested type.

    • parentModel

      default <P> Optional<P> parentModel(Class<P> parentType)
      Returns the value of the closest parent assignable to the requested type.

    • ancestor

      <A> Optional<Graph<A>> ancestor(Class<A> ancestorType)
      Returns the closest ancestor, including the current graph, assignable to the requested type. The concrete graph placement is searched before alternate parent branches.

    • ancestorModel

      default <A> Optional<A> ancestorModel(Class<A> ancestorType)
      Returns the value of the closest ancestor, including the current model, assignable to the requested type.

    • children

      List<Graph<?>> children()
      Returns all direct children in deterministic relationship-path order.

    • childPaths

      default List<String> childPaths()
      Returns the declared serialized child paths in deterministic order, including paths that currently have no children. Pathless relationships are deliberately absent because they are graph context rather than JSON structure.

    • selectPaths

      default Graph<T> selectPaths(String... paths)
      Returns an immutable graph view containing only the selected serialized relationship paths and their ancestors. Model values and graph nodes are shared with this graph; no models are copied or loaded merely by creating the view. An empty selection returns this complete graph.

    • selectPaths

      default Graph<T> selectPaths(Collection<String> paths)
      See selectPaths(String...).

    • filterNodes

      default Graph<T> filterNodes(Predicate<? super Graph<?>> predicate)
      Returns an immutable, lazy view whose model values are retained only when the supplied predicate accepts their graph placement. Rejected descendants remain structurally addressable as empty graphs but are omitted during graph serialization; accepted values are shared and never copied. A caller that retains a deep descendant should also retain its serialized ancestors.

    • filterBranches

      default Graph<T> filterBranches(Predicate<? super Graph<?>> predicate)
      Returns an immutable response view containing every matching placement, its complete descendant branch and the ancestors needed to preserve its serialized path. This is useful for selecting independently addressed branches: matching a parent retains its whole subtree, while matching a leaf retains only that leaf and its ancestors. The graph is traversed once; retained model values are shared and never copied.

    • children

      <C> List<Graph<C>> children(Class<C> childType)
      Returns direct children of the requested type.

    • children

      <C> List<Graph<C>> children(String path, Class<C> childType)
      Returns direct children placed at the requested explicit relationship path.

    • childModels

      default <C> List<C> childModels(Class<C> childType)
      Returns direct child values of the requested type.

    • childModels

      default <C> List<C> childModels(String path, Class<C> childType)
      Returns direct child values placed at the requested explicit relationship path.

    • descendants

      <D> List<Graph<D>> descendants(Class<D> descendantType)
      Returns all descendants assignable to the requested type in deterministic graph order.

    • descendants

      <D> List<Graph<D>> descendants(String path, Class<D> descendantType)
      Returns descendants reached through the requested relationship path.

    • descendantModels

      default <D> List<D> descendantModels(Class<D> descendantType)
      Returns all descendant values assignable to the requested type.

    • descendantModels

      default <D> List<D> descendantModels(String path, Class<D> descendantType)
      Returns descendant values reached through the requested relationship path.

    • stream

      default Stream<Graph<?>> stream()
      Lazily traverses this graph in deterministic pre-order, including this graph itself. Relationship context is loaded only when the returned stream is consumed.

    • find

      default Optional<Graph<?>> find(Predicate<? super Graph<?>> predicate)
      Finds the first graph in deterministic graph order matching the supplied condition.

    • find

      default Optional<Graph<?>> find(Object idOrAlias)
      Finds a graph by exact persisted identity or alias. Exact identities take precedence over aliases throughout the complete graph, even when an earlier graph owns a colliding alias.

    • find

      default <M> Optional<Graph<M>> find(Object idOrAlias, Class<M> modelType)
      Finds a graph by functional identity or alias and expected model type. The expected type applies the same EntityId and nested Id affixes as a typed model load.

    • find

      default <M> Optional<Graph<M>> find(Object idOrAlias, Class<M> modelType, GraphLookupPolicy lookupPolicy)
      Finds a graph by functional identity or alias and expected model type using the supplied ambiguity policy. Exact identities take precedence over aliases throughout the complete graph.

    • apply

      Graph<T> apply(Object update)
      Applies one update to this graph's current model and returns the staged resulting graph.

    • apply

      Graph<T> apply(Object update, io.fluxzero.common.api.Metadata metadata)
      Applies one update with explicit metadata.

    • apply

      Graph<T> apply(DeserializingMessage update)
      Applies a deserializing message.

    • apply

      Graph<T> apply(Message update)
      Applies a complete message.

    • apply

      Graph<T> apply(Object... updates)
      Applies the supplied updates in order.

    • apply

      Graph<T> apply(Collection<?> updates)
      Applies the supplied updates in order.

    • update

      Graph<T> update(UnaryOperator<T> update)
      Updates the current value directly. When returned by an apply interceptor, the staged update joins that interceptor's atomic model commit and is replayed against fresh state after an accepted conflict. The operator must therefore be deterministic and free of external side effects. Prefer apply(Object) for domain updates whose apply-specific event publication settings should govern the transition.

    • delete

      default Graph<T> delete()
      Marks this model as deleted and returns the staged resulting graph. Return it from model handling so it joins the surrounding commit, or call commit() for an explicit graph operation.

    • commit

      Graph<T> commit()
      Explicitly commits staged changes. Normal handler processing commits automatically.

    • assertLegal

      <E extends Exception> Graph<T> assertLegal(Object update) throws E
      Verifies that the supplied update is legal and returns this graph.
      Throws:
      E

    • assertAndApply

      Graph<T> assertAndApply(Object update)
      Verifies and applies the supplied update. For an independent Model, this enters the regular model pipeline and returns after the selected model commit is durable; payload IDs do not replace this graph's explicit identity. Interceptor payload transformations retain that identity, while returning an explicit Message starts a separately routed update. Aggregate-backed graphs retain their surrounding aggregate lifecycle.

    • assertAndApply

      Graph<T> assertAndApply(Object update, io.fluxzero.common.api.Metadata metadata)
      Verifies and applies the supplied update with explicit metadata.

    • assertAndApply

      default Graph<T> assertAndApply(Object... updates)
      Verifies and applies the supplied updates in order.

    • assertAndApply

      default Graph<T> assertAndApply(Collection<?> updates)
      Verifies and applies the supplied updates in order.

    • previous

      @Nullable Graph<T> previous()
      Returns the preceding model revision as a lazy graph, or null when none is retained. Surrounding models and relationships are resolved immediately before the current revision became effective. This keeps children added after the preceding root revision visible while excluding changes made by the update whose before-state is being observed.

    • revisions

      default Stream<Graph<T>> revisions()
      Returns current and retained preceding revisions, newest first.

    • highestEventIndex

      @Nullable default Long highestEventIndex()
      Returns the newest event index retained by this graph's revision history.

    • atStateIndex

      Graph<T> atStateIndex(long stateIndex)
      Returns the same model graph reconstructed at the requested durable state boundary.

    • playBackToEvent

      Optional<Graph<T>> playBackToEvent(Long eventIndex, String eventId)
      Plays back to the first retained revision matching the supplied event boundary.

    • playBackToCondition

      Optional<Graph<T>> playBackToCondition(Predicate<Graph<T>> condition)
      Plays back to the first retained revision matching the supplied condition.

    • hasChanged

      default boolean hasChanged(Function<? super T, ?> selector)
      Returns whether the selected value differs from the preceding revision.

    • previousValue

      @Nullable default <V> V previousValue(Function<? super T, V> selector)
      Returns the selected value from the preceding revision, or null when unavailable.