Draft: Establish JPA 4 compatibility baseline with minimal changes

[oscarfanchin]

Summary

This draft provides an exploratory compatibility baseline for Jakarta Persistence 4 and Hibernate ORM 8.

The goal is to compile and run the existing Spring Data JPA functionality against this new baseline, validate the migration direction, and identify follow-up work.

This is not a complete or final support statement.

Scope

• Minimal compatibility adaptations for Jakarta Persistence 4 and Hibernate ORM 8.
• Test adjustments required by API or provider behavior changes.
• Existing Spring Data JPA functionality only.

Support for new Jakarta Persistence 4 features is intentionally out of scope.

Intentional exclusions

• EclipseLink tests are excluded because no Jakarta Persistence 4-compatible EclipseLink build is currently available.
• Querydsl tests are disabled because the Querydsl version currently used by the project is not compatible with Jakarta Persistence 4.

Dependency baseline

This branch currently uses snapshot dependencies where required because the relevant Hibernate ORM and Jakarta Persistence APIs are still evolving.

More stable milestone builds are available, but they do not yet provide the compatibility surface required by this draft.

Current status

• The project compiles.
• 3,591 tests were run: 3,413 passed, 108 were skipped, 7 failed, and 63 ended in errors.
• All 70 failures and errors are confined to three AOT repository test suites.
• All executed non-AOT tests pass, including the database-specific tests.
• The Spring Data Envers module test suite passes without failures.
• AOT named-query discovery requires dedicated follow-up work.

Test command:

mvn -pl spring-data-jpa -Pall-dbs clean process-test-classes
surefire:test@unit-test
surefire:test@integration-test
surefire:test@mysql-test
surefire:test@postgres-test
surefire:test@oracle-test
-Dmaven.test.failure.ignore=true -U

Full Surefire reports from the test run are attached.
surefire-reports.zip

AOT note

The remaining AOT failures originate from named-query discovery in QueriesFactory.

With the current Hibernate ORM 8 baseline, untyped named queries may be represented by a TypedQueryReference whose result type is null.

QueriesFactory currently probes multiple result-type candidates, including null, when looking up named queries. Passing the null candidate to EntityManagerFactory.getNamedQueries(Class<R>) results in an NPE.

Removing the null candidate avoids the NPE but does not solve the underlying problem: untyped named queries can no longer be discovered. This causes AOT repository method contributions to be omitted and produces cascading metadata and integration-test failures.

This behavior needs further discussion and dedicated follow-up work, potentially involving coordination with Hibernate ORM.

Related issues

Related to #4187
Related to #4197

• You have read the Spring Data contribution guidelines.
• You use the code formatters provided here and have them applied to your changes. Don’t submit any formatting related changes.
• You submit test cases (unit or integration tests) that back your changes.
• You added yourself as author in the headers of the classes you touched. Amend the date range in the Apache license header if needed. For new types, add the license header (copy from another file and set the current year only).