An identity class models an entity whose distinctness comes from its identity rather than solely from current data values. In persistence-oriented designs, classes such as Invoice, Customer, and LineItem become database-backed entities with identifiers, relationships, mutable fields, and nullable concessions. section 5.1.3
Identity classes shape the surrounding application in recognizable ways:
- Repositories expose CRUD operations such as getById and save, while services gather repositories and external APIs around business workflows. section 5.1.3
- Canonical entities often absorb difficult distinctions through enums and nullable fields instead of separate domain representations. section 5.1.3
- A mutable identity class can be wrapped by a record when data-oriented code needs a lightweight informational view without immediately rewriting the entity. section 5.4.1
Wrapping mutable identity
A record PastDue(Invoice invoice) captures an informational fact about an Invoice. The wrapper does not make Invoice immutable, but it creates a boundary that discourages in-place mutation while the model evolves toward clearer data representations. section 5.4.1
Listing 5.2 The core Entities we’re starting with
enum InvoiceType {LATEFEE, STANDARD}; #A
enum InvoiceStatus {OPEN, CLOSED}
@Entity #B
class Invoice {
@ID #B
String invoiceId;
String customerId;
@ManyToOne #B
List<LineItem> lineItems;
InvoiceStatus status;
LocalDate invoiceDate;
LocalDate dueDate;
InvoiceType type;
@Nullable
AuditInfo auditInfo; #C
}
@Entity
class LineItem {
@Id
String id;
String description;
BigDecimal charges; #D
Currency currency; #D
}
@Entity
class AuditInfo {
@Id
@OneToOne
String invoiceId;
@ManyToMany
List<Invoice> includedInFee;
@Nullable
String cannotBillReason;
}
@Entity
class Customer { #E
@ID
String customerId;
Address address;
@Nullable
String approvalId; #F
} Inspect the entity listing to see identifiers, relationships, enums, mutable fields, and nullable persistence-driven state in one model. section 5.1.3
Listing 5.52 The finished model
record PastDue(Invoice value) {}
sealed interface Lifecycle {
record Draft() implements Lifecycle {}
record Billed(String invoiceId) implements Lifecycle {}
record Rejected(Reason reason) implements Lifecycle {}
record InReview(ApprovalId approvalId) implements Lifecycle {}
}
record LateFee<State extends Lifecycle>(
String customerId,
USD total,
State state,
LocalDate invoiceDate,
LocalDate dueDate,
List<Invoice> includedInFee
){}
sealed interface ReviewedFee {
record Billable(LateFee<Draft> latefee)
implements ReviewedFee {}
record NeedsReview(LateFee<Draft> latefee)
implements ReviewedFee {}
record NotBillable(LateFee<Draft> latefee, Reason reason)
implements ReviewedFee {}
}
record EnrichedCustomer(
CustomerId id,
Address address,
Percent feePercentage,
PaymentTerms terms,
CustomerRating rating,
Optional<Approval> approval
){}
List<PastDue> collectPastDue(List<Invoice> invoices){...}
LateFee<Lifecycle.Draft> buildDraft(List<PastDue> invoices){...}
ReviewedFee assesDraft(LateFee<Lifecycle.Draft> invoice){...}
LateFee<? extends Lifecycle> submitBill(Billable draft){...}
LateFee<InReview> startApproval(NeedsReview needsReview){...}
record USD(BigDecimal value) {}
record CustomerId(String value){}
record ApprovalId(String value){}
record Reason(String value) {}
record Percent(double numerator, double denominator) { /*...*/ }Compare identity-centered entities with purpose-built records and sealed types that make lifecycle states and domain distinctions explicit. section 5.7
