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.type.descriptor.sql.SqlTypeDescriptor 実装は、org.hibernate.type.descriptor.sql.SqlTypeDescriptorRegistry で自動登録しないようになりました。組み込みの実装を拡張し、その動作に依存するカスタム SqlTypeDescriptor 実装を使用するアプリケーションを更新し、SqlTypeDescriptorRegistry.addDescriptor() を呼び出すようにする必要があります。
  • 生成された UUID として定義された ID では、BINARY(16) を生成して適切に比較が行われるようにするため、一部のデータベースでは @Column(length=16) を明示的に設定する必要があります。
  • javax.persistence.EnumType.STRING name-mapping を希望する、hbm.xml に定義された EnumType マッピングでは、 useNamed(true) 設定を使用するか、VARCHAR の値を 12 に指定して、設定を明示的に示す必要があります。
トランザクション管理
  • Hibernate ORM 5 では、トランザクションSPI が大幅に再設計されました。Hibernate ORM 4.3 では、org.hibernate.Transaction API を使用して異なるバックエンドトランザクションストラテジーに直接アクセスしました。Hibernate ORM 5 には間接参照のレベルが導入されました。org.hibernate.Transaction 実装はバックエンドで、バックエンドストラテジーに応じて指定のセッションのトランザクションコンテキストを表す org.hibernate.resource.transaction.TransactionCoordinator と対話するようになりました。開発者への直接的な影響はありませんが、ブートストラップの設定に影響する可能性があります。これまで、アプリケーションは非推奨となった hibernate.transaction.factory_class プロパティーを指定し、org.hibernate.engine.transaction.spi.TransactionFactory FQN (完全修飾名) を参照しました。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 を提供する必要があります。

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 の JPA schema-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.EnhancementTask Ant タスクの 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 のリファレンスまたはメソッド

org.hibernate.BasicQueryContract.getFlushMode()

org.hibernate.BasicQueryContract.getHibernateFlushMode()

org.hibernate.Session.getFlushMode()

org.Session.getHibernateFlushMode()

Enum org.hibernate.FlushMode.NEVER (0)

Enum org.hibernate.FlushMode.MANUAL (0)

org.hibernate.Query.getMaxResults()

org.hibernate.Query.getHibernateMaxResults()

org.hibernate.Query.setMaxResults(int)

org.hibernate.Query.setHibernateMaxResults(int)

org.hibernate.Query.getFirstResult(int)

org.hibernate.Query.getHibernateFirstResult()

org.hibernate.Query.setFirstResult(int)

org.hibernate.Query.setHibernateFirstResult(int)