5.8. Hibernate および JPA の移行の変更
5.8.1. Hibernate ORM 3.0
JBoss EAP 6.4 の Hibernate ORM 3 を簡単に使用できるようにする統合クラスは JBoss EAP 7 から削除されました。膨大な作業を行わないと JBoss EAP で Hibernate ORM 3 を実行できなくなったため、アプリケーションが Hibernate ORM 3 ライブラリーを使用する場合は、アプリケーションを移行して Hibernate ORM 5 を使用するようにすることが強く推奨されます。Hibernate ORM 5 へ移行できない場合は、Hibernate ORM 3 JAR のカスタム JBoss モジュールを定義し、アプリケーションから Hibernate ORM 5 のクラスを除外する必要があります。
5.8.2. Hibernate ORM 4.0 - 4.3
アプリケーションに対して 2 次キャッシュを有効にする必要がある場合、nfinispan 8.x が Hibernate ORM 5.0 と統合されたことに注意してください。Infinispan を Hibernate の 2 次キャッシュプロバイダーとして使用するためのサポートは、Hibernate ORM 5.3 の Infinispan プロジェクトに移されました。 そのため、hibernate-infinispan モジュールは本リリースより削除されました。
Hibernate ORM 4.x で作成されたアプリケーションは Hibernate ORM 4.x を引き続き使用できます。Hibernate ORM 4.x JAR のカスタム JBoss モジュールを定義し、アプリケーションから Hibernate ORM 5 クラスを排除する必要があります。しかし、Hibernate ORM 5 を使用するようにアプリケーションコードを書き直すことが強く推奨されます。Hibernate ORM 5 への移行に関する情報は、「Hibernate ORM 5 への移行」を参照してください。
5.8.3. Hibernate ORM 5 への移行
JBoss EAP 7.0 には Hibernate ORM 5.0 が含まれていました。ここでは、Hibernate ORM をバージョン 4.3 からバージョン 5 に移行する際に必要な変更について説明します。Hibernate ORM 4 から Hibernate ORM 5 の間に実装された変更は、『Hibernate ORM 5.0 Migration Guide』を参照してください。
削除および非推奨となったクラス
以下のクラスは非推奨となり、Hibernate ORM 5 から削除されました。
クラスおよびパッケージのその他の変更
-
ブートストラップの再設計に合わせて、
org.hibernate.integrator.spi.Integratorインターフェースが変更になりました。 -
新しいパッケージ
org.hibernate.engine.jdbc.env.spiが作成されました。これには、org.hibernate.engine.jdbc.spi.JdbcServicesインターフェースから展開されたorg.hibernate.engine.jdbc.env.spi.JdbcEnvironmentインターフェースが含まれます。 -
org.hibernate.id.PersistentIdentifierGenerator実装に影響する、新しいorg.hibernate.boot.model.relational.ExportableProducerインターフェースが導入されました。 -
org.hibernate.id.Configurableの署名が変更になり、org.hibernate.dialect.Dialectのみでなくorg.hibernate.service.ServiceRegistryを許可するようになりました。 -
org.hibernate.metamodel.spi.TypeContributorインターフェースはorg.hibernate.boot.model.TypeContributorに移行されました。 -
org.hibernate.metamodel.spi.TypeContributionsインターフェースはorg.hibernate.boot.model.TypeContributionsに移行されました。
タイプ処理
-
組み込みの
org.hibernate.type.descriptor.sql.SqlTypeDescriptor実装は、org.hibernate.type.descriptor.sql.SqlTypeDescriptorRegistryで自動登録しないようになりました。組み込みの実装を拡張し、その動作に依存するカスタムSqlTypeDescriptor実装を使用するアプリケーションを更新し、SqlTypeDescriptorRegistry.addDescriptor()を呼び出すようにする必要があります。 -
生成された UUID として定義された ID では、
BINARY(16)を生成して適切に比較が行われるようにするため、一部のデータベースでは@Column(length=16)を明示的に設定する必要があります。 -
name-mapping を希望する、javax.persistence.EnumType.STRINGhbm.xmlに定義されたEnumTypeマッピングでは、useNamed(true)設定を使用するか、VARCHAR の値を12に指定して、設定を明示的に示す必要があります。
トランザクション管理
-
Hibernate ORM 5 では、トランザクションSPI が大幅に再設計されました。Hibernate ORM 4.3 では、
org.hibernate.TransactionAPI を使用して異なるバックエンドトランザクションストラテジーに直接アクセスしました。Hibernate ORM 5 には間接参照のレベルが導入されました。org.hibernate.Transaction実装はバックエンドで、バックエンドストラテジーに応じて指定のセッションのトランザクションコンテキストを表すorg.hibernate.resource.transaction.TransactionCoordinatorと対話するようになりました。開発者への直接的な影響はありませんが、ブートストラップの設定に影響する可能性があります。これまで、アプリケーションは非推奨となったhibernate.transaction.factory_classプロパティーを指定し、org.hibernate.engine.transaction.spi.TransactionFactoryFQN (完全修飾名) を参照しました。Hibernate ORM 5 では、hibernate.transaction.coordinator_class設定を指定し、org.hibernate.resource.transaction.TransactionCoordinatorBuilderを参照します。詳細は、「org.hibernate.cfg.AvailableSettings.TRANSACTION_COORDINATOR_STRATEGY」を参照してください。 以下の短縮名が認識されるようになりました。
-
jdbc: JDBC
java.sql.Connectionを使用してトランザクションを管理します。これは、JPA 以外のトランザクションのデフォルトです。 jta: JTA を使用してトランザクションを管理します。
重要JPA アプリケーションが
hibernate.transaction.coordinator_classプロパティーの設定を提供しない場合、Hibernate は永続化ユニットのトランザクションタイプを基にして自動的に適切なトランザクションコーディネーターを構築します。JPA でないアプリケーションが
hibernate.transaction.coordinator_classプロパティーの設定を提供しない場合、Hibernate はデフォルトでjdbcを使用してトランザクションを管理します。アプリケーションが実際に JTA ベースのトランザクションを使用する場合は、このデフォルトによって問題が発生します。JTA ベースのトランザクションを使用する JPA でないアプリケーションでは、hibernate.transaction.coordinator_classプロパティーの値を明示的にjtaに設定するか、JTA ベースのトランザクションを適切に調整するorg.hibernate.resource.transaction.TransactionCoordinatorを構築するカスタムのorg.hibernate.resource.transaction.TransactionCoordinatorBuilderを提供する必要があります。
-
jdbc: JDBC
Hibernate ORM 5 のその他の変更
-
cfg.xmlファイルは完全に解析され、イベント、セキュリティー、およびその他の関数と統合されます。 -
EntityManagerFactoryを使用してcfg.xmlからロードされたプロパティーは、これまで名前の前にhibernateが付きませんでした。これにより、一貫性が確立されました。 - 設定がシリアライズ不可能になりました。
-
org.hibernate.dialect.Dialect.getQuerySequencesString()メソッドがカタログ、スキーマ、およびインクリメントの値を取得するようになりました。 -
AuditConfigurationはorg.hibernate.envers.boot.internal.EnversServiceから削除されました。 -
AuditStrategyメソッドが変更され、廃止されたAuditConfigurationを削除し、新しいEnversServiceを使用するようになりました。 -
org.hibernate.hql.spiパッケージおよびサブパッケージの複数のクラスおよびインターフェースが新しいorg.hibernate.hql.spi.idに移動されました。これにはMultiTableBulkIdStrategyクラスが含まれ、さらにAbstractTableBasedBulkIdHandler、TableBasedDeleteHandlerImpl、およびTableBasedUpdateHandlerImplインターフェースとそれらのサブクラスが含まれます。 - プロパティーアクセスコントラクトが完全に再設計されました。
-
有効な
hibernate.cache.default_cache_concurrency_strategy設定の値は、org.hibernate.cache.spi.access.AccessType列挙定数ではなく、org.hibernate.cache.spi.access.AccessType.getExternalName()メソッドを使用して定義されるようになりました。これにより、他の Hibernate 設定と統一されます。
5.8.4. Hibernate ORM 5.0 から Hibernate ORM 5.1 への移行
JBoss EAP 7.1 には Hibernate ORM 5.1 が含まれていました。ここでは、この 2 つの違いと、Hibernate ORM のバージョン 5.0 からバージョン 5.1 に移行する際に必要な変更について説明します。
Hibernate ORM 5.1 の機能
このリリースの Hibernate には、JBoss EAP 7.1.0 リリースノート の Hibernate ORM 5.1 の機能 に記載されているパフォーマンスの改善やバグ修正が含まれます。Hibernate ORM 5.0 から Hibernate ORM 5.1 の間に実装された変更に関する詳細は、『Hibernate ORM 5.1 Migration Guide』を参照してください。
スキーマ管理ツールの変更
JBoss EAP 7 でのスキーマ管理ツールの変更
Hibernate ORM 5.1 のスキーマ管理ツールは、主に以下の項目を中心に変更されています。
-
hbm2ddl.autoと Hibernate の JPAschema-generationサポートの処理を統合。 - NoSQL データストアの Java Persistance (JPA) サポートを提供する永続化エンジンである Hibernate OGM の置き換えを容易にするため、SPI から JDBC の懸念事項を削除。
移行時にスキーマ管理ツールの変更に注意する必要があるのは、以下のクラスを直接使用するアプリケーションのみです。
-
org.hibernate.tool.hbm2ddl.SchemaExport -
org.hibernate.tool.hbm2ddl.SchemaUpdate -
org.hibernate.tool.hbm2ddl.SchemaValidator -
org.hibernate.tool.schema.spi.SchemaManagementToolまたはこの委譲
JBoss EAP 7.1 でのスキーマ管理ツールの変更
JBoss EAP 7.1 に含まれる Hibernate ORM 5.1.10 には、SchemaMigrator および SchemaValidator のパフォーマンスを向上するデータベーステーブル取得の新しいストラテジーが導入されました。このストラテジーは、単一の java.sql.DatabaseMetaData#getTables(String, String, String, String[]) 呼び出しを実行して、各 javax.persistence.Entity がマップされたデータベーステーブルを持っているかどうかを判断します。これはデフォルトのストラテジーで、hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=grouped プロパティー設定を使用します。このストラテジーには、hibernate.default_schema や hibernate.default_catalog を提供する必要があることがあります。
each javax.persistence.Entity に java.sql.DatabaseMetaData#getTables(String, String, String, String[]) 呼び出しを実行する旧式のストラテジーを使用するには、hibernate.hbm2ddl.jdbc_metadata_extraction_strategy=individually プロパティー設定を使用します。
5.8.5. Hibernate ORM 5.1 から Hibernate ORM 5.3 への移行
JBoss EAP 7.2 には Hibernate ORM 5.3 が含まれていました。ここでは、この 2 つの違いと、Hibernate ORM のバージョン 5.1からバージョン 5.3 に移行する際に必要な変更について説明します。
Hibernate ORM 5.2 の機能
Hibernate ORM 5.2 は、Java 8 JDK を使用して構築され、起動時に Java 8 JRE が必要になります。以下は、本リリースに追加された変更の一部を示しています。
-
The
hibernate-java8モジュールはhibernate-coreにマージされ、Java 8 date/time データ型はネイティブにサポートされるようになりました。 -
hibernate-entitymanagerモジュールはhibernate-coreにマージされました。HibernateEntityManagerおよびHibernateEntityManagerFactoryは非推奨となりました。 -
非推奨のクラスを削除し、JPA Metamodel API と適合させるため、
Session、StatelessSession、およびSessionFactoryクラスの階層がリファクタリングされました。 -
org.hibernate.persisterおよびorg.hibernate.tupleパッケージの SPI が変更になりました。これらの SPI を使用したカスタムクラスをすべて確認および更新する必要があります。 -
LimitHandlerの変更によって、レガシー Hibernate 4.3 の制限ハンドラーの動作を有効にできる新しいhibernate.legacy_limit_handler設定が追加されました。これはデフォルトでfalseに設定されています。 これは一部のダイアレクトに影響します。 -
SchemaMigratorおよびSchemaValidatorのパフォーマンスを向上する、データベーステーブル取得の新しいストラテジーが導入されました。 -
本リリースでは、PostgreSQL81Dialect とそのサブクラスの使用時に、
@Lobアノテーションが付けられたString、character[]、およびCharacter[]属性のCLOB値を処理する方法が変更になりました。 -
@TableGeneratorおよび@SequenceGenerator名の範囲がグローバルからローカルに変更になりました。
Hibernate 5.2 に実装された変更の完全リストは、『Hibernate ORM 5.2 Migration Guide』を参照してください。
Hibernate ORM 5.3 の機能
Hibernate ORM 5.3 には JPA 2.2 仕様のサポートが追加されました。本リリースにはこの仕様に準拠する変更と、その他の改善点が含まれています。以下にこれらの変更の一部を示します。
位置クエリーパラメーター処理の変更により、以下が変更になりました。
- HQL/JPQL クエリーの JDBC スタイルパラメーター宣言のサポートが削除されました。
- JPA 位置パラメーターは名前付きパラメーターのように動作します。
-
ネイティブクエリーの JDBC スタイルパラメーター宣言は、JPA との一貫性を保つため、ゼロベースではなく 1 ベースのパラメーターバインディングを使用します。ゼロベースのバインディングに戻すには、
hibernate.query.sql.jdbc_style_params_baseプロパティーをtrueに設定します。
-
JPA に準拠するため、
@TableGenerator値によって保存されるシーケンス値は最後に生成された値になります。これまで Hibernate は、次のシーケンス値を保存しました。このレガシー動作を有効にするには、hibernate.id.generator.stored_last_usedプロパティーを使用します。@TableGeneratorを使用し、Hibernate 5.3 に移行する既存のアプリケーションはhibernate.id.generator.stored_last_used configurationプロパティーをfalseに設定する必要があります。 -
org.hibernate.query.QueryParameterクラスのgetType()メソッドの名前がgetHibernateType()に変更されました。 - さまざまなキャッシングプロバイダーの要件により多く適合するため、Hibernate の 2次レベルキャッシュ SPI が再設計されました。詳細は「HHH-11264」を参照してください。
- HHH-11356 の変更により、コンシューマーの変更も必要になりました。 これは Hibernate Statistics システムに影響します。
-
ネイティブアプリケーションの Hibernate ORM 5.1 から 5.3 への移行を容易にし、Hibernate 5.1 の改ページ調整動作を維持するため、一部のメソッドが一時的に
org.hibernate.Queryクラスに追加されましたが、これらのメソッドは非推奨となりました。今後のバージョンの Hibernate に移植できるようにするため、JPA メソッドを使用するようアプリケーションをアップデートする必要があります。 -
Infinispan を Hibernate の 2 次キャッシュプロバイダーとして使用するためのサポートは、Infinispan プロジェクトに移されました。そのため、
hibernate-infinispanモジュールは削除されました。 -
org.hibernate.tool.enhance.EnhancementTaskAnt タスクの API が変更になりました。setBase()およびsetDir()メソッドが推奨されるため、addFileset()メソッドは削除されました。詳細は「HHH-11264」を参照してください。 - Hibernate 4.3 で見つかったバグにより、明示的にレイジーとしてマップした場合でも、埋め込み可能なコレクション要素と複合 ID の多対 1 の関連が集中的に取得されました。Hibernate 5.3.2 ではこのバグが修正されました。そのため、このような関連はマッピングで指定されたとおりに取得されるようになりました。詳細は「HHH-11264」を参照してください。
-
本リリースでは、Hibernate イベントリスナーの JPA とネイティブ実装が統一されました。そのため、
JpaIntegratorクラスは廃止されました。org.hibernate.jpa.event.spi.JpaIntegratorを拡張するクラスを変更し、org.hibernate.integrator.spi.Integratorインターフェースを実装するように変更する必要があります。詳細は「HHH-11264」を参照してください。 -
org.hibernate.persisterパッケージの SPI が変更になりました。これらの SPI を使用したカスタムクラスをすべて確認および更新する必要があります。
Hibernate 5.3 に実装された変更の完全リストは、『Hibernate ORM 5.3 Migration Guide』を参照してください。
5.8.5.1. Hibernate 5.1 および Hibernate 5.3 間の例外処理の変更
Hibernate 5.2 と 5.3 では、JPA 仕様に準拠して、Hibernate のネイティブブートストラップを使用して構築される SessionFactory の例外処理は HibernateException をラッピングまたは変換しました。Session.save() や Session.saveOrUpdate() のように操作が Hibernate 固有の場合のみこの動作の例外となります。
Hibernate 5.3.3 では、hibernate.native_exception_handling_51_compliance プロパティーが追加されました。このプロパティーは、Hibernate のネイティブブートストラップを使用して構築された SessionFactory の例外処理が、Hibernate ORM 5.1 でのネイティブの例外処理と同じように動作すべきかどうかを示します。true に設定すると HibernateException は JPA 仕様のとおりにラップまたは変換されません。この設定は、JPA ブートストラップを使用して構築された SessionFactory では無視されます。
5.8.5.2. 互換性トランスフォーマー
JBoss EAP 7.2 には、Hibernate ORM 5.1 との互換性がなくなった Hibernate ORM 5.3 API メソッドに対応する互換性トランスフォーマーが含まれています。トランスフォーマーは、Hibernate ORM 5.1 を使用して構築されたアプリケーションが JBoss EAP 7.2 の Hibernate 5.3 で同じ動作を実行できるようにする一時的な措置です。これは一時的な対策であり、これらのメソッド呼び出しを推奨される JPA メソッド呼び出しに置き換える必要があります。
トランスフォーマーを有効にするには、以下の方法の 1 つを使用します。
-
Hibernate51CompatibilityTransformerシステムプロパティーをtrueに設定すると、トランスフォーマーをすべてのアプリケーションに対してグローバルに有効化できます。 jboss-deployment-structure.xmlファイルを使用すると、アプリケーションレベルでトランスフォーマーを有効にできます。<jboss-deployment-structure> <deployment> <transformers> <transformer class="org.jboss.as.hibernate.Hibernate51CompatibilityTransformer"/> </transformers> </deployment> <sub-deployment name="main.war"> <transformers> <transformer class="org.jboss.as.hibernate.Hibernate51CompatibilityTransformer"/> </transformers> </sub-deployment> </jboss-deployment-structure>
以下の表は、変換前の Hibernate 5.1 メソッドと、変換後の Hibernate 5.3 メソッドを表しています。
| Hibernate 5.1 のリファレンスまたはメソッド | 変換後の Hibernate 5.3 のリファレンスまたはメソッド |
|---|---|