[hibernate-dev] API incompatibilities between Hibernate ORM 5.3 and 6.0

[Gail Badner]

I sent this last night with a huge report file, and it seems that it didn't
get out.

I'm re-sending without the report file...

I ran japi-compliance-checker to compare differences in APIs
between hibernate-core-5.3.0-SNAPSHOT.jar and hibernate-core-6.0.0-
SNAPSHOT.jar.

I ran it last week, so it may not include updates made since that time.

Differences in Envers shown in the report should be disregarded because it
only reflects that hibernate-envers was merged into hibernate-core. A
separate comparison between hibernate-envers-5.3.0-SNAPSHOT.jar and
hibernate-core-6.0.0-SNAPSHOT.jar needs to be done to see Envers changes.

Chris will provide details about Envers differences in a separate email.

The report is huge; it took me 3 to 4 hours to scan it. AFAICT, what I've
documented are the only non-Envers API changes that could affect
applications. They all involve removed classes/methods.

My intention here is just to get this information out, so we have some
solid examples to discuss.

Regards,
Gail

------------------------------------------------------------
----------------------------------------------------------------------

Custom types: I am not familiar with how this will work in 6.0. Steve,
please fill in details about any incompatibilities.

org.hibernate.Criteria and org.hibernate.criterion.DetachedCriteria:

In 5.0/5.1/5.2:
* user guides say, "This appendix covers the legacy Hibernate
org.hibernate.Criteria API, which should be considered deprecated. New
development should focus on the JPA javax.persistence.criteria.CriteriaQuery
API. Eventually, Hibernate-specific criteria features will be ported as
extensions to the JPA javax.persistence.criteria.CriteriaQuery. For details
on the JPA APIs, see Criteria."

In 5.2/5.3:
* Criteria and DetachedCriteria are not deprecated;
* all SharedSessionContract#createCriteria methods are deprecated;
* public static methods in DetachedCriteria are not deprecated;

In 6.0:
* Criteria and DetachedCriteria are removed along with other classes in
org.hibernate.criterion.

Incompatibilities migrating from 5.3 -> 6.0:
1) Existing applications using legacy org.hibernate.Criteria will need to
be updated to use javax.persistence.criteria.CriteriaQuery;
2) If Hibernate's implementation of javax.persistence.criteria.CriteriaQuery
does not include the Hibernate-specific extensions that were available
using org.hibernate.Criteria, applications may not have a straightforward
way to change their applications to work.

org.hibernate.Query

In 5.1:
* SharedSessionContract#createQuery returns org.hibernate.Query
(org.hibernate.Session extends SharedSessionContract);

In 5.2/5.3:
* org.hibernate.Query was deprecated; org.hibernate.query.Query should be
used instead; org.hibernate.query.Query extends org.hibernate.Query;
* SharedSessionContract#createQuery moved to
org.hibernate.query.QueryProducer#createQuery,
returning  org.hibernate.query.Query (which extends org.hibernate.Query);
(org.hibernate.Session extends QueryProducer);

In 6.0:
* org.hibernate.Query was removed.

Incompatibilities migrating from 5.3 -> 6.0:
1) Existing applications that explicitly use org.hibernate.Query (including
javax.persistence.Query.unwrap( org.hibernate.Query.class )) will have to
be changed to use org.hibernate.query.Query.

org.hibernate.SQLQuery:

In 5.1:
* SharedSessionContract#createSQLQuery returns org.hibernate.SQLQuery
(org.hibernate.Session extends SharedSessionContract);

In 5.2/5.3:
* SQLQuery was deprecated; NativeQuery should be used instead; NativeQuery
extends SQLQuery;
* SharedSessionContract#createSQLQuery moved to
QueryProducer#createSQLQuery, returning  NativeQuery (which extends
SQLQuery); Session extends QueryProducer;
* QueryProducer#createSQLQuery is deprecated; QueryProducer#createNativeQuery
should be used instead

In 6.0:
* SQLQuery and org.hibernate.query.QueryProducer#createSQLQuery are removed.

