hibernate-orm/migration-guide.adoc

= 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`).