Describes the new features and capabilities added to Hibernate ORM in 7.4.

If migrating from earlier versions, be sure to also check out the Migration Guide for discussion of impactful changes.

Temporal and Audited Data

As an incubating feature, this release introduces the brand new and extremely powerful StateManagement SPI along with:

  • The @Temporal annotation, for mapping temporal data and querying based on temporal effectivity, and

  • The @Audited annotation, for mapping data with modifications tracked in a separate audit log.

Temporal data may be mapped to:

  • database-native temporal tables (when provided by the underlying RDBMS),

  • a single table with effectivity columns (which might be partitioned into current and historical partitions), or

  • a table holding currently effective data, and a second table holding historical data with effectivity.

The mapping strategy is transparent to client code.

Historical temporal data may be queried at a given effective data/time.

Audited data is mapped to a regular table along with an audit log which is backward compatible with Hibernate Envers. Optionally, the application may provide a @Changelog entity tracking information about each changeset. The AuditLog object may be used to query the audit log.

For examples and more details, see Temporal data and Audit logs in A Short Guide to Hibernate 7.

Limits and Fetch Joins

It is now perfectly safe to combine a HQL limit or pagination using setMaxResults() with a collection join fetch, on any database which supports limits and offsets inside subqueries (which includes all the supported databases except Sybase ASE). Similarly, it’s now safe to use a collection join fetch with getResultStream() or scroll().

In Hibernate 6, and in previous versions of Hibernate 7, the combination of limits/pagination with a many-valued fetch join forced Hibernate to fall back to applying the limit in the JVM, which usually exhibited terrible performance characteristics. This problem is finally solved.

To recover the previous behavior, using the query hint org.hibernate.limitInMemory. Use of this hint will almost certainly harm performance.

CacheMode.REFRESH_SESSION

The new REFRESH_SESSION mode, which may be

  • passed as an option to EntityManager.find() or

  • requested via SelectionQuery.setCacheMode()

specifies that entities returned in a query result set should be efficiently refreshed in the first-level cache, as if they had been passed to EntityManager.refresh(), overwriting the current state held in the persistence context.

Reverse Engineering

The reverse engineering module, previously part of the standalone Hibernate Tools project, is now integrated directly into Hibernate ORM. It is available as plugins for Gradle, Maven, and Ant.

The reverse engineering plugins can generate:

  • Java entity classes

  • DAO classes

  • hbm.xml mapping files

  • mapping.xml mapping files

  • hibernate.cfg.xml configuration files

  • DDL scripts

  • HTML documentation

The process is customizable via XML configuration files and custom strategy classes.

See the Reverse Engineering chapter in the User Guide for details.

See the dedicated blog post for the motivation and migration hints.

HBM XML Transformation

The Maven plugin now includes a transformHbm goal that transforms legacy hbm.xml mapping files into ORM mapping.xml files. This does not involve reverse engineering from a database — it converts existing HBM mappings.

See the HBM XML Transformation section in the User Guide for details.

Joins and Join Fetching for @Any and @ManyToAny

Discriminated association mappings may now:

  • be used freely in HQL joins and treated joins.

  • be fetched using a join.

The joining and fetching semantics for @Any and @ManyToAny are aligned with @ManyToOne and @ManyToMany respectively.

Join fetching may be requested using join fetch in HQL, or using an EntityGraph.

Also, the cascade member was added to @Any and @ManyToAny as a replacement for the deprecated @Cascade annotation.

@OneToMany with @JoinFormula

Mappings combining @OneToMany and @JoinFormula now function correctly.

Database-generated Columns within Primary Keys

A database-generated column (for example, an identity column) may now form part of a composite primary key.

Package-level @Nationalized

The @Nationalized annotation may now be placed on a package descriptor, acting as a default for every character-typed attribute of every entity or embeddable belonging to the package.

New Services

The SPI interfaces BatchBuilder, StatisticsFactory, MutationExecutorService, and SchemaManagementTool are now Java services, allowing customization via the service loader mechanism.

Support for Google Cloud Spanner PostgreSQL-compatible Dialect

The dialect for Google Cloud Spanner’s PostgreSQL-compatible interface (SpannerPostgreSQLDialect) is now fully integrated into Hibernate ORM Core, and is officially tested and supported out of the box.