migration-guide.adoc

5.3 Migration Guide

Table of Contents

• Background
• Known changes
  • Changes to positional query parameter handling
  • Change in the @TableGenerator stored value
  • Change in the @TableGenerator and @SequenceGenerator name scope
  • Drop hibernate-infinispan module

This guide discusses migration from Hibernate ORM version 5.2 to version 5.3. For migration from earlier versions, see any other pertinent migration guides as well.

Background

5.3 represents a JPA 2.2 compatible version on top of 5.2

Known changes

Changes to positional query parameter handling

This really breaks down into 2 related changes:

• Support for JDBC-style parameter declarations in HQL/JPQL queries has been removed. This feature has been deprecated since 4.1 and removing it made implementing the second change, so we decided to remove that support. JDBC-style parameter declaration is still supported in native-queries.

• Since JPA positional parameters really behave more like named parameters (they can be repeated, declared in any order, etc.) Hibernate used to treat them as named parameters - it relied on Hibernate’s JPA wrapper to interpret the JPA setParameter calls and properly handle delegating to the named variant. This is actually a regression in 5.2 as it causes javax.persistence.Parameter#getPosition to report null.

For JDBC-style parameter declarations in native queries, we have also moved to using one-based instead of zero-bade parameter binding to be consistent with JPA. That can temporarily be reverted by setting the hibernate.query.sql.jdbc_style_params_base setting to true which reverts to expecting zero-based binding.

Change in the @TableGenerator stored value

In order to be compliant with the JPA specification, the sequence value stored by Hibernate 5.3 in the database table used by the javax.persistence.TableGenerator is the last generated value. Previously, Hibernate stored the next sequence value.

For backward compatibility, a new setting called hibernate.id.generator.stored_last_used was introduced, which gives you the opportunity to fall back to the old Hibernate behavior.

Note	Existing applications migrating to 5.3 and using the @TableGenerator have to set the hibernate.id.generator.stored_last_used configuration property to false.

Change in the @TableGenerator and @SequenceGenerator name scope

In order to be compliant with the JPA specification, generators names are now considered global (e.g. HHH-12157) . Configuring two generators, even if with different types but with the same name will now cause a `java.lang.IllegalArgumentException' to be thrown at boot time.

For example, the following mappings are no longer valid:

@Entity
@TableGenerator(name = "ID_GENERATOR", ... )
public class FirstEntity {
    ....
}

@Entity
@TableGenerator(name = "ID_GENERATOR", ... )
public class SecondEntity {
    ....
}

or

@Entity
@TableGenerator(name = "ID_GENERATOR", ... )
public class FirstEntity {
    ....
}

@Entity
@SequenceGenerator(name="ID_GENERATOR", ... )
public class SecondEntity {
    ....
}

The solution is to make all generators unique so that there are no two generators with the same name.

Drop hibernate-infinispan module

Support for using Infinispan as a Hibernate 2nd-level cache provider has been moved to the Infinispan project so the hibernate-infinispan module has been dropped.

A relocation pom which is pointing to org.infinispan:infinispan-hibernate-cache dependency is still generated, therefore, avoiding the need of updating any library dependency.

The relocation pom may be dropped in a future release.