Annotation Interface Member

@Documented
@Target({FIELD,METHOD,ANNOTATION_TYPE})
@Retention(RUNTIME)
@Inherited
public @interface Member

Indicates that the annotated field or getter represents a nested entity or collection of entities within an aggregate, independently stored model, or stateful handler.

Entities marked with @Member share the persistence boundary of their owning root. Within an @Aggregate or @Model, they share the root's stream, cache, search document, snapshots, and lifecycle. When an update targets a nested entity, Fluxzero traverses the root structure to locate the correct entity (or entities). In @Stateful handlers, member objects may also declare @Handle... methods and their own @Association properties; updates are written back by storing the parent stateful handler.

For a Model, choose @Member only when the nested value deliberately has no independent lifecycle: creation, change history, retention, and deletion all belong to the root. State that can live or evolve independently is another Model, connected through Parent, even when it is normally rendered as an item in a root collection. A meaningful identity is strong evidence of that independent lifecycle, but the identity may be parent-scoped; lack of a globally unique functional ID is not a reason to embed. Searchability, update frequency, load strategy, and convenient collection placement are persistence or query choices, not lifecycle boundaries.

This annotation supports modeling persistence roots with deliberately embedded values, for example:

@Model
public class Invoice {
    @EntityId
    String invoiceId;

    @Member
    List<InvoiceLine> lines;
}

Here, a line exists only as part of its invoice and deliberately shares the invoice's entire lifecycle. Updates targeting InvoiceLine values are routed by matching the identifier declared inside that class.

Support for new entities

If no matching entity is found for a given update, Fluxzero will still evaluate the update against applicable @Apply and @AssertLegal methods. This allows new entity creation directly from the update payload when appropriate logic is defined.
For example:

@Apply
InvoiceLine create() {
    return new InvoiceLine(lineId, amount);
}

will be used to create a new InvoiceLine if no matching line exists in the lines member list.

Immutability and parent updates

Fluxzero assumes immutability by default. When a nested entity is added, removed, or modified, Fluxzero will attempt to create a new version of the parent entity by copying and updating the annotated container field (list, map, etc.). The parent is not modified directly.
This behavior ensures safe update propagation and accurate change tracking, especially during event sourcing.
For example, if Invoice has a list of InvoiceLines:

@Member
List<InvoiceLine> lines;

and one line is updated, Fluxzero will replace the lines list with a new list containing the updated value.

For record owners, Fluxzero rebuilds the owner through the canonical constructor when the member is a record component. For Kotlin data classes, Fluxzero can use the generated copy(...) method. A type can still expose an explicit wither such as withLines(...) or configure wither() when custom update behavior is needed.

public record Invoice(@EntityId String id, @Member List<InvoiceLine> lines) {
    public Invoice withLines(List<InvoiceLine> lines) {
        return new Invoice(id, lines);
    }
}

Optional attributes

• idProperty (default: empty):
  Use this to explicitly specify the identifier property name on the nested entity. By default, Fluxzero locates the identifier via the EntityId annotation.
• wither (default: empty):
  Defines a method (by name) that should be invoked to update the container when the entity is added, removed, or replaced. Normally, Fluxzero will update the container (e.g., list or map) automatically. This setting is useful for immutable containers or cases requiring side effects during updates.

Supported container types:

• Single nested entities (e.g., Product product)
• Collections of entities (e.g., List<Product>). Non-null EntityId values must be unique within one member collection.
• Maps of entities keyed by their identifier. Newly added map members use EntityId or idProperty() as the map key.

See Also:

• EntityId
• Aggregate
• Model
• Apply
• AssertLegal

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	idProperty	Specifies the name of the identifier property on the nested entity, if different from the default detected one.
String	wither	Optionally defines the name of a method that should be used to apply updates to the container of the nested entity.

Element Details

idProperty

String idProperty

Specifies the name of the identifier property on the nested entity, if different from the default detected one.

Default:

""

wither

String wither

Optionally defines the name of a method that should be used to apply updates to the container of the nested entity.

Normally, Fluxzero automatically updates the container (for lists, maps, or singletons). This attribute is only necessary if a custom update method must be invoked instead.

Default:

""