diff --git a/migration-guide.adoc b/migration-guide.adoc index c623a342a2d2..44c9a90fdad5 100644 --- a/migration-guide.adoc +++ b/migration-guide.adoc @@ -5,6 +5,7 @@ :versionDocBase: {docsBase}/7.0 :userGuideBase: {versionDocBase}/userguide/html_single/Hibernate_User_Guide.html :javadocsBase: {versionDocBase}/javadocs +:releaseSeriesBase: https://hibernate.org/orm/releases/7.0/ :fn-cascase-type: footnote:cascade-type[`org.hibernate.annotations.Cascade` and `org.hibernate.annotations.CascadeType` are both fully deprecated as of 7.0] This guide discusses migration to Hibernate ORM version 7.0. For migration from @@ -44,10 +45,15 @@ This required a few actions on our part: [[requirements]] == Requirements -* Java 17, or greater +* <>, or greater * <> * <> +[[java-17]] +=== Java 17 + +Hibernate now baselines on Java 17. Newer Java versions may also be used. + [[jpa-32]] === Jakarta Persistence 3.2 @@ -70,6 +76,9 @@ This required a few actions on our part: See this https://in.relation.to/2024/04/01/jakarta-persistence-3/[blog post] for a good discussion of the changes in Jakarta Persistence 3.2. +- https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/24/[TCK Results] with Java 17 +- https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/25/[TCK Results] with Java 21 + [[hibernate-models]] === Hibernate Models @@ -94,144 +103,8 @@ annotations. Check out its project page for complete details. [[new-features]] == New Features -New features introduced in 7.0... - -[[soft-delete-timestamp]] -=== @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 link:{user-guide-url}#soft-delete[User Guide] for details. - - -[[embedded-column-naming]] -=== @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 a little more flexible than just a prefix. - -Consider a typical `Person` / `Address` composition: - -[source,java] ----- -@Embeddable -class Address { - String street; - String city; - ... -} - -@Entity -class Person { - ... - - @Embedded - @EmbeddedColumnNaming("home_%") - Address homeAddress; - - @Embedded - @EmbeddedColumnNaming("work_%") - Address workAddress; - -} ----- - -This instructs Hibernate to use the column names `home_street`, `home_city`, `work_street`, and so on. - -See the link:{user-guide-url}#embeddable-column-naming[User Guide] for details. - -[[NamedEntityGraph]] -=== @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. - - -[source,java] ----- -@Entity -@NamedEntityGraph( graph="title, isbn, author( name, phoneNumber )" ) -class Book { - // ... -} ----- - - -See `org.hibernate.graph.GraphParser` for details on the syntax and the -link:{user-guide-url}#fetching-strategies-dynamic-fetching-entity-graph-parsing-annotation[User Guide] for additional details. - - -[[enum-checks]] -=== 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. - -[[hbm-transform]] -=== hbm.xml Transformation - -Hibernate's legacy `hbm.xml` mapping schema has been deprecated for quite some time, replaced by a new `mapping.xml` -schema. In 7.0, this `mapping.xml` is stabilized and we now offer a transformation of `hbm.xml` files into `mapping.xml` files. - -This tool is available as both: - -* a build-time transformation (currently only offered as a Gradle plugin), or -* a runtime transformation, using `hibernate.transform_hbm_xml.enabled=true` - -Build-time transformation is preferred. - -[NOTE] -==== -Initial versions of the transformation processed one file at a time. -This is now done across the entire set of `hbm.xml` files at once. -While most users will never see this change, it might impact integrations which tie-in to XML processing. -==== - -[[stateless-session-cache]] -=== 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. -To completely bypass the second-level cache, recovering the previous behavior, call `setCacheMode(CacheMode.IGNORE)`. - -It's often important to explicitly disable puts to the second-level cache in code which performs bulk processing. -Set the cache mode to `GET` or configure `jakarta.persistence.cache.storeMode` to `BYPASS`. - -[[stateless-session-jdbc-batching]] -=== 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()`. +See the link:{releaseSeriesBase}#whats-new[website] for the list of new features in the 7.0 series. -[[session-find-multiple]] -=== findMultiple() - -The new operation `Session.findMultiple()`, along with the `BatchSize` option provides a convenient way to fetch a batch of entities by id. - -[[session-managed-entities]] -=== Direct access to first-level cache - -The new operation `Session.getManagedEntities()` allows the application program to iterate over all entities in the first-level cache, or over all entities of a given type. - -[[schema-manager-populate]] -=== 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`. - -[[transaction-api]] -=== 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. // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -241,21 +114,27 @@ New operations were added to the `Transaction` interface, allowing code to inspe [[api-changes]] == Changes to API +This section describes changes to contracts (classes, interfaces, methods, etc.) which are consider https://hibernate.org/community/compatibility-policy/#api[API]. + +[[defer-to-jpa]] +=== Defer to JPA + A general theme in 7.0 has been to remove Hibernate-specific features that have a direct replacement in JPA. [[session-load]] -=== Session#load +==== Session#load `Session#load` methods have been removed in favor of `Session#getReference` which have the same semantic. + [[session-get]] -=== Session#get +==== Session#get `Session#get` methods were deprecated in favor of the JPA-standard `Session#find`, and new overloads of `Session#find` were added. NOTE: `Session#get` was not previously deprecated as `Session#load` was, so it was not appropriate to remove it. [[session-refresh]] -=== Session#refresh +==== Session#refresh The forms of `Session#refresh` accepting an entity-name have been removed; the passed entity already indicates the entity-name (even with dynamic models). @@ -265,7 +144,7 @@ The forms of `Session#refresh` accepting an entity-name have been removed; the p Removed in favor of `Session#refresh(Object object, LockOptions lockOptions)` [[session-save-update]] -=== Session#save, Session#update, Session#saveOrUpdate +==== Session#save, Session#update, Session#saveOrUpdate All forms of `Session#save`, `Session#update`, `Session#saveOrUpdate` have been removed. See the discussion at <>. @@ -280,7 +159,7 @@ Relatedly, `org.hibernate.annotations.CascadeType#SAVE_UPDATE` has been removed [[session-delete]] -=== Session#delete +==== Session#delete `Session#delete` methods has been removed in favor of `Session#remove`. Relatedly, `org.hibernate.annotations.CascadeType#DELETE` was removed in favor of `org.hibernate.annotations.CascadeType#REMOVE`{fn-cascase-type} @@ -346,13 +225,6 @@ All such cases though are already controllable by the application. The effect can also often be mitigated using Hibernate's bytecode-based laziness (possibly combined with `@ConcreteProxy`). -[[usertype]] -=== Changes to UserType and CompositeUserType - -The API interfaces `UserType` and `CompositeUserType` leaked the SPI types `SharedSessionContractImplementor` and `SessionFactoryImplementor`, which was a layer-breaker. - -The solution was to change the signature of `nullSafeSet()` and `nullSafeGet()` in `UserType` via deprecation of the previous declarations, and remove some unnecessary parameters from methods of the incubating interface `CompositeUserType`. - [[misc-api]] === Miscellaneous @@ -373,6 +245,8 @@ The solution was to change the signature of `nullSafeSet()` and `nullSafeGet()` [[spi-changes]] == Changes to SPI +This section describes changes to contracts (classes, interfaces, methods, etc.) which are consider https://hibernate.org/community/compatibility-policy/#spi[SPI]. + [[configurable-generators]] === Configurable generators @@ -401,13 +275,12 @@ Quite a few (again, previously deprecated) methods on `Interceptor` have been re Additionally, `EmptyInterceptor` was removed. As `org.hibernate.Interceptor` now uses default methods, one can simply implement `Interceptor` to the same end. -[[misc-spi]] -=== Miscellaneous +[[usertype]] +=== Changes to UserType and CompositeUserType -* `org.hibernate.metamodel.spi.MetamodelImplementor` -was removed in favor of `org.hibernate.metamodel.MappingMetmodel` or `org.hibernate.metamodel.model.domain.JpaMetamodel` -* Removed `AdditionalJaxbMappingProducer` in favor of `AdditionalMappingContributor`. -* Removed `MetadataContributor` in favor of `AdditionalMappingContributor` +The API interfaces `UserType` and `CompositeUserType` leaked the SPI types `SharedSessionContractImplementor` and `SessionFactoryImplementor`, which was a layer-breaker. + +The solution was to change the signature of `nullSafeSet()` and `nullSafeGet()` in `UserType` via deprecation of the previous declarations, and remove some unnecessary parameters from methods of the incubating interface `CompositeUserType`. [[jfr-spi]] === JFR SPI @@ -416,6 +289,15 @@ The types `EventMonitor` and `DiagonosticEvent` replace the now-deprecated SPIs Hibernate now reports many more kinds of `DiagnosticEvent` to JFR. +[[misc-spi]] +=== Miscellaneous + +* `org.hibernate.metamodel.spi.MetamodelImplementor` +was removed in favor of `org.hibernate.metamodel.MappingMetmodel` or `org.hibernate.metamodel.model.domain.JpaMetamodel` +* Removed `AdditionalJaxbMappingProducer` in favor of `AdditionalMappingContributor`. +* Removed `MetadataContributor` in favor of `AdditionalMappingContributor` + + // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ // Changes in Behavior @@ -424,6 +306,7 @@ Hibernate now reports many more kinds of `DiagnosticEvent` to JFR. [[behavior-changes]] == Changes in Behavior + [[model-validation]] === Domain Model Validations @@ -506,6 +389,29 @@ This includes auto-applied converters. To suppress the error for an auto-applied converter, use `@Convert(disableConversion=true)`. +[[stateless-session-behavior]] +=== StatelessSession Behavior + +The behavior of Hibernate's `StatelessSession` has changed in 2 specific ways to be aware of: + +[[stateless-session-cache]] +==== StatelessSession and Second-Level Cache + +A stateless session now link:{releaseSeriesBase}#stateless-session-cache[makes use of the second-level cache] by default. This will affect migrating applications using second-level cache and `StatelessSession`. + +To completely bypass the second-level cache, recovering the previous behavior, call `setCacheMode(CacheMode.IGNORE)`. + +It's often important to explicitly disable puts to the second-level cache in code which performs bulk processing. +Set the cache mode to `GET` or configure `jakarta.persistence.cache.storeMode` to `BYPASS`. + + +[[stateless-session-jdbc-batching]] +==== StatelessSession and JDBC Batching + +The configuration property `hibernate.jdbc.batch_size` now has link:{releaseSeriesBase}#stateless-session-jdbc-batching[no effect on a StatelessSession]. +JDBC batching may be enabled by explicitly calling `setJdbcBatchSize()`. +However, the preferred approach is to use the new link:{releaseSeriesBase}#stateless-session-multiple[explicit batch operations] via `insertMultiple()`, `updateMultiple()`, or `deleteMultiple()`. + [[create-query]] === Query with Implicit SELECT and No Explicit Result Type @@ -521,7 +427,7 @@ or: [source,java] List query = - session.createQuery("from X join ys") + session.createQuery("from X join y") .getResultList() The select list was inferred based on the `from` clause. @@ -550,12 +456,13 @@ or: [source,java] List result = - session.createQuery("from X join ys", X.class) + session.createQuery("from X join y", X.class) .getResultList() [[flush-persist]] === Session flush and persist + The removal of `CascadeType.SAVE_UPDATE` slightly changes the persist and flush behaviour to conform with the Jakarta Persistence specification. Making a transient entity persistent or flushing a managed entity now results in an `jakarta.persistence.EntityExistsException` if: @@ -710,6 +617,8 @@ Starting in 7.0, when `ValidationMode#AUTO` is specified and a Bean Validation p [[ddl-changes]] == Changes Affecting DDL +This section describes changes which may affect the application's database schema. + [[ddl-implicit-datatype-timestamp]] === Default Precision for timestamp @@ -762,9 +671,7 @@ Now, `varchar(1)` is used by default. [[pools]] == Connection Pools -Since Vibur and Proxool are no longer actively developed, support for these connection pools was removed. - -As part of the effort to relicense Hibernate, it also became necessary to drop support for Oracle UCP connection pool. +We have decided to drop built-in support for the Vibur, Proxool and UCP Connection Pools for a variety of reasons - the main one being that we are not able to properly test them. We recommend using https://github.com/agroal/agroal[Agroal] or https://github.com/brettwooldridge/HikariCP[HikariCP] instead. Alternatively, you may implement the `ConnectionProvider` interface to integrate the connection pool of your choice. diff --git a/release/README.adoc b/release/README.adoc index e222698144c7..49e7fe7229ce 100644 --- a/release/README.adoc +++ b/release/README.adoc @@ -1,22 +1,86 @@ -This project coordinates the tasks that need to be performed as part of creating a release for Hibernate. += ORM Releases +:toc: -== Artifacts +This module performs the tasks needed as part of creating a release for Hibernate ORM. Releases are triggered as a Jenkins job. -Both snapshot and release artifacts are published to Sonatype https://oss.sonatype.org/[OSSRH]. +== Preparation -The "official" detials about OSSRH + Gradle can be found at https://central.sonatype.org/publish/publish-gradle/. -However, its content is way out of date as of the time of this writing. -https://dev.to/kengotoda/deploying-to-ossrh-with-gradle-in-2020-1lhi presents a much better guide. Regardless, -This is all just for background; all of this information is "backed into" the build scripts. +There are a few steps that need to be performed prior to starting the release job: -After release, be sure to manage the staging repository created for it on https://oss.sonatype.org/[OSSRH]. +. Pull all upstream changes and perform `./gradlew preVerifyRelease`. +. Verify issues in the Jira version +.. Remove fix version for anything rejected, etc. +.. Move unresolved issues to another version +. Mark version released in Jira +. Bulk close all issues in the Jira version +=== New Series -== Documentation +If this is a new series, some additional steps are required to prepare the website: -JBoss doc server... +. Create the series descriptor +.. create the directory `_data/projects/orm/releases/${family_name}` +.. create the file `series.yml` +.. add the appropriate content (_generally this can be copied from previous series_) +. Create the series listing +.. create the directory `orm/releases/${family_name}` +.. create the file `index.adoc` +.. add listing of all new features in the series +. Create the documentation listing +.. create the directory `orm/documentation/${family_name}` +.. create the file `index.adoc` +.. add links to all documentation (_generally this can be copied from previous series_) +. If this new series is to support a new JPA release, also be sure to update `orm/releases/index.adoc` -== SourceForge +== Perform the Release + +Start the appropriate Jenkins https://ci.hibernate.org/view/Release/job/hibernate-orm-release[job]. + +NOTE: When a release is started, the job coordinates with the unified Hibernate https://github.com/hibernate/hibernate-release-scripts[release scripts] in a number of stages and steps, +calling tasks on this module's link:./release.gradle[Gradle script]. + +At a high-level, this process: + +* builds and verifies the individual modules +* produces artifacts and publishes them +* tags the release +* updates the website + +This process has a number of "outputs"... + + +=== Release Artifacts (jar) + +Release artifacts are published to https://oss.sonatype.org/[Sonatype OSSRH] (aka, Maven Central). For each module, we publish: + +* The "main" jar +* The sources jar +* The javadoc jar + + +=== Gradle Plugin + +The Gradle plugin gets published to Gradle's https://plugins.gradle.org/[Plugin Portal]. + +See https://plugins.gradle.org/plugin/org.hibernate.orm + + +=== Documentation + +All documentation for the release is generated, assembled and then published to the https://docs.jboss.org/hibernate/orm/[documentation server]. + + +== Announce + +If the release is a maintenance release, there is nothing more to do. + +However, for Alpha, Beta, CR and first Final releases some announcements are in order: + +. Write a release announcement blog post. +. Announce the release, with link to the blob post: +.. on the hibernate-dev and hibernate-announce mailing lists +.. on the https://discourse.hibernate.org/[forums] +.. on Twitter +.. anywhere else you wish (BlueSky, etc). -Release bundles (as ZIP and TGZ) are uploaded to https://sourceforge.net/projects/hibernate/files/hibernate-orm/[SourceForge] \ No newline at end of file diff --git a/release/jenkins-release-process.adoc b/release/jenkins-release-process.adoc deleted file mode 100644 index 56b5cae4002c..000000000000 --- a/release/jenkins-release-process.adoc +++ /dev/null @@ -1,37 +0,0 @@ -= Release Process (Jenkins) - -Details for releasing ORM via a Jenkins job. - -The release can alternatively be performed manually - see <<./manual-release-process.adoc>> for details. - -== Resources - -First, a list of resources you will need access to in order to perform a release: - -* Post permissions for both hibernate-dev and hibernate-announce mailing lists -* Post permissions for Hibernate forums -* Post permissions for both G+ and Twitter - - -== Steps - -1. Perform `./gradlew preVerifyRelease` locally (after pulling all upstream changes). The Jenkins job does only the release steps, and we need to make sure tests are ok -2. Mark the version as released in Jira -3. Close all issues associated with the version as closed. Be sure to remove the version from any issues that are not resolved (e.g. rejected) - the Jira "release notes" mechanism includes all issues with that version as the fix-for regardless of the resolution -4. Start the https://ci.hibernate.org/view/Release/job/hibernate-orm-release-jdk17/[Jenkins job]. It is a parameterized build - Jenkins will prompt user for needed information: -.. The version to be released (e.g. 7.0.0.Final) -.. The next development version (e.g. 7.0.1-SNAPSHOT) -.. The GitHub branch from which to release - -The Jenkins job performs the following tasks: - -1. sets the version to the provided release version -2. updates the changelog with the info from Jira -3. performs bintray, sourceforge and documentation upload -4. tags the version and push it to github -5. changes the version to the provided development version -6. push to github - -== Post-release steps - -See <<./post-release-steps.adoc>> \ No newline at end of file diff --git a/release/manual-release-process.adoc b/release/manual-release-process.adoc deleted file mode 100644 index e9fec5067a6b..000000000000 --- a/release/manual-release-process.adoc +++ /dev/null @@ -1,40 +0,0 @@ -= Release Process (manual) - -Details for releasing ORM manually from developers machine. - -The release can alternatively be performed via a Jenkins job - see <<./jenkins-release-process.adoc>> for details - - -== Resources - -First, a list of resources you will need access to in order to perform a release: - -* JBoss doc server - SSH key. See List of resources a dev team member needs access to -* SourceForge - SSH key. There is a great wiki on SourceForge covering setting up your SSH key ( https://sourceforge.net/p/forge/documentation/SSH/ ). You must also be added to the admin group of the Hibernate SourceForge project. -* Bintray - Uses an "api key". Both the username (PERSONAL_BINTRAY_USER) and the api key (PERSONAL_BINTRAY_API_KEY) are needed - add them to ~/.gradle/gradle.properties. To find your api key, go to Bintray.com > Edit Profile > API Key. -* Post permissions for both hibernate-dev and hibernate-announce mailing lists. Again, see List of resources a dev team member needs access to -* Post permissions for Hibernate forums -* Post permissions for both G+ and Twitter - -NOTE: Realistically, release builds can only be run on *Nix systems. We rely on system commands for parts of the release tasks in the build script. Specifically we use `rsync` and `ln` (for symlink creation). - -== Steps - -Many release steps have been automated, but some still need to be done manually: - -1. Mark version released in Jira -2. Bulk close all the version's Jira tickets -3. Get changelog from Jira and add to `../changelog.txt` -4. Change version in `gradle/version.properties` to the release version -5. Commit - do not push, because pushing will cause CI to upload another staging repository -6. Do the release - from the root-dir, `./gradlew release`. This relies on Gradle's UP-TO-DATE checks, assuming you have verified the build already. `./gradlew cleanAndRelease` can be used instead to trigger a full clean+build for the release -7. Verify / trigger the sync to Central from BinTray happened. This never seems to happen automatically so plan on triggering the sync manually. -8. Create the release tag -9. Change version in `gradle/version.properties` to the next development version -10. Commit -11. Push (both the branch and tag) upstream - - -== Post-release steps - -See <<./post-release-steps.adoc>> \ No newline at end of file diff --git a/release/post-release-steps.adoc b/release/post-release-steps.adoc deleted file mode 100644 index 6cffbe90682e..000000000000 --- a/release/post-release-steps.adoc +++ /dev/null @@ -1,20 +0,0 @@ -= Post-release Steps - -Whether releasing <<./manual-release-process.adoc>>[manually] or via the <<./jenkins-release-process.adoc>>[Jenkins job], -there are a number of "post" release steps that need to be performed... - -1. Complete release process on https://oss.sonatype.org/[OSSRH] -2. Write release announcement blog post (see http://in.relation.to/README/[Blog site instructions]) -3. Write release descriptor as part of the https://github.com/hibernate/hibernate.org[website] -.. If this is the first release in a new family/series, some additional steps are required: -... Create a directory `_data/projects/orm/releases/${family_name}` and create a file named `series.yml`. E.g. for 4.3.0.Final you'd be adding _data/projects/orm/releases/4.3/series.yml -... Create a directory `orm/releases/${family_name}` and create a file named `index.adoc`. E.g. for 4.3.0.Final you'd be adding orm/releases/4.3/index.adoc -... Create a directory `orm/documentation/${family_name}` and create a file named `index.adoc`. E.g. for 4.3.0.Final you'd be adding orm/documentation/4.3/index.adoc -... If this new series is to support a new JPA release, also be sure to update `orm/releases/index.adoc` -.. Create a release-specific yml file in `_data/projects/orm/releases/${family_name}`. E.g. for 4.3.0.Final you'd add _data/projects/orm/releases/4.3/4.3.0.Final.yml -.. Add/update the XSD descriptor(s) -4. Announce the release -.. on the hibernate-dev and hibernate-announce mailing lists -.. on Twitter (use hibernate account not the dev one) -.. on https://discourse.hibernate.org/[forums] -5. Possibly update "current" symlink on the documentation server - only for a new minor or major release diff --git a/release_notes.md b/release_notes.md index b34ec135f7ef..dd81f5179db6 100644 --- a/release_notes.md +++ b/release_notes.md @@ -1,89 +1,3 @@ -### Jakarta Persistence 3.2 - -7.0 migrates to Jakarta Persistence 3.2 which can be fairly disruptive. -See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#jpa-32) for details. - -See [this blog post](https://in.relation.to/2024/04/01/jakarta-persistence-3/) for a summary of the changes in 3.2 - -- [TCK Results](https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/24/) with Java 17 -- [TCK Results](https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/25/) with Java 21 - -### Java 17 - -Version 3.2 of Jakarta Persistence requires Java 17. -Hibernate 7.0 therefore baselines on Java 17 whereas previous versions baseline on Java 11. - -### Domain Model Validations - -7.0 does much more validation of an application's domain model and especially its mapping details, e.g. - -* illegal combinations such as `@Basic` and `@ManyToOne` on the same attribute -* misplaced annotations such as an annotated getter method with FIELD access -* stricter following of JavaBean conventions - -See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#model-validation) for details. - - -### mapping.xsd - -Hibernate 7.0 provides a new XSD that represents an "extension" of the Jakarta Persistence orm.xsd weaving in Hibernate-specific mapping features. -The namespace for this extended mapping is `http://www.hibernate.org/xsd/orm/mapping` - -For applications using Hibernate's legacy `hbm.xml` format, we provide a tool to help with the transformation. -See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#hbm-transform) for details. - - -### Hibernate Models - -7.0 migrates from [Hibernate Commons Annotations](https://github.com/hibernate/hibernate-commons-annotations/) (HCANN) to the new [Hibernate Models](https://github.com/hibernate/hibernate-models) project for low-level processing of an application domain model, reading annotations and weaving in XML mapping documents. -See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#hibernate-models) for details. - - -### 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()` -* any many more - -> The functions are incubating/tech-preview - to use them in HQL it is necessary to enable the `hibernate.query.hql.json_functions_enabled` and `hibernate.query.hql.xml_functions_enabled` configuration settings. - - -### 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. - -See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/userguide/html_single/Hibernate_User_Guide.html#associations-any) for details. - -### Clean-up - -A lot of deprecated contracts and behavior has been removed. -See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html#cleanup) for details. - +* See the [website](https://hibernate.org.orm/releases/7.0) for requirements and new features in 7.0. +* See the [Migration Guide](https://docs.jboss.org/hibernate/orm/7.0/migration-guide/migration-guide.html) for details about migration from version 6.6 to 7.0.