Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

5.9. Hibernate 搜索更改

JBoss EAP 7 随附的 Hibernate Search 版本已有变化。之前的 JBoss EAP 版本随附了 Hibernate Search 4.6.x。JBoss EAP 7 随附 Hibernate Search 5.5.x。

Hibernate 搜索 5.5 基于 Apache Lucene 5.3.1 构建。如果您使用任何原生 Lucene API，请务必与这个版本一致。Hibernate Search 5.5 API 打包并隐藏了版本 3 和版本 5 之间进行的许多 Lucene API 更改的复杂性；但是，一些类现已弃用、重命名或重新打包。本节论述了这些更改会如何影响应用程序代码。

Hibernate 搜索映射更改

嵌入式关系的 id 字段索引

在使用 @IndexedEmbedded 注释来包含相关实体的字段时，相关实体的 id 不再包含在内。您可以使用 @Indexed Embedded 注释的 includeEmbeddedObjectId 属性来启用 id 包含。

示例： @IndexedEmbedded Annotation

@IndexedEmbedded(includeEmbeddedObjectId=true)

编号和日期索引格式变化

数字和日期现在默认作为数字字段索引。int、long、float 、 ual及其 对应的 wrapper 类的属性不再被索引为字符串。相反，它们现在使用 Lucene 的相应数字编码进行索引。id 字段是一个规则的例外。即使它们由数字类型表示，默认情况下它们仍然会作为字符串关键字进行索引。@NumericField 的使用现已过时，除非您要为数字编码指定自定义精确度。您可以通过显式指定字符串编码字段桥接来保留旧的基于字符串的索引格式。对于整数，这是 org.hibernate.search.bridge.builtin.IntegerBridge。检查 org.hibernate.search.bridge.builtin 软件包，以查找其他公开可用的字段网桥。

date 和 Calendar 不再作为字符串索引。相反，实例编码为长值，代表 1970 年 1 月 1 日的毫秒数，即 00:00:00。您可以使用新的 EncodingType 枚举来切换索引格式。例如：

示例： @DateBridge 和 @CalendarBridge Annotation

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

数字和日期的编码变化非常重要，可能会对应用程序行为产生重大影响。如果您的查询以之前字符串编码的字段为目标，但现在以数字编码，则必须更新查询。数字字段必须使用 NumericRangeQuery 进行搜索。您还必须确保通过_cot 为目标的所有字段都经过字符串编码。如果您使用 Search 查询 DSL，则会自动为您创建正确的查询。

其他 Hibernate 搜索更改

  • 排序选项有所改进，对于排序选项，字段编码会错误地指定，从而导致运行时异常。如果事先知道排序中使用的字段，Lucene 还提供了更高性能的排序。Hibernate Search 5.5 提供新的 @SortableField 注释及其多值配套 @SortableFields。如需更多信息，请参阅 Hibernate Search 5.4 到 5.5 的迁移指南。

  • Lucene SortField API 需要更改以下应用程序代码：

    在上一版本的 JBoss EAP 中，您将按照如下所示设置查询中的 sort 字段类型： 

    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。
  • enum 值 SpatialMode.GRID 被重命名为 SpatialMode.HASH。
  • FullTextIndexEventListener 现在是最终课程。如果您当前扩展了本课程，您必须找到达成相同功能的替代解决方案。
  • hibernate-search-analyzers 模块已被删除。建议的做法是直接使用适当的 Lucene 构件，如 org.apache.lucene:lucene-analyzers-common。
  • JMS 控制器 API 已经改变。删除了对 Hibernate ORM 的 JMS 后端依赖关系，以便它可以在其他非ORM 环境中使用。因此，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。建议您使用 massive indexer 重新构建索引。如果您无法做到这一点，请尝试使用 Lucene 的 IndexUpgrader。如果默认行为发生更改，您必须仔细更新 Hibernate Search 映射。如需更多信息，请参阅 Apache Lucene 迁移指南。
  • Apache Lucene 在 JBoss EAP 7 中已从 3.6 升级到 5.3。如果您的代码直接导入 Lucene 代码，请参阅 Apache Lucene 迁移指南以了解更改的详情。其他信息也可在 Lucene 更改日志中找到。
  • 使用 @Field(indexNullAs=) 对索引中的空标记值进行编码时，标记的类型必须与同一字段中索引的所有其他值兼容。例如，之前可以使用字符串"null"为数字字段编码空值。这已不再被允许。相反，您必须选择一个代表 null 值的数字，如 -1。
  • 对面市引擎进行了显著改进。大多数更改不会影响 API。个值得注意的例外是，您必须现在给计划用于遇到 @Facet 或 @Facet s 注释的任何字段添加注解。

Hibernate Search Renamed 和 Repackaged 类

以下是已重新打包或重命名的 Hibernate Search 类的列表。

Expand
以前的软件包和类新软件包和类

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.QueryParser 改为 org.apache.lucene.queryparser.classic.QueryParser。

许多 Lucene 分析器被重构，导致打包更改。请参阅 Apache Lucene 文档来查找替换软件包。

某些 Apache Solr 实用程序类（如 TokenizerFactory 或 TokenFilterFactory） 已移到 Apache Lucene 中。如果您的应用程序使用这些实用程序或自定义分析器，则必须在 Apache Lucene 中找到新软件包名称。

如需更多信息，请参阅 Apache Lucene 迁移指南。

Hibernate Search 弃用 API

有关 Hibernate Search 弃用接口、类、数字、注解类型、方法、构造器和枚举常量的完整列表，请参阅 Hibernate Search 弃用 API 文档。

Hibernate 搜索已弃用接口
Expand
Interface描述

org.hibernate.search.store.IndexShardingStrategy

自 Hibernate Search 4.4 弃用.可能会在搜索 5 中删除。改为使用 ShardIdentifierProvider。

org.hibernate.search.store.Workspace

此接口将被移动，并被视为非公共 API。如需更多信息，请参阅 HSEARCH-1915。

Hibernate 搜索已弃用的类
Expand
class描述

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 已弃用的枚举
Expand
enum描述

org.hibernate.search.annotations.FieldCacheType

删除 CacheFromIndex 注解，因为它已弃用。请参阅已弃用的 Hibernate 搜索注解。

Hibernate Search 已弃用注解
Expand
注解描述

org.hibernate.search.annotations.CacheFromIndex

删除注解。不需要替代。

org.hibernate.search.annotations.Key

自定义过滤器缓存键是已弃用的功能，计划在 Hibernate Search 6 中删除。自 Hibernate Search 5.1 起，过滤器缓存密钥根据过滤器参数自动确定，因此不再需要提供密钥对象。

Hibernate 搜索已弃用的方法
Expand
方法描述

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)

Use FuzzyContext.withEditDistanceUpTo(int).

Hibernate Search 已弃用的 Constructors
Expand
构造器描述

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

使用 NumericFieldMapping.NumericFieldMapping(String, RolesDescriptor, EntityDescriptor, SearchMapping) 代替。

影响高级集成商的更改

本节论述了不属于公共 API 一部分的更改。它们不应影响平均开发人员，因为这些构件应仅由扩展 Hibernate Search 框架的集成商访问。

Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2026 Red Hat返回顶部