Upgrade to Hibernate 7+

Retargeting to Hibernate 7: 6.6 is already in limited support (6.5 and older are EOL) and 7.4 is the current stable series (7.4.13.Final). 7.4 requires Java 17 and Jakarta Persistence 3.2 (hence the dependency on XCOMMONS-3499 and XWIKI-22774).

Hibernate 6 vs 7

The binary breakage for code compiled against 5.6 is almost the same with 6.6 and 7.4 (checked with japicmp on 5.6.15 -> 6.6.59 and 5.6.15 -> 7.4.13), so going through 6 would only mean a second migration later. The only notable difference is that 6.6 still has Session#update, Session#saveOrUpdate and Session#delete (deprecated), which 7.0 removed.

What still works (binary compatible)

Session#createQuery(String) (still returns org.hibernate.query.Query), createNativeQuery, getNamedQuery, doWork, Query#list, uniqueResult, setParameter(String, Object), setFirstResult, setMaxResults, executeUpdate. Legacy hbm.xml mappings are still supported in 7.4 (deprecated since 6.0, so probably removed in 8).

What breaks for extensions compiled against Hibernate 5.6

• Session: save, update, saveOrUpdate, delete, all load variants, createSQLQuery, createFilter, setFlushMode(FlushMode), refresh(String, Object), lock(String, Object, LockMode), getTypeHelper are removed. get(Class|String, Serializable) became get(Class|String, Object) and getIdentifier now returns Object: both are binary breakages even if the source is unchanged.
• SharedSessionContract#createCriteria and getNamedSQLQuery are removed, as well as the org.hibernate.Criteria, org.hibernate.SQLQuery and org.hibernate.Query types.
• Query: about 80 methods removed, including the typed setters (setString, setLong, setInteger, setTimestamp, setBoolean, setEntity, ...), setParameter(..., Type), setParameterList(..., Type), setFlushMode, setLockMode, getParameterMetadata.
• NativeQuery: addScalar(String, Type), setParameter(..., Type), setResultSetMapping removed.
• SessionFactory: getClassMetadata, getAllClassMetadata, getCollectionMetadata, getTypeHelper removed.
• Configuration: addResource(String, ClassLoader), addXML, addDocument, addSqlFunction, buildMappings removed, and several setters now return Configuration instead of void.
• Everything using javax.persistence types now uses jakarta.persistence (e.g. getCriteriaBuilder()).

A session wrapper (like the existing LegacySessionImplementor) cannot fix this: the JVM fails to resolve the call on the org.hibernate.Session interface itself. Keeping extensions working without recompilation requires putting those methods back on the Hibernate types, for example with a legacy module producing a woven hibernate-core (AspectJ inter-type default methods delegating to the new API, plus ASM for the methods which only differ by return type), the same way xwiki-platform-legacy-oldcore weaves oldcore. update and saveOrUpdate on a detached entity can only be emulated (no reattach anymore in 7). A scan of the published extensions bytecode would tell which of those methods are actually used.

Other impacts

• org.hibernate.tool.hbm2ddl.SchemaUpdate is gone (used by XWikiHibernateBaseStore#getSchemaUpdateScript).
• Version specific dialects (MySQL57Dialect, MariaDB103Dialect, ...) were removed and DerbyDialect moved to hibernate-community-dialects: existing hibernate.cfg.xml files might reference removed dialect classes.
• ConnectionProvider SPI changes to adapt in DBCPConnectionProvider.
• HQL is stricter since 6.0: = null is no longer special, comparing an association to an identifier value is rejected, collection pseudo attributes (.size, .elements, ...) are removed, comparisons are type checked, plain SQL tokens are no longer passed through. This impacts HQL written in wiki pages, which cannot be recompiled, so some query rewriting might be needed for retro compatibility.
• Internal code relying on removed internals: LegacySessionImplementor (QueryTranslator, query plan cache), HqlQueryExecutor (RowSelection, NamedSQLQueryDefinition), XWikiHibernateRecycleBinStore (query.criteria.internal), migrations using createSQLQuery.