Annotation Interface Parent

@Documented @Target({FIELD,METHOD}) @Retention(RUNTIME) public @interface Parent
Declares that a model property contains the ID of a parent model.

Both sides remain independent model and persistence boundaries. Use a parent relationship when the child has its own creation, update history, retention, or deletion lifecycle but belongs in the parent's domain graph. Being rendered below the parent, or being deleted with it by default, does not turn the child into an embedded Member. A child identifier that is meaningful only below this parent can use EntityId.parentScoped().

A parent reference is stored independently from both model values so changing this property can attach, detach, or move the child without loading or rewriting either parent. A null value means that the property currently has no parent. Non-null values use their Object.toString() representation as the referenced model identity.

The parent model type is inferred when the property is an Id<T>. For a String or another untyped ID, value() may name the parent model explicitly. An explicit type is required only for features that need parent model metadata, including automatic graph-document composition. A typed parent may target the declaring model type itself, for example to represent folders within folders. Concrete relationship cycles are rejected atomically when the relationship change is committed.

pathInParent() is an optional path relative to the parent document. Supplying it opts this edge into automatic virtual-document stitching and CQRS graph placement. Omitting it leaves relationship navigation and graph bundles available without silently deriving a durable document path from a Java class name. The path names a list-valued collection: the runtime appends deterministic numeric child positions, so numeric path segments are not allowed. Graph placement is independent from Model.persistence(): a child without a direct document but with an explicit path is retained in a type-isolated private current-document collection for composition and indexed relationship selection, but is not exposed through its own collection. Parent and Graph searches can therefore select matching children first and traverse their current relationship edges without composing unrelated roots. apiDoc() optionally describes the list-valued property created at that path when the graph is used as a documented web response. It has no effect unless pathInParent() is set.

By default the relationship also owns the child's lifecycle: deleting the referenced parent deletes this model and its likewise owned descendants in the same atomic model commit. Set deleteOnParentDeletion() to false for a shared or independently retained child. This lifecycle rule does not require a graph path and moving a child by changing its parent ID does not count as parent deletion.

Declaring metadata does not cause a parent to be loaded when the child is loaded or updated. A one-to-one companion model may annotate the same property with EntityId; entity-ID affixes affect only the companion's repository identity and do not alter the parent reference value.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    ApiDoc
    apiDoc
    Optional API documentation for the list-valued graph property at pathInParent().
    boolean
    deleteOnParentDeletion
    Whether this model is deleted when the referenced parent is logically deleted.
    String
    pathInParent
    Optional slash-separated, non-reserved collection path relative to the parent document.
    Class<?>[]
    types
    Explicit possible parent model types for a polymorphic Id property.
    Class<?>
    value
    Explicit parent model type for an untyped ID.

  • Element Details

    • value

      Class<?> value
      Explicit parent model type for an untyped ID. Must match the inferred Id target when both are present.
      Default:
      void.class

    • types

      Class<?>[] types
      Explicit possible parent model types for a polymorphic Id property.

      At runtime the concrete Id subtype selects exactly one of these model types through its declared type. This keeps graph validation, API documentation, cascade deletion and cycle detection statically knowable while allowing one domain property such as Id<?> nominee to refer to different model types. This attribute and value() are mutually exclusive.

      Default:
      {}

    • pathInParent

      String pathInParent
      Optional slash-separated, non-reserved collection path relative to the parent document.
      Default:
      ""

    • apiDoc

      ApiDoc apiDoc
      Optional API documentation for the list-valued graph property at pathInParent().

      The child item schema is inferred from the model that declares this parent reference. Nested path segments are represented as objects, while the final path segment is represented as an array of child models. Structural ApiDoc hints such as ApiDoc.type(), ApiDoc.format(), and ApiDoc.implementation() cannot override that inferred array and child type. Use ApiDoc.exclude() to keep this relationship out of every documented graph while retaining it in the runtime model graph.

      Default:
      @io.fluxzero.sdk.web.ApiDoc

    • deleteOnParentDeletion

      boolean deleteOnParentDeletion
      Whether this model is deleted when the referenced parent is logically deleted.

      The default expresses ordinary parent-owned child lifecycle. Opt out for shared graph edges or models which must remain independently addressable after their parent disappears.

      Default:
      true