Value-based Classes

# {@index "Value-based Classes"}

Some classes, such as {@code java.lang.Integer} and {@code java.time.LocalDate}, are value-based. A value-based class has the following properties:

- the class declares only final instance fields (though these may contain references to mutable objects);
- the class's implementations of {@code equals}, {@code hashCode}, and {@code toString} compute their results solely from the values of the class's instance fields (and the members of the objects they reference), not from the instance's identity;
- the class's methods treat instances as freely substitutable when equal, meaning that interchanging any two instances {@code x} and {@code y} that are equal according to {@code equals()} produces no visible change in the behavior of the class's methods;
- the class performs no synchronization using an instance's monitor;
- the class does not declare (or discourages use of) accessible constructors;
- the class does not provide any instance creation mechanism that promises a unique identity on each method call—in particular, any factory method's contract must allow for the possibility that if two independently-produced instances are equal according to {@code equals()}, they may also be equal according to {@code ==};
- the class is final, and extends either {@code Object} or a hierarchy of abstract classes that declare no instance fields or instance initializers and whose constructors are empty.

When two instances of a value-based class are equal (according to `equals`), a program should not attempt to distinguish between their identities, whether directly via reference equality {@code ==} or indirectly via an appeal to synchronization, identity hashing, serialization, or any other identity-sensitive mechanism.

Synchronization on instances of value-based classes is strongly discouraged, because the programmer cannot guarantee exclusive ownership of the associated monitor.

Use of instances of value-based classes as referents in {@linkplain java.lang.ref.Reference reference objects} is strongly discouraged, because these instances do not have reliable identity.

Identity-related behavior of value-based classes may change in a future release. For example, synchronization may fail.