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

[Steve Ebersole]

We have not integrated changes from master into 6.0 for a long time.  And
we probably won't for some time yet either.  So comparisons between 5.2 or
5.3 and 6.0 right now are pointless

On Wed, Feb 14, 2018 at 12:09 PM Gail Badner <gbadner at redhat.com> wrote:

> 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.
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>