Jakarta Persistence 3.2 (under development)

Release for Jakarta EE 11

Jakarta Persistence defines a standard for management of persistence and object/relational mapping in Java(R) environments.

New features, enhancements or additions

• Adds support for Java record types as embeddable classes
• Adds support for java.time.Instant and java.time.Year and Clarifies JDBC mappings for basic types
• Adds union, intersect, except, cast, left, right, and replace for Jakarta Persistence QL and criteria queries
• Adds || string concatenation operator to Jakarta Persistence QL
• Adds CriteriaSelect, subquery(EntityType) and joins on EntityType to Criteria API
• Adds support for specifying null precedence when ordering Jakarta Persistence QL and criteria queries
• Adds getSingleResultOrNull() to Query, TypedQuery, StoredProcedureQuery
• Adds entities(), classes() and columns() to NamedNativeQuery
• Adds lockMode() to EntityResult with the default being OPTIMISTIC
• Adds getVersion(), isLoaded(), load(), isInstance() and getClass() methods to PersistenceUnitUtil
• Adds overload of entity() accepting an entity name to Metamodel
• Adds javax.annotation.processing.Generated to the list of defined annotations on StaticMetamodel
• Adds constants for managed types, named queries, named graphs and named result set mappings to generated StaticMetamodel
• Adds LocalDateTime and Instant to supported Version types
• Adds where(), having(), and(), and or() overloads accepting List to CriteriaQuery and CriteriaBuilder
• Adds equalTo() and notEqualTo() to Expression
• Adds concat() overload accepting list of expressions and extract() to CriteriaBuilder
• Adds Graph interface as parent of EntityGraph and Subgraph and moved common operations there
• Adds addAttributeNode(), removeAttributeNode(), addTreatedSubgraph(), addElementSubgraph(), addTreatedElementSubgraph(), addMapKeySubgraph(), and addTreatedMapKeySubgraph() methods to Graph
• Adds getReference overload, runWithConnection() and callWithConnection() to EntityManager
• Adds find(), refresh(), lock() overloads to EntityManager taking newly introduced FindOption, RefreshOption, and LockOption respectively
• Adds setCacheStoreMode(), and setCacheRetrieveMode() methods to EntityManager and Query
• Adds runInTransaction() and callInTransaction() to EntityManagerFactory
• Adds getName() to EntityManagerFactory
• Adds programmatic API to obtain EntityManagerFactory using PersistenceConfiguration
• Adds constants for properties defined by the specification to the PersistenceConfiguration
• Adds SchemaManager API
• Adds options member to elements which result in DDL generation
• Adds EnumeratedValue allowing custom mapping of fields of Java enums
• Adds comment and check members to Table and Column annotations, along with CheckConstraint
• Adds secondPrecision to Column annotation and clarified semantics of Column members
• Adds factory-level access to named queries and named entity graphs
• Adds integration points for dependency injection
• Allows usage of TableGenerator and SequenceGenerator at the java package level
• Makes the name member of TableGenerator and SequenceGenerator optional
• Clarifies the primary key types supported for each GenerationType
• Clarifies availability of SEQUENCE, TABLE and UUID generated IDs on PrePersist
• Clarifies semantics of numeric literals and numeric type promotions, and adds support for bi and bd suffixes
• Clarifies semantics of Convert/Converter annotations
• Clarifies rules around distinction of entity names and identification variables and case-sensitivity in Jakarta Persistence QL queries
• Clarifies the semantics of Bindable.ENTITY_TYPE in javadoc
• Clarifies the semantics of collection-valued query parameters
• Entity and embeddable classes may now be static inner classes
• Primary key classes are no longer required to be public and serializable
• Pulls getParameters() up from CriteriaQuery to CommonAbstractCriteria
• Fixes wildcard types in addSubgraph and addAttributeNode in Graph
• Fixes lower type bounds to the Path.get entity argument X
• Fixes example code in the javadoc of AttributeOverrides
• Partially fixes raw types warnings through the API
• Improves AsciiDoc formatting and fixes typos through the specification document

Removals, deprecations or backwards incompatible changes

Deprecations

• Deprecates usage of Calendar, Date, Time, Timestamp, Temporal, MapKeyTemporal and TemporalType in new applications in favour of java.time API
• Deprecates multiselect methods in CriteriaQuery. The preference is to use array or tuple method defined in CriteriaBuilder
• Deprecates use of Byte[] and Character[] arrays types for basic attributes, in favor of primitive array types

Deprecations for removal

• Deprecates addSubclassSubgraph() in EntityGraph for removal; addTreatedSubgraph() method should be used as direct replacement
• Deprecates addSubgraph(Attribute, Class) and addKeySubgraph() in Graph/EntityGraph/SubGraph for removal; addTreatedSubgraph(Attribute, Class) and addMapKeySubgraph() methods should be used as direct replacements
• Deprecates jakarta.persistence.spi.PersistenceUnitTransactionType for removal; jakarta.persistence.PersistenceUnitTransactionType methods should be used as direct replacement
• Deprecates default public no-arg constructor in jakarta.persistence.Persistence and PERSISTENCE_PROVIDER and providers fields in this class for removal with no replacement. This class is not designed for extensibility

Minimum Java SE Version

Java SE 17 or higher

Details

• Jakarta Persistence 3.2 Release Record
  • Jakarta EE Platform 11 Release Plan
• Jakarta Persistence 3.2 Specification Document (PDF)
• Jakarta Persistence 3.2 Specification Document (HTML)
• Jakarta Persistence 3.2 Javadoc
• Jakarta Persistence 3.2 XML Schemas
  • XML Schema for the persistence configuration file
  • XML Schema for the persistence object/relational mapping file
• Maven coordinates
  • jakarta.persistence:jakarta.persistence-api:jar:3.2.0-M2

Compatible Implementations

• TBD

Ballots

Release Review

Plan Review

The Specification Committee Ballot concluded successfully on 2023-06-29 with the following results.

Non-binding votes

The ballot was run in the jakarta.ee-spec mailing list

Plan Review

TBD