Skip to content

Latest commit

 

History

History
302 lines (211 loc) · 10 KB

whats-new.adoc

File metadata and controls

302 lines (211 loc) · 10 KB

What’s New in 7.0

Table of Contents

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

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

Apache License

Starting with 7.0, Hibernate ORM will be licensed under the Apache License 2.0.

As part of this effort, the Hibernate team reached out to the authors of "non-trivial" contributions to request permission to relicense their work under the Apache License. The response was overwhelming positive, although we never heard back from some contributors and another explicitly disagreed. This required a few actions on our part:

Java 17

Java 17 is the new baseline Java version.

Jakarta Persistence 3.2

7.0 migrates to Jakarta Persistence 3.2, which is fairly disruptive. See this blog post for a good discussion of the changes.

Hibernate Models

For many years Hibernate has used the Hibernate Commons Annotations (HCANN) library for handling various low-level tasks related to understanding the structure of an application domain model, reading annotations and weaving in XML mapping documents. The Hibernate Models project was developed to be a better alternative to HCANN. 7.0 uses Hibernate Models in place of HCANN.

@SoftDelete with TIMESTAMP

Soft-delete now supports the strategy of tracking the timestamp at which the soft-delete occurred, in addition to the previous truth-based strategies. See the User Guide for details.

@EmbeddedColumnNaming

A long-requested feature for both Hibernate and Jakarta Persistence has been the ability to define a prefix for the names of columns associated with an embedded value.

7.0 adds support for this using the new @EmbeddedColumnNaming annotation. The annotation accepts a format pattern, so is more flexible than just a prefix.

@Embeddable
class Address {
    String street;
    String city;
	...
}

@Entity
class Person {
    ...
    @Embedded
    @EmbeddedColumnNaming("home_%")
    Address homeAddress;

    @Embedded
    @EmbeddedColumnNaming("work_%")
    Address workAddress;
}
Note

This feature is considered incubating.

See the User Guide for details.

@NamedEntityGraph

A new annotation (@org.hibernate.annotations.NamedEntityGraph) has been added to allow specifying a named entity-graph using Hibernate’s ability to parse a string representation of the graph.

@Entity
@NamedEntityGraph( graph="title, isbn, author(name, phoneNumber)" )
class Book {
	// ...
}

See org.hibernate.graph.GraphParser for details on the syntax and the User Guide for additional details.

findMultiple() and getMultiple()

The new operations Session.findMultiple() and StatelessSession.getMultiple() provide a convenient way to fetch a batch of entities by id. Combined with the BatchSize option, allows breaking up the JDBC calls into "batches".

QuerySpecification, Restriction, and Range

A new API has been added for incremental definition of a query, with support for selections -

SelectionQuery<Book> qry = SelectionSpecification.create(
    Book.class,
    "from Book"
).restrict(
    Restriction.restrict(
        Book_.suggestedCost,
        Range.closed(10.00, 19.99)
    )
).sort(
    Order.asc(Book_.suggestedCost)
).createQuery(session);

as well as mutations -

MutationQuery<Book> qry = MutationSpecification.create(
    Book.class,
    "delete Book"
).restrict(
    Restriction.restrict(
        Book_.suggestedCost,
        Range.closed(10.00, 19.99)
    )
).createQuery(session);
Note

This feature is considered incubating.

See the User Guide for details.

Direct access to first-level cache

The new operation Session.getManagedEntities() allows the application to iterate over all entities in the first-level cache, or over all entities of a given type.

Note

This feature is considered incubating.

Converted Enums and Check Constraints

Hibernate previously added support for generating check constraints for enums mapped using @Enumerated as part of schema generation. 7.0 adds the same capability for enums mapped using an AttributeConverter, by asking the converter to convert all the enum constants on start up.

JSON and XML functions

Support for most of the JSON and XML functions that the SQL standard specifies was added to HQL/Criteria. The implementations retain the SQL standard semantics and will throw an error if emulation on a database is impossible.

New functions include:

  • construction functions like json_array(), json_object(), xmlelement() and xmlforest()

  • query functions like json_value(), json_query() and xmlquery()

  • aggregation functions like json_agg(), json_object_agg() and xmlagg()

  • manipulation functions like json_set(), json_mergepatch()

  • many others

Set-returning Functions

A set-returning function is a new type of function that can return rows and is exclusive to the from clause. The concept is known in many different database SQL dialects and is sometimes referred to as table valued function or table function.

Custom set-returning functions can be registered via a FunctionContributor. Out-of-the-box, some common set-returning functions are already supported or emulated

  • unnest() - allows to turn an array into rows

  • generate_series() - can be used to create a series of values as rows

  • json_table() - turns a JSON document into rows

  • xmltable() - turns an XML document into rows

@AnyDiscriminatorImplicitValues

The new @AnyDiscriminatorImplicitValues offers 2 related improvements for the mapping of discriminator values for @Any and ManyToAny associations.

First, it allows control over how Hibernate determines the discriminator value to store in the database for implicit discriminator mappings. Historically, Hibernate would always use the full name of the associated entity.

Second, it allows mixing of explicit and implicit value strategies.

Note

This feature is considered incubating.

See the User Guide for details.

StatelessSession and Batch Operations

StatelessSession now supports explicit batch operations via insertMultiple(), updateMultiple(), or deleteMultiple().

Note

This feature is considered incubating.

StatelessSession and Second Level Cache

Previously, stateless sessions never interacted with the second-level cache. This reflected their original intended role in bulk processing. With the advent of Jakarta Data and Hibernate Data Repositories, the responsibilities of StatelessSession have now expanded, and this behavior is no longer appropriate. Thus, a stateless session now makes use of the second-level cache by default.

See the Migration Guide for additional details.

StatelessSession and JDBC Batching

Automatic JDBC batching has the side effect of delaying the execution of the batched operation, and this undermines the synchronous nature of operations performed through a stateless session. In Hibernate 7, the configuration property hibernate.jdbc.batch_size now has no effect on a stateless session. Automatic batching may be enabled by explicitly calling setJdbcBatchSize(). However, the preferred approach is to explicitly batch operations via insertMultiple(), updateMultiple(), or deleteMultiple().

Improvements to Transaction

The Transaction interface leaks the SPI type TransactionStatus via getStatus(), and the JTA-defined type Synchronization via registerSynchronization(), which breaks layering in a fairly harmless way. New operations were added to the Transaction interface, allowing code to inspect the status of the transaction or register callbacks without the use of layer-breaking operations.

Note

This feature is considered incubating.

Data population

Setting jakarta.persistence.schema-generation.database.action=populate or calling SchemaManager.populate() populates an existing schema with initial data in /import.sql or other SQL scripts specified via jakarta.persistence.sql-load-script-source.

XML mappings

Hibernate’s legacy hbm.xml mapping schema has been deprecated for quite some time, replaced by a new mapping.xml schema, which is now stabilized and should be prefered. Support for hbm.xml mappings will be removed in 8.0.

We offer a transformation of hbm.xml files into mapping.xml files, which is available both at build-time (Gradle plugin) and at run-time (using hibernate.transform_hbm_xml.enabled=true).