This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Upgrade to Hibernate 6

Introduction

Hibernate 6 (https://hibernate.org/orm/releases/6.0/) is based on Jakarta EE 9 (jakarta.persistence:jakarta.persistence-api version 3.x), which renamed all javax.persistence.* packages to jakarta.persistence.*.

Note

The .editorconfig file in the feature branch has been adjusted to properly layout the imports of the new jakarta.* packages

This implies that all other libraries that depend on Jakarta EE need to be updated as well (list may be incomplete):

  • jakarta.activation:jakarta.activation-api: 1.2.2 –> 2.x

  • jakarta.xml.bind:jakarta.xml.bind-api: 2.3.3 –> 3.x

  • jakarta.annotation:jakarta.annotation-api: 1.3.5 –> 2.x

  • com.sun.mail:jakarta.mail: 1.6.7 –> 2.x

  • jakarta.ws.rs:jakarta.ws.rs-api: 2.1.6 –> 3.x

  • com.sun.xml.ws:jaxws-ri: 2.3.5 –> 3.x

  • org.glassfish.jersey.*: 2.x –> 3.x

  • org.glassfish.hk2.*: 2.x –> 3.x

  • org.apache.tomcat.embed:*: 9.x –> 10.x

This also requires a Spring Boot upgrade as Jakarta EE 9 is only supported in version 3.0. Currently the first milestone has been released (https://spring.io/blog/2022/01/20/spring-boot-3-0-0-m1-is-now-available).

There seems to be a jakarta version of Hibernate 5 (https://mvnrepository.com/artifact/org.hibernate/hibernate-core-jakarta) so it would probably possible to upgrade to Spring Boot 3 before upgrading to Hibernate 6 (but it’s not possible to upgrade to Hibernate 6 before upgrading to Spring Boot 3).

To do

A prototype of the Spring Boot 3 / Hibernate 6 migration can be found on the branch features/spring-boot-3-hibernate-6.

Jersey

The current Spring Boot 3.0 milestone does not provide an integration with Jersey yet (see https://github.com/spring-projects/spring-boot/issues/28808). Therefore a temporary workaround has been implemented which can be reverted as soon as a new org.springframework.boot:spring-boot-starter-jersey version is available.

Note

These changes have been made in a separate commit on the feature branch so that it should be obvious what needs to be reverted/adjusted. The fixed versions for jackson and the validation-api introduced in this commit should probably not be reverted. Perhaps it is not necessary to use org.springframework.boot:spring-boot-starter-jersey and just add the jersey-spring6 dependency as soon as it exists, as we don’t use any other spring features of this starter. Also see the comment in ToccoSpringBootApplication: JerseyAutoConfiguration should be excluded again in case the jersey-starter is used again.

Types

Custom types have been rewritten in Hibernate 6. All custom types have been migrated to a org.hibernate.type.descriptor.java.JavaType (see ‘Compositional basic mapping’ (https://docs.jboss.org/hibernate/orm/6.0/userguide/html_single/Hibernate_User_Guide.html#basic-mapping-composition).

DWR

Nice2DwrServlet and BinaryDownloadManager have been disabled because they use the javax.servlet namespace. It’s unlikely that a new official version will be released - if DWR should still be supported it will probably be required to create and deploy a custom build based on https://github.com/directwebremoting/dwr/tree/3.0.2-RELEASE which uses the jakarta.servlet namespace.

Note

These changes have been made in a separate commit so that it should be obvious what needs to be reverted/adjusted.

Solr

Fulltext search has been disabled because the Solr server used for local development uses the javax.servlet namespace. Can probably be ignored as Solr will be replaced by Elasticsearch soon.

Note

These changes have been made in a separate commit so that it should be obvious what needs to be reverted/adjusted.

Other stuff

  • An ugly reflection hack is used in ch.tocco.nice2.persist.core.impl.hibernate.bootstrap.SessionFactoryProvider#sessionFactory to set our custom bytecode provider - should be removed once https://hibernate.atlassian.net/browse/HHH-12193 is resolved (the jdk.unsupported module should also be removed from the module-info.java file when this has been fixed).

  • Remove milestone/snapshot repositories in build.gradle and settings.gradle as soon as all dependencies are available from maven central

  • PostDataFilter has been rewritten without the commons-fileupload library which cannot be used any longer and needs to be tested

  • When updating the springBootVersion the springVersion must be updated as well

  • Investigate why the hibernate-commons-annotations dependency needs to be specified explicitly and check whether the versioning is independent of hibernate-core. It is probably related to the fact that this (and other) dependencies used to be compile dependencies of hibernate core, but are now runtime dependencies since version 6. Additionally check if jboss-logging and akarta.transaction have a similar problem (see TODO in build.gradle)

Merging

After merging the integration/master into the features/spring-boot-3-hibernate-6 branch you can replace the following imports:

  • import javax.mail. -> import jakarta.mail.

  • import javax.annotation.Resource; -> import jakarta.annotation.Resource;

  • import javax.ws.rs. -> import jakarta.ws.rs.

  • import javax.persistence. -> import jakarta.persistence.

  • import javax.activation. -> import jakarta.activation.

  • import javax.servlet. -> import jakarta.servlet.

If a customer module imports a class from the package “jakarta.persistence.*” requires jakarta.persistence; must be added to the module-info.java of the customer. There is a task to analyze why this is necessary as this is a transitive module of core.persist.core.