Part 036 — JPA Mapping Association Patterns

Association mapping adalah area JPA yang paling sering terlihat sederhana tetapi mahal di production.

Satu anotasi:

@OneToMany(cascade = CascadeType.ALL, orphanRemoval = true)

bisa berarti:

• banyak query;
• cascade insert/update/delete;
• orphan delete;
• collection dirty checking;
• fetch strategy;
• ordering;
• ownership;
• FK update;
• N+1;
• cartesian explosion;
• data loss jika collection diganti dari request DTO.

Association harus dimodelkan berdasarkan lifecycle dan access pattern, bukan hanya berdasarkan foreign key.

Part ini membahas pola mapping association JPA untuk production.

1. Core Thesis

JPA association mapping harus menjawab:

Do we need object navigation?
Who owns the relationship?
Who owns child lifecycle?
How large can the collection be?
How is it loaded?
Can it be modified independently?
What cascade is safe?
What database constraints enforce truth?

Do not map every FK as object association automatically.

Sometimes best mapping is simply:

@Column(name = "officer_id")
private UUID officerId;

instead of:

@ManyToOne(fetch = FetchType.LAZY)
private OfficerEntity officer;

2. Association Types

JPA association types:

Production preference:

Use explicit join entity for rich many-to-many.
Use unidirectional/FK field when object navigation is not needed.
Be very careful with collections.

3. Many-to-One Pattern

Example assignment references case:

@Entity
@Table(name = "case_assignment")
public class CaseAssignmentEntity {
    @Id
    private UUID id;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(
        name = "case_id",
        nullable = false,
        foreignKey = @ForeignKey(name = "fk_case_assignment_case")
    )
    private CaseFileEntity caseFile;

    @Column(name = "officer_id", nullable = false)
    private UUID officerId;
}

Always specify fetch = FetchType.LAZY because JPA default for many-to-one is eager.

4. Many-to-One as FK Field

Alternative:

@Column(name = "case_id", nullable = false)
private UUID caseId;

Pros:

• no proxy;
• no lazy loading;
• simple insert/update;
• less object graph complexity;
• good for DAO/projection/batch.

Cons:

• no object navigation;
• no cascade via association;
• manual FK handling.

For many systems, FK field is better for references outside aggregate boundary.

5. Many-to-One Decision

Use object association if:

• navigation is common inside transaction;
• parent lifecycle relevant;
• cascade/locking/fetch plan intentionally used;
• association belongs to same module/aggregate.

Use FK field if:

• only need ID;
• reference belongs to another aggregate/service;
• avoiding lazy loading matters;
• query uses DTO projection;
• batch operation;
• simple insert with FK.

Do not map association for aesthetics.

6. One-to-Many Pattern

Parent collection:

@OneToMany(
    mappedBy = "caseFile",
    cascade = CascadeType.ALL,
    orphanRemoval = true
)
private List<CaseAssignmentEntity> assignments = new ArrayList<>();

Child owns FK via @ManyToOne.

Parent helper:

public void addAssignment(CaseAssignmentEntity assignment) {
    assignments.add(assignment);
    assignment.setCaseFile(this);
}

public void removeAssignment(CaseAssignmentEntity assignment) {
    assignments.remove(assignment);
    assignment.setCaseFile(null);
}

Bidirectional association must keep both sides in sync.

7. One-to-Many Without Parent Collection

You do not always need parent collection.

Instead:

CaseAssignmentRepository.findActiveByCaseId(caseId)

This can be better when:

• child collection large;
• child access is query-specific;
• parent command does not need all children;
• read path uses projection;
• child lifecycle independent.

Avoid loading huge child collections through aggregate root.

8. Collection Size Rule

Before @OneToMany, ask:

Can this collection grow unbounded?

Examples:

• audit logs: unbounded;
• actions/history: unbounded;
• documents: maybe bounded, maybe not;
• assignments: maybe bounded by rule;
• line items: bounded-ish per order;
• comments: unbounded.

Unbounded collection should not be ordinary eager/lazy entity collection for command aggregate.

Use query/chunk instead.

9. One-to-Many Fetch

Default @OneToMany fetch is LAZY.