Incompatibilities migrating from 5.3 -> 6.0:
1) Existing applications using Session#createSQLQuery will need to be
updated to use Session#createNativeQuery.
2) Existing applications that explicitly use org.hibernate.SQLQuery
(including javax.persistence.Query.unwrap( SQLQuery.class )) will have to
be changed to use NativeQuery.

org.hibernate.SynchronizeableQuery

In 5.2/5.3:
* org.hibernate.SynchronizeableQuery is not deprecated;
* SQLQuery, NativeQuery and ProcedureCall extend org.hibernate.
SynchronizeableQuery

In 6.0:
* org.hibernate.SynchronizeableQuery is moved to org.hibernate.query.
SynchronizeableQuery;
* NativeQuery and ProcedureCall extend
org.hibernate.query.SynchronizeableQuery;
(SQLQuery was removed as mentioned above)

Incompatibilities migrating from 5.3 -> 6.0:
1) In 6.0, existing applications that use org.hibernate.SynchronizeableQuery
(including javax.persistence.Query.unwrap(
org.hibernate.SynchronizeableQuery.class
)) will need to be updated to use org.hibernate.query.SynchronizeableQuery

org.hibernate.Session#createFilter

In 5.1:
* Session#createFilter returns org.hibernate.Query;

In 5.2/5.3:
* Session#createFilter returns org.hibernate.query.Query (which extends
org.hibernate.Query);
* org.hibernate.Session#createFilter is not deprecated;

In 6.0:
* org.hibernate.Session#createFilter is removed.

Incompatibilities migrating from 5.3 -> 6.0:
1) Existing applications that call Session#createFilter will need to be
updated (to what???); does collection filter functionality exist in 6.0???

org.hibernate.Session.#getTypeHelper

In 5.1/5.2/5.3:
* org.hibernate.Session.#getTypeHelper returns org.hibernate.TypeHelper;
* Session#getTypeHelper is not deprecated;

In 6.0: org.hibernate.Session.#getTypeHelper is removed;

Incompatibilities migrating from 5.3 -> 6.0:
1) In 6.0, existing applications that call Session.#getTypeHelper will need
to be updated (to what???).

org.hibernate.metadata.ClassMetadata, org.hibernate.metadata.
CollectionMetadata

In 5.2/5.3:
* SessionFactory#getClassMetadata(Class), #getClassMetadata(String),
#getAllClassMetadata, #getCollectionMetadata, #getAllCollectionMetadata
were deprecated; descriptors from
javax.persistence.EntityManagerFactory#getMetamodel
should be used instead; org.hibernate.SessionFactory extends
javax.persistence.EntityManagerFactory;

In 6.0:
* ClassMetadata and CollectionMetadata removed.

Incompatibilities migrating from 5.3 -> 6.0:
1) In 6.0, existing applications that call
org.hibernate.SessionFactory#getClassMetadata(Class),
#getClassMetadata(String), #getAllClassMetadata, #getCollectionMetadata,
#getAllCollectionMetadata will need to be updated to use descripters from
javax.persistence.EntityManagerFactory#getMetamodel.

org.hibernate.stat.NaturalIdCacheStatistics

In 5.2/5.3:
* Statistics#getNaturalIdCacheStatistics returns NaturalIdCacheStatistics;

