Gail Badner
2018-02-14 18:05:29 UTC
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.
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.