Keep it lazy by default.

But lazy collection access can create:

• N+1;
• lazy init exception;
• hidden query during serialization;
• large load unexpectedly.

For read screen, use DTO projection or explicit query.

For command, load required children intentionally.

10. One-to-Many Cascade

Cascade all:

cascade = CascadeType.ALL

Means persist, merge, remove, refresh, detach cascade to children.

Use only when parent truly owns child lifecycle.

Good:

Order -> OrderLine
CaseDraft -> DraftAttachmentMetadata

Danger:

CaseFile -> Officer
CaseFile -> AuditLog
CaseFile -> OutboxEvent

Never cascade remove to shared aggregate/reference.

11. Orphan Removal

orphanRemoval = true

Removing child from collection deletes row.

Good for owned child:

Order line removed from draft order.

Danger:

Audit/event/history removed because collection replaced.

Example bug:

entity.setAssignments(mapper.toEntities(request.assignments()));

If old collection replaced, Hibernate may delete old children.

Prefer explicit mutation methods.

12. Collection Replacement Anti-Pattern

Bad:

public void setAssignments(List<CaseAssignmentEntity> assignments) {
    this.assignments = assignments;
}

with orphan removal.

Better:

public void assignPrimaryOfficer(UUID officerId, Instant now) {
    endCurrentPrimaryAssignment(now);
    addAssignment(CaseAssignmentEntity.primary(officerId, now));
}

Expose domain operation, not raw collection setter.

13. Many-to-Many Avoidance

Avoid:

@ManyToMany
@JoinTable(...)
private Set<ReviewerEntity> reviewers;

For production domain, join table often needs attributes:

• role;
• status;
• created_at;
• created_by;
• ended_at;
• reason;
• version;
• audit;
• source command.

Use join entity:

@Entity
@Table(name = "case_reviewer")
class CaseReviewerEntity {
    @Id
    private UUID id;

    @ManyToOne(fetch = FetchType.LAZY)
    private CaseFileEntity caseFile;

    @Column(name = "reviewer_id")
    private UUID reviewerId;

    @Column(name = "role")
    private String role;

    @Column(name = "started_at")
    private Instant startedAt;

    @Column(name = "ended_at")
    private Instant endedAt;
}

14. Join Entity Benefits

Explicit join entity gives:

• attributes on relationship;
• lifecycle;
• versioning;
• constraints;
• audit;
• status;
• query flexibility;
• no hidden many-to-many collection behavior.

Database constraints:

create unique index uq_case_reviewer_active_role
on case_reviewer(case_id, reviewer_id, role)
where ended_at is null;

This is much stronger than raw @ManyToMany.

15. One-to-One Pattern

Example case has detail row:

@OneToOne(fetch = FetchType.LAZY, optional = false, cascade = CascadeType.ALL)
@JoinColumn(name = "detail_id", nullable = false)
private CaseDetailEntity detail;

Or shared primary key:

@OneToOne(fetch = FetchType.LAZY, mappedBy = "caseFile", cascade = CascadeType.ALL)
private CaseDetailEntity detail;

Use one-to-one when lifecycle truly one-to-one.

Sometimes simpler to keep columns in same table or use explicit FK query.

16. One-to-One Lazy Caveat

Lazy one-to-one can be provider-specific/tricky depending ownership and bytecode enhancement.

Do not assume it is lazy without verifying SQL.

If detail is large/optional, consider:

• separate query;
• DTO projection;
• explicit repository load;
• FK field;
• bytecode enhancement with tests.

17. Ownership Side

Owning side controls FK.

For bidirectional one-to-many:

CaseAssignmentEntity.caseFile

is owning side with @JoinColumn.

CaseFileEntity.assignments with mappedBy is inverse side.

If you update only inverse side incorrectly, FK may not change.

Always update owning side.

Helper methods prevent bugs.

18. Unidirectional One-to-Many

JPA supports unidirectional one-to-many, often via join table or FK depending mapping.

It can generate less intuitive schema/SQL.

For relational clarity, bidirectional with child owning FK or child-only many-to-one is often clearer.

19. Collection Type: List vs Set

List:

• ordered by index/order if configured;
• duplicates possible unless domain prevents;
• easier for ordered child rows.

Set:

• needs correct equals/hashCode;
• entity equality pitfalls;
• can hide duplicate object issues;
• may be expensive.

Do not choose Set hoping it enforces database uniqueness. Use unique constraint.

20. Ordering Collections

@OrderBy:

@OrderBy("startedAt DESC")
private List<CaseAssignmentEntity> assignments;

Orders when collection loaded.

@OrderColumn:

@OrderColumn(name = "position")
private List<LineItemEntity> lineItems;

Persists list order, can cause many updates when reordering.

For large collections, query with explicit order instead.

21. Map Association

Sometimes:

@MapKey(name = "role")
@OneToMany(mappedBy = "caseFile")
private Map<String, CaseReviewerEntity> reviewersByRole;

Can be useful for bounded keyed child collection.

But map key must be stable and constraints enforce uniqueness.

For complex queries, DAO/projection may be clearer.

22. Association and Aggregate Boundary

If child cannot be modified outside parent invariant, association can be aggregate internal.

If child is independent aggregate, avoid cascade and direct collection mutation.

Example:

CaseFile references Officer.
Officer is separate aggregate.

Do not cascade from case to officer.

Store officer ID or lazy many-to-one without cascade.

23. Association and Tenant

Foreign keys should not cross tenant.

Database constraints can include tenant-aware uniqueness/FK design.

At application level, association loading should not accidentally load entity from another tenant.

If using plain UUID FK, repository query must include tenant predicate.

For high safety, composite FK (tenant_id, id) can enforce tenant consistency, but mapping becomes more complex.

24. Association and Soft Delete

If child soft-deleted:

ended_at is not null

or:

deleted_at is not null

JPA collection may still include it unless filtered.

Options:

• explicit query for active children;
• provider filter/where annotation;
• separate active collection;
• avoid collection and use DAO.

Be careful with provider-specific filters. They can hide rows needed for admin/audit.

25. Association Filter Anti-Pattern

Using provider-specific @Where to hide deleted rows can be convenient.

Risk:

• admin cannot see hidden rows through same entity;
• constraints/invariants may need all rows;
• debugging confusion;
• provider-specific.

Use intentionally and document.

26. Association Fetch Plan

For command:

loadForAssignment(caseId)

may need active assignments.

Options:

• JPQL fetch join;
• entity graph;
• separate query;
• repository composes entity + children;
• direct SQL/projection.

Do not rely on random lazy loading in domain method.

27. Fetch Join for Association

select distinct c
from CaseFileEntity c
left join fetch c.assignments a
where c.id = :id

Cautions:

• collection fetch join duplicates parent rows;
• distinct may be needed;
• multiple collection fetch joins can explode;
• pagination with collection fetch join is problematic;
• large collection loads fully.

Use for bounded associations.

28. Multiple Collection Fetch Join

Fetching:

case assignments
case documents
case actions

in one query can create cartesian explosion.

If each has 10 rows:

10 * 10 * 10 = 1000 rows for one case

Better:

• separate section queries;
• DTO detail view;
• bounded recent actions;
• read model.

29. Association and Serialization

Do not serialize entity association graph to JSON.

Issues:

• lazy loading;
• recursion;
• sensitive data;
• huge payload;
• N+1;
• closed session error.

Use response DTO.

Annotations like @JsonIgnore are band-aids, not architecture.

30. Association and DTO Mapping

Mapping entity to DTO can trigger lazy loads:

dto.officerName = entity.getOfficer().getDisplayName();

If not fetched, query occurs.

For list projections, use SQL/JPQL DTO query.

For detail, load explicit fetch plan or section queries.

31. Association and Batch

Batch processing entity associations can be expensive.

Bad:

for (CaseFileEntity c : cases) {
    for (AssignmentEntity a : c.getAssignments()) {
        ...
    }
}

May trigger N+1 and huge context.

Better:

• query needed rows directly;
• process by IDs;
• batch fetch if moderate;
• use projection.

32. Association and Database Constraints

JPA mapping is not enough.

Use DB constraints:

• FK;
• unique constraints;
• partial unique indexes if supported;
• not null;
• check;
• indexes for FK/filter.

Example active primary assignment:

create unique index uq_case_active_primary_assignment
on case_assignment(case_id)
where assignment_type = 'PRIMARY'
  and ended_at is null;

JPA association cannot enforce concurrency uniqueness alone.

33. Association and Indexes

Every FK usually needs index depending DB/workload.

create index ix_case_assignment_case_id
on case_assignment(case_id);

Query for active children:

create index ix_case_assignment_case_active
on case_assignment(case_id, assignment_type)
where ended_at is null;

Association mapping without indexes creates slow lazy loads and deletes.

34. Association and Delete

Deleting parent with children:

Options:

• cascade remove through ORM;
• DB on delete cascade;
• soft delete parent and children;
• reject delete if children exist;
• explicit domain transition.

For domain data, hard delete/cascade often dangerous.

Audit/legal systems usually prefer status/archive.

35. DB Cascade vs ORM Cascade

ORM cascade:

• happens in persistence context;
• can trigger entity callbacks;
• can generate many SQL statements;
• controlled by object graph.

DB cascade:

• database deletes children automatically;
• ORM may not know if entities managed;
• callbacks not invoked;
• efficient but hidden from app object state.

Use DB cascade mostly for technical dependent rows where semantics are clear. Avoid for audit-critical domain deletion unless intended.

36. Association and Optimistic Version

Child update may not increment parent version.

If aggregate version should reflect child changes, handle explicitly:

• update parent field;
• force increment lock;
• child has own version plus aggregate rules;
• DB trigger;
• repository saves parent.

Test:

assignReviewer();
assert parent version incremented

If version does not increment, events/projections relying on parent version may be wrong.

37. Association and Locking

Parent row lock pattern:

CaseFileEntity caseFile = entityManager.find(
        CaseFileEntity.class,
        id,
        LockModeType.PESSIMISTIC_WRITE
);

Then modify child collection.

This serializes child invariant if all code paths lock parent.

JPA association alone does not lock children or parent automatically unless operation does so.

38. Association and Lazy Proxy Equality

Lazy proxies can complicate:

officer.getClass()

may be proxy class.

equals using getClass() can behave unexpectedly with proxies.

Use consistent equality strategy and test if entities appear in sets/maps.

Avoid exposing proxies outside persistence context.

39. Association and toString

Do not include lazy associations in toString.

Bad:

return "CaseFile(assignments=" + assignments + ")";

Can trigger lazy loading or recursion.

Keep entity toString simple:

CaseFileEntity{id=..., status=...}

40. Association and Lombok

Be careful with Lombok @Data on entities.

It generates:

• getters/setters for everything;
• equals/hashCode including associations;
• toString including associations.

This can trigger lazy loading, recursion, and equality bugs.

Avoid @Data on JPA entities.

Use explicit methods or limited Lombok annotations with exclusions.

41. Association and Immutable Collections

Expose collections as read-only:

public List<CaseAssignmentEntity> assignments() {
    return Collections.unmodifiableList(assignments);
}

Provide methods:

addAssignment(...)
endAssignment(...)

Prevents external arbitrary collection replacement.

JPA still needs mutable field internally.

42. Association and Domain Method

public void assignPrimaryOfficer(UUID officerId, Instant now) {
    endActivePrimaryAssignment(now);

    CaseAssignmentEntity assignment =
            CaseAssignmentEntity.primary(this, officerId, now);

    assignments.add(assignment);

    this.updatedAt = now;
}

This keeps association mutation controlled.

Still need database constraint for concurrency.

43. Association and Partial Loading

If assignments not loaded, domain method may trigger lazy load.

This can be okay if command intentionally loaded aggregate with assignments.

But hidden I/O in domain method is risky.

Repository method name should say:

loadForAssignment(...)

and use fetch plan.

44. Association and Entity Graph

EntityGraph<CaseFileEntity> graph =
        entityManager.createEntityGraph(CaseFileEntity.class);
graph.addSubgraph("assignments");

CaseFileEntity entity = entityManager.find(
        CaseFileEntity.class,
        id,
        Map.of("jakarta.persistence.fetchgraph", graph)
);

Useful for use-case-specific loading.

Test SQL and graph size.

45. Association and Query Service

For read endpoints, prefer query service.

CaseDetailView view = caseDetailQuery.getDetail(id);

with explicit section queries.

Do not require association graph to match every view shape.

46. Association and Migration

Changing association mapping often requires schema migration.

Examples:

• many-to-many join table becomes join entity;
• nullable FK becomes not null;
• one-to-one split table;
• child table gets status/history;
• cascade behavior changes.

Plan rolling deployment compatibility.

47. Association Failure Mode: N+1

Symptom:

• one query loads cases;
• many queries load assignments/officers.

Fix:

• DTO projection;
• fetch join;
• batch fetch;
• read model.

Add query count tests.

48. Association Failure Mode: Cartesian Explosion

Symptom:

• one detail endpoint returns slow/huge query;
• duplicate parent rows;
• memory spike.

Cause:

• multiple collection fetch joins.

Fix:

• separate queries;
• bounded sections;
• read model.

49. Association Failure Mode: Accidental Delete

Symptom:

• child rows disappear after update.

Cause:

• orphan removal + collection replacement;
• cascade remove too broad.

Fix:

• explicit add/remove;
• remove orphan removal where unsafe;
• test child lifecycle.

50. Association Failure Mode: Shared Entity Cascade

Symptom:

• deleting case deletes officer/reference data.

Cause:

• cascade remove to shared association.

Fix:

• remove cascade;
• use FK field or many-to-one without cascade;
• restore data from backup if production.

51. Association Failure Mode: Version Not Incremented

Symptom:

• assignment changes but case version unchanged;
• projection ordering wrong;
• stale event version.

Fix:

• force parent version increment;
• update parent updatedAt;
• explicit version strategy.

52. Association Review Checklist

• Association is needed, not just FK mirror.
• Ownership side understood.
• Fetch type explicit.
• Collection bounded or avoided.
• Cascade matches lifecycle ownership.
• Orphan removal safe.
• Many-to-many avoided if relationship has attributes.
• Join entity used for rich relationship.
• Helper methods sync bidirectional sides.
• No entity exposed to JSON.
• No Lombok @Data on entity.
• DB constraints/indexes enforce relationship truth.
• Parent version behavior tested.
• N+1/cartesian risks tested.
• Tenant boundaries respected.
• Delete behavior explicit.

53. Mapping Example: Case Assignment

@Entity
@Table(
    name = "case_assignment",
    indexes = {
        @Index(name = "ix_case_assignment_case_active", columnList = "case_id, ended_at")
    }
)
public class CaseAssignmentEntity {
    @Id
    @Column(nullable = false, updatable = false)
    private UUID id;

    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "case_id", nullable = false)
    private CaseFileEntity caseFile;

    @Column(name = "officer_id", nullable = false)
    private UUID officerId;

    @Column(name = "assignment_type", nullable = false, length = 32)
    private String assignmentType;

    @Column(name = "started_at", nullable = false)
    private Instant startedAt;

    @Column(name = "ended_at")
    private Instant endedAt;

    protected CaseAssignmentEntity() {}

    public static CaseAssignmentEntity primary(
            CaseFileEntity caseFile,
            UUID officerId,
            Instant now
    ) {
        CaseAssignmentEntity entity = new CaseAssignmentEntity();
        entity.id = UUID.randomUUID();
        entity.caseFile = caseFile;
        entity.officerId = officerId;
        entity.assignmentType = "PRIMARY";
        entity.startedAt = now;
        return entity;
    }

    public boolean isActivePrimary() {
        return "PRIMARY".equals(assignmentType) && endedAt == null;
    }

    public void end(Instant now) {
        if (endedAt == null) {
            endedAt = now;
        }
    }
}

54. Parent Helper Example

@Entity
@Table(name = "case_file")
public class CaseFileEntity {
    @OneToMany(
        mappedBy = "caseFile",
        cascade = CascadeType.ALL,
        orphanRemoval = false
    )
    private List<CaseAssignmentEntity> assignments = new ArrayList<>();

    public void assignPrimaryOfficer(UUID officerId, Instant now) {
        assignments.stream()
                .filter(CaseAssignmentEntity::isActivePrimary)
                .forEach(a -> a.end(now));

        CaseAssignmentEntity newAssignment =
                CaseAssignmentEntity.primary(this, officerId, now);

        assignments.add(newAssignment);

        this.updatedAt = now;
    }
}

Whether orphanRemoval is false/true depends lifecycle. For assignment history, usually do not delete ended assignment.

55. Test: Helper Syncs Association

@Test
void assignPrimaryOfficerPersistsChildWithCaseFk() {
    CaseFileEntity caseFile = fixture.managedCase();

    caseFile.assignPrimaryOfficer(officerId, now);

    entityManager.flush();
    entityManager.clear();

    List<CaseAssignmentRow> rows = jdbcQuery.assignments(caseFile.getId());

    assertThat(rows).hasSize(1);
    assertThat(rows.get(0).officerId()).isEqualTo(officerId);
}

56. Test: No Cascade Delete to Shared Reference

@Test
void deletingCaseDoesNotDeleteOfficer() {
    CaseFileEntity caseFile = fixture.caseAssignedToOfficer(officerId);

    entityManager.remove(caseFile);
    entityManager.flush();

    assertThat(officerQuery.exists(officerId)).isTrue();
}

If this fails, cascade is dangerous.

57. Test: Parent Version Increment

@Test
void assignmentChangeIncrementsCaseVersion() {
    CaseFileEntity caseFile = repository.loadForAssignment(caseId).orElseThrow();
    long before = caseFile.getVersion();

    caseFile.assignPrimaryOfficer(officerId, now);
    entityManager.lock(caseFile, LockModeType.OPTIMISTIC_FORCE_INCREMENT);
    entityManager.flush();

    assertThat(caseFile.getVersion()).isGreaterThan(before);
}

Adapt based on chosen strategy.

58. Anti-Pattern: Association Mapping for Every FK

Map only what object navigation/lifecycle needs.

59. Anti-Pattern: Many-to-Many for Domain Relationship

Use join entity when relationship has lifecycle/attributes.

60. Anti-Pattern: Cascade Remove to Shared Aggregate

Never cascade remove to shared reference/aggregate root.

61. Anti-Pattern: Orphan Removal on History/Audit

Audit/history should not disappear from collection mutation.

62. Anti-Pattern: Entity Graph as API Graph

Entity association graph is not API response graph.

Use DTO.

63. Mini Lab

Design associations for:

CaseFile
- primary officer
- many reviewers
- assignment history
- documents
- audit log
- outbox events
- risk score snapshot

Questions:

1. Which are FK fields only?
2. Which are ManyToOne?
3. Which are OneToMany?
4. Which need join entity?
5. Which collection is bounded?
6. Which cascade is safe?
7. Which should never orphan-remove?
8. Which read path should use DTO projection?
9. Which database constraints/indexes are needed?
10. How does parent version change when child changes?

64. Summary

JPA association mapping is not a class diagram exercise. It is lifecycle and data-access design.

You must master:

• many-to-one with explicit fetch;
• FK field alternative;
• one-to-many ownership;
• bidirectional sync helper;
• collection size rule;
• cascade design;
• orphan removal risk;
• many-to-many avoidance;
• join entity;
• one-to-one caveats;
• collection type/order;
• soft delete filtering;
• fetch plan;
• fetch join risk;
• DTO projection separation;
• DB constraints/indexes;
• parent version strategy;
• N+1/cartesian/delete failure modes;
• association tests.

Part berikutnya membahas Lazy Loading and N+1 secara khusus: fetch join, entity graph, batch size, subselect, projection strategy, query count tests, and production performance debugging.

65. References

• Jakarta Persistence Specification: https://jakarta.ee/specifications/persistence/3.2/jakarta-persistence-spec-3.2
• Hibernate ORM User Guide: https://docs.hibernate.org/stable/orm/userguide/html_single/
• Spring Data JPA Reference: https://docs.spring.io/spring-data/jpa/reference/