From c2ad82ef2b1d799ea746bbcd90df342a45a3742a Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Thu, 20 Aug 2015 14:29:48 -0500 Subject: [PATCH] HHH-10043 - Migration Guide --- migration-guide-5.0.adoc | 28 -------- migration-guide.adoc | 118 +++++++++++++++++++++++++++++++++ working-5.0-migration-guide.md | 97 --------------------------- 3 files changed, 118 insertions(+), 125 deletions(-) delete mode 100644 migration-guide-5.0.adoc create mode 100644 migration-guide.adoc delete mode 100644 working-5.0-migration-guide.md diff --git a/migration-guide-5.0.adoc b/migration-guide-5.0.adoc deleted file mode 100644 index 3cd1efaa20..0000000000 --- a/migration-guide-5.0.adoc +++ /dev/null @@ -1,28 +0,0 @@ -= 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. - -* 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. todo : topical guide on bootstrapping, reference that here. - -* Migrated `org.hibernate.metamodel.spi.TypeContributor` and `org.hibernate.metamodel.spi.TypeContributions` -to `org.hibernate.boot.model.TypeContributor` and `org.hibernate.boot.model.TypeContributions` - -* Naming strategies - discuss split. - -* implicit column names, add to strategy? Currently these are handled "specially": -** PrimaryKeyJoinColumn -*** joined-subclass key column(s) - JPA defaults -*** secondary table key column(s) - JPA defaults -*** one-to-one key column(s) - JPA defaults -** entity simple identifier column - JPA defaults -** entity version - currently uses #determineAttributeColumnName -** collection-id column name - currently hard-coded as "id" -** list-index column name - currently hard-coded as "idx" - -* hibernate.jdbc.batch_versioned_data default value is true, Oracle dialects set this property to false except for Oracle12cDialect \ No newline at end of file diff --git a/migration-guide.adoc b/migration-guide.adoc new file mode 100644 index 0000000000..e6b93d99f2 --- /dev/null +++ b/migration-guide.adoc @@ -0,0 +1,118 @@ += 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. + +== 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) 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`) + +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. +* 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` diff --git a/working-5.0-migration-guide.md b/working-5.0-migration-guide.md deleted file mode 100644 index fa0472b9c6..0000000000 --- a/working-5.0-migration-guide.md +++ /dev/null @@ -1,97 +0,0 @@ -Working list of changes for 5.0 -=================================== - -* Switch from Configuration to ServiceRegistry+Metadata for SessionFactory building -* `org.hibernate.hql.spi.MultiTableBulkIdStrategy#prepare` contract has been changed to account for Metadata -* (proposed) `org.hibernate.persister.spi.PersisterFactory` contract, specifically building CollectionPersisters) - has been changed to account for Metadata -* extract `org.hibernate.engine.jdbc.env.spi.JdbcEnvironment` from `JdbcServices`; create - `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 -* Change to signature of `org.hibernate.id.Configurable` to accept `ServiceRegistry` rather than just `Dialect` -* 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 -* cfg.xml files are again fully parsed and integrated (events, security, etc) -* Removed the deprecated `org.hibernate.cfg.AnnotationConfiguration` -* `Integrator` contract -* `Configuration` is no longer `Serializable` -* `org.hibernate.dialect.Dialect.getQuerySequencesString` expected to retrieve catalog, schema, and increment values as well -* properties loaded from cfg.xml through EMF did not previously prefix names with "hibernate." this is now made consistent. -* removed AuditConfiguration in preference for new `org.hibernate.envers.boot.internal.EnversService` -* changed AuditStrategy method parameters from (removed) AuditConfiguration to (new) EnversService -* 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. -* Moving `org.hibernate.hql.spi.MultiTableBulkIdStrategy` and friends to new `org.hibernate.hql.spi.id` package - and sub-packages -* Changes to "property access" contracts, including -* 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 -* 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). -* 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. - - -TODOs -===== -* Still need to go back and make all "persistent id generators" to properly implement ExportableProducer -* Add a setting to "consistently apply" naming strategies. E.g. use the "join column" methods from hbm.xml binding. -* Along with this ^^ consistency setting, split the implicit naming strategy for join columns into multiple methods - one for each usage: - * many-to-one - * one-to-one - * etc - - -Blog items -========== -* New bootstrapping API - better determinism, better integration -* Java 8 Support (though still compatible with Java 6). -* hibernate-spatial -* Ability to handle additional Java types for id attributes marked as `GenerationType#AUTO`. Built-in support - for Number and UUID. Expandable via new `org.hibernate.boot.model.IdGeneratorStrategyInterpreter` extension -* Expanded support for AttributeConverters. - * fully supported for non-`@Enumerated` enum values - * applicable in conjunction with `@Nationalized` support - * called to handle null values - * settable in hbm.xml by using `type="converter:fully.qualified.AttributeConverterName"` - * integrated with hibernate-envers - * collection values, map keys -* scanning support for non-JPA usage -* naming strategy split. default is now to be jpa-compliant -* OSGi improvements, Karaf feature file published - - -Proposals for discussion -======================== -* Currently there is a "post-binding" hook to allow validation of the bound model (PersistentClass, -Property, Value, etc). However, the top-level entry points are currently the only possible place -(per contract) to throw exceptions when a validation fails". I'd like to instead consider a pattern -where each level is asked to validate itself. Given the current model, however, this is unfortunately -not a win-win situation. `org.hibernate.boot.model.source.internal.hbm.ModelBinder#createManyToOneAttribute` -illustrates one such use case where this would be worthwhile, and also can illustrate how pushing the -validation (and exception throwing down) can be less than stellar given the current model. In the process -of binding a many-to-one, we need to validate that any many-to-one that defines "delete-orphan" cascading -is a "logical one-to-one". There are 2 ways a many-to-one can be marked as a "logical one-to-one"; first -is at the `` level; the other is through a singular `` that is marked as unique. -Occasionally the binding of the column(s) of a many-to-one need to be delayed until a second pass, which -means that sometimes we cannot perform this check immediately from the `#createManyToOneAttribute` method. -What would be ideal would be to check this after all binding is complete. In current code, this could be -either an additional SecondPass or done in a `ManyToOne#isValid` override of `SimpleValue#isValid`. The -`ManyToOne#isValid` approach illustrates the conundrum... In the `ManyToOne#isValid` call we know the real -reason the validation failed (non-unique many-to-one marked for orphan delete) but not the property name/path. -Simply returning false from `ManyToOne#isValid` would instead lead to a misleading exception message, which -would at least have the proper context to know the property name/path. -* Consider an additional "naming strategy contract" specifically for logical naming. This would be non-pluggable, and -would be the thing that generates the names we use to cross-reference and locate tables, columns, etc.