In 6.0:
* NaturalIdCacheStatistics is renamed to NaturalIdQueryStatistics;
* NaturalIdQueryStatistics excludes #getHitCount, #getMissCount,
#getPutCount, #getElementCountInMemory, #getElementCountOnDisk,
#getSizeInMemory, and #getEntries which were originally in
NaturalIdCacheStatistics; instead org.hibernate.stat.
SecondLevelCacheStatistics#getHitCount, #getMissCount, #getPutCount,
#getElementCountInMemory, #getElementCountOnDisk, #getSizeInMemory should
be used.
(SecondLevelCacheStatistics#getEntries was removed due to HHH-11356, so
there is no substitute for org.hibernate.stat.NaturalIdCacheStatistics#
getEntries;
* Statistics#getNaturalIdCacheStatistics is renamed to
#getNaturalIdStatistics.

Incompatibilities migrating from 5.3 -> 6.0:
1) Existing applications that explicitly use NaturalIdCacheStatistics will
need to be updated to use NaturalIdCacheStatistics.
2) Existing applications that call Statistics#getNaturalIdCacheStatistics
will need to be updated to use Statistics#getNaturalIdCacheStatistics.
3) Existing applications that call org.hibernate.stat.
NaturalIdCacheStatistics#getHitCount, #getMissCount, #getPutCount,
#getElementCountInMemory, #getElementCountOnDisk, #getSizeInMemory, or
#getEntries will need to be updated to obtain the
SecondLevelCacheStatistics object for the particular natural ID using
Statistics#getSecondLevelCacheStatistics( naturalIdRegionName??? ) (How is
naturalIdRegionName determined???). The application will need to be changed
to used SecondLevelCacheStatistics#getHitCount, #getMissCount,
#getPutCount, #getElementCountInMemory, #getElementCountOnDisk, and
#getSizeInMemory instead.
4) Existing applications that call NaturalIdCacheStatistics#getEntries will
need to be updated to no longer call that method.

org.hibernate.stat.SecondLevelCacheStatistics

In 5.3:
* SecondLevelCacheStatistics#getEntries is not deprecated;

In 6.0:
* SecondLevelCacheStatistics#getEntries is removed due to HHH-11356.
* SecondLevelCacheStatistics no longer implements Serializable;

Incompatibilities migrating from 5.3 -> 6.0:
1) Existing applications that call SecondLevelCacheStatistics#getEntries
will need to be updated to no longer call that method.
2) Existing applications that implement SecondLevelCacheStatistics (SPI)
will need to explicitly implement Serializable.

QueryStatistics#getCacheHitCount, #getCacheMissCount, and #getCachePutCount

In 5.3:
* QueryStatistics#getCacheHitCount, #getCacheMissCount, and
#getCachePutCount are not deprecated;

In 6.0:
* QueryStatistics#getCacheHitCount, #getCacheMissCount, and
#getCachePutCount were removed;
* ConcurrentQueryStatisticsImpl implements QueryStatistics and still
contains public methods, #getCacheHitCount, #getCacheMissCount, and
#getCachePutCount (why???).

Incompatibilities migrating from 5.3 -> 6.0:
1) Existing applications that use
org.hibernate.stat.QueryStatistics#getCacheHitCount,
#getCacheMissCount, and #getCachePutCount will need to be changed (to use
SecondLevelCacheStatistics???).

org.hibernate.jpa.HibernateEntityManager

In 5.2/5.3:
* HibernateEntityManager is deprecated; Session (or SessionImplementor
(SPI)) should be used instead;
* Session extends HibernateEntityManager;

In 6.0:
* HibernateEntityManager is removed.

Incompatibilities migrating from 5.3 -> 6.0:
1) In 6.0, existing applications that  explicitly use
org.hibernate.jpa.HibernateEntityManager
(including javax.persistence.EntityManager.unwrap(
HibernateEntityManager.class )) will have to be changed to use Session (or
SessionImplementor (SPI)).

org.hibernate.jpa.HibernateEntityManagerFactory

In 5.2/5.3:
* HibernateEntityManagerFactory is deprecated; SessionFactory (or
SessionFactoryImplementor (SPI)) should be used instead;
* SessionFactory extends HibernateEntityManagerFactory;

In 6.0:
* HibernateEntityManagerFactory is removed.

Incompatibilities migrating from 5.3 -> 6.0:
1) In 6.0, existing applications that explicitly use
org.hibernate.jpa.HibernateEntityManagerFactory
(including javax.persistence.EntityManagerFactory.unwrap(
HibernateEntityManagerFactory.class )) will have to be changed to use
Session (or SessionImplementor (SPI)).

org.hibernate.Hibernate#unproxy

In 5.2/5.3:
* Hibernate#unproxy was introduced by HHH-10831 in 5.2.10

In 6.0:
* the fix for HHH-10831 has not been incorporated into 6.0, so it is not
present. Will it be??

Incompatibilities migrating from 5.3 -> 6.0:
1) Existing applications that use Hibernate#unproxy will have to be be
changed to explicitly initialize and unproxy.