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

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(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev