Skip to content

Commit 2bf4d6d

Browse files
author
Pankaj Agrawal
committed
java docs
1 parent 955f829 commit 2bf4d6d

File tree

5 files changed

+207
-50
lines changed

5 files changed

+207
-50
lines changed

‎powertools-sqs/src/main/java/software/amazon/lambda/powertools/sqs/PowertoolsSqs.java

Lines changed: 104 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,7 @@
3333
import static software.amazon.lambda.powertools.sqs.internal.SqsLargeMessageAspect.processMessages;
3434

3535
/**
36-
* A class of helper functions to add additional functionality to LargeMessageHandler.
37-
* <p>
38-
* {@see PowertoolsLogging}
36+
* A class of helper functions to add additional functionality to {@link SQSEvent} processing.
3937
*/
4038
public final class PowertoolsSqs {
4139
private static final Log LOG = LogFactory.getLog(PowertoolsSqs.class);
@@ -99,22 +97,64 @@ public static void defaultSqsClient(SqsClient client) {
9997
}
10098

10199
/**
102-
* @param event
103-
* @param handler
104-
* @param <R>
105-
* @return
100+
* This utility method is used to processes each {@link SQSMessage} inside received {@link SQSEvent}
101+
*
102+
* <p>
103+
* Utility will take care of calling {@link SqsMessageHandler#process(SQSMessage)} method for each {@link SQSMessage}
104+
* in the received {@link SQSEvent}
105+
* </p>
106+
*
107+
* </p>
108+
* If any exception is thrown from {@link SqsMessageHandler#process(SQSMessage)} during processing of a messages,
109+
* Utility will take care of deleting all the successful messages from SQS. When one or more single message fails
110+
* processing due to exception thrown from {@link SqsMessageHandler#process(SQSMessage)}
111+
* {@link SQSBatchProcessingException} is thrown with all the details of successful and failed messages.
112+
* <p>
113+
* If all the messages are successfully processes, No SQS messages are deleted explicitly but is rather delegated to
114+
* Lambda execution context for deletion.
115+
* </p>
116+
*
117+
* <p>
118+
* If you dont want to utility to throw {@link SQSBatchProcessingException} in case of failures but rather suppress
119+
* it, Refer {@link PowertoolsSqs#batchProcessor(SQSEvent, boolean, Class)}
120+
* </p>
121+
*
122+
* @param event {@link SQSEvent} received by lambda function.
123+
* @param handler Class implementing {@link SqsMessageHandler} which will be called for each message in event.
124+
* @return List of values returned by {@link SqsMessageHandler#process(SQSMessage)} while processing each message.
125+
* @throws SQSBatchProcessingException if some messages fail during processing.
106126
*/
107127
public static <R> List<R> batchProcessor(final SQSEvent event,
108128
final Class<? extends SqsMessageHandler<R>> handler) {
109129
return batchProcessor(event, false, handler);
110130
}
111131

112132
/**
113-
* @param event
114-
* @param suppressException
115-
* @param handler
116-
* @param <R>
117-
* @return
133+
* This utility method is used to processes each {@link SQSMessage} inside received {@link SQSEvent}
134+
*
135+
* <p>
136+
* Utility will take care of calling {@link SqsMessageHandler#process(SQSMessage)} method for each {@link SQSMessage}
137+
* in the received {@link SQSEvent}
138+
* </p>
139+
*
140+
* </p>
141+
* If any exception is thrown from {@link SqsMessageHandler#process(SQSMessage)} during processing of a messages,
142+
* Utility will take care of deleting all the successful messages from SQS. When one or more single message fails
143+
* processing due to exception thrown from {@link SqsMessageHandler#process(SQSMessage)}
144+
* {@link SQSBatchProcessingException} is thrown with all the details of successful and failed messages.
145+
* <p>
146+
* Exception can also be suppressed if desired.
147+
* <p>
148+
* If all the messages are successfully processes, No SQS messages are deleted explicitly but is rather delegated to
149+
* Lambda execution context for deletion.
150+
* </p>
151+
*
152+
* @param event {@link SQSEvent} received by lambda function.
153+
* @param suppressException if this is set to true, No {@link SQSBatchProcessingException} is thrown even on failed
154+
* messages.
155+
* @param handler Class implementing {@link SqsMessageHandler} which will be called for each message in event.
156+
* @return List of values returned by {@link SqsMessageHandler#process(SQSMessage)} while processing each message.
157+
* @throws SQSBatchProcessingException if some messages fail during processing and no suppression enabled.
118158
*/
119159
public static <R> List<R> batchProcessor(final SQSEvent event,
120160
final boolean suppressException,
@@ -125,22 +165,64 @@ public static <R> List<R> batchProcessor(final SQSEvent event,
125165
}
126166

127167
/**
128-
* @param event
129-
* @param handler
130-
* @param <R>
131-
* @return
168+
* This utility method is used to processes each {@link SQSMessage} inside received {@link SQSEvent}
169+
*
170+
* <p>
171+
* Utility will take care of calling {@link SqsMessageHandler#process(SQSMessage)} method for each {@link SQSMessage}
172+
* in the received {@link SQSEvent}
173+
* </p>
174+
*
175+
* </p>
176+
* If any exception is thrown from {@link SqsMessageHandler#process(SQSMessage)} during processing of a messages,
177+
* Utility will take care of deleting all the successful messages from SQS. When one or more single message fails
178+
* processing due to exception thrown from {@link SqsMessageHandler#process(SQSMessage)}
179+
* {@link SQSBatchProcessingException} is thrown with all the details of successful and failed messages.
180+
* <p>
181+
* If all the messages are successfully processes, No SQS messages are deleted explicitly but is rather delegated to
182+
* Lambda execution context for deletion.
183+
* </p>
184+
*
185+
* <p>
186+
* If you dont want to utility to throw {@link SQSBatchProcessingException} in case of failures but rather suppress
187+
* it, Refer {@link PowertoolsSqs#batchProcessor(SQSEvent, boolean, SqsMessageHandler)}
188+
* </p>
189+
*
190+
* @param event {@link SQSEvent} received by lambda function.
191+
* @param handler Instance of class implementing {@link SqsMessageHandler} which will be called for each message in event.
192+
* @return List of values returned by {@link SqsMessageHandler#process(SQSMessage)} while processing each message-
193+
* @throws SQSBatchProcessingException if some messages fail during processing.
132194
*/
133195
public static <R> List<R> batchProcessor(final SQSEvent event,
134196
final SqsMessageHandler<R> handler) {
135197
return batchProcessor(event, false, handler);
136198
}
137199

138200
/**
139-
* @param event
140-
* @param suppressException
141-
* @param handler
142-
* @param <R>
143-
* @return
201+
* This utility method is used to processes each {@link SQSMessage} inside received {@link SQSEvent}
202+
*
203+
* <p>
204+
* Utility will take care of calling {@link SqsMessageHandler#process(SQSMessage)} method for each {@link SQSMessage}
205+
* in the received {@link SQSEvent}
206+
* </p>
207+
*
208+
* </p>
209+
* If any exception is thrown from {@link SqsMessageHandler#process(SQSMessage)} during processing of a messages,
210+
* Utility will take care of deleting all the successful messages from SQS. When one or more single message fails
211+
* processing due to exception thrown from {@link SqsMessageHandler#process(SQSMessage)}
212+
* {@link SQSBatchProcessingException} is thrown with all the details of successful and failed messages.
213+
* <p>
214+
* Exception can also be suppressed if desired.
215+
* <p>
216+
* If all the messages are successfully processes, No SQS messages are deleted explicitly but is rather delegated to
217+
* Lambda execution context for deletion.
218+
* </p>
219+
*
220+
* @param event {@link SQSEvent} received by lambda function.
221+
* @param suppressException if this is set to true, No {@link SQSBatchProcessingException} is thrown even on failed
222+
* messages.
223+
* @param handler Instance of class implementing {@link SqsMessageHandler} which will be called for each message in event.
224+
* @return List of values returned by {@link SqsMessageHandler#process(SQSMessage)} while processing each message.
225+
* @throws SQSBatchProcessingException if some messages fail during processing and no suppression enabled.
144226
*/
145227
public static <R> List<R> batchProcessor(final SQSEvent event,
146228
final boolean suppressException,
@@ -158,12 +240,7 @@ public static <R> List<R> batchProcessor(final SQSEvent event,
158240
}
159241
}
160242

161-
try {
162-
batchContext.processSuccessAndReset(suppressException);
163-
} catch (SQSBatchProcessingException e) {
164-
e.addSuccessMessageReturnValues(handlerReturn);
165-
throw e;
166-
}
243+
batchContext.processSuccessAndHandleFailed(handlerReturn, suppressException);
167244

168245
return handlerReturn;
169246
}

‎powertools-sqs/src/main/java/software/amazon/lambda/powertools/sqs/SQSBatchProcessingException.java

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,34 @@
55

66
import com.amazonaws.services.lambda.runtime.events.SQSEvent;
77

8+
import static com.amazonaws.services.lambda.runtime.events.SQSEvent.SQSMessage;
89
import static java.util.stream.Collectors.joining;
910

1011
/**
12+
* <p>
13+
* When one or more {@link SQSMessage} fails and if any exception is thrown from {@link SqsMessageHandler#process(SQSMessage)}
14+
* during processing of a messages, this exception is with all the details of successful and failed messages.
15+
* </p>
1116
*
17+
* <p>
18+
* This exception can be thrown form:
19+
* <ul>
20+
* <li>{@link SqsBatchProcessor}</li>
21+
* <li>{@link PowertoolsSqs#batchProcessor(SQSEvent, Class)}</li>
22+
* <li>{@link PowertoolsSqs#batchProcessor(SQSEvent, boolean, Class)}</li>
23+
* <li>{@link PowertoolsSqs#batchProcessor(SQSEvent, SqsMessageHandler)}</li>
24+
* <li>{@link PowertoolsSqs#batchProcessor(SQSEvent, boolean, SqsMessageHandler)}</li>
25+
* </ul>
26+
* </p>
1227
*/
1328
public class SQSBatchProcessingException extends RuntimeException {
1429

1530
private final List<Exception> exceptions;
16-
private final List<SQSEvent.SQSMessage> failures;
31+
private final List<SQSMessage> failures;
1732
private final List<Object> returnValues;
1833

1934
public <T> SQSBatchProcessingException(final List<Exception> exceptions,
20-
final List<SQSEvent.SQSMessage> failures,
35+
final List<SQSMessage> failures,
2136
final List<T> successReturns) {
2237
super(exceptions.stream()
2338
.map(Throwable::toString)
@@ -28,15 +43,27 @@ public <T> SQSBatchProcessingException(final List<Exception> exceptions,
2843
this.returnValues = new ArrayList<>(successReturns);
2944
}
3045

46+
/**
47+
* Details for exceptions that occurred while processing messages in {@link SqsMessageHandler#process(SQSMessage)}
48+
* @return List of exceptions that occurred while processing messages
49+
*/
3150
public List<Exception> getExceptions() {
3251
return exceptions;
3352
}
3453

54+
/**
55+
* List of returns from {@link SqsMessageHandler#process(SQSMessage)} that were successfully processed.
56+
* @return List of returns from successfully processed messages
57+
*/
3558
public List<Object> successMessageReturnValues() {
3659
return returnValues;
3760
}
3861

39-
public List<SQSEvent.SQSMessage> getFailures() {
62+
/**
63+
* Details of {@link SQSMessage} that failed in {@link SqsMessageHandler#process(SQSMessage)}
64+
* @return List of failed messages
65+
*/
66+
public List<SQSMessage> getFailures() {
4067
return failures;
4168
}
4269

‎powertools-sqs/src/main/java/software/amazon/lambda/powertools/sqs/SqsBatchProcessor.java

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,52 @@
55
import java.lang.annotation.RetentionPolicy;
66
import java.lang.annotation.Target;
77

8+
import com.amazonaws.services.lambda.runtime.events.SQSEvent;
9+
10+
import static com.amazonaws.services.lambda.runtime.events.SQSEvent.*;
11+
812
/**
13+
* {@link SqsBatchProcessor} is used to process batch messages in {@link SQSEvent}
14+
*
15+
* <p>
16+
* When using the annotation, implementation of {@link SqsMessageHandler} is required. Annotation will take care of
17+
* calling {@link SqsMessageHandler#process(SQSMessage)} method for each {@link SQSMessage} in the received {@link SQSEvent}
18+
* </p>
19+
*
20+
* </p>
21+
* If any exception is thrown from {@link SqsMessageHandler#process(SQSMessage)} during processing of a messages, Utility
22+
* will take care of deleting all the successful messages from SQS. When one or more single message fails processing due
23+
* to exception thrown from {@link SqsMessageHandler#process(SQSMessage)}, Lambda execution will fail
24+
* with {@link SQSBatchProcessingException}.
25+
*
26+
* If all the messages are successfully processes, No SQS messages are deleted explicitly but is rather delegated to
27+
* Lambda execution context for deletion.
28+
* </p>
29+
*
30+
* <p>
31+
* If you want to suppress the exception even if any message in batch fails, set
32+
* {@link SqsBatchProcessor#suppressException()} to true. By default its value is false
33+
* </p>
34+
*
35+
* <pre>
36+
* public class SqsMessageHandler implements RequestHandler<SQSEvent, String> {
37+
*
38+
* {@literal @}Override
39+
* {@literal @}{@link SqsBatchProcessor(SqsMessageHandler)}
40+
* public String handleRequest(SQSEvent sqsEvent, Context context) {
41+
*
42+
* return "ok";
43+
* }
44+
*
45+
* public class DummySqsMessageHandler implements SqsMessageHandler<Object>{
46+
* @Override
47+
* public Object process(SQSEvent.SQSMessage message) {
48+
* throw new UnsupportedOperationException();
49+
* }
50+
* }
951
*
52+
* ...
53+
* </pre>
1054
*/
1155
@Retention(RetentionPolicy.RUNTIME)
1256
@Target(ElementType.METHOD)

‎powertools-sqs/src/main/java/software/amazon/lambda/powertools/sqs/SqsMessageHandler.java

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,26 @@
11
package software.amazon.lambda.powertools.sqs;
22

3+
import com.amazonaws.services.lambda.runtime.events.SQSEvent;
4+
35
import static com.amazonaws.services.lambda.runtime.events.SQSEvent.SQSMessage;
46

57
/**
8+
* <p>
9+
* This interface should be implemented for processing {@link SQSMessage} inside {@link SQSEvent} received by lambda
10+
* function.
11+
* </p>
612
*
7-
* @param <R>
13+
* <p>
14+
* It is required by utilities:
15+
* <ul>
16+
* <li>{@link SqsBatchProcessor}</li>
17+
* <li>{@link PowertoolsSqs#batchProcessor(SQSEvent, Class)}</li>
18+
* <li>{@link PowertoolsSqs#batchProcessor(SQSEvent, boolean, Class)}</li>
19+
* <li>{@link PowertoolsSqs#batchProcessor(SQSEvent, SqsMessageHandler)}</li>
20+
* <li>{@link PowertoolsSqs#batchProcessor(SQSEvent, boolean, SqsMessageHandler)}</li>
21+
* </ul>
22+
* </p>
23+
* @param <R> Return value type from {@link SqsMessageHandler#process(SQSMessage)}
824
*/
925
@FunctionalInterface
1026
public interface SqsMessageHandler<R> {

‎powertools-sqs/src/main/java/software/amazon/lambda/powertools/sqs/internal/BatchContext.java

Lines changed: 12 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
package software.amazon.lambda.powertools.sqs.internal;
22

3-
import java.awt.geom.Area;
43
import java.util.ArrayList;
54
import java.util.List;
65

@@ -37,21 +36,21 @@ public void addFailure(SQSMessage event, Exception e) {
3736
exceptions.add(e);
3837
}
3938

40-
public <T> void processSuccessAndReset(final boolean suppressException) {
41-
try {
42-
if (hasFailures()) {
39+
public <T> void processSuccessAndHandleFailed(final List<T> successReturns,
40+
final boolean suppressException) {
41+
if (hasFailures()) {
42+
deleteSuccessMessage();
4343

44-
deleteSuccessMessage();
44+
if (suppressException) {
45+
List<String> messageIds = failures.stream().
46+
map(SQSMessage::getMessageId)
47+
.collect(toList());
4548

46-
if (suppressException) {
47-
List<String> messageIds = failures.stream().map(SQSMessage::getMessageId).collect(toList());
48-
LOG.debug(format("[%s] records failed processing, but exceptions are suppressed. Failed messages %s", failures.size(), messageIds));
49-
} else {
50-
throw new SQSBatchProcessingException(exceptions, failures, new ArrayList<T>());
51-
}
49+
LOG.debug(format("[%s] records failed processing, but exceptions are suppressed. " +
50+
"Failed messages %s", failures.size(), messageIds));
51+
} else {
52+
throw new SQSBatchProcessingException(exceptions, failures, successReturns);
5253
}
53-
} finally {
54-
reset();
5554
}
5655
}
5756

@@ -81,10 +80,4 @@ private String url() {
8180
.build())
8281
.queueUrl();
8382
}
84-
85-
private void reset() {
86-
success.clear();
87-
failures.clear();
88-
exceptions.clear();
89-
}
9083
}

0 commit comments

Comments
 (0)