hibernate-orm/migration-guide.adoc

102 lines
5.7 KiB
Plaintext

= 5.2 Migration Guide
:toc:
This guide discusses migration from Hibernate ORM version 5.1 to version 5.2. For migration from
earlier versions, see any other pertinent migration guides as well.
== Background
Lots of work has been done for 6.0. One of the things 6.0 will need is a unified view of "type systems"
including its own type system (Type, EntityPersister, CollectionPersister, etc) and JPA's type system - which
would mean unifying all of this in hibernate-core. Because of this and the other large changes slated for 6.0
we decided to release a 5.2 that showed a clear migration path to the changes in 6.0 but that still supported the
older calls and expectations as much as possible.
== Move to Java 8 for baseline
Hibernate 5.2 is built using Java 8 JDK and will require Java 8 JRE at runtime (we are investigating whether
Java 9 will also work). This has a number of implications:
* The hibernate-java8 module has been merged into hibernate-core and the Java 8 date/time types are now natively
supported.
* (todo) support for Java 8 Optional
* (todo) support for other Java 8 features?
== hibernate-entitymanager merged into hibernate-core
The hibernate-entitymanager module has also been merged into hibernate-core.
* `org.hibernate.SessionFactory` now extends `javax.persistence.EntityManagerFactory` - temporarily it
technically extends `org.hibernate.jpa.HibernateEntityManagerFactory` (which in turn extends
`javax.persistence.EntityManagerFactory`) for backwards compatibility. `HibernateEntityManagerFactory`
is deprecated.
* `org.hibernate.Session` now extends `javax.persistence.EntityManager` - temporarily it
technically extends `org.hibernate.jpa.HibernateEntityManager` (which in turn extends
`javax.persistence.EntityManager`) for backwards compatibility. `HibernateEntityManager` is deprecated.
* `org.hibernate.Query` (deprecated in favor of new `org.hibernate.query.Query`) now extends the JPA contracts
`javax.persistence.Query` and `javax.persistence.TypedQuery`. `ProcedureCall` and `StoredProcedureQuery` as well.
* `org.hibernate.HibernateException` now extends `javax.persistence.PersistenceExceptions`. Hibernate methods
that "override" methods from their JPA counterparts now will also throw various JDK defined RuntimeExceptions
(such as `IllegalArgumentException`, `IllegalStateException`, etc) as required by the JPA contract.
* Persister/type access is now exposed through `org.hibernate.Metamodel`, which extends
`javax.persistence.metamodel.Metamodel`. MetamodelImpl now manages all aspects of type system (see below).
* Cache management has also been consolidated. `org.hibernate.Cache` now extends `javax.persistence.Cache`. CacheImpl
now manages all aspects of cache regions (see below).
== SessionFactory hierarchy cleanup
As part of merging hibernate-entitymanager into hibernate-core, I also wanted to take a moment to clean up
some of these very old contracts, In conjunction with the move to Java 8 (default methods) and needing to
implement JPA methods now in core I decided to implement more of a composition approach here, thus:
* SessionFactoryImplementor used to have a number of methods pertaining to managing and accessing entity and collection persisters.
Since we need to deal with JPA Metamodel contract anyway, I went ahead and moved all of that code into our new
`org.hibernate.metamodel.spi.MetamodelImplementor`
* SessionFactory and SessionFactoryImplementor each had a number of methods dealing with cache regions.
Many of these methods have been deprecated since 5.0 and those will be removed. However, the functionality
has been moved into the `org.hibernate.Cache` and `org.hibernate.engine.spi.CacheImplementor` contracts
helping implement JPA's `javax.persistence.Cache` role.
== LimitHandler changes
In Hibernate 4.3, dialect implementations that did not support a limit offset would fetch all rows for a query and
perform pagination in-memory. This solution, while functional, could have severe performance penalties. In 5.x,
we preferred to favor performance optimizations which meant dialect implementations would throw an exception if a
limit offset was specified but the dialect didn't support such syntax.
As of 5.2.5.Final, we have introduced a new setting, `hibernate.legacy_limit_handler`, that is designed to allow
users to enable the legacy 4.3 limit handler behavior. By default, this setting is _false_.
The specific dialects impacted by this change are restricted to the following.
* Cache71Dialect
* DB2390Dialect
* InformixDialect
* IngresDialect
* RDMSOS2200Dialect
* SQLServerDialect
* TimesTenDialect
NOTE: If a dialect that extends any in the above list but overrides the limit handler implementation, then those
dialects remain unchanged, e.g. SQLServer2005Dialect.
== Misc
* QueryCacheFactory contract changed
* RegionFactory contract changes
* todo : merge AvailableSettings together
* org.hibernate.Transaction now extends JPA's EntityTransaction and follows its pre- and post- assertions.
e.g. begin() now throws an exception if transaction is already active.
* (todo) following the above one, JPA also says that only PersistenceUnitTransactionType#JTA EntityManagers
are allowed to access EntityTransactions. Need a strategy to handle this
* Session#getFlushMode and Query#getFlushMode clash in terms of Hibernate (FlushMode) and JPA (FlushModeType)
returns. #getFlushMode has been altered to return JPA's FlushModeType. The Hibernate FlushMode
is still available via #getHibernateFlushMode and #setHibernateFlushMode. Same for Session#getFlushMode
and EntityManager#getFlushMode.
* Setting `hibernate.listeners.envers.autoRegister` has been deprecated in favor of
`hibernate.envers.autoRegisterListeners`.
* AuditReader#getCurrentRevision has been deprecated in favor of `org.hibernate.envers.RevisionListener`.