175 lines
10 KiB
Plaintext
175 lines
10 KiB
Plaintext
= 5.0 Migration Guide
|
|
:toc:
|
|
|
|
This guide discusses migration from Hibernate ORM version 4.3 to version 5.0. For migration from
|
|
earlier versions, see any other pertinent migration guides as well.
|
|
|
|
Several updates have been added to this document for changes that took affect after
|
|
5.0.0.Final was released. See <<migration-updates, Migration Updates>> for details
|
|
migrating to later 5.0 releases.
|
|
|
|
|
|
== Re-purposing of Configuration
|
|
|
|
Configuration, historically, allowed users to iteratively add settings and mappings in any order and to query the
|
|
state of settings and mapping information in the middle of that process. Which meant that building the mapping
|
|
information could not effectively rely on any settings being available. This lead to many limitations and problems.
|
|
|
|
Quite a few methods have been removed from Configuration. Be sure to see the User Guide chapter on bootstrapping for
|
|
details. For applications that integrate with Hibernate via one or more APIs, this change might effect your
|
|
integrations as well.
|
|
|
|
|
|
== Short-naming
|
|
|
|
In an effort to insulate applications from refactoring efforts, Hibernate has begun to recognize "short name" values for
|
|
certain configuration settings. These are discussed in detail in the User Guide in the pertinent sections.
|
|
|
|
Where available, we highly recommend using the short name for a setting value.
|
|
|
|
|
|
== Transactions
|
|
|
|
The transaction SPI underwent a major redesign as part of 5.0 as well. From a user perspective this generally
|
|
only comes into view in terms of configuration. Previously applications would work with the different backend
|
|
transaction stratagies directly via the `org.hibernate.Transaction` API. In 5.0 a level of indirection has been
|
|
added here. The API implementation of `org.hibernate.Transaction` is always the same now. On the backend, the
|
|
`org.hibernate.Transaction` impl talks to a `org.hibernate.resource.transaction.TransactionCoordinator` which represents
|
|
the "transactional context" for a given Session according to the backend transaction strategy. Users generally do not
|
|
need to care about the distinction.
|
|
|
|
The change is noted here because it might affect your bootstrap configuration. Whereas previously applications would
|
|
specify `hibernate.transaction.factory_class` and refer to a `org.hibernate.engine.transaction.spi.TransactionFactory` FQN,
|
|
with 5.0 the new contract is `org.hibernate.resource.transaction.TransactionCoordinatorBuilder` and is specified using the
|
|
`hibernate.transaction.coordinator_class` setting. See `org.hibernate.cfg.AvailableSettings.TRANSACTION_COORDINATOR_STRATEGY`
|
|
JavaDocs for additional details.
|
|
|
|
The following short-names are recognized:
|
|
`jdbc`::(the default for non-JPA applications) says to use JDBC-based transactions (`org.hibernate.resource.transaction.backend.jdbc.internal.JdbcResourceLocalTransactionCoordinatorImpl`)
|
|
`jta`::says to use JTA-based transactions (`org.hibernate.resource.transaction.backend.jta.internal.JtaTransactionCoordinatorImpl`)
|
|
|
|
If a JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate will
|
|
automatically build the proper transaction coordinator based on the transaction type for the persistence unit.
|
|
|
|
If a non-JPA application does not provide a setting for `hibernate.transaction.coordinator_class`, Hibernate
|
|
will use `jdbc` as the default. This default will cause problems if the application actually uses JTA-based transactions.
|
|
A non-JPA application that uses JTA-based transactions should explicitly set `hibernate.transaction.coordinator_class=jta`
|
|
or provide a custom `org.hibernate.resource.transaction.TransactionCoordinatorBuilder` that builds a
|
|
`org.hibernate.resource.transaction.TransactionCoordinator` that properly coordinates with JTA-based transactions.
|
|
|
|
See the User Guide for additional details.
|
|
|
|
== Type handling
|
|
|
|
* Migrated `org.hibernate.metamodel.spi.TypeContributor` and `org.hibernate.metamodel.spi.TypeContributions`
|
|
to `org.hibernate.boot.model.TypeContributor` and `org.hibernate.boot.model.TypeContributions`
|
|
* Built-in `org.hibernate.type.descriptor.sql.SqlTypeDescriptor` implementations no longer auto-register themselves
|
|
with `org.hibernate.type.descriptor.sql.SqlTypeDescriptorRegistry`. Applications using custom SqlTypeDescriptor
|
|
implementations extending the built-in ones and relying on that behavior should be updated to call
|
|
`SqlTypeDescriptorRegistry#addDescriptor` themselves.
|
|
* The JDBC type for "big_integer" (org.hibernate.type.BigIntegerType) properties has changed from
|
|
java.sql.Types.NUMERIC to java.sql.Types.BIGINT. This change was reverted in 5.0.1.Final.
|
|
See <<migration-updates, Migration Updates>> for details.
|
|
* For ids defined as UUID with generation, for some databases it is required to explicitly set the `@Column( length=16 )`
|
|
in order to generate BINARY(16) so that comparisons properly work.
|
|
* For EnumType mappings defined in hbm.xml where the user wants name-mapping (`javax.persistence.EnumType#STRING`)
|
|
the configuration must explicitly state that using either the `useNamed` (true) setting or by specifying the `type`
|
|
setting set to the value 12 (VARCHAR JDBC type code).
|
|
|
|
|
|
== Naming strategies
|
|
|
|
Historically Hibernate provided just a singular contract for applying a "naming strategy". Starting in 5.0 this has
|
|
been split into 2 distinct contracts:
|
|
* `ImplicitNamingStrategy` - is used whenever a table or column is not explicitly named to determine the name to use.
|
|
* `PhysicalNamingStrategy` - is used to convert a "logical name" (either implicit or explicit) name of a table or column
|
|
into a physical name (e.g. following corporate naming guidelines)
|
|
|
|
|
|
== Changed setting defaults
|
|
|
|
* Default value for `hibernate.id.new_generator_mappings` setting changed to true for 5.0. See
|
|
`org.hibernate.cfg.AvailableSettings#USE_NEW_ID_GENERATOR_MAPPINGS` javadocs.
|
|
* The default ImplicitNamingStrategy (`hibernate.implicit_naming_strategy`) has changed to the JPA-compliant one. See
|
|
`org.hibernate.cfg.AvailableSettings.IMPLICIT_NAMING_STRATEGY` javadocs for details. If you experience problems
|
|
migrating dues to implicit table or column names you may want to specify the legacy strategy
|
|
(`legacy-hbm` \ `org.hibernate.boot.model.naming.ImplicitNamingStrategyLegacyHbmImpl`).
|
|
* `hibernate.jdbc.batch_versioned_data` default value is now true; Oracle dialects set this property to false,
|
|
except for Oracle12cDialect
|
|
|
|
|
|
== Misc
|
|
|
|
* `cfg.xml` files are again fully parsed and integrated (events, security, etc)
|
|
* properties loaded from `cfg.xml` through EntityManagerFactory did not previously prefix names with "hibernate." this is now made consistent.
|
|
* `Configuration` is no longer `Serializable`
|
|
* `org.hibernate.dialect.Dialect.getQuerySequencesString` expected to retrieve catalog, schema, and increment values as well
|
|
* removed AuditConfiguration in preference for new `org.hibernate.envers.boot.internal.EnversService`
|
|
* changed AuditStrategy method parameters from (removed) AuditConfiguration to (new) EnversService
|
|
* Moving `org.hibernate.hql.spi.MultiTableBulkIdStrategy` and friends to new `org.hibernate.hql.spi.id` package
|
|
and sub-packages
|
|
* Complete redesign of "property access" contracts
|
|
* Valid `hibernate.cache.default_cache_concurrency_strategy` setting values are now defined via
|
|
`org.hibernate.cache.spi.access.AccessType#getExternalName` rather than the `org.hibernate.cache.spi.access.AccessType`
|
|
enum names; this is more consistent with other Hibernate settings
|
|
|
|
|
|
== Deprecations
|
|
|
|
* Removed the deprecated `org.hibernate.cfg.AnnotationConfiguration`
|
|
* Removed deprecated `org.hibernate.id.TableGenerator` id-generator
|
|
* Removed deprecated `org.hibernate.id.TableHiLoGenerator` (hilo) id-generator
|
|
* Deprecated `org.hibernate.id.SequenceGenerator` and its subclasses
|
|
* Added a new dedicated "deprecation logger" to consolidate logging for deprecated uses.
|
|
|
|
== Changed/Moved contracts
|
|
|
|
* `org.hibernate.integrator.spi.Integrator` contract changed to account for bootstrap redesign
|
|
* Extracted `org.hibernate.engine.jdbc.env.spi.JdbcEnvironment` from `JdbcServices`;
|
|
created `org.hibernate.engine.jdbc.env` package and moved a few contracts there.
|
|
* Introduction of `org.hibernate.boot.model.relational.ExportableProducer` which will effect any
|
|
`org.hibernate.id.PersistentIdentifierGenerator` implementations
|
|
* Changed to signature of `org.hibernate.id.Configurable` to accept `ServiceRegistry` rather than just `Dialect`
|
|
|
|
|
|
[[migration-updates]]
|
|
=== Migration from 5.0.0.Final to 5.0.1.Final
|
|
|
|
As of 5.0.1.Final, the JDBC type for "big_integer" (`org.hibernate.type.BigIntegerType`)
|
|
properties has been changed back from `java.sql.Types.BIGINT` to `java.sql.Types.NUMERIC`.
|
|
This is consistent with earlier versions (pre-5.0.0.Final).
|
|
See https://hibernate.atlassian.net/browse/HHH-10053[HHH-10053] for details.
|
|
|
|
|
|
=== Migration from 5.0.1.Final to 5.0.2.Final
|
|
|
|
As of 5.0.2.Final, usage of JPQL KEY() for an `Map` key that is an entity results in the
|
|
addition of an inner join with the entity table. Earlier versions only referenced the
|
|
entity ID and did not add an inner join.
|
|
See https://hibernate.atlassian.net/browse/HHH-10537[HHH-10537] for details.
|
|
|
|
|
|
=== Migration from 5.0.2.Final to 5.0.3.Final
|
|
|
|
As of 5.0.3.Final, when using an `AttributeConverter` for an enum, queries must refer
|
|
to the enum value (e.g., MyEnum.TYPE1). Queries that refer to a literal that is
|
|
the "converted" value (e.g., returned by AttributeConverter#convertToDatabaseColumn)
|
|
will cause a failure.
|
|
See https://hibernate.atlassian.net/browse/HHH-10282[HHH-10282] for details.
|
|
|
|
|
|
=== Migration from 5.0.3.Final to 5.0.8.Final
|
|
|
|
As of 5.0.8.Final, Oracle12cDialect maps byte[] and Byte[] to BLOB.
|
|
|
|
Previous versions of Hibernate have mapped `byte[]` and `Byte[]` to Oracle's `LONG RAW` data type (via the JDBC
|
|
`LONGVARBINARY` type). Oracle has deprecated the `LONG RAW` data type for many releases - possibly as far back
|
|
as 8i. Therefore it was decided to start having Hibernate map `byte[]` and `Byte[]` to `BLOB` for Oracle.
|
|
|
|
However, in the interest of backwards compatibility and not breaking existing applications it was also decided to
|
|
limit this change to just the Oracle12cDialect. So starting in 5.0.8.Final applications using Oracle12cDialect and
|
|
implicitly mapping `byte[]` and `Byte[]` values will start seeing those handled as `BLOB` data rather than `LONG RAW`
|
|
data. For existing applications that want to continue to use Oracle12cDialect and still continue to implicitly map
|
|
`byte[]` and `Byte[]` attributes to `LONG RAW`, there is a new configuration setting you can use to enable that:
|
|
`hibernate.dialect.oracle.prefer_longvarbinary`, which is false by default (map to `BLOB`).
|