diff --git a/migration-guide.adoc b/migration-guide.adoc index 95fc7ac16d..4cec430b2f 100644 --- a/migration-guide.adoc +++ b/migration-guide.adoc @@ -75,6 +75,39 @@ did not implement "correctly" anyway The change for HHH-11356 required changes in its consumers. One such consumer is the Hibernate Statistics system.... +=== Native (non-JPA) Pagination changes + +When hibernate-entitymanager module was merged into hibernate-core in Hibernate ORM 5.2, the contracts for the +following pre-existing `org.hibernate.Query` methods were changed to be specified by JPA `javax.persistence.Query` +methods: `getFirstResult()`, `setFirstResult(int)`, `getMaxResults()`, and `setMaxResults()`. + +In 5.3.2, the following methods were temporarily added to +http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html[`org.hibernate.Query`] to make it +easier to migrate native applications from Hibernate ORM 5.1 to 5.3, and maintain 5.1 pagination behavior: + +* http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html#setHibernateFirstResult-int-[`setHibernateFirstResult(int)`] +behaves the same as the 5.1 version of `setFirstResult()`, with a small difference -- calling +`setHibernateFirstResult(int)` with a negative value will result in `getHibernateFirstResult()` returning 0, instead +of the negative value. Note that this behavior differs from JPA in that `javax.persistence.Query.setFirstResult(int)` +throws `IllegalArgumentException` when called with a negative value. +* http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html#getHibernateFirstResult--[`getHibernateFirstResult()`] +behaves the same as the 5.1 version of `getFirstResult()`, except for the difference mentioned above when `setHibernateFirstResult(int)` is called with a negative number. This method returns `null` if no value was set +via `setHibernateFirstResult(int)` (or `setFirstResult(int)`). Note that this behavior differs from JPA in that +`javax.persistence.Query.getFirstResult()` returns 0 when uninitialized. +* http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html#setHibernateMaxResults-int-[`setHibernateMaxResults`] +behaves the same as the 5.1 version of `setMaxResults()`; setting a value less than or equal to 0 is +considered uninitialized, resulting in *no limit* on the number of results. Note that this behavior differs +from JPA `javax.persistence.Query.setMaxResults(int)`, which, when called with a negative value, +throws `IllegalArgumentException`, and when called with a value of 0, indicates that the query should return +*no results*. +* http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html#getHibernateMaxResults--[`getHibernateMaxResults`] +behaves the same as the 5.1 version of `#getMaxResults`. This method returns `null` if uninitialized or +a value less than or equal to 0 was set via `setHibernateMaxResults(int)` (or `setMaxResults(int)`). +Note that this behavior differs from JPA in that `javax.persistence.Query.getMaxResults() returns +`Integer.MAX_VALUE` when uninitialized. + +These methods are deprecated, and will be removed in a future version. To be portable with future Hibernate +versions, applications should be changed to use the JPA methods. === Drop hibernate-infinispan module @@ -139,7 +172,6 @@ Existing applications migrating to 5.3 with classes extending `org.hibernate.jpa The original driving force behind these series of changes is an effort to be as proactive as possible about designing compatibility between 5.3 and 6.0. - ==== Type system changes -Use of NavigableRole, back-ported from 6.0 rather than plain String \ No newline at end of file +Use of NavigableRole, back-ported from 6.0 rather than plain String