HSEARCH-3729 Give more information about failures to MassIndexer users

documentation/src/main/asciidoc/mapper-orm-indexing-massindexer.asciidoc

@@ -193,6 +193,25 @@ and passing an instance using the `monitor` method.
 +
 Implementations of `MassIndexingMonitor` must be threadsafe.
 
+|`failureHandler(MassIndexingFailureHandler)`
+|A failure handler.
+|
+The component responsible for handling failures occurring during mass indexing.
++
+A `MassIndexer` performs multiple operations in parallel,
+some of which can fail without stopping the whole mass indexing process.
+As a result, it may be necessary to trace individual failures.
+The default, built-in failure handler just forwards the failures
+to the global <<configuration-background-failure-handling,background failure handler>>,
+which by default will log them at the `ERROR` level,
+but a custom handler can be set by implementing the `MassIndexingFailureHandler` interface
+and passing an instance using the `failureHandler` method.
+This can be used to simply log failures in a context specific to the mass indexer,
+e.g. a web interface in a maintenance console from which mass indexing was requested,
+or for more advanced use cases, such as cancelling mass indexing on the first failure.
++
+Implementations of `MassIndexingFailureHandler` must be threadsafe.
+
 |===
 
 [[mapper-orm-indexing-massindexer-tuning]]

engine/src/main/java/org/hibernate/search/engine/reporting/FailureHandler.java

@@ -15,9 +15,6 @@
  * but it can be replaced with a custom implementations through
  * {@link org.hibernate.search.engine.cfg.EngineSettings#BACKGROUND_FAILURE_HANDLER a configuration property}.
  * <p>
- * Handlers should <strong>never</strong> throw any exception:
- * doing so will lead to undetermined behavior in Hibernate Search background threads.
- * <p>
  * Handlers can be called from multiple threads simultaneously: implementations must be thread-safe.
  *
  * @author Amin Mohammed-Coleman
@@ -31,8 +28,7 @@ public interface FailureHandler {
 	 * then return as quickly as possible.
 	 * Heavy error processing (sending emails, ...), if any, should be done asynchronously.
 	 * <p>
-	 * This method should <strong>never</strong> throw any exception:
-	 * doing so will lead to undetermined behavior in Hibernate Search background threads.
+	 * Any error or exception thrown by this method will be caught by Hibernate Search and logged.
 	 *
 	 * @param context Contextual information about the failure (throwable, operation, ...)
 	 */
@@ -45,8 +41,7 @@ public interface FailureHandler {
 	 * then return as quickly as possible.
 	 * Heavy error processing (sending emails, ...), if any, should be done asynchronously.
 	 * <p>
-	 * This method should <strong>never</strong> throw any exception:
-	 * doing so will lead to undetermined behavior in Hibernate Search background threads.
+	 * Any error or exception thrown by this method will be caught by Hibernate Search and logged.
 	 *
 	 * @param context Contextual information about the failure (throwable, operation, ...)
 	 */
@@ -59,8 +54,7 @@ public interface FailureHandler {
 	 * then return as quickly as possible.
 	 * Heavy error processing (sending emails, ...), if any, should be done asynchronously.
 	 * <p>
-	 * This method should <strong>never</strong> throw any exception:
-	 * doing so will lead to undetermined behavior in Hibernate Search background threads.
+	 * Any error or exception thrown by this method will be caught by Hibernate Search and logged.
 	 *
 	 * @param context Contextual information about the failure (throwable, operation, ...)
 	 */