Java DDD Aggregates
Purpose and authority
Implement the domain aggregate patterns captured from ddd-example/domain. This is
the technical reference for this skill, not one optional DDD style among competing
examples. Preserve its differences between aggregates. Do not replace them with a
generic Order model, a richer base class, immutable roots, automatic validation,
transaction annotations or a new persistence version field.
The packaged references contain the relevant contracts and source provenance; the
authoring machine's C:\git\ddd-example\domain path is not a runtime prerequisite.
Inspect the target domain and build before editing. If a requested business rule or
new aggregate family has no counterpart in the supplied evidence, ask a focused
question about the missing rule or reference family. Keep unknown behavior explicit.
Workflow
- Map the aggregate to the reference. Identify its root, typed ID, validator,
Gateway interface and associated values/enums in one aggregate package. Keep
other roots as typed IDs. Read
aggregate organization when introducing
a root, deciding package placement or reviewing a relationship.
- Select the actual lifecycle family. Read
factories and lifecycle before changing
construction, reconstruction, copying, validation or transitions.
Category and
Video expose external validation; Genre and CastMember call selfValidate()
in their constructor and after assigning updated fields. An exception from the
latter does not undo those assignments. Preserve the selected family's
contract rather than standardizing these paths.
When implementing or reproducing a root, read its complete production template:
Category,
Genre,
CastMember or
Video. Follow its full signatures, checks,
method ordering and clock calls; use the lifecycle reference for dependencies
and adaptation rules. Do not infer missing code from the summary tables.
Resolve imported and same-package types through the
complete domain source index, which
covers all 49 production types across the hub and specialists. These sibling
resources require the optional java-ddd hub and owning specialists to be
available; installing this aggregate skill alone does not supply them. The
four root templates are not a standalone Java source set or build.
- Separate new state, restored state and copies.
newCategory, newGenre,
newMember and newVideo generate an ID and read time once. Full with(...)
restores the supplied facts. Copy with(existing) has aggregate-specific
collection and pending-event behavior. Category.clone() is a separate,
shallow-copy path; do not silently substitute it for with(...).
- Implement the observed transition. Keep mutable private state,
final
parameters, the actual constructor visibility, typed IDs and methods returning
this where the reference does. Preserve activation/deactivation, audit fields,
null handling and list/set behavior. Unmodifiable accessors do not establish
defensive ownership of constructor arguments. Fluent calls do not supply rollback.
- Verify observable domain behavior. Use real roots, IDs, values and validation
handlers. Every domain unit test must have a meaningful
@DisplayName; use no
mocks, spies, Mockito or framework context. Read
focused verification for executable examples and
cases that distinguish the lifecycle families. Assert the contract at the point
it actually runs, without adding business constraints absent from the reference.
When checking those paths against the reference module, use
AggregateLifecycleTest.java with its stated
prerequisites.
Scope and handoffs
java-ddd supplies the canonical foundation sources. Before introducing a root
or resolving its typed ID, read
AggregateRoot.java,
Entity.java,
Identifier.java
and ValueObject.java.
Reuse this foundation and its exceptions/utilities; root identity follows the
inherited ID-based equality.
java-ddd-value-objects owns concrete IDs and media/value semantics.
Preserve each ID factory's behavior instead of passing strings between roots.
java-ddd-domain-services owns validators and validation handlers. A validator
reports the root's current state and performs no Gateway call.
java-ddd-repositories owns the domain Gateway interfaces. Aggregates do not call
those interfaces; adapter implementation remains outside this domain-only task.
java-ddd-domain-events owns buffering, publication and media event semantics.
Read it when changing pending events; a successful domain method is not proof of
delivery or persistence.
java-ddd-testing owns the broader domain testing conventions.
Keep Spring/JPA/HTTP, application use cases, transactions, brokers and database
concurrency mechanisms outside this skill's implementation. The source domain has
no aggregate version field or locking protocol. A request for such guarantees needs
separate scope and evidence; a domain unit test cannot establish them.
Deliverable and compatibility
For implementation, deliver the affected root and supporting domain changes, identify
the reference family followed, and report executed checks. For review, show the
source method and the behavioral mismatch before proposing a correction. Preserve
adequate code and separate unknown business requirements from observed differences.
Keep the target Java and dependency versions. The reference build inspected for
this review declares JUnit Jupiter 5.9.2 but no explicit Java toolchain/release in
its shared conventions. The bundled verification class uses Java 17-compatible
source; that is an example compatibility target, not a claim about the reference's
declared Java baseline. Do not upgrade a project to apply this skill.
1---2name: java-ddd-aggregates3description: >-4 Implement and review Java domain aggregates using the ddd-example domain contract.5 Use when organizing aggregate packages, implementing typed roots, new/with factories,6 validation timing, lifecycle methods, cross-aggregate IDs or collection ownership.7 Covers Category, Genre, CastMember and Video patterns with domain unit checks;8 application orchestration, persistence adapters and concurrency protocols are outside scope.9metadata:10 source: https://skillmd.com/skills/robsonkades/java-ddd-aggregates11---1213# Java DDD Aggregates1415## Purpose and authority1617Implement the domain aggregate patterns captured from `ddd-example/domain`. This is18the technical reference for this skill, not one optional DDD style among competing19examples. Preserve its differences between aggregates. Do not replace them with a20generic Order model, a richer base class, immutable roots, automatic validation,21transaction annotations or a new persistence version field.2223The packaged references contain the relevant contracts and source provenance; the24authoring machine's `C:\git\ddd-example\domain` path is not a runtime prerequisite.25Inspect the target domain and build before editing. If a requested business rule or26new aggregate family has no counterpart in the supplied evidence, ask a focused27question about the missing rule or reference family. Keep unknown behavior explicit.2829## Workflow30311. **Map the aggregate to the reference.** Identify its root, typed ID, validator,32 Gateway interface and associated values/enums in one aggregate package. Keep33 other roots as typed IDs. Read34 [aggregate organization](references/aggregate-organization.md) when introducing35 a root, deciding package placement or reviewing a relationship.362. **Select the actual lifecycle family.** Read37 [factories and lifecycle](references/java-lifecycle-pattern.md) before changing38 construction, reconstruction, copying, validation or transitions. `Category` and39 `Video` expose external validation; `Genre` and `CastMember` call `selfValidate()`40 in their constructor and after assigning updated fields. An exception from the41 latter does **not** undo those assignments. Preserve the selected family's42 contract rather than standardizing these paths.43 When implementing or reproducing a root, read its complete production template:44 [Category](assets/reference/category/Category.java),45 [Genre](assets/reference/genre/Genre.java),46 [CastMember](assets/reference/castmember/CastMember.java) or47 [Video](assets/reference/video/Video.java). Follow its full signatures, checks,48 method ordering and clock calls; use the lifecycle reference for dependencies49 and adaptation rules. Do not infer missing code from the summary tables.50 Resolve imported and same-package types through the51 [complete domain source index](../java-ddd/references/source-index.md), which52 covers all 49 production types across the hub and specialists. These sibling53 resources require the optional `java-ddd` hub and owning specialists to be54 available; installing this aggregate skill alone does not supply them. The55 four root templates are not a standalone Java source set or build.563. **Separate new state, restored state and copies.** `newCategory`, `newGenre`,57 `newMember` and `newVideo` generate an ID and read time once. Full `with(...)`58 restores the supplied facts. Copy `with(existing)` has aggregate-specific59 collection and pending-event behavior. `Category.clone()` is a separate,60 shallow-copy path; do not silently substitute it for `with(...)`.614. **Implement the observed transition.** Keep mutable private state, `final`62 parameters, the actual constructor visibility, typed IDs and methods returning63 `this` where the reference does. Preserve activation/deactivation, audit fields,64 null handling and list/set behavior. Unmodifiable accessors do not establish65 defensive ownership of constructor arguments. Fluent calls do not supply rollback.665. **Verify observable domain behavior.** Use real roots, IDs, values and validation67 handlers. Every domain unit test must have a meaningful `@DisplayName`; use no68 mocks, spies, Mockito or framework context. Read69 [focused verification](references/verification.md) for executable examples and70 cases that distinguish the lifecycle families. Assert the contract at the point71 it actually runs, without adding business constraints absent from the reference.72 When checking those paths against the reference module, use73 [AggregateLifecycleTest.java](assets/AggregateLifecycleTest.java) with its stated74 prerequisites.7576## Scope and handoffs7778- `java-ddd` supplies the canonical foundation sources. Before introducing a root79 or resolving its typed ID, read80 [AggregateRoot.java](../java-ddd/assets/domain/src/main/java/com/robsonkades/admin/catalogo/domain/AggregateRoot.java),81 [Entity.java](../java-ddd/assets/domain/src/main/java/com/robsonkades/admin/catalogo/domain/Entity.java),82 [Identifier.java](../java-ddd/assets/domain/src/main/java/com/robsonkades/admin/catalogo/domain/Identifier.java)83 and [ValueObject.java](../java-ddd/assets/domain/src/main/java/com/robsonkades/admin/catalogo/domain/ValueObject.java).84 Reuse this foundation and its exceptions/utilities; root identity follows the85 inherited ID-based equality.86- `java-ddd-value-objects` owns concrete IDs and media/value semantics.87 Preserve each ID factory's behavior instead of passing strings between roots.88- `java-ddd-domain-services` owns validators and validation handlers. A validator89 reports the root's current state and performs no Gateway call.90- `java-ddd-repositories` owns the domain Gateway interfaces. Aggregates do not call91 those interfaces; adapter implementation remains outside this domain-only task.92- `java-ddd-domain-events` owns buffering, publication and media event semantics.93 Read it when changing pending events; a successful domain method is not proof of94 delivery or persistence.95- `java-ddd-testing` owns the broader domain testing conventions.9697Keep Spring/JPA/HTTP, application use cases, transactions, brokers and database98concurrency mechanisms outside this skill's implementation. The source domain has99no aggregate version field or locking protocol. A request for such guarantees needs100separate scope and evidence; a domain unit test cannot establish them.101102## Deliverable and compatibility103104For implementation, deliver the affected root and supporting domain changes, identify105the reference family followed, and report executed checks. For review, show the106source method and the behavioral mismatch before proposing a correction. Preserve107adequate code and separate unknown business requirements from observed differences.108109Keep the target Java and dependency versions. The reference build inspected for110this review declares JUnit Jupiter 5.9.2 but no explicit Java toolchain/release in111its shared conventions. The bundled verification class uses Java 17-compatible112source; that is an example compatibility target, not a claim about the reference's113declared Java baseline. Do not upgrade a project to apply this skill.