Address initial review comments

examples/pom.xml

@@ -20,6 +20,7 @@
         <module>powertools-examples-parameters</module>
         <module>powertools-examples-serialization</module>
         <module>powertools-examples-sqs</module>
+        <module>powertools-examples-batch</module>
         <module>powertools-examples-validation</module>
         <module>powertools-examples-cloudformation</module>
     </modules>

examples/powertools-examples-batch/pom.xml

@@ -44,6 +44,16 @@
             <artifactId>sdk-core</artifactId>
             <version>${sdk.version}</version>
         </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>sqs</artifactId>
+            <version>${sdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>url-connection-client</artifactId>
+            <version>${sdk.version}</version>
+        </dependency>
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
             <artifactId>dynamodb-enhanced</artifactId>

examples/powertools-examples-batch/src/main/java/org/demo/batch/dynamo/DynamoDBStreamBatchHandler.java

@@ -26,12 +26,9 @@ private void processMessage(DynamodbEvent.DynamodbStreamRecord dynamodbStreamRec
     }
 
     @Override
-    public StreamsEventResponse handleRequest(DynamodbEvent kinesisEvent, Context context) {
-        return handler.processBatch(kinesisEvent, context);
+    public StreamsEventResponse handleRequest(DynamodbEvent ddbEvent, Context context) {
+        return handler.processBatch(ddbEvent, context);
     }
 
-    private void processMessage(Product p, Context c) {
-        LOGGER.info("Processing product " + p);
-    }
 
 }

examples/powertools-examples-batch/src/main/java/org/demo/batch/kinesis/KinesisBatchSender.java

@@ -26,6 +26,12 @@
 
 import static java.util.stream.Collectors.toList;
 
+
+/**
+ * A Lambda handler used to send message batches to Kinesis Streams. This is only here
+ * to produce an end-to-end demo, so that the {{@link org.demo.batch.kinesis.KinesisBatchHandler}}
+ * has some data to consume.
+ */
 public class KinesisBatchSender implements RequestHandler<ScheduledEvent, String> {
 
     private static final Logger LOGGER = LogManager.getLogger(KinesisBatchSender.class);

examples/powertools-examples-batch/src/main/java/org/demo/batch/sqs/SqsBatchSender.java

@@ -21,6 +21,11 @@
 import static java.util.stream.Collectors.toList;
 
 
+/**
+ * A Lambda handler used to send message batches to SQS. This is only here
+ * to produce an end-to-end demo, so that the {{@link org.demo.batch.sqs.SqsBatchHandler}}
+ * has some data to consume.
+ */
 public class SqsBatchSender implements RequestHandler<ScheduledEvent, String> {
 
     private static final Logger LOGGER = LogManager.getLogger(SqsBatchSender.class);

pom.xml

@@ -39,9 +39,8 @@
         <module>powertools-cloudformation</module>
         <module>powertools-idempotency</module>
         <module>powertools-e2e-tests</module>
-        <module>examples</module>
         <module>powertools-batch</module>
-        <module>examples/powertools-examples-batch</module>
+        <module>examples</module>
     </modules>
 
     <scm>

powertools-batch/pom.xml

@@ -24,11 +24,6 @@
             <artifactId>powertools-serialization</artifactId>
             <version>${project.version}</version>
         </dependency>
-        <dependency>
-            <groupId>software.amazon.lambda</groupId>
-            <artifactId>powertools-idempotency</artifactId>
-            <version>${project.version}</version>
-        </dependency>
         <dependency>
             <groupId>org.aspectj</groupId>
             <artifactId>aspectjrt</artifactId>
@@ -61,10 +56,6 @@
             <artifactId>mockito-inline</artifactId>
             <scope>test</scope>
         </dependency>
-        <dependency>
-            <groupId>software.amazon.lambda</groupId>
-            <artifactId>powertools-sqs</artifactId>
-        </dependency>
     </dependencies>
 
 </project>

powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/BatchMessageHandlerBuilder.java

@@ -3,9 +3,13 @@
 import software.amazon.lambda.powertools.batch.builder.*;
 
 /**
- * A builder-style interface we can use within an existing Lambda RequestHandler to
- * deal with our batch responses. A second tier of builders is returned per-event-source
- * to bind the appropriate message types and provider source-specific logic and tuneables.
+ * A builder-style interface we can use to build batch processing handlers for SQS, Kinesis Streams,
+ * and DynamoDB Streams batches. The batch processing handlers that are returned allow
+ * the user to easily process batches of messages, one-by-one, while offloading
+ * the common issues - failure handling, partial responses, deserialization -
+ * to the library.
+ *
+ * @see <a href="https://docs.powertools.aws.dev/lambda/java/utilities/batch/">Powertools for AWS Lambda (Java) Batch Documentation</a>
  **/
 public class BatchMessageHandlerBuilder {
 
@@ -23,8 +27,8 @@ public SqsBatchMessageHandlerBuilder withSqsBatchHandler() {
      *
      * @return A fluent builder interface to continue the building
      */
-    public DdbBatchMessageHandlerBuilder withDynamoDbBatchHandler() {
-        return new DdbBatchMessageHandlerBuilder();
+    public DynamoDbBatchMessageHandlerBuilder withDynamoDbBatchHandler() {
+        return new DynamoDbBatchMessageHandlerBuilder();
     }
 
     /**

powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/builder/AbstractBatchMessageHandlerBuilder.java

@@ -25,9 +25,10 @@ abstract class AbstractBatchMessageHandlerBuilder<T, C, E, R> {
     protected Consumer<T> successHandler;
 
     /**
-     * Provides a success handler. A success handler is invoked once for
-     * each message after it has been processed by the user-provided
+     * Provides an (Optional!) success handler. A success handler is invoked
+     * once for each message after it has been processed by the user-provided
      * handler.
+     *
      * If the success handler throws, the item in the batch will be
      * marked failed.
      *
@@ -39,9 +40,16 @@ public C withSuccessHandler(Consumer<T> handler) {
     }
 
     /**
-     * Provides a failure handler. A failure handler is invoked once
-     * for each message after it has failed to be processed by the
-     * user-provided handler.
+     * Provides an (Optional!) failure handler. A failure handler is invoked
+     * once for each message after it has failed to be processed by the
+     * user-provided handler. This gives the user's code a useful hook to do
+     * anything else that might have to be done in response to a failure - for
+     * instance, updating a metric, or writing a detailed log.
+     *
+     * Please note that this method has nothing to do with the partial batch
+     * failure mechanism. Regardless of whether a failure handler is
+     * specified, partial batch failures and responses to the Lambda environment
+     * are handled by the batch utility separately.
      *
      * @param handler The handler to invoke on failure
      */
@@ -53,21 +61,28 @@ public C withFailureHandler(BiConsumer<T, Throwable> handler) {
     /**
      * Builds a BatchMessageHandler that can be used to process batches, given
      * a user-defined handler to process each item in the batch. This variant
-     * takes a function that consumes a raw message and the Lambda context.
+     * takes a function that consumes a raw message and the Lambda context. This
+     * is useful for handlers that need access to the entire message object, not
+     * just the deserialized contents of the body.
+     *
      * Note:  If you don't need the Lambda context, use the variant of this function
      * that does not require it.
      *
-     * @param handler Takes a raw message - the AWS-SDK-shaped inner type of the batch - to process
+     * @param handler Takes a raw message - the underlying AWS Events Library event - to process.
+     *                  For instance for SQS this would be an SQSMessage.
      * @return A BatchMessageHandler for processing the batch
      */
     public abstract BatchMessageHandler<E, R> buildWithRawMessageHandler(BiConsumer<T, Context> handler);
 
     /**
      * Builds a BatchMessageHandler that can be used to process batches, given
      * a user-defined handler to process each item in the batch. This variant
-     * takes a function that consumes a raw message.
+     * takes a function that consumes a raw message and the Lambda context. This
+     * is useful for handlers that need access to the entire message object, not
+     * just the deserialized contents of the body.
      *
-     * @param handler Takes a raw message - the AWS-SDK-shaped inner type of the batch - to process
+     * @param handler Takes a raw message - the underlying AWS Events Library event - to process.
+     *                  For instance for SQS this would be an SQSMessage.
      * @return A BatchMessageHandler for processing the batch
      */
     public BatchMessageHandler<E, R> buildWithRawMessageHandler(Consumer<T> handler) {

powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/builder/DdbBatchMessageHandlerBuilder.java → powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/builder/DynamoDbBatchMessageHandlerBuilder.java

@@ -5,19 +5,22 @@
 import com.amazonaws.services.lambda.runtime.events.StreamsEventResponse;
 import software.amazon.lambda.powertools.batch.exception.DeserializationNotSupportedException;
 import software.amazon.lambda.powertools.batch.handler.BatchMessageHandler;
-import software.amazon.lambda.powertools.batch.handler.DdbBatchMessageHandler;
+import software.amazon.lambda.powertools.batch.handler.DynamoDbBatchMessageHandler;
 
 import java.util.function.BiConsumer;
 
-public class DdbBatchMessageHandlerBuilder extends AbstractBatchMessageHandlerBuilder<DynamodbEvent.DynamodbStreamRecord,
-        DdbBatchMessageHandlerBuilder,
+/**
+ * Builds a batch processor for processing DynamoDB Streams batch events
+ **/
+public class DynamoDbBatchMessageHandlerBuilder extends AbstractBatchMessageHandlerBuilder<DynamodbEvent.DynamodbStreamRecord,
+        DynamoDbBatchMessageHandlerBuilder,
         DynamodbEvent,
         StreamsEventResponse> {
 
 
     @Override
     public BatchMessageHandler<DynamodbEvent, StreamsEventResponse> buildWithRawMessageHandler(BiConsumer<DynamodbEvent.DynamodbStreamRecord, Context> rawMessageHandler) {
-        return new DdbBatchMessageHandler(
+        return new DynamoDbBatchMessageHandler(
                 this.successHandler,
                 this.failureHandler,
                 rawMessageHandler);
@@ -30,7 +33,7 @@ public <M> BatchMessageHandler<DynamodbEvent, StreamsEventResponse> buildWithMes
     }
 
     @Override
-    protected DdbBatchMessageHandlerBuilder getThis() {
+    protected DynamoDbBatchMessageHandlerBuilder getThis() {
         return this;
     }
 }

powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/builder/KinesisBatchMessageHandlerBuilder.java

@@ -8,6 +8,9 @@
 
 import java.util.function.BiConsumer;
 
+/**
+ * Builds a batch processor for processing Kinesis Streams batch events
+ */
 public class KinesisBatchMessageHandlerBuilder extends AbstractBatchMessageHandlerBuilder<KinesisEvent.KinesisEventRecord,
         KinesisBatchMessageHandlerBuilder,
         KinesisEvent,

powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/exception/DeserializationNotSupportedException.java

@@ -1,5 +1,10 @@
 package software.amazon.lambda.powertools.batch.exception;
 
+/**
+ * Thrown by message handlers that do not support deserializing arbitrary payload
+ * contents. This is the case for instance with DynamoDB Streams, which stream
+ * changesets about user-defined data, but not the user-defined data models themselves.
+ */
 public class DeserializationNotSupportedException extends RuntimeException {
 
     public DeserializationNotSupportedException() {

powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/handler/DdbBatchMessageHandler.java → powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/handler/DynamoDbBatchMessageHandler.java

@@ -11,14 +11,20 @@
 import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
-public class DdbBatchMessageHandler implements BatchMessageHandler<DynamodbEvent, StreamsEventResponse>{
-    Logger LOGGER = LoggerFactory.getLogger(DdbBatchMessageHandler.class);
+/**
+ * A batch message processor for DynamoDB Streams batches.
+ *
+ * @see <a href="https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html#services-ddb-batchfailurereporting">DynamoDB Streams batch failure reporting</a>
+ *
+ */
+public class DynamoDbBatchMessageHandler implements BatchMessageHandler<DynamodbEvent, StreamsEventResponse>{
+    private final static Logger LOGGER = LoggerFactory.getLogger(DynamoDbBatchMessageHandler.class);
 
     private final Consumer<DynamodbEvent.DynamodbStreamRecord> successHandler;
     private final BiConsumer<DynamodbEvent.DynamodbStreamRecord, Throwable> failureHandler;
     private final BiConsumer<DynamodbEvent.DynamodbStreamRecord, Context> rawMessageHandler;
 
-    public DdbBatchMessageHandler(Consumer<DynamodbEvent.DynamodbStreamRecord> successHandler, BiConsumer<DynamodbEvent.DynamodbStreamRecord, Throwable> failureHandler, BiConsumer<DynamodbEvent.DynamodbStreamRecord, Context> rawMessageHandler) {
+    public DynamoDbBatchMessageHandler(Consumer<DynamodbEvent.DynamodbStreamRecord> successHandler, BiConsumer<DynamodbEvent.DynamodbStreamRecord, Throwable> failureHandler, BiConsumer<DynamodbEvent.DynamodbStreamRecord, Context> rawMessageHandler) {
         this.successHandler = successHandler;
         this.failureHandler = failureHandler;
         this.rawMessageHandler = rawMessageHandler;

powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/handler/KinesisStreamsBatchMessageHandler.java

@@ -14,13 +14,13 @@
 import java.util.function.Consumer;
 
 /**
- * A batch message handler for Kinesis Streams batch processing.
+ * A batch message processor for Kinesis Streams batch processing.
  *
- * Refer to <a href="https://docs.aws.amazon.com/lambda/latest/dg/with-kinesis.html#services-kinesis-batchfailurereporting">The kinesis batch processing document</a>
- * @param <M>
+ * Refer to <a href="https://docs.aws.amazon.com/lambda/latest/dg/with-kinesis.html#services-kinesis-batchfailurereporting">Kinesis Batch failure reporting</a>
+ * @param <M> The user-defined type of the Kinesis record payload
  */
 public class KinesisStreamsBatchMessageHandler <M> implements BatchMessageHandler<KinesisEvent, StreamsEventResponse> {
-    Logger LOGGER = LoggerFactory.getLogger(KinesisStreamsBatchMessageHandler.class);
+    private final static Logger LOGGER = LoggerFactory.getLogger(KinesisStreamsBatchMessageHandler.class);
 
     private final BiConsumer<KinesisEvent.KinesisEventRecord, Context> rawMessageHandler;
     private final BiConsumer<M, Context> messageHandler;

powertools-batch/src/main/java/software/amazon/lambda/powertools/batch/handler/SqsBatchMessageHandler.java

@@ -11,14 +11,20 @@
 import java.util.function.BiConsumer;
 import java.util.function.Consumer;
 
+/**
+ * A batch message processor for SQS batches.
+ *
+ * @see <a href="https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html#services-sqs-batchfailurereporting">SQS Batch failure reporting</a>
+ * @param <M> The user-defined type of the message payload
+ */
 public class SqsBatchMessageHandler <M> implements BatchMessageHandler<SQSEvent, SQSBatchResponse> {
-    private final Class<M> messageClass;
-    Logger LOGGER = LoggerFactory.getLogger(SqsBatchMessageHandler.class);
+    private final static Logger LOGGER = LoggerFactory.getLogger(SqsBatchMessageHandler.class);
 
     // The attribute on an SQS-FIFO message used to record the message group ID
     // https://docs.aws.amazon.com/lambda/latest/dg/with-sqs.html#sample-fifo-queues-message-event
-    String MESSAGE_GROUP_ID_KEY = "MessageGroupId";
+    private final static String MESSAGE_GROUP_ID_KEY = "MessageGroupId";
 
+    private final Class<M> messageClass;
     private final BiConsumer<M, Context> messageHandler;
     private final BiConsumer<SQSEvent.SQSMessage, Context> rawMessageHandler;
     private final Consumer<SQSEvent.SQSMessage> successHandler;
@@ -30,7 +36,6 @@ public SqsBatchMessageHandler(BiConsumer<M, Context> messageHandler, Class<M> me
         this.rawMessageHandler = rawMessageHandler;
         this.successHandler = successHandler;
         this.failureHandler = failureHandler;
-
     }
 
     @Override