GH-615: Docs - Migrating Legacy Error Handlers

spring-kafka-docs/src/main/asciidoc/kafka.adoc

@@ -5058,6 +5058,8 @@ These error handlers can handle errors for both record and batch listeners, allo
 `CommonErrorHandler` implementations to replace most legacy framework error handler implementations are provided and the legacy error handlers deprecated.
 The legacy interfaces are still supported by listener containers and listener container factories; they will be deprecated in a future release.
 
+See <<migrating-legacy-eh>> for information to migrate custom error handlers to `CommonErrorHandler`.
+
 When transactions are being used, no error handlers are configured, by default, so that the exception will roll back the transaction.
 Error handling for transactional containers are handled by the <<after-rollback,`AfterRollbackProcessor`>>.
 If you provide a custom error handler when using transactions, it must throw an exception if you want the transaction rolled back.
@@ -5267,7 +5269,7 @@ By default, the exception type is not considered.
 Also see <<delivery-header>>.
 
 [[batch-listener-conv-errors]]
-===== Conversion Errors with Batch Error Handlers
+====== Conversion Errors with Batch Error Handlers
 
 Starting with version 2.8, batch listeners can now properly handle conversion errors, when using a `MessageConverter` with a `ByteArrayDeserializer`, a `BytesDeserializer` or a `StringDeserializer`, as well as a `DefaultErrorHandler`.
 When a conversion error occurs, the payload is set to null and a deserialization exception is added to the record headers, similar to the `ErrorHandlingDeserializer`.
@@ -5384,6 +5386,20 @@ If you wish to use a different error handling strategy for record and batch list
 |No replacements - use `DefaultErrorHandler` and throw an exception other than `BatchListenerFailedException`.
 |===
 
+[[migrating-legacy-eh]]
+====== Migrating Custom Legacy Error Handler Implementations to `CommonErrorHandler`
+
+Refer to the javadocs in `CommonErrorHandler`.
+
+To replace an `ErrorHandler` or `ConsumerAwareErrorHandler` implementation, you should implement `handleRecord()` and leave `remainingRecords()` to return `false` (default).
+You should also implement `handleOtherException()` - to handle exceptions that occur outside the scope of record processing (e.g. consumer errors).
+
+To replace a `RemainingRecordsErrorHandler` implementation, you should implement `handleRemaining()`  and override `remainingRecords()` to return `true`.
+You should also implement `handleOtherException()` - to handle exceptions that occur outside the scope of record processing (e.g. consumer errors).
+
+To replace any `BatchErrorHandler` implementation, you should implement `handleBatch()`
+You should also implement `handleOtherException()` - to handle exceptions that occur outside the scope of record processing (e.g. consumer errors).
+
 [[after-rollback]]
 ===== After-rollback Processor
 

spring-kafka-docs/src/main/asciidoc/whats-new.adoc

@@ -54,7 +54,7 @@ See <<kafka-template-receive>> for more information.
 ==== `CommonErrorHandler` Added
 
 The legacy `GenericErrorHandler` and its sub-interface hierarchies for record an batch listeners have been replaced by a new single interface `CommonErrorHandler` with implementations corresponding to most legacy implementations of `GenericErrorHandler`.
-See <<error-handlers>> for more information.
+See <<error-handlers>> and <<migrating-legacy-eh>> for more information.
 
 [[x28-lcc]]
 ==== Listener Container Changes
@@ -92,4 +92,4 @@ You can now use blocking and non-blocking retries in conjunction.
 See <<retry-topic-combine-blocking>> for more information.
 
 The KafkaBackOffException thrown when using the retryable topics feature is now logged at DEBUG level.
-See <<change-kboe-logging-level>> if you need to change the logging level back to WARN or set it to any other level.
+See <<change-kboe-logging-level>> if you need to change the logging level back to WARN or set it to any other level.