Skip to content

Commit 61e555b

Browse files
zoewanggzoewangg
authored
Update javadoc regarding exception handling in async clients (#5089)
* Update javadoc regarding exception handling in async clients * Fix tests
1 parent 6ff1c94 commit 61e555b

16 files changed

+359
-178
lines changed

‎codegen/src/main/java/software/amazon/awssdk/codegen/docs/DocumentationBuilder.java

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,9 @@ public final class DocumentationBuilder {
3333
// TODO This prefix is not suitable for paginated operations. Either remove it for paginated operations
3434
// or change the statement to something generic
3535
private static final String ASYNC_THROWS_PREFIX = "The CompletableFuture returned by this method can be completed " +
36-
"exceptionally with the following exceptions.";
36+
"exceptionally with the following exceptions. The exception returned is "
37+
+ "wrapped with CompletionException, so you need to invoke {@link "
38+
+ "Throwable#getCause} to retrieve the underlying exception.";
3739

3840
private String desc;
3941
private List<Pair<String, String>> params = new ArrayList<>();

‎codegen/src/test/java/software/amazon/awssdk/codegen/model/intermediate/DocumentationBuilderTest.java

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,9 @@ public void asyncReturns_FormatsExceptionsInUnorderedList() {
6767
"\n" +
6868
"@param paramOne param one docs\n" +
6969
"@return CompletableFuture of success<br/>\n" +
70-
"The CompletableFuture returned by this method can be completed exceptionally with the following exceptions.\n" +
70+
"The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. "
71+
+ "The exception returned is wrapped with CompletionException, "
72+
+ "so you need to invoke {@link Throwable#getCause} to retrieve the underlying exception.\n" +
7173
"<ul>\n" +
7274
"<li>FooException Foo docs</li>\n" +
7375
"<li>BarException Bar docs</li>\n" +
@@ -87,7 +89,9 @@ public void asyncReturnsWithoutDocsForSuccessReturn_FormatsExceptionsInUnordered
8789
"\n" +
8890
"@param paramOne param one docs\n" +
8991
"@return A CompletableFuture indicating when result will be completed.<br/>\n" +
90-
"The CompletableFuture returned by this method can be completed exceptionally with the following exceptions.\n" +
92+
"The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. "
93+
+ "The exception returned is wrapped with CompletionException, so you need to invoke {@link Throwable#getCause} "
94+
+ "to retrieve the underlying exception.\n" +
9195
"<ul>\n" +
9296
"<li>FooException Foo docs</li>\n" +
9397
"<li>BarException Bar docs</li>\n" +

‎codegen/src/test/resources/software/amazon/awssdk/codegen/poet/client/sra/test-aws-json-async-client-class.java

Lines changed: 28 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,8 @@ public JsonUtilities utilities() {
151151
* @param aPostOperationRequest
152152
* @return A Java Future containing the result of the APostOperation operation returned by the service.<br/>
153153
* The CompletableFuture returned by this method can be completed exceptionally with the following
154-
* exceptions.
154+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
155+
* {@link Throwable#getCause} to retrieve the underlying exception.
155156
* <ul>
156157
* <li>InvalidInputException The request was rejected because an invalid or out-of-range value was supplied
157158
* for an input parameter.</li>
@@ -215,7 +216,8 @@ public CompletableFuture<APostOperationResponse> aPostOperation(APostOperationRe
215216
* @param aPostOperationWithOutputRequest
216217
* @return A Java Future containing the result of the APostOperationWithOutput operation returned by the service.<br/>
217218
* The CompletableFuture returned by this method can be completed exceptionally with the following
218-
* exceptions.
219+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
220+
* {@link Throwable#getCause} to retrieve the underlying exception.
219221
* <ul>
220222
* <li>InvalidInputException The request was rejected because an invalid or out-of-range value was supplied
221223
* for an input parameter.</li>
@@ -276,7 +278,8 @@ public CompletableFuture<APostOperationWithOutputResponse> aPostOperationWithOut
276278
* @param eventStreamOperationRequest
277279
* @return A Java Future containing the result of the EventStreamOperation operation returned by the service.<br/>
278280
* The CompletableFuture returned by this method can be completed exceptionally with the following
279-
* exceptions.
281+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
282+
* {@link Throwable#getCause} to retrieve the underlying exception.
280283
* <ul>
281284
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
282285
* Can be used for catch all scenarios.</li>
@@ -368,7 +371,8 @@ public CompletableFuture<Void> eventStreamOperation(EventStreamOperationRequest
368371
* @return A Java Future containing the result of the EventStreamOperationWithOnlyInput operation returned by the
369372
* service.<br/>
370373
* The CompletableFuture returned by this method can be completed exceptionally with the following
371-
* exceptions.
374+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
375+
* {@link Throwable#getCause} to retrieve the underlying exception.
372376
* <ul>
373377
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
374378
* Can be used for catch all scenarios.</li>
@@ -435,7 +439,8 @@ public CompletableFuture<EventStreamOperationWithOnlyInputResponse> eventStreamO
435439
* @return A Java Future containing the result of the EventStreamOperationWithOnlyOutput operation returned by the
436440
* service.<br/>
437441
* The CompletableFuture returned by this method can be completed exceptionally with the following
438-
* exceptions.
442+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
443+
* {@link Throwable#getCause} to retrieve the underlying exception.
439444
* <ul>
440445
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
441446
* Can be used for catch all scenarios.</li>
@@ -522,7 +527,8 @@ public CompletableFuture<Void> eventStreamOperationWithOnlyOutput(
522527
* @param getWithoutRequiredMembersRequest
523528
* @return A Java Future containing the result of the GetWithoutRequiredMembers operation returned by the service.<br/>
524529
* The CompletableFuture returned by this method can be completed exceptionally with the following
525-
* exceptions.
530+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
531+
* {@link Throwable#getCause} to retrieve the underlying exception.
526532
* <ul>
527533
* <li>InvalidInputException The request was rejected because an invalid or out-of-range value was supplied
528534
* for an input parameter.</li>
@@ -583,7 +589,8 @@ public CompletableFuture<GetWithoutRequiredMembersResponse> getWithoutRequiredMe
583589
* @return A Java Future containing the result of the OperationWithChecksumRequired operation returned by the
584590
* service.<br/>
585591
* The CompletableFuture returned by this method can be completed exceptionally with the following
586-
* exceptions.
592+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
593+
* {@link Throwable#getCause} to retrieve the underlying exception.
587594
* <ul>
588595
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
589596
* Can be used for catch all scenarios.</li>
@@ -645,7 +652,8 @@ public CompletableFuture<OperationWithChecksumRequiredResponse> operationWithChe
645652
* @param operationWithNoneAuthTypeRequest
646653
* @return A Java Future containing the result of the OperationWithNoneAuthType operation returned by the service.<br/>
647654
* The CompletableFuture returned by this method can be completed exceptionally with the following
648-
* exceptions.
655+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
656+
* {@link Throwable#getCause} to retrieve the underlying exception.
649657
* <ul>
650658
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
651659
* Can be used for catch all scenarios.</li>
@@ -704,7 +712,8 @@ public CompletableFuture<OperationWithNoneAuthTypeResponse> operationWithNoneAut
704712
* @return A Java Future containing the result of the OperationWithRequestCompression operation returned by the
705713
* service.<br/>
706714
* The CompletableFuture returned by this method can be completed exceptionally with the following
707-
* exceptions.
715+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
716+
* {@link Throwable#getCause} to retrieve the underlying exception.
708717
* <ul>
709718
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
710719
* Can be used for catch all scenarios.</li>
@@ -768,7 +777,8 @@ public CompletableFuture<OperationWithRequestCompressionResponse> operationWithR
768777
* @return A Java Future containing the result of the PaginatedOperationWithResultKey operation returned by the
769778
* service.<br/>
770779
* The CompletableFuture returned by this method can be completed exceptionally with the following
771-
* exceptions.
780+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
781+
* {@link Throwable#getCause} to retrieve the underlying exception.
772782
* <ul>
773783
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
774784
* Can be used for catch all scenarios.</li>
@@ -827,7 +837,8 @@ public CompletableFuture<PaginatedOperationWithResultKeyResponse> paginatedOpera
827837
* @return A Java Future containing the result of the PaginatedOperationWithoutResultKey operation returned by the
828838
* service.<br/>
829839
* The CompletableFuture returned by this method can be completed exceptionally with the following
830-
* exceptions.
840+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
841+
* {@link Throwable#getCause} to retrieve the underlying exception.
831842
* <ul>
832843
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
833844
* Can be used for catch all scenarios.</li>
@@ -890,7 +901,8 @@ public CompletableFuture<PaginatedOperationWithoutResultKeyResponse> paginatedOp
890901
* uploading from a file. The service documentation for the request content is as follows 'This be a stream'
891902
* @return A Java Future containing the result of the StreamingInputOperation operation returned by the service.<br/>
892903
* The CompletableFuture returned by this method can be completed exceptionally with the following
893-
* exceptions.
904+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
905+
* {@link Throwable#getCause} to retrieve the underlying exception.
894906
* <ul>
895907
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
896908
* Can be used for catch all scenarios.</li>
@@ -962,7 +974,8 @@ public CompletableFuture<StreamingInputOperationResponse> streamingInputOperatio
962974
* the response content is as follows 'This be a stream'.
963975
* @return A future to the transformed result of the AsyncResponseTransformer.<br/>
964976
* The CompletableFuture returned by this method can be completed exceptionally with the following
965-
* exceptions.
977+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
978+
* {@link Throwable#getCause} to retrieve the underlying exception.
966979
* <ul>
967980
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
968981
* Can be used for catch all scenarios.</li>
@@ -1047,7 +1060,8 @@ public <ReturnT> CompletableFuture<ReturnT> streamingInputOutputOperation(
10471060
* the response content is as follows 'This be a stream'.
10481061
* @return A future to the transformed result of the AsyncResponseTransformer.<br/>
10491062
* The CompletableFuture returned by this method can be completed exceptionally with the following
1050-
* exceptions.
1063+
* exceptions. The exception returned is wrapped with CompletionException, so you need to invoke
1064+
* {@link Throwable#getCause} to retrieve the underlying exception.
10511065
* <ul>
10521066
* <li>SdkException Base class for all exceptions that can be thrown by the SDK (both service and client).
10531067
* Can be used for catch all scenarios.</li>

0 commit comments

Comments
 (0)