Added documentation for stream analytics and custom checkpointing event structures (#206)

cr https://code.amazon.com/reviews/CR-41217330

Co-authored-by: Vinayak <vinayaks@amazon.com>

Author: vinayaksood

aws-lambda-java-events/src/main/java/com/amazonaws/services/lambda/runtime/events/DynamodbTimeWindowEvent.java

@@ -23,18 +23,44 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Represents an Amazon Dynamodb event when using <a href="https://docs.aws.amazon.com/lambda/latest/dg/with-ddb.html#services-ddb-windows">time windows</a>.
+ */
 @Data
 @NoArgsConstructor
 @EqualsAndHashCode(callSuper = true)
 public class DynamodbTimeWindowEvent extends DynamodbEvent implements Serializable, Cloneable {
 
     private static final long serialVersionUID = -5449871161108629510L;
 
+    /**
+     * Time window for the records in the event.
+     */
     private TimeWindow window;
+
+    /**
+     * State being built up to this invoke in the time window.
+     */
     private Map<String, String> state;
+
+    /**
+     * Shard id of the records
+     */
     private String shardId;
+
+    /**
+     * Dynamodb stream arn.
+     */
     private String eventSourceArn;
+
+    /**
+     * Set to true for the last invoke of the time window. Subsequent invoke will start a new time window along with a fresh state.
+     */
     private Boolean isFinalInvokeForWindow;
+
+    /**
+     * Set to true if window is terminated prematurely. Subsequent invoke will continue the same window with a fresh state.
+     */
     private Boolean isWindowTerminatedEarly;
 
     @Builder(setterPrefix = "with")

aws-lambda-java-events/src/main/java/com/amazonaws/services/lambda/runtime/events/KinesisTimeWindowEvent.java

@@ -23,18 +23,44 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Represents an Amazon Kinesis event when using <a href="https://docs.aws.amazon.com/lambda/latest/dg/with-kinesis.html#services-kinesis-windows">time windows</a>.
+ */
 @Data
 @NoArgsConstructor
 @EqualsAndHashCode(callSuper = true)
 public class KinesisTimeWindowEvent extends KinesisEvent implements Serializable, Cloneable {
 
     private static final long serialVersionUID = 8926430039233062266L;
 
+    /**
+     * Time window for the records in the event.
+     */
     private TimeWindow window;
+
+    /**
+     * State being built up to this invoke in the time window.
+     */
     private Map<String, String> state;
+
+    /**
+     * Shard id of the records
+     */
     private String shardId;
+
+    /**
+     * Kinesis stream or consumer arn.
+     */
     private String eventSourceArn;
+
+    /**
+     * Set to true for the last invoke of the time window. Subsequent invoke will start a new time window along with a fresh state.
+     */
     private Boolean isFinalInvokeForWindow;
+
+    /**
+     * Set to true if window is terminated prematurely. Subsequent invoke will continue the same window with a fresh state.
+     */
     private Boolean isWindowTerminatedEarly;
 
     @Builder(setterPrefix = "with")

aws-lambda-java-events/src/main/java/com/amazonaws/services/lambda/runtime/events/StreamsEventResponse.java

@@ -21,13 +21,20 @@
 import java.io.Serializable;
 import java.util.List;
 
+/**
+ * Function response type to report batch item failures for {@link KinesisEvent} and {@link DynamodbEvent}.
+ * https://docs.aws.amazon.com/lambda/latest/dg/with-kinesis.html#services-kinesis-batchfailurereporting
+ */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
 @Builder(setterPrefix = "with")
 public class StreamsEventResponse implements Serializable {
     private static final long serialVersionUID = 3232053116472095907L;
 
+    /**
+     * A list of records which failed processing. Returning the first record which failed would retry all remaining records from the batch.
+     */
     private List<BatchItemFailure> batchItemFailures;
 
     @Data
@@ -37,6 +44,9 @@ public class StreamsEventResponse implements Serializable {
     public static class BatchItemFailure implements Serializable {
         private static final long serialVersionUID = 1473983466096085881L;
 
+        /**
+         * Sequence number of the record which failed processing.
+         */
         String itemIdentifier;
     }
 }

aws-lambda-java-events/src/main/java/com/amazonaws/services/lambda/runtime/events/TimeWindowEventResponse.java

@@ -22,14 +22,25 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Response type to return a new state for the time window and to report batch item failures. This should be used along with {@link KinesisTimeWindowEvent} or {@link DynamodbTimeWindowEvent}.
+ * https://docs.aws.amazon.com/lambda/latest/dg/with-kinesis.html#services-kinesis-windows
+ */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor
 @Builder(setterPrefix = "with")
 public class TimeWindowEventResponse implements Serializable {
     private static final long serialVersionUID = 2259096191791166028L;
 
+    /**
+     * New state after processing a batch of records.
+     */
     private Map<String, String> state;
+
+    /**
+     * A list of records which failed processing. Returning the first record which failed would retry all remaining records from the batch.
+     */
     private List<BatchItemFailure> batchItemFailures;
 
     @Data
@@ -39,6 +50,9 @@ public class TimeWindowEventResponse implements Serializable {
     public static class BatchItemFailure implements Serializable {
         private static final long serialVersionUID = 5224634072234167773L;
 
+        /**
+         * Sequence number of the record which failed processing.
+         */
         String itemIdentifier;
     }
 }

aws-lambda-java-events/src/main/java/com/amazonaws/services/lambda/runtime/events/models/TimeWindow.java

@@ -18,11 +18,22 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * Represents a time window.
+ */
 @Data
 @Builder(setterPrefix = "with")
 @NoArgsConstructor
 @AllArgsConstructor
 public class TimeWindow {
+
+    /**
+     * Window start instant represented as ISO-8601 string.
+     */
     private String start;
+
+    /**
+     * Window end instant represented as ISO-8601 string.
+     */
     private String end;
 }