GH-1459: Pollable Consumer and Requeue

Resolves https://github.com/spring-cloud/spring-cloud-stream/issues/1459

Add a mechanism to cause a requeue of the current message.

Polishing - PR Comments - simpler logic, no configuration needed.

Polishing

Resolves #1467

spring-cloud-stream-core-docs/src/main/asciidoc/spring-cloud-stream-overview.adoc

@@ -664,6 +664,8 @@ To do that Spring Cloud Function allows you to use `|` (pipe) symbol. So to fini
 [[spring-cloud-streams-overview-using-polled-consumers]]
 ==== Using Polled Consumers
 
+===== Overview
+
 When using polled consumers, you poll the `PollableMessageSource` on demand.
 Consider the following example of a polled consumer:
 
@@ -697,7 +699,7 @@ public ApplicationRunner poller(PollableMessageSource destIn, MessageChannel des
                 }
             }
             catch (Exception e) {
-                // handle failure (throw an exception to reject the message);
+                // handle failure
             }
         }
     };
@@ -710,7 +712,7 @@ It returns `true` if the message was received and successfully processed.
 As with message-driven consumers, if the `MessageHandler` throws an exception, messages are published to error channels, as discussed in "`<<binder-error-channels>>`".
 
 Normally, the `poll()` method acknowledges the message when the `MessageHandler` exits.
-If the method exits abnormally, the message is rejected (not re-queued).
+If the method exits abnormally, the message is rejected (not re-queued), but see <<polled-errors>>.
 You can override that behavior by taking responsibility for the acknowledgment, as shown in the following example:
 
 [source,java]
@@ -754,6 +756,17 @@ boolean result = pollableSource.poll(received -> {
 		}, new ParameterizedTypeReference<Map<String, Foo>>() {});
 ----
 
+[[polled-errors]]
+===== Handling Errors
+
+By default, an error channel is configured for the pollable source; if the callback throws an exception, an `ErrorMessage` is sent to the error channel (`<destination>.<group>.errors`); this error channel is also bridged to the global Spring Integration `errorChannel`.
+
+You can subscribe to either error channel with a `@ServiceActivator` to handle errors; without a subscription, the error will simply be logged and the message will be acknowledged as successful.
+If the error channel service activator throws an exception, the message will be rejected (by default) and won't be redelivered.
+If the service activator throws a `RequeueCurrentMessageException`, the message will be requeued at the broker and will be again retrieved on a subsequent poll.
+
+If the listener throws a `RequeueCurrentMessageException` directly, the message will be requeued, as discussed above, and will not be sent to the error channels.
+
 [[spring-cloud-stream-overview-error-handling]]
 === Error Handling