Summary

Provide library support for value classes and objects, and migrate certain standard classes to be value classes.

Problem

The value classes and objects features are motivated and described by the JEP.

A runtime environment that supports these features needs some accommodation from the standard libraries, including:

• Identity-based equality and hash code operations need an alternative behavior for value objects that depends on field values, not identity
• Synchronization does not make sense for value objects
• Reflection should support queries about an object's identity, and about new modifiers on classes and fields
• Serialization must not expose not-yet-initialized value objects when it creates them
• The garbage collection concept of "reachability" does not make sense for value objects—identical instances can always be reconstructed
• The class file API should support new modifiers and the new LoadableDescriptors attribute

In addition, to properly introduce users to the new features, the standard libraries should migrate some commonly-used classes to be treated as value classes (but only in preview mode).

Solution

The following APIs are modified to handle value objects:

• System.identityHashCode is specified to hash together the class and field values of a value object.

• The methods of java.lang.Object are indirectly affected by language changes involving == and synchronized, and the revised identityHashCode. Their specifications would benefit, in general, from a direct explanation of their behavior for value objects.

• A preview exception class, IdentityException, is available to indicate that an object is expected to have identity.

• java.util.Objects adds preview methods hasIdentity and requireIdentity to help distinguish identity objects from value objects.

• java.lang.Class, java.lang.reflect.Modifier, and java.lang.reflect.AccessFlag reflect the new value/ACC_IDENTITY and ACC_STRICT flags.

• ObjectInputStream.readObject and writeObject generally throw an InvalidClassException if the object being serialized/deserialized is an instance of a value class, whether concrete or abstract, with some exceptions for cases like value records and primitive wrapper classes.

• Instances of java.lang.ref.Reference throw an exception if created for a value object, and WeakHashMap rejects value objects as keys.

• java.lang.classfile supports new class file modifiers and the new LoadableDescriptors attribute.

The following classes get preview-only value class variations (no changes to the APIs other than the value modifier):

• java.lang.Number
• java.lang.Record
• All 8 primitive wrapper classes
• All 4 java.util.Optional* classes
• 12 java.time classes: Duration, Instant, LocalTime, Year, YearMonth, MonthDay, Period, LocalDate, LocalDateTime, OffsetTime, OffsetDateTime, ZonedDateTime
• 5 java.time.chrono classes: ChronoLocalDateImpl, MinguoDate, HijrahDate, JapaneseDate, and ThaiBuddhistDate

A more comprehensive outline of the solution can be found in the JDK-8317279 description.

Specification

Javadoc changes will be attached.

Changes to the serialization spec will also be attached.