Designing Objects in Java
In this pack: sizing and rule strictness are set by the core
plugin's oo-design skill; each rule here keeps a core rule in this
language.
Overview
Java carries much of a design in its type system: a record for a value,
a sealed interface for a set the clinic closes, a checked exception for
a refusal, and Optional for an answer that may be absent. This skill
applies the pack's core rules to plain Java, from version 21 on, with no
framework. It says which feature keeps each rule and how the compiler
then helps: an equal value that stays equal while it sits in a set, a
switch that a new case cannot leave half-answered, and a caller that
cannot ignore a refusal by accident.
When to use
- A class holds several fields and two instances with the same contents
stand for the same thing.
- A set of cases is closed, and code answers it with
if chains or a
switch that has a default branch.
- A method on a port can fail in a way its caller can act on.
- A query can have no answer, and the code answers
null today.
- A class is public and has no subclass, and someone asks whether it may
be extended.
- Several implementations of one interface share a piece of behaviour.
When not to use
- The classes are built, wired or extended by a framework, such as one
that fills objects from annotations: outside this skill.
- The question is one no Java feature changes, such as which object owns
a rule or where a module's boundary runs. The core skills answer it,
starting from
oo-design.
- The source files are not
.java but Kotlin, another language that
runs on the same virtual machine: outside this skill; oo-kotlin says
which Kotlin feature keeps each rule.
Core rules
Default. Write a value as a record, check its rules in the compact
canonical constructor, and copy each collection component there with
List.copyOf, Set.copyOf or Map.copyOf. A record's components
are final fields, and the equals and hashCode it derives read all
of them, so a record is a value as
oo-modeling-values-and-entities rules 2 and 3 ask, once its
arguments are checked, as oo-constructing-valid-objects rule 3
asks, and its collections are copied, as
oo-encapsulating-state-and-behaviour rule 6 asks.
The exception is a value whose representation must stay hidden,
because each component of a record has a public accessor: write it as
a final class with private final fields, and give it equals and
hashCode as rule 2 asks.
Rule. In a class that compares by value, override equals and
hashCode together, from the same fields, and keep compareTo
consistent with equals, as oo-modeling-values-and-entities rule 3
asks. A field that equals reads never changes while its object
sits in a HashSet or keys a HashMap, because a set's behaviour is
not specified once an element changes in a way that affects equals:
a value has no such field, as oo-modeling-values-and-entities rule
2 says, and an entity compares by its identifier alone, as rule 4
there says.
Default. Close a set of cases the domain closes with a sealed
interface whose permitted classes are records, and answer each case in
a switch expression that names every permitted class and has no
default branch, as oo-making-illegal-states-impossible rule 2 and
oo-patterns-the-language-provides rule 5 ask: the compiler then
rejects a switch that a new case leaves out. The exception is a
set to which new kinds arrive more often than new operations: give
each kind its behaviour as a method of the interface, as
oo-replacing-conditionals-with-polymorphism rule 7 weighs it.
Rule. Declare on each method of a port, in its throws clause,
every checked exception its implementations throw, and let the adapter
catch a library's checked exception, such as IOException, and throw
the port's refusal or an unchecked fault in its place, as
oo-designing-failure-behaviour rule 7 asks. The compiler then
rejects an implementation that throws a checked exception its port
does not declare.
Default. Make a refusal a checked exception and a fault an unchecked
one, once oo-designing-failure-behaviour rule 2 has told them
apart. The compiler then makes each caller handle or declare a
refusal, which is how that rule asks a refusal to be declared, and
lets a fault pass up, undeclared, to the one handler at the edge; when
a module raises more than one refusal, they share a checked base
exception, as oo-designing-failure-behaviour rule 3 asks.
The exception is a refusal raised inside a function value that a
library method runs, such as the function given to a stream's map:
the library's functional interfaces declare no checked exception, so
loop over the items yourself where a refusal can be raised.
Rule. Answer a value that may be absent as an Optional, never as
null, as oo-designing-failure-behaviour rule 5 asks, and keep
Optional to return types, the use its documentation names. Where
absence is an error, throw instead.
Default. Declare a class final, or sealed with the classes it
permits, unless it was built for extension, as
oo-honouring-substitutability rule 5 asks; a record is final
already. The exception is a class built for extension: declare it
abstract, mark final each method a subclass must not override, and
write beside each method a subclass may override the contract the
override keeps.
Judgement. Choose a default method or an abstract class for
behaviour that implementations share, as oo-designing-interfaces
rule 4 chooses an interface or a base class: a default method when
it can be written from the interface's own abstract methods alone, an
abstract class when it needs fields or fixes the order in which its
own methods run. What tips the balance is whether the shared code
needs state, which an interface cannot hold.
Pattern
DosageInstruction is how often a patient takes one medication and the
warnings that go with it, and two instructions with the same contents
are the same instruction, a value
(oo-modeling-values-and-entities rule 1).
Before:
import java.util.List;
public class DosageInstruction {
private String medication;
private int timesPerDay;
private List<String> warnings;
public DosageInstruction(
String medication, int timesPerDay, List<String> warnings) {
this.medication = medication;
this.timesPerDay = timesPerDay;
this.warnings = warnings;
}
public void setTimesPerDay(int timesPerDay) {
this.timesPerDay = timesPerDay;
}
public List<String> getWarnings() {
return warnings;
}
@Override
public boolean equals(Object other) {
return other instanceof DosageInstruction that
&& medication.equals(that.medication)
&& timesPerDay == that.timesPerDay;
}
}
In the Before, setTimesPerDay changes a field that equals reads, so
an instruction changed while it sits in a HashSet leaves the set's
behaviour unspecified (rule 2), and equals is overridden without
hashCode, so two equal instructions can hash apart (rule 2). equals
ignores warnings, part of the instruction's contents
(oo-modeling-values-and-entities rule 3). The caller's list is kept
and handed out by getWarnings, so either holder can change it (rule 1,
oo-encapsulating-state-and-behaviour rule 6). Nothing refuses a blank
medication or no dose a day (rule 1).
After:
import java.util.List;
public record DosageInstruction(
String medication, int timesPerDay, List<String> warnings) {
public DosageInstruction {
if (medication.isBlank()) {
throw new IllegalArgumentException("no medication is named");
}
if (timesPerDay < 1) {
throw new IllegalArgumentException("fewer than one dose a day");
}
warnings = List.copyOf(warnings);
}
public DosageInstruction withTimesPerDay(int newTimesPerDay) {
return new DosageInstruction(medication, newTimesPerDay, warnings);
}
}
In the After, the record's equals and hashCode are derived from all
three components (rules 1 and 2). The compact constructor refuses a
blank medication and fewer than one dose a day, and it copies warnings
with List.copyOf, which answers an unmodifiable list (rule 1).
withTimesPerDay answers a new instruction instead of changing this
one (rule 1). isBlank answers whether a string is empty or holds only
white space. Every field is set by the constructor before a method
reads it. The fences store nothing.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A class that overrides
equals without hashCode.
- A setter on a class whose instances sit in a
HashSet or key a
HashMap.
- A
switch over a sealed interface that has a default branch.
- A method that answers
null for "not found".
- A port method that declares a library's checked exception, such as
IOException.
Optional as the type of a field or a parameter.
- A public class that is neither
final nor says what a subclass may
override.
Common mistakes
- Writing an entity as a record, so two patients with the same details
compare equal.
- Keeping a caller's list in a record without copying it.
- Making a fault a checked exception, so every caller must declare it.
- Wrapping each refusal in an unchecked exception so the compiler stops
asking.
- Adding a
default branch to a switch to quiet the compiler.
- Answering
Optional from a method that can also answer null.
Related skills
oo-design sizes a task and defines the rule labels.
oo-modeling-values-and-entities decides whether a concept is a value
or an entity, and what equality compares.
oo-making-illegal-states-impossible closes a set of states where the
domain closes it.
oo-designing-failure-behaviour tells a refusal from a fault and
chooses how absence is answered.
oo-honouring-substitutability decides whether a class may be
extended and what an override keeps.
oo-designing-interfaces chooses an interface or a base class for
shared behaviour.
oo-patterns-the-language-provides shows when a language feature
replaces a pattern.
oo-constructing-valid-objects makes a constructor refuse broken
input.
oo-encapsulating-state-and-behaviour keeps a collection private and
copies it at the boundary.
Further reading
1---2name: oo-java3description: Use when plain Java code with no framework needs a record or a sealed type, equals and hashCode, a checked exception, or a choice to make a class final.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-java7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Designing Objects in Java1213**In this pack:** sizing and rule strictness are set by the core14plugin's `oo-design` skill; each rule here keeps a core rule in this15language.1617## Overview1819Java carries much of a design in its type system: a record for a value,20a sealed interface for a set the clinic closes, a checked exception for21a refusal, and `Optional` for an answer that may be absent. This skill22applies the pack's core rules to plain Java, from version 21 on, with no23framework. It says which feature keeps each rule and how the compiler24then helps: an equal value that stays equal while it sits in a set, a25`switch` that a new case cannot leave half-answered, and a caller that26cannot ignore a refusal by accident.2728## When to use2930- A class holds several fields and two instances with the same contents31 stand for the same thing.32- A set of cases is closed, and code answers it with `if` chains or a33 `switch` that has a `default` branch.34- A method on a port can fail in a way its caller can act on.35- A query can have no answer, and the code answers `null` today.36- A class is public and has no subclass, and someone asks whether it may37 be extended.38- Several implementations of one interface share a piece of behaviour.3940## When not to use4142- The classes are built, wired or extended by a framework, such as one43 that fills objects from annotations: outside this skill.44- The question is one no Java feature changes, such as which object owns45 a rule or where a module's boundary runs. The core skills answer it,46 starting from `oo-design`.47- The source files are not `.java` but Kotlin, another language that48 runs on the same virtual machine: outside this skill; `oo-kotlin` says49 which Kotlin feature keeps each rule.5051## Core rules52531. Default. **Write a value as a record, check its rules in the compact54 canonical constructor, and copy each collection component there with55 `List.copyOf`, `Set.copyOf` or `Map.copyOf`.** A record's components56 are final fields, and the `equals` and `hashCode` it derives read all57 of them, so a record is a value as58 `oo-modeling-values-and-entities` rules 2 and 3 ask, once its59 arguments are checked, as `oo-constructing-valid-objects` rule 360 asks, and its collections are copied, as61 `oo-encapsulating-state-and-behaviour` rule 6 asks.6263 The exception is a value whose representation must stay hidden,64 because each component of a record has a public accessor: write it as65 a `final` class with private final fields, and give it `equals` and66 `hashCode` as rule 2 asks.67682. Rule. **In a class that compares by value, override `equals` and69 `hashCode` together, from the same fields, and keep `compareTo`70 consistent with `equals`, as `oo-modeling-values-and-entities` rule 371 asks.** A field that `equals` reads never changes while its object72 sits in a `HashSet` or keys a `HashMap`, because a set's behaviour is73 not specified once an element changes in a way that affects `equals`:74 a value has no such field, as `oo-modeling-values-and-entities` rule75 2 says, and an entity compares by its identifier alone, as rule 476 there says.77783. Default. **Close a set of cases the domain closes with a `sealed`79 interface whose permitted classes are records, and answer each case in80 a `switch` expression that names every permitted class and has no81 `default` branch, as `oo-making-illegal-states-impossible` rule 2 and82 `oo-patterns-the-language-provides` rule 5 ask: the compiler then83 rejects a `switch` that a new case leaves out.** The exception is a84 set to which new kinds arrive more often than new operations: give85 each kind its behaviour as a method of the interface, as86 `oo-replacing-conditionals-with-polymorphism` rule 7 weighs it.87884. Rule. **Declare on each method of a port, in its `throws` clause,89 every checked exception its implementations throw, and let the adapter90 catch a library's checked exception, such as `IOException`, and throw91 the port's refusal or an unchecked fault in its place, as92 `oo-designing-failure-behaviour` rule 7 asks.** The compiler then93 rejects an implementation that throws a checked exception its port94 does not declare.95965. Default. **Make a refusal a checked exception and a fault an unchecked97 one, once `oo-designing-failure-behaviour` rule 2 has told them98 apart.** The compiler then makes each caller handle or declare a99 refusal, which is how that rule asks a refusal to be declared, and100 lets a fault pass up, undeclared, to the one handler at the edge; when101 a module raises more than one refusal, they share a checked base102 exception, as `oo-designing-failure-behaviour` rule 3 asks.103104 The exception is a refusal raised inside a function value that a105 library method runs, such as the function given to a stream's `map`:106 the library's functional interfaces declare no checked exception, so107 loop over the items yourself where a refusal can be raised.1081096. Rule. **Answer a value that may be absent as an `Optional`, never as110 `null`, as `oo-designing-failure-behaviour` rule 5 asks, and keep111 `Optional` to return types, the use its documentation names.** Where112 absence is an error, throw instead.1131147. Default. **Declare a class `final`, or `sealed` with the classes it115 permits, unless it was built for extension, as116 `oo-honouring-substitutability` rule 5 asks; a record is final117 already.** The exception is a class built for extension: declare it118 `abstract`, mark `final` each method a subclass must not override, and119 write beside each method a subclass may override the contract the120 override keeps.1211228. Judgement. **Choose a `default` method or an abstract class for123 behaviour that implementations share, as `oo-designing-interfaces`124 rule 4 chooses an interface or a base class: a `default` method when125 it can be written from the interface's own abstract methods alone, an126 abstract class when it needs fields or fixes the order in which its127 own methods run.** What tips the balance is whether the shared code128 needs state, which an interface cannot hold.129130## Pattern131132`DosageInstruction` is how often a patient takes one medication and the133warnings that go with it, and two instructions with the same contents134are the same instruction, a value135(`oo-modeling-values-and-entities` rule 1).136137Before:138139```java140import java.util.List;141142public class DosageInstruction {143 private String medication;144 private int timesPerDay;145 private List<String> warnings;146147 public DosageInstruction(148 String medication, int timesPerDay, List<String> warnings) {149 this.medication = medication;150 this.timesPerDay = timesPerDay;151 this.warnings = warnings;152 }153154 public void setTimesPerDay(int timesPerDay) {155 this.timesPerDay = timesPerDay;156 }157158 public List<String> getWarnings() {159 return warnings;160 }161162 @Override163 public boolean equals(Object other) {164 return other instanceof DosageInstruction that165 && medication.equals(that.medication)166 && timesPerDay == that.timesPerDay;167 }168}169```170171In the Before, `setTimesPerDay` changes a field that `equals` reads, so172an instruction changed while it sits in a `HashSet` leaves the set's173behaviour unspecified (rule 2), and `equals` is overridden without174`hashCode`, so two equal instructions can hash apart (rule 2). `equals`175ignores `warnings`, part of the instruction's contents176(`oo-modeling-values-and-entities` rule 3). The caller's list is kept177and handed out by `getWarnings`, so either holder can change it (rule 1,178`oo-encapsulating-state-and-behaviour` rule 6). Nothing refuses a blank179medication or no dose a day (rule 1).180181After:182183```java184import java.util.List;185186public record DosageInstruction(187 String medication, int timesPerDay, List<String> warnings) {188189 public DosageInstruction {190 if (medication.isBlank()) {191 throw new IllegalArgumentException("no medication is named");192 }193 if (timesPerDay < 1) {194 throw new IllegalArgumentException("fewer than one dose a day");195 }196 warnings = List.copyOf(warnings);197 }198199 public DosageInstruction withTimesPerDay(int newTimesPerDay) {200 return new DosageInstruction(medication, newTimesPerDay, warnings);201 }202}203```204205In the After, the record's `equals` and `hashCode` are derived from all206three components (rules 1 and 2). The compact constructor refuses a207blank medication and fewer than one dose a day, and it copies `warnings`208with `List.copyOf`, which answers an unmodifiable list (rule 1).209`withTimesPerDay` answers a new instruction instead of changing this210one (rule 1). `isBlank` answers whether a string is empty or holds only211white space. Every field is set by the constructor before a method212reads it. The fences store nothing.213214## Red flags215216Places to look, not verdicts. A red flag becomes a finding only with217evidence: a measurement, a reproducible bug, or a failing test.218219- A class that overrides `equals` without `hashCode`.220- A setter on a class whose instances sit in a `HashSet` or key a221 `HashMap`.222- A `switch` over a sealed interface that has a `default` branch.223- A method that answers `null` for "not found".224- A port method that declares a library's checked exception, such as225 `IOException`.226- `Optional` as the type of a field or a parameter.227- A public class that is neither `final` nor says what a subclass may228 override.229230## Common mistakes231232- Writing an entity as a record, so two patients with the same details233 compare equal.234- Keeping a caller's list in a record without copying it.235- Making a fault a checked exception, so every caller must declare it.236- Wrapping each refusal in an unchecked exception so the compiler stops237 asking.238- Adding a `default` branch to a `switch` to quiet the compiler.239- Answering `Optional` from a method that can also answer `null`.240241## Related skills242243- `oo-design` sizes a task and defines the rule labels.244- `oo-modeling-values-and-entities` decides whether a concept is a value245 or an entity, and what equality compares.246- `oo-making-illegal-states-impossible` closes a set of states where the247 domain closes it.248- `oo-designing-failure-behaviour` tells a refusal from a fault and249 chooses how absence is answered.250- `oo-honouring-substitutability` decides whether a class may be251 extended and what an override keeps.252- `oo-designing-interfaces` chooses an interface or a base class for253 shared behaviour.254- `oo-patterns-the-language-provides` shows when a language feature255 replaces a pattern.256- `oo-constructing-valid-objects` makes a constructor refuse broken257 input.258- `oo-encapsulating-state-and-behaviour` keeps a collection private and259 copies it at the boundary.260261## Further reading262263- [Closed sets and refusals](references/closed-sets-and-refusals.md)