4.0.0-M2 Release

[gavinking]

Jakarta Persistence 4.0 Milestone 2

Specification draft: jakarta-persistence-spec-4.0-M2.pdf

Maven central: https://central.sonatype.com/artifact/jakarta.persistence/jakarta.persistence-api/4.0.0-M2

Announcement: https://in.relation.to/2026/04/23/JPA-4-M2/

Changelog

Changes to API

• Expanded the criteria and metamodel type systems with specialized expression types ComparableExpression, NumericExpression, TextExpression, TemporalExpression, and BooleanExpression, plus matching metamodel attribute types such as ComparableAttribute, NumericAttribute, TextAttribute, TemporalAttribute, and BooleanAttribute.

• Added criteria builder operations accepting JPQL query strings and returning corresponding criteria objects.

• Added FetchOption, AttributeNode.addOption(), and BatchSize to improve expressivity of entity graphs.

• Extended flush control with QueryFlushMode, Query.setQueryFlushMode(), flush members on @NamedQuery and @NamedNativeQuery, and FlushModeType.EXPLICIT.

• Completed the query or statement split by introducing StatementOrTypedQuery as the bridge type returned from string-based query factory methods.

• Added @EntityListener,

• Allow an entity listener to declared multiple callback methods of the same type.

• Formalized metadata discovery by adding @Discoverable, and allowed named queries and named statements to be
  declared in package and module descriptors.

• Consolidated static query metadata by replacing @ReadQueryOptions and @WriteQueryOptions with @StaticQueryOptions.

• Allow @EntityResult, @ColumnResult, and @ConstructorResult to be placed on a @StaticNativeQuery method.

• Improved @Index so generated DDL can be customized more precisely.

• Reworked the named entity graph helper annotations into nested forms: @NamedEntityGraph.AttributeNode and @NamedEntityGraph.Subgraph.

• Allow use of @MapsId with @IdClass

Changes to the specification

• Substantially clarified derived identity and and @MapsId.

• Specified that a null collection-valued persistent attribute is interpreted as an empty collection, and that a provider may replace a null collection with an empty collection instance.

• Specified that changes to owned collections and owned associations trigger entity lifecycle callbacks, while changes affecting only unowned associations do not.

• Clarified behavior when duplicate persistent field names occur in an inheritance hierarchy.

• Clarified that @OrderColumn and @MapKeyColumn are for owned collections, and should not be used on the unowned side identified by mappedBy.

• Tightened the documentation around mappedBy, including dot-notation cases involving embedded attributes.

• Clarified that criteria comparison operations such as lt() and gt() accept heterogeneous but comparable arguments.