A value object represents what something is, not which particular object it is. Its meaning comes entirely from one immutable state: two instances with equal state are the same value, even when Java gives them different object identities. Treating identity as meaningful here invites surprises, such as cached Integer instances making == appear to work for one number and fail for another. section 2.2
Listing 2.3 An example Value Class
class Vector {
private double x; #A
private double y; #A
public Vector(double x, double y) {
this.x = x;
this.y = y;
}
public double x() { return this.x; } #B
public double y() { return this.y; } #B
public boolean equals(Object o) { #C
if (this == o) return true; #C
if (o == null || getClass() != o.getClass()) return false; #C
Vector vector = (Vector) o; #C
return Double.compare(x, vector.x) == 0 #C
&& Double.compare(y, vector.y) == 0; #C
} #C
public int hashcode() { #C
return Objects.hash(x, y); #C
} #C
#D
}A conventional Java value class exposes fixed coordinates and defines equality and hashing from those coordinates. The important design decision is not the boilerplate; it is that x and y completely determine the Vector. section 2.2
Equal state, separate instances
Two Vector instances created with (1.0, 3.0) are not the same Java object, yet they compare equal. That substitutability is the practical test: replacing one with an equivalent instance must not change the program’s meaning. section 2.2
Immutability must extend through the whole object graph. A final field or an unmodifiable collection is insufficient when it exposes a mutable Date, list element, or other mutable reference: later mutation changes the apparent value and can break hash-based collections. Build complex values from other values, whether the model is a Ball composed of Point and Vector or an invoice with many attributes. section 2.2.1 section 2.2.4
Model change as a succession of values rather than mutation. A step operation can accept a Ball and return its next state, or live on Ball and return a new Ball; repeated calls then form a readable fluent chain. This style suits transformations while preserving each earlier state. section 2.5
In Java, records are a terse tool for value objects: their header states the representation, and equal component values produce equal records. Use compact constructors to validate or transform incoming arguments so the type preserves its intended semantics. Records trade away information hiding: their representation is directly part of the public model. section 2.6 section 2.8
A value object can be small or large. Do not reject a substantial immutable domain description merely because it lacks identity-driven behavior; choose identity only when continuity through change is part of what the domain needs to represent. section 2.2.1 section 2.8




