Applying DDD¶
This page covers modeling with aggregate roots, value objects and cross-aggregate associations using FluDa Data's DDD-aligned annotations.
Core concepts¶
FluDa Data provides annotations that map directly to Domain-Driven Design building blocks:
| DDD Concept | FluDa Annotation | Description |
|---|---|---|
| Aggregate Root | @AggregateRoot |
The entry point to an aggregate — a cluster of objects modified as a unit. The root controls all changes to its owned entities and value objects. |
| Entity | @Entity |
An object defined by its identity rather than its attributes. Entities within an aggregate have their own table and a foreign key back to the root. |
| Value Object | @ValueObject |
An immutable object defined entirely by its attributes — no identity. Value objects are embedded into the owning entity's table. |
These annotations let you model your domain in plain Java while FluDa handles the persistence mapping. The design follows DDD principles: aggregates are transactional boundaries, value objects are immutable and embedded, and entities have their own identity and lifecycle within the aggregate.
Aggregate Root¶
An aggregate is a cluster of objects that is modified as a unit through a single entry point: the aggregate root. Mark the root type with @AggregateRoot. Everything the root owns — embedded value objects, composed child entities and element collections — is persisted and loaded with it, and a save of the root cascades to the objects it owns.
import io.github.fludakit.data.annotation.AggregateRoot;
import io.github.fludakit.data.annotation.Identity;
@AggregateRoot
public class Profile {
@Identity Long id;
String fullName;
Address address; // value object -> flattened into this table
List<WorkExperience> workHistory; // entity collection -> own table, fk profile_id
List<Education> education; // entity collection -> own table, fk profile_id
List<ContactPoint> contacts; // value-object element collection -> child table
// getters and setters ...
}
The owner's fields are classified by the type they reference:
| Field | Type | Storage |
|---|---|---|
address |
@ValueObject |
Embedded — its leaves are flattened into the root's own table (address.city, address.zip, …). A value object has no identity of its own. |
contacts |
List< @ValueObject > |
Element collection — a child table (profile_contacts) keyed by the root's foreign key plus the flattened value-object columns. |
workHistory, education |
List< @Entity > |
Composition — each target is an entity with its own identity and its own table, carrying a foreign key back to the root (profile_id). |
Value objects¶
A @ValueObject is immutable in spirit and defined entirely by its attributes — it has no identity. Embedded value objects may nest (an Address may hold a GeoPoint), and their leaves are flattened into the owning table. Because they are part of the root's row, you can sort and filter through them with a dot path:
Composition children¶
A composed @Entity (such as WorkExperience) manages its own table and identity, and holds a reference back to the root. The child's bare inverse field maps to the same foreign key the aggregate loader walks:
@Entity
public class WorkExperience {
@Identity Long id;
String company;
int yearStart;
int yearEnd;
Profile profile; // inverse reference -> profile_id
// ...
}
Querying through a composition collection renders an EXISTS semi-join, so the root never fans out into duplicate rows and the count stays correct:
@Find
List<Profile> findByWorkHistoryCompany(@By("workHistory.company") String company);
long countByWorkHistoryCompany(String company); // query-by-method-name equivalent
Associations: referencing another aggregate¶
Not every relationship is composition. When a field points at an entity that belongs to a different aggregate (typically another bounded context), mark it @Association. An association is persisted as a foreign key only:
- On write, the referenced entity's identifier is extracted into the
<field>_idcolumn; the referenced entity itself is never cascaded. - On read, the reference is not eagerly resolved — the field is left
nulland the application resolves it lazily when it needs to.
@Entity
public class Order {
@Identity Long id;
BigDecimal amount;
@Association Customer customer; // persisted as customer_id, not cascaded
List<OrderItem> orderItems; // composition, owned by this aggregate
// ...
}
This keeps aggregate boundaries explicit: Order owns its orderItems, but only points at a Customer that some other aggregate owns and saves.