Hibernate Search 中文操作指南

8. Configuration

8.1. Configuration sources

8.1.1. Configuration sources when integrating into Hibernate ORM

在 Hibernate ORM 中使用 Hibernate Search 时，配置属性会从 Hibernate ORM 中检索。

When using Hibernate Search within Hibernate ORM, configuration properties are retrieved from Hibernate ORM.

这意味着，只要您设置 Hibernate ORM 属性，均可设置 Hibernate Search 属性：

This means that wherever you set Hibernate ORM properties, you can set Hibernate Search properties:

In a hibernate.properties file at the root of your classpath.
In persistence.xml, if you bootstrap Hibernate ORM with the JPA APIs
In JVM system properties (-DmyProperty=myValue passed to the java command)
In the configuration file of your framework, for example application.yaml/application.properties.

通过框架的配置文件设置属性时，配置属性的键可能与本文档中提到的键不同。

When setting properties through the configuration file of your framework, the keys of configuration properties will likely be different from the keys mentioned in this documentation.

例如， hibernate.search.backend.hosts 将在 Quarkus 中变为 quarkus.hibernate-search-orm.elasticsearch.hosts ，在 Spring Boot 中变为 spring.jpa.properties.hibernate.search.backend.hosts 。

For example hibernate.search.backend.hosts will become quarkus.hibernate-search-orm.elasticsearch.hosts in Quarkus or spring.jpa.properties.hibernate.search.backend.hosts in Spring Boot.

有关详细信息，请参阅 Framework support 。

See Framework support for more information.

8.1.2. Configuration sources with the Standalone POJO mapper

在 Standalone POJO Mapper（不带 Hibernate ORM）的应用程序中使用 Hibernate Search 时，配置属性必须在构建映射时以编程方式设置。

When using Hibernate Search in the Standalone POJO Mapper (without Hibernate ORM), configuration properties must be set programmatically as you build the mapping.

有关更多信息，请参见 this section。

See this section for more information.

8.2. Configuration properties

8.2.1. Structure of configuration properties

所有配置属性都分在同一个根下。在 ORM 集成中，此根是 hibernate.search，但其他集成（Infinispan，……）可能使用其他根。此文档将在所有示例中使用 hibernate.search。

Configuration properties are all grouped under a common root. In the ORM integration, this root is hibernate.search, but other integrations (Infinispan, …) may use a different one. This documentation will use hibernate.search in all examples.

在此根下，我们可以区分三类属性。

Under that root, we can distinguish between three categories of properties.

Global properties

这些属性可能影响所有 Hibernate Search。它们通常位于 hibernate.search 根目录的正下方。

These properties potentially affect all Hibernate Search. They are generally located just under the hibernate.search root.

全局属性在本文档的相关部分进行了解释：

Global properties are explained in the relevant parts of this documentation:

Hibernate ORM integration

Standalone POJO Mapper

Mapping configuration

等等。

And many more.

Backend properties

这些属性影响后端。它们被分组在公共根目录下：

These properties affect a single backend. They are grouped under a common root:

hibernate.search.backend 表示默认后端（最常见的用法）。

hibernate.search.backend for the default backend (most common usage).

对于命名的后端（高级用法）： hibernate.search.backends.<backend-name>

hibernate.search.backends.<backend-name> for a named backend (advanced usage).

后端属性在文档的相关部分中进行了解释：

Backend properties are explained in the relevant parts of this documentation:

Lucene backend

Elasticsearch backend

Index properties

这些属性要么影响单个索引，要么影响多个索引，具体取决于根目录。

These properties affect either one or multiple indexes, depending on the root.

在根 hibernate.search.backend 中，它们为后端的全部索引设置默认值。

With the root hibernate.search.backend, they set defaults for all indexes of the backend.

在根 hibernate.search.backend.indexes.<index-name> 中，它们为特定索引设置值，覆盖默认值（如果有）。后端和索引名称必须与映射中定义的名称匹配。对于 Hibernate ORM 实体，默认索引名称是已编入索引类的名称，不带包：org.mycompany.Book 的默认索引名称为 Book。可以在映射中自定义索引名称。

With the root hibernate.search.backend.indexes.<index-name>, they set the value for a specific index, overriding the defaults (if any). The backend and index names must match the names defined in the mapping. For Hibernate ORM entities, the default index name is the name of the indexed class, without the package: org.mycompany.Book will have Book as its default index name. Index names can be customized in the mapping.

或者，也可以按名称引用后端，即，以上根也可以是 hibernate.search.backends.<backend-name> 或 hibernate.search.backends.<backend-name>.indexes.<index-name>。

Alternatively, the backend can also be referenced by name, i.e. the roots above can also be hibernate.search.backends.<backend-name> or hibernate.search.backends.<backend-name>.indexes.<index-name>.

示例：

Examples:

hibernate.search.backend.io.commit_interval = 500 为默认后端的全部索引设置 io.commit_interval 属性。

hibernate.search.backend.io.commit_interval = 500 sets the io.commit_interval property for all indexes of the default backend.

hibernate.search.backend.indexes.Product.io.commit_interval = 2000 为默认后端的 Product 索引设置 io.commit_interval 属性。

hibernate.search.backend.indexes.Product.io.commit_interval = 2000 sets the io.commit_interval property for the Product index of the default backend.

hibernate.search.backends.myBackend.io.commit_interval = 500 为后端 myBackend 的全部索引设置 io.commit_interval 属性。

hibernate.search.backends.myBackend.io.commit_interval = 500 sets the io.commit_interval property for all indexes of backend myBackend.

hibernate.search.backends.myBackend.indexes.Product.io.commit_interval = 2000 为后端 myBackend 的 Product 索引设置 io.commit_interval 属性。

hibernate.search.backends.myBackend.indexes.Product.io.commit_interval = 2000 sets the io.commit_interval property for the Product index of backend myBackend.

其他索引属性在文档的相关部分中进行了解释：

Other index properties are explained in the relevant parts of this documentation:

Lucene backend

Elasticsearch backend

8.2.2. Building property keys programmatically

BackendSettings 和 IndexSettings 均提供工具来帮助构建配置属性关键字。

Both BackendSettings and IndexSettings provide tools to help build the configuration property keys.

BackendSettings

BackendSettings.backendKey(ElasticsearchBackendSettings.HOSTS) 等效于 hibernate.search.backend.hosts。

BackendSettings.backendKey(ElasticsearchBackendSettings.HOSTS) is equivalent to hibernate.search.backend.hosts.

BackendSettings.backendKey("myBackend", ElasticsearchBackendSettings.HOSTS) 等效于 hibernate.search.backends.myBackend.hosts。

BackendSettings.backendKey("myBackend", ElasticsearchBackendSettings.HOSTS) is equivalent to hibernate.search.backends.myBackend.hosts.

有关可用属性键的列表，请参见 the Elasticsearch backend configuration properties appendix或 the Lucene backend configuration properties appendix。

For a list of available property keys, see the Elasticsearch backend configuration properties appendix or the Lucene backend configuration properties appendix.

IndexSettings

IndexSettings.indexKey("myIndex", ElasticsearchIndexSettings.INDEXING_QUEUE_SIZE) 等效于 hibernate.search.backend.indexes.myIndex.indexing.queue_size。

IndexSettings.indexKey("myIndex", ElasticsearchIndexSettings.INDEXING_QUEUE_SIZE) is equivalent to hibernate.search.backend.indexes.myIndex.indexing.queue_size.

IndexSettings.indexKey("myBackend", "myIndex", ElasticsearchIndexSettings.INDEXING_QUEUE_SIZE) 等效于 hibernate.search.backends.myBackend.indexes.myIndex.indexing.queue_size。

IndexSettings.indexKey("myBackend", "myIndex", ElasticsearchIndexSettings.INDEXING_QUEUE_SIZE) is equivalent to hibernate.search.backends.myBackend.indexes.myIndex.indexing.queue_size.

有关可用属性键的列表，请参见 the Elasticsearch backend configuration properties appendix或 the Lucene backend configuration properties appendix。查找其变型以 _hibernate.search.backend.indexes_开头的属性。

For a list of available property keys, see the Elasticsearch backend configuration properties appendix or the Lucene backend configuration properties appendix. Look for properties having a variant starting with a hibernate.search.backend.indexes.

示例 6. 使用该帮助器构建 Hibernate 配置

. Example 6. Using the helper to build hibernate configuration

private Properties buildHibernateConfiguration() {
    Properties config = new Properties();
    // backend configuration
    config.put( BackendSettings.backendKey( ElasticsearchBackendSettings.HOSTS ), "127.0.0.1:9200" );
    config.put( BackendSettings.backendKey( ElasticsearchBackendSettings.PROTOCOL ), "http" );
    // index configuration
    config.put(
            IndexSettings.indexKey( "myIndex", ElasticsearchIndexSettings.INDEXING_MAX_BULK_SIZE ),
            20
    );
    // orm configuration
    config.put(
            HibernateOrmMapperSettings.INDEXING_PLAN_SYNCHRONIZATION_STRATEGY,
            IndexingPlanSynchronizationStrategyNames.ASYNC
    );
    // engine configuration
    config.put( EngineSettings.BACKGROUND_FAILURE_HANDLER, "myFailureHandler" );
    return config;
}

8.2.3. Type of configuration properties

属性值可以以 Java 对象的形式以编程方式设置，也可以通过作为字符串的配置文件进行设置，该字符串将要被解析。

Property values can be set programmatically as Java objects, or through a configuration file as a string that will have to be parsed.

Hibernate Search 中的每个配置属性都有一个分配的类型，此类型定义了两种情况下的接受值。

Each configuration property in Hibernate Search has an assigned type, and this type defines the accepted values in both cases.

以下是全部属性类型的定义。

Here are the definitions of all property types.

Designation

Accepted Java objects

Accepted String format

String

java.lang.String

Any string

Boolean

java.lang.Boolean

true or false (case-insensitive)

Integer

java.lang.Number (will call .intValue())

Any string that can be parsed by Integer.parseInt

Long

java.lang.Number (will call .longValue())

Any string that can be parsed by Long.parseLong

Bean reference of type T

An instance of T or BeanReference or a reference by type as a java.lang.Class (see Bean references)

See Parsing of bean references

当上述任何类型的配置属性被记录为多值时，该属性接受以下内容：

When a configuration property of any type above is documented as multivalued, that property accepts either:

A java.util.Collection containing any Java object that would be accepted for a single-valued property of the same type (see above);
or a comma-separated string containing strings that would be accepted for a single-valued property of the same type (see above);
or a single Java object that would be accepted for a single-valued property of the same type (see above).

8.3. Configuration property checking

Hibernate Search 将跟踪实际使用的已提供配置的部分，并且如果以“hibernate.search.”开头的任何配置属性从未被使用，它将记录警告，因为这可能表明存在配置问题。

Hibernate Search will track the parts of the provided configuration that are actually used and will log a warning if any configuration property starting with "hibernate.search." is never used, because that might indicate a configuration issue.

要禁用此警告，将 hibernate.search.configuration_property_checking.strategy 属性设置为 ignore。

To disable this warning, set the hibernate.search.configuration_property_checking.strategy property to ignore.

8.4. Beans

Hibernate Search 允许插入对以下各个位置中自定义 bean 的引用：配置属性、映射注释、API 参数，…

Hibernate Search allows plugging in references to custom beans in various places: configuration properties, mapping annotations, arguments to APIs, …

本节介绍 the supported frameworks、 how to reference beans、 how the beans are resolved和 how the beans can get injected with other beans。

This section describes the supported frameworks, how to reference beans, how the beans are resolved and how the beans can get injected with other beans.

8.4.1. Supported frameworks

Supported frameworks when integrating into Hibernate ORM

在将 Hibernate Search 集成到 Hibernate ORM 中时，所有集成的到 Hibernate ORM 中的依赖注入框架也都会自动集成到 Hibernate Search 中。

When using the Hibernate Search integration into Hibernate ORM, all dependency injection frameworks integrated into Hibernate ORM are automatically integrated into Hibernate Search.

包括但不限于：

This includes, but may not be limited to:

all CDI-compliant frameworks, including WildFly and Quarkus;
the Spring framework.

如果不使用依赖项注入框架，或者未将其集成到 Hibernate ORM 中，则只能通过调用所引用类型的公用无参数构造函数来使用反射来检索 Bean；参见 Bean resolution。

When not using a dependency injection framework, or when it is not integrated into Hibernate ORM, beans can only be retrieved using reflection by calling the public, no-arg constructor of the referenced type; see Bean resolution.

Supported frameworks when using the Standalone POJO Mapper

使用 Standalone POJO Mapper时，必须 plugged in manually依赖项注入支持。

When using the Standalone POJO Mapper dependency injection support must be plugged in manually.

如果没有，则只能通过调用所引用类型的公用无参数构造函数来使用反射来检索 Bean；参见 Bean resolution。

Failing that, beans can only be retrieved using reflection by calling the public, no-arg constructor of the referenced type; see Bean resolution.

8.4.2. Bean references

Bean 引用由两部分组成：

Bean references are composed of two parts:

The type, i.e. a java.lang.Class.
Optionally, the name, as a String.

在使用配置属性中的字符串值引用 bean 时，类型会隐式设置为 Hibernate Search 对该配置属性预期的任何接口。

When referencing beans using a string value in configuration properties, the type is implicitly set to whatever interface Hibernate Search expects for that configuration property.

对于有经验的用户而言，Hibernate Search 还提供 org.hibernate.search.engine.environment.bean.BeanReference 类型，在配置属性和 API 中会接受该类型。此接口允许插入自定义实例化并清理代码。请参阅此接口的 javadoc 了解详情。

For experienced users, Hibernate Search also provides the org.hibernate.search.engine.environment.bean.BeanReference type, which is accepted in configuration properties and APIs. This interface allows plugging in custom instantiation and cleanup code. See the javadoc of this interface for details.

8.4.3. Parsing of bean references

在使用配置属性中的字符串值引用 bean 时，解析该字符串。

When referencing beans using a string value in configuration properties, that string is parsed.

以下是常见的格式：

Here are the most common formats:

bean: followed by the name of a Spring or CDI bean. For example bean:myBean.
class: followed by the fully-qualified name of a class, to be instantiated through Spring/CDI if available, or through its public, no-argument constructor otherwise. For example class:com.mycompany.MyClass.
An arbitrary string that doesn’t contain a colon: it will be interpreted as explained in Bean resolution. In short:

首先，查找具有给定名称的内置 bean；

first, look for a built-in bean with the given name;

然后，尝试从 Spring/CDI（如果可用）中检索具有给定名称的 bean；

then try to retrieve a bean with the given name from Spring/CDI (if available);

再尝试将字符串解释为完全限定类名，并从 Spring/CDI（如果可用）中检索相应的 bean；

then try to interpret the string as a fully-qualified class name and to retrieve the corresponding bean from Spring/CDI (if available);

最后尝试将字符串解释为完全限定类名并通过其公共，无参数构造函数对其进行实例化。

then try to interpret the string as a fully-qualified class name and to instantiate it through its public, no-argument constructor.

first, look for a built-in bean with the given name;
then try to retrieve a bean with the given name from Spring/CDI (if available);
then try to interpret the string as a fully-qualified class name and to retrieve the corresponding bean from Spring/CDI (if available);
then try to interpret the string as a fully-qualified class name and to instantiate it through its public, no-argument constructor.

还接受以下格式，但仅对高级用例有用：

The following formats are also accepted, but are only useful for advanced use cases:

any: followed by an arbitrary string. Equivalent to leaving out the prefix in most cases. Only useful if the arbitrary string contains a colon.
builtin: followed by the name of a built-in bean, e.g. simple for the Elasticsearch index layout strategies. This will not fall back to Spring/CDI or a direct constructor call.
constructor: followed by the fully-qualified name of a class, to be instantiated through its public, no-argument constructor. This will ignore built-in beans and will not try to instantiate the class through Spring/CDI.

8.4.4. Bean resolution

Bean 解析（即，将此引用转换为对象实例的过程）在默认情况下按如下方式进行：

Bean resolution (i.e. the process of turning this reference into an object instance) happens as follows by default:

If the given reference matches a built-in bean, that bean is used.

示例：作为属性 hibernate.search.backend.layout.strategy_的值来配置 Elasticsearch index layout strategy时使用的名称 _simple，解析为内置 _simple_策略。

Example: the name simple, when used as the value of the property hibernate.search.backend.layout.strategy to configure the Elasticsearch index layout strategy, resolves to the built-in simple strategy.

Otherwise, if a supported Dependency Injection (DI) framework is available, the reference is resolved using the DI framework.

如果存在具有给定类型（如果已提供，则要有名称）的受管 bean，则使用该 bean。

If a managed bean with the given type (and if provided, name) exists, that bean is used.

示例：作为属性 hibernate.search.backend.layout.strategy_的值来配置 Elasticsearch index layout strategy时使用的名称 _myLayoutStrategy，解析为类型为 _IndexLayoutStrategy_并带有 _@Named("myLayoutStrategy")_注释的来自 CDI/Spring 的任何 Bean。

Example: the name myLayoutStrategy, when used as the value of the property hibernate.search.backend.layout.strategy to configure the Elasticsearch index layout strategy, resolves to any bean known from CDI/Spring of type IndexLayoutStrategy and annotated with @Named("myLayoutStrategy").

否则，如果给定了名称，并且该名称是完全限定的类名以及存在该类型的受管 bean，则使用该 bean。

Otherwise, if a name is given, and that name is a fully-qualified class name, and a managed bean of that type exists, that bean is used.

示例：作为属性 hibernate.search.backend.layout.strategy_的值来配置 Elasticsearch index layout strategy时使用的名称 _com.mycompany.MyLayoutStrategy，解析为来自 CDI/Spring 的任何 Bean 并扩展 com.mycompany.MyLayoutStrategy。

Example: the name com.mycompany.MyLayoutStrategy, when used as the value of the property hibernate.search.backend.layout.strategy to configure the Elasticsearch index layout strategy, resolves to any bean known from CDI/Spring and extending com.mycompany.MyLayoutStrategy.

If a managed bean with the given type (and if provided, name) exists, that bean is used.

Otherwise, if a name is given, and that name is a fully-qualified class name, and a managed bean of that type exists, that bean is used.

Otherwise, reflection is used to resolve the bean.

如果给定了名称，并且该名称是完全限定的类名以及该类扩展了类型引用，则通过调用该类的公有无参数构造函数来创建一个实例。

If a name is given, and that name is a fully-qualified class name, and that class extends the type reference, an instance is created by invoking the public, no-argument constructor of that class.

示例：作为属性 hibernate.search.backend.layout.strategy_的值来配置 Elasticsearch index layout strategy时使用的名称 _com.mycompany.MyLayoutStrategy，解析为 _com.mycompany.MyLayoutStrategy_的一个实例。

如果未给定名称，则通过调用所引用类型的公有无参数构造函数来创建一个实例。

If no name is given, an instance is created by invoking the public, no-argument constructor of the referenced type.

示例：作为属性 hibernate.search.backend.layout.strategy_的值来配置 Elasticsearch index layout strategy时使用的类 _com.mycompany.MyLayoutStrategy.class（一个 java.lang.Class，不是一个 String），解析为 _com.mycompany.MyLayoutStrategy_的一个实例。

Example: the class com.mycompany.MyLayoutStrategy.class (a java.lang.Class, not a String), when used as the value of the property hibernate.search.backend.layout.strategy to configure the Elasticsearch index layout strategy, resolves to an instance of com.mycompany.MyLayoutStrategy.

If a name is given, and that name is a fully-qualified class name, and that class extends the type reference, an instance is created by invoking the public, no-argument constructor of that class.

If no name is given, an instance is created by invoking the public, no-argument constructor of the referenced type.

可以通过选择 _BeanRetrieval_进行更精细的 bean 检索控制；有关详细信息，请参见 _org.hibernate.search.engine.environment.bean.BeanRetrieval_的说明文档。另请参阅 Parsing of bean references来了解允许在配置属性中引用 bean 时指定 bean 检索的前缀。

It is possible to control bean retrieval more finely by selecting a BeanRetrieval; see the javadoc of org.hibernate.search.engine.environment.bean.BeanRetrieval for more information. See also Parsing of bean references for the prefixes that allow to specify the bean retrieval when referencing a bean from configuration properties.

8.4.5. Bean injection

所有 Bean resolved by Hibernate Search使用 supported framework都可以利用此框架的注入功能。

All beans resolved by Hibernate Search using a supported framework can take advantage of injection features of this framework.

例如，可以在网桥中的某个字段带 @Inject 注释以注入另一个 bean。

For example a bean can be injected with another bean by annotating one of its fields in the bridge with @Inject.

像 @PostConstruct 这样的生命周期注释也应该按预期工作。

Lifecycle annotations such as @PostConstruct should also work as expected.

即使没有使用任何框架，也可以利用 BeanResolver 的优势。此组件在引导期间传递给多个方法，公开多种方法用于 resolve 将引用插入 bean，以编程方式公开通常通过 @Inject 注释实现的功能。有关详细信息，请参见 BeanResolver 的 javadoc。

Even when not using any framework, it is still possible to take advantage of the BeanResolver. This component, passed to several methods during bootstrap, exposes several methods to resolve a reference into a bean, exposing programmatically what would usually be achieved with an @Inject annotation. See the javadoc of BeanResolver for more information.

8.4.6. Bean lifecycle

一旦不再需要 Bean，Hibernate Search 就会释放它们并让依赖注入框架调用适当的方法（@PreDestroy，…）。

As soon as beans are no longer needed, Hibernate Search will release them and let the dependency injection framework call the appropriate methods (@PreDestroy, …).

有些 Bean 只有在引导期间才需要，例如 ElasticsearchAnalysisConfigurer，因此它们会在引导后立即释放。

Some beans are only necessary during bootstrap, such as _ElasticsearchAnalysisConfigurer_s, so they will be released just after bootstrap.

其他 Bean 在运行时需要，例如 ValueBridge，因此它们会在关闭时释放。

Other beans are necessary at runtime, such as _ValueBridge_s, so they will be released on shutdown.

请务必根据适当的方式定义 bean 的范围。

Be careful to define the scope of your beans as appropriate.

不可变 bean 或仅使用一次的 bean（例如 ElasticsearchAnalysisConfigurer ）可以安全地分配任何范围。

Immutable beans or beans used only once such as ElasticsearchAnalysisConfigurer may be safely assigned any scope.

但是，某些 bean 预计是可变的并且会被多次实例化，例如 PropertyBinder 。对于这些 bean，建议使用“dependent”范围（CDI 术语）或“prototype”范围（Spring 术语）。如果有疑问，这也是注入到 Hibernate Search 中的 bean 的最安全选择。

However, some beans are expected to be mutable and instantiated multiple times, such as for example PropertyBinder. For these beans, it is recommended to use the "dependent" scope (CDI terminology) or the "prototype" scope (Spring terminology). When in doubt, this is also generally the safest choice for beans injected into Hibernate Search.

使用 supported framework 的 Bean resolved by Hibernate Search 可以利用此框架的注入功能。

Beans resolved by Hibernate Search using a supported framework can take advantage of injection features of this framework.

8.5. Global configuration

本节介绍了适用于所有 mappers 和 backends 的全局配置。

This section presents global configuration, common to all mappers and backends.

8.5.1. Background failure handling

Hibernate Search 通常将后台线程中发生的异常传播到用户线程，但在某些情况下，例如 Lucene 段合并失败，或 some indexing plan synchronization failures，后台线程中的异常无法传播。默认情况下，当发生这种情况时，将以 ERROR 级别记录失败。

Hibernate Search generally propagates exceptions occurring in background threads to the user thread, but in some cases, such as Lucene segment merging failures, or some indexing plan synchronization failures, the exception in background threads cannot be propagated. By default, when that happens, the failure is logged at the ERROR level.

要自定义后台故障处理，你需要：

To customize background failure handling, you will need to:

Define a class that implements the org.hibernate.search.engine.reporting.FailureHandler interface.
Configure the backend to use that implementation by setting the configuration property hibernate.search.background_failure_handler to a bean reference pointing to the implementation, for example class:com.mycompany.MyFailureHandler.

每当发生故障时，Hibernate Search 都会调用 handle 方法。

Hibernate Search will call the handle methods whenever a failure occurs.

示例 7. 实现和使用 FailureHandler

. Example 7. Implementing and using a FailureHandler

package org.hibernate.search.documentation.reporting.failurehandler;

import org.hibernate.search.engine.common.EntityReference;
import org.hibernate.search.engine.reporting.EntityIndexingFailureContext;
import org.hibernate.search.engine.reporting.FailureContext;
import org.hibernate.search.engine.reporting.FailureHandler;
import org.hibernate.search.util.impl.test.extension.StaticCounters;

public class MyFailureHandler implements FailureHandler {

    @Override
    public void handle(FailureContext context) { (1)
        String failingOperationDescription = context.failingOperation().toString(); (2)
        Throwable throwable = context.throwable(); (3)

        // ... report the failure ... (4)
    }

    @Override
    public void handle(EntityIndexingFailureContext context) { (5)
        String failingOperationDescription = context.failingOperation().toString();
        Throwable throwable = context.throwable();
        for ( EntityReference entityReference : context.failingEntityReferences() ) { (6)
            Class<?> entityType = entityReference.type(); (7)
            String entityName = entityReference.name(); (7)
            Object entityId = entityReference.id(); (7)
            String entityReferenceAsString = entityReference.toString(); (8)

            // ... process the entity reference ... (9)
        }
    }

}

hibernate.search.background_failure_handler = class:org.hibernate.search.documentation.reporting.failurehandler.MyFailureHandler

当某个故障处理程序的 handle 方法抛出错误或异常时，Hibernate Search 会捕获它并以 ERROR 级别对其进行记录。它不会传播出去。

When a failure handler’s handle method throws an error or exception, Hibernate Search will catch it and log it at the ERROR level. It will not be propagated.

8.5.2. Multi-tenancy

如果您的应用程序使用了 Hibernate ORM 的 multi-tenancy support，或者如果您 configured multi-tenancy explicitly in the Standalone POJO Mapper，Hibernate Search 应该检测到该应用程序并透明地配置您的后端。有关详细信息，请参见：

If your application uses Hibernate ORM’s multi-tenancy support, or if you configured multi-tenancy explicitly in the Standalone POJO Mapper, Hibernate Search should detect that and configure your backends transparently. For details, see:

here for Lucene
here for Elasticsearch

在某些情况下，特别是当 using the outbox-polling coordination strategy 或预期 mass indexer to implicitly target all tenants 时，您需要明确列出应用程序可能使用的所有租户标识符。当生成应将操作应用于每个租户的后台进程时，Hibernate Search 会使用此信息。

In some cases, in particular when using the outbox-polling coordination strategy or when expecting the mass indexer to implicitly target all tenants, you will need to list explicitly all tenant identifiers that your application might use. This information is used by Hibernate Search when spawning background processes that should apply an operation to every tenant.

标识符列表通过以下配置属性定义：

The list of identifiers is defined through the following configuration property:

hibernate.search.multi_tenancy.tenant_ids = mytenant1,mytenant2,mytenant3

此属性可以设置为包含多个用逗号分隔的租户标识符的字符串，或者包含租户标识符的 Collection<String>。

This property may be set to a String containing multiple tenant identifiers separated by commas, or a Collection<String> containing tenant identifiers.