5.9. Hibernate Search の変更

JBoss EAP 7 に同梱される Hibernate Search のバージョンが変更になりました。以前のリリースの JBoss EAP には Hibernate Search 4.6.x が同梱されていました。JBoss EAP 7 には Hibernate Search 5.5.x が同梱されます。

Hibernate Search 5.5 は Apache Lucene 5.3.1 に構築されます。ネイティブ Lucene API を使用する場合は、必ずこのバージョンに合わせてください。Hibernate Search 5.5 API では、バージョン 3 からバージョン 5 の間に加えられた複雑な Lucene API の変更の多くがラップされ、隠されていますが、クラスの一部は非推奨となったり、名前変更または再パッケージされています。ここでは、これらの変更がアプリケーションコードに与える影響について説明します。

Hibernate Search マッピングの変更

埋め込み関係の ID フィールドのインデックス化

@IndexedEmbedded アノテーションを使用して関連エントリーからのフィールドを含む場合、関連エントリーの id が含まれなくなりました。id が含まれるようにするには、@IndexedEmbedded アノテーションの includeEmbeddedObjectId 属性を使用します。

例: @IndexedEmbedded アノテーション

@IndexedEmbedded(includeEmbeddedObjectId=true)

番号および日付のインデックス形式の変更

番号や日付はデフォルトで数字フィールドとしてインデックス化されるようになりました。タイプ int、long、float、double のプロパティーおよびこれらのラッパークラスは文字列としてインデックス化されないようになりました。代わりに、これらは Lucene の適切な数字エンコーディングを使用してインデックス化されるようになりました。id フィールドはこのルールの例外で、数字タイプによって表されても、デフォルトで文字列キーワードとしてインデックス化されます。@NumericField の使用は、数字エンコーディングのカスタム精度を指定する場合以外は廃止されました。数値エンコーディングのカスタム精度を指定しない限り、@NumericField が廃止されるようになりました。文字列エンコーディングフィールドブリッジを明示的に指定すると、これまでの文字列ベースのインデックス形式を保持できます。整数の場合、これは org.hibernate.search.bridge.builtin.IntegerBridge です。その他の公開されているフィールドブリッジは、org.hibernate.search.bridge.builtin パッケージを確認してください。

Date および Calendar は文字列としてインデックス化されないようになりました。代わりに、インスタンスは 1970 年 1 月 1 日グリニッジ標準時 00:00:00 からの期間 (ミリ秒) を表す長整数としてエンコードされます。新しい EncodingType 列挙を使用するとインデックス形式を切り替えできます。例を以下に示します。

例: @DateBridge および @CalendarBridge アノテーション

@DateBridge(encoding=EncodingType.STRING)
@CalendarBridge(encoding=EncodingType.STRING)

数字と日付のエンコーディングの変更は重要で、アプリケーションの動作に大きく影響する可能性があります。以前は文字列にエンコードされ、現在は数字にエンコードされるフィールドをターゲットとするクエリーがある場合、クエリーを更新する必要があります。NumericRangeQuery で数字フィールドを検索する必要があります。また、ファセッティングがターゲットとするすべてのフィールドが文字列でエンコードされるようにする必要があります。Search クエリー DSL を使用する場合、適切なクエリーが自動的に作成されるはずです。

その他の Hibernate Search の変更

  • ソートオプションが改良され、ソートオプションに対してフィールドエンコーディングが誤って指定されるとランタイム例外が発生するようになりました。また、あらかじめソートに使用されるフィールドが分かる場合、Lucene によってより高性能なソート機能が提供されます。Hibernate Search 5.5 は新しい @SortableField および @SortableFields アノテーションを提供します。詳細は、Migration Guide from Hibernate Search 5.4 to 5.5 を参照してください。

  • Lucene の SortField API には、以下のアプリケーションコードの変更を適用する必要があります。

    以前のリリースの JBoss EAP では、以下のようにクエリーでソートフィールドのタイプを設定しました。 

    fulltextQuery.setSort(new Sort(new SortField("title", SortField.STRING)));

    JBoss EAP 7 での設定例は次のとおりです。 

    fulltextQuery.setSort(new Sort(new SortField("title", SortField.Type.STRING)));
  • SearchFactory は ORM の統合でのみ使用される必要があるため、hibernate-search-engine モジュールから hibernate-search-orm モジュールに移動されました。他のインタグレーターは SearchIntegrator のみに依存する必要があります。これは、非推奨となった SearchFactoryIntegrator の代わりに使用されます。
  • 列挙値 SpatialMode.GRID の名前が SpatialMode.HASH に変更になりました。
  • FullTextIndexEventListener が最終クラスになりました。現在このクラスを拡張する場合、同じ機能を実現できる他の方法を見つける必要があります。
  • hibernate-search-analyzers モジュールが削除されました。org.apache.lucene:lucene-analyzers-common などの適切な Lucene アーティファクトを直接使用する方法が推奨されます。
  • JMS コントロール API が変更になりました。他の ORM 環境で使用できるようにするため、Hibernate ORM の JMS バックエンド依存関係が削除されました。そのため、 org.hibernate.search.backend.impl.jms.AbstractJMSHibernateSearchController のインプリメンターを新しい署名に応じて調整する必要があります。このクラスは内部クラスで、拡張せずに例として使用することが推奨されます。
  • org.hibernate.search.spi.ServiceProvider SPI がリファクターされました。古いサービスコントラクトで統合している場合は、ServiceManager、 Service、 Startable、および Stoppable の Hibernate Search 5.5 Javadoc で新しいコントラクトの詳細を確認してください。
  • Lucene 3.x によって生成されたインデックスを保持し、これらのインデックスを Hibernate Search 5.0 以上で再構築していない場合、IndexFormatTooOldException が発生します。マスインデクサーでインデックスを再構築することが推奨されます。再構築できない場合は、ILucene の IndexUpgrader を使用してください。デフォルトの動作が変更になった場合があるため、注意して Hibernate Search のマッピングを更新する必要があります。詳細は Apache Lucene Migration Guide を参照してください。
  • JBoss EAP 7 では、Apache Lucene が 3.6 から 5.3 にアップグレードされました。ご使用のコードが 直接 Lucene のコードをインポートする場合は、Apache Lucene Migration Guide で変更の詳細を確認してください。Lucene Change Log にも追加の情報が記載されています。
  • @Field(indexNullAs=) を使用してインデックスの null マーカー値をエンコードする場合、同じフィールドでインデックス化されるその他の値すべてに適合するマーカーのタイプである必要があります。たとえば、これまでは文字列 null を使用して数字フィールドの null 値 をエンコードすることが可能でした。しかし、本リリースではこれができないようになりました。代わりに、-1 などの null 値を表す数字を選択する必要があります。
  • ファセッティングエンジンに大幅な改良が加えられました。多くの変更は API には影響しません。ファセッティングに使用する予定のフィールドすべてに @Facet または @Facets アノテーションを付ける必要があります。

Hibernate Search の名前変更および再パッケージされたクラス

以下は、名前変更または再パッケージされた Hibernate Search クラスのリストになります。

以前のパッケージおよびクラス新しいパッケージおよびクラス

org.hibernate.search.Environment

org.hibernate.search.cfg.Environment

org.hibernate.search.FullTextFilter

org.hibernate.search.filter.FullTextFilter

org.hibernate.search.ProjectionConstants

org.hibernate.search.engine.ProjectionConstants

org.hibernate.search.SearchException

org.hibernate.search.exception.SearchException

org.hibernate.search.Version

org.hibernate.search.engine.Version

Lucene - 名前変更および再パッケージされたクラス

クエリーパーサーが新しいモジュールに移動されたため、パッケージが org.apache.lucene.queryParser.QueryParser から org.apache.lucene.queryparser.classic.QueryParser に変更になりました。

Lucene アナライザーの多くがリファクターされたため、パッケージが変更になりました。Apache Lucene Documentation を参照してください。

TokenizerFactory や TokenFilterFactory などの Apache Solr ユーティリティークラスの一部が Apache Lucene に移動されました。これらのユーティリティーやカスタムアナライザーがアプリケーションによって使用される場合は、Apache Lucene で新パッケージ名を探す必要があります。

詳細は Apache Lucene Migration Guide を参照してください。

Hibernate Search で非推奨となった API

Hibernate Search で非推奨となったインターフェイス、クラス、列挙、アノテーションタイプ、メソッド、コンストラクター、および列挙定数の完全リストは、Hibernate Search Deprecated API を参照してください。

Hibernate Search で非推奨となったインターフェイス
インターフェイス説明

org.hibernate.search.store.IndexShardingStrategy

Hibernate Search 4.4 で非推奨となりました。Hibernate Search 5 で削除される可能性があります。代わりに ShardIdentifierProvider を使用してください。

org.hibernate.search.store.Workspace

このインターフェイスは移動され、パブリックでない API として考慮すべきです。詳細は、HSEARCH-1915 を参照してください。

Hibernate Search で非推奨となったクラス
クラス説明

org.hibernate.search.filter.FilterKey

カスタムフィルターキーは非推奨となり、Hibernate Search 6 で削除される予定です。Hibernate Search 5.1 では、Lucene フィルターをキャッシュするキーは指定のフィルターパラメーターを基に自動的に算出されます。

org.hibernate.search.filter.StandardFilterKey

カスタムフィルターキーは非推奨となり、Hibernate Search 6 で削除される予定です。Hibernate Search 5.1 では、Lucene フィルターをキャッシュするキーは指定のフィルターパラメーターを基に自動的に算出されます。

Hibernate Search で非推奨となった列挙
列挙説明

org.hibernate.search.annotations.FieldCacheType

非推奨となったため CacheFromIndex アノテーションを削除します。Hibernate Search で非推奨となったアノテーション を参照してください。

Hibernate Search で非推奨となったアノテーション
アノテーション説明

org.hibernate.search.annotations.CacheFromIndex

アノテーションを削除してください。代替は必要ありません。

org.hibernate.search.annotations.Key

カスタムフィルターキャッシュキーは非推奨機能となり、Hibernate Search 6 で削除される予定です。Hibernate Search 5.1 では、フィルターキャッシュキーはフィルターパラメーターを基に自動的に判断されるため、キーオブジェクトを提供する必要がなくなりました。

Hibernate Search で非推奨となったメソッド
方法説明

org.hibernate.search.FullTextSharedSessionBuilder.autoClose()

代替はありません。

org.hibernate.search.FullTextSharedSessionBuilder.autoClose(boolean)

代替はありません。

org.hibernate.search.cfg.IndexedMapping.cacheFromIndex(FieldCacheType…​)

今後削除される予定で、代替はありません。

org.hibernate.search.cfg.EntityDescriptor.getCacheInMemory()

今後削除される予定で、代替はありません。

org.hibernate.search.cfg.ContainedInMapping.numericField()

代わりに、field().numericField() を呼び出します。

org.hibernate.search.cfg.EntityDescriptor.setCacheInMemory(Map<String, Object>)

今後削除される予定で、代替はありません。

org.hibernate.search.MassIndexer.threadsForSubsequentFetching(int)

このメソッドは削除される予定です。

org.hibernate.search.query.dsl.FuzzyContext.withThreshold(float)

FuzzyContext.withEditDistanceUpTo(int) を使用します。

Hibernate Search で非推奨となったコンストラクター
コンストラクター説明

org.hibernate.search.cfg.NumericFieldMapping(PropertyDescriptor, EntityDescriptor, SearchMapping)

代わりに NumericFieldMapping.NumericFieldMapping(String, PropertyDescriptor, EntityDescriptor, SearchMapping) を使用します。

上級インテグレーターに影響する変更

ここでは、パブリック API の一部ではない変更について説明します。これらのアーティファクトは、Hibernate Search フレームワークを拡張するインテグレーターのみがアクセスできる必要があるため、通常の開発者には影響はないはずです。