Skip to content

Commit 50f9b5e

Browse files
Alexander Kiselyovzoewangg
Alexander Kiselyov
authored and
zoewangg
committed
Align streaming methods' parameter names with javadocs #2022
Storing sourcePath/destinationPath parameter names in constants and reusing them in the sync client interface generator and javadoc provider instead of duplicating literals. Replacing JavaPoet literals ($L) with safer by-name references ($N) in the sync client interface generator. Enabling auto-wrapping of excessively long lines.
1 parent 7016bf1 commit 50f9b5e

File tree

6 files changed

+72
-31
lines changed

6 files changed

+72
-31
lines changed

‎.changes/next-release/bugfix-AWSSDKforJavav2-11ac2d8.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"description": "Formal parameter names of sychronous streaming methods were aligned with their javadocs.",
3+
"type": "bugfix",
4+
"category": "AWS SDK for Java v2"
5+
}

‎build-tools/src/main/resources/software/amazon/awssdk/intellij-codestyle.xml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@
5959
<option name="DOWHILE_BRACE_FORCE" value="3" />
6060
<option name="WHILE_BRACE_FORCE" value="3" />
6161
<option name="FOR_BRACE_FORCE" value="3" />
62+
<option name="WRAP_LONG_LINES" value="true" />
63+
<option name="WRAP_ON_TYPING" value="1" />
6264
<indentOptions>
6365
<option name="CONTINUATION_INDENT_SIZE" value="4" />
6466
</indentOptions>

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@
1515

1616
package software.amazon.awssdk.codegen.docs;
1717

18+
import static software.amazon.awssdk.codegen.internal.Constant.SYNC_CLIENT_DESTINATION_PATH_PARAM_NAME;
19+
import static software.amazon.awssdk.codegen.internal.Constant.SYNC_CLIENT_SOURCE_PATH_PARAM_NAME;
20+
1821
import software.amazon.awssdk.codegen.model.intermediate.IntermediateModel;
1922
import software.amazon.awssdk.codegen.model.intermediate.OperationModel;
2023
import software.amazon.awssdk.codegen.utils.PaginatorUtils;
@@ -101,12 +104,12 @@ static class SyncFile extends SyncOperationDocProvider {
101104
protected void applyParams(DocumentationBuilder docBuilder) {
102105
emitRequestParm(docBuilder);
103106
if (opModel.hasStreamingInput()) {
104-
docBuilder.param("sourcePath", SIMPLE_FILE_INPUT_DOCS + getStreamingInputDocs())
107+
docBuilder.param(SYNC_CLIENT_SOURCE_PATH_PARAM_NAME, SIMPLE_FILE_INPUT_DOCS + getStreamingInputDocs())
105108
// Link to non-simple method for discoverability
106109
.see("#%s(%s, RequestBody)", opModel.getMethodName(), opModel.getInput().getVariableType());
107110
}
108111
if (opModel.hasStreamingOutput()) {
109-
docBuilder.param("destinationPath", SIMPLE_FILE_OUTPUT_DOCS + getStreamingOutputDocs())
112+
docBuilder.param(SYNC_CLIENT_DESTINATION_PATH_PARAM_NAME, SIMPLE_FILE_OUTPUT_DOCS + getStreamingOutputDocs())
110113
// Link to non-simple method for discoverability
111114
.see("#%s(%s, ResponseTransformer)", opModel.getMethodName(),
112115
opModel.getInput().getVariableType());

‎codegen/src/main/java/software/amazon/awssdk/codegen/internal/Constant.java

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515

1616
package software.amazon.awssdk.codegen.internal;
1717

18+
import java.nio.file.Path;
19+
1820
public final class Constant {
1921

2022
public static final String CUSTOMIZATION_CONFIG_FILE = "customization.config";
@@ -26,6 +28,18 @@ public final class Constant {
2628

2729
public static final String SYNC_CLIENT_INTERFACE_NAME_PATTERN = "%sClient";
2830
public static final String SYNC_CLIENT_CLASS_NAME_PATTERN = "Default%sClient";
31+
32+
/**
33+
* Name of the source {@link Path}-typed formal method parameters of streaming input operations.
34+
*/
35+
public static final String SYNC_CLIENT_SOURCE_PATH_PARAM_NAME = "sourcePath";
36+
37+
/**
38+
* Name of the destination {@link Path}-typed formal method parameters of streaming output
39+
* operations.
40+
*/
41+
public static final String SYNC_CLIENT_DESTINATION_PATH_PARAM_NAME = "destinationPath";
42+
2943
public static final String SYNC_BUILDER_INTERFACE_NAME_PATTERN = "%sClientBuilder";
3044
public static final String SYNC_BUILDER_CLASS_NAME_PATTERN = "Default%sClientBuilder";
3145

‎codegen/src/main/java/software/amazon/awssdk/codegen/poet/client/SyncClientInterface.java

Lines changed: 38 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,14 @@
1717

1818
import static java.util.stream.Collectors.toCollection;
1919
import static java.util.stream.Collectors.toList;
20+
import static software.amazon.awssdk.codegen.internal.Constant.SYNC_CLIENT_DESTINATION_PATH_PARAM_NAME;
21+
import static software.amazon.awssdk.codegen.internal.Constant.SYNC_CLIENT_SOURCE_PATH_PARAM_NAME;
2022
import static software.amazon.awssdk.codegen.poet.client.AsyncClientInterface.STREAMING_TYPE_VARIABLE;
2123

2224
import com.squareup.javapoet.ClassName;
2325
import com.squareup.javapoet.FieldSpec;
2426
import com.squareup.javapoet.MethodSpec;
27+
import com.squareup.javapoet.ParameterSpec;
2528
import com.squareup.javapoet.ParameterizedTypeName;
2629
import com.squareup.javapoet.TypeName;
2730
import com.squareup.javapoet.TypeSpec;
@@ -338,17 +341,21 @@ private List<MethodSpec> streamingSimpleMethods(OperationModel opModel) {
338341
* @return Simple method for streaming input operations to read data from a file.
339342
*/
340343
private MethodSpec uploadFromFileSimpleMethod(OperationModel opModel, TypeName responseType, ClassName requestType) {
341-
return MethodSpec.methodBuilder(opModel.getMethodName())
344+
String methodName = opModel.getMethodName();
345+
ParameterSpec inputVarParam = ParameterSpec.builder(requestType, opModel.getInput().getVariableName()).build();
346+
ParameterSpec srcPathParam = ParameterSpec.builder(ClassName.get(Path.class),
347+
SYNC_CLIENT_SOURCE_PATH_PARAM_NAME).build();
348+
return MethodSpec.methodBuilder(methodName)
342349
.returns(responseType)
343350
.addModifiers(Modifier.PUBLIC, Modifier.DEFAULT)
344-
.addParameter(requestType, opModel.getInput().getVariableName())
345-
.addParameter(ClassName.get(Path.class), "filePath")
351+
.addParameter(inputVarParam)
352+
.addParameter(srcPathParam)
346353
.addJavadoc(opModel.getDocs(model, ClientType.SYNC, SimpleMethodOverload.FILE))
347354
.addExceptions(getExceptionClasses(model, opModel))
348-
.addStatement("return $L($L, $T.fromFile($L))", opModel.getMethodName(),
349-
opModel.getInput().getVariableName(),
355+
.addStatement("return $L($N, $T.fromFile($N))", methodName,
356+
inputVarParam,
350357
ClassName.get(RequestBody.class),
351-
"filePath")
358+
srcPathParam)
352359
.build();
353360
}
354361

@@ -390,17 +397,21 @@ private MethodSpec bytesSimpleMethod(OperationModel opModel, TypeName responseTy
390397
* @return Simple method for streaming output operations to write response content to a file.
391398
*/
392399
private MethodSpec downloadToFileSimpleMethod(OperationModel opModel, TypeName responseType, ClassName requestType) {
393-
return MethodSpec.methodBuilder(opModel.getMethodName())
400+
String methodName = opModel.getMethodName();
401+
ParameterSpec inputVarParam = ParameterSpec.builder(requestType, opModel.getInput().getVariableName()).build();
402+
ParameterSpec dstFileParam =
403+
ParameterSpec.builder(ClassName.get(Path.class), SYNC_CLIENT_DESTINATION_PATH_PARAM_NAME).build();
404+
return MethodSpec.methodBuilder(methodName)
394405
.returns(responseType)
395406
.addModifiers(Modifier.PUBLIC, Modifier.DEFAULT)
396-
.addParameter(requestType, opModel.getInput().getVariableName())
397-
.addParameter(ClassName.get(Path.class), "filePath")
407+
.addParameter(inputVarParam)
408+
.addParameter(dstFileParam)
398409
.addJavadoc(opModel.getDocs(model, ClientType.SYNC, SimpleMethodOverload.FILE))
399410
.addExceptions(getExceptionClasses(model, opModel))
400-
.addStatement("return $L($L, $T.toFile($L))", opModel.getMethodName(),
401-
opModel.getInput().getVariableName(),
411+
.addStatement("return $L($N, $T.toFile($N))", methodName,
412+
inputVarParam,
402413
ClassName.get(ResponseTransformer.class),
403-
"filePath")
414+
dstFileParam)
404415
.build();
405416
}
406417

@@ -411,19 +422,25 @@ private MethodSpec downloadToFileSimpleMethod(OperationModel opModel, TypeName r
411422
private MethodSpec streamingInputOutputFileSimpleMethod(OperationModel opModel,
412423
TypeName responseType,
413424
ClassName requestType) {
414-
return MethodSpec.methodBuilder(opModel.getMethodName())
425+
String methodName = opModel.getMethodName();
426+
ParameterSpec inputVarParam = ParameterSpec.builder(requestType, opModel.getInput().getVariableName()).build();
427+
ParameterSpec srcFileParam = ParameterSpec.builder(ClassName.get(Path.class), SYNC_CLIENT_SOURCE_PATH_PARAM_NAME).build();
428+
ParameterSpec dstFileParam =
429+
ParameterSpec.builder(ClassName.get(Path.class), SYNC_CLIENT_DESTINATION_PATH_PARAM_NAME).build();
430+
return MethodSpec.methodBuilder(methodName)
415431
.returns(responseType)
416432
.addModifiers(Modifier.PUBLIC, Modifier.DEFAULT)
417-
.addParameter(requestType, opModel.getInput().getVariableName())
418-
.addParameter(ClassName.get(Path.class), "sourcePath")
419-
.addParameter(ClassName.get(Path.class), "destinationPath")
433+
.addParameter(inputVarParam)
434+
.addParameter(srcFileParam)
435+
.addParameter(dstFileParam)
420436
.addJavadoc(opModel.getDocs(model, ClientType.SYNC, SimpleMethodOverload.FILE))
421437
.addExceptions(getExceptionClasses(model, opModel))
422-
.addStatement("return $L($L, $T.fromFile(sourcePath), $T.toFile(destinationPath))",
423-
opModel.getMethodName(),
424-
opModel.getInput().getVariableName(),
425-
ClassName.get(RequestBody.class),
426-
ClassName.get(ResponseTransformer.class))
438+
.addStatement("return $L($N, $T.fromFile($N), $T.toFile($N))",
439+
methodName,
440+
inputVarParam,
441+
ClassName.get(RequestBody.class), srcFileParam,
442+
ClassName.get(ResponseTransformer.class),
443+
dstFileParam)
427444
.build();
428445
}
429446

‎codegen/src/test/resources/software/amazon/awssdk/codegen/poet/client/test-json-client-interface.java

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -850,9 +850,9 @@ default StreamingInputOperationResponse streamingInputOperation(
850850
* target="_top">AWS API Documentation</a>
851851
*/
852852
default StreamingInputOperationResponse streamingInputOperation(
853-
StreamingInputOperationRequest streamingInputOperationRequest, Path filePath) throws AwsServiceException,
853+
StreamingInputOperationRequest streamingInputOperationRequest, Path sourcePath) throws AwsServiceException,
854854
SdkClientException, JsonException {
855-
return streamingInputOperation(streamingInputOperationRequest, RequestBody.fromFile(filePath));
855+
return streamingInputOperation(streamingInputOperationRequest, RequestBody.fromFile(sourcePath));
856856
}
857857

858858
/**
@@ -884,10 +884,10 @@ default StreamingInputOperationResponse streamingInputOperation(
884884
* target="_top">AWS API Documentation</a>
885885
*/
886886
default StreamingInputOperationResponse streamingInputOperation(
887-
Consumer<StreamingInputOperationRequest.Builder> streamingInputOperationRequest, Path filePath)
887+
Consumer<StreamingInputOperationRequest.Builder> streamingInputOperationRequest, Path sourcePath)
888888
throws AwsServiceException, SdkClientException, JsonException {
889889
return streamingInputOperation(StreamingInputOperationRequest.builder().applyMutation(streamingInputOperationRequest)
890-
.build(), filePath);
890+
.build(), sourcePath);
891891
}
892892

893893
/**
@@ -1143,9 +1143,9 @@ default <ReturnT> ReturnT streamingOutputOperation(
11431143
* target="_top">AWS API Documentation</a>
11441144
*/
11451145
default StreamingOutputOperationResponse streamingOutputOperation(
1146-
StreamingOutputOperationRequest streamingOutputOperationRequest, Path filePath) throws AwsServiceException,
1146+
StreamingOutputOperationRequest streamingOutputOperationRequest, Path destinationPath) throws AwsServiceException,
11471147
SdkClientException, JsonException {
1148-
return streamingOutputOperation(streamingOutputOperationRequest, ResponseTransformer.toFile(filePath));
1148+
return streamingOutputOperation(streamingOutputOperationRequest, ResponseTransformer.toFile(destinationPath));
11491149
}
11501150

11511151
/**
@@ -1176,10 +1176,10 @@ default StreamingOutputOperationResponse streamingOutputOperation(
11761176
* target="_top">AWS API Documentation</a>
11771177
*/
11781178
default StreamingOutputOperationResponse streamingOutputOperation(
1179-
Consumer<StreamingOutputOperationRequest.Builder> streamingOutputOperationRequest, Path filePath)
1179+
Consumer<StreamingOutputOperationRequest.Builder> streamingOutputOperationRequest, Path destinationPath)
11801180
throws AwsServiceException, SdkClientException, JsonException {
11811181
return streamingOutputOperation(StreamingOutputOperationRequest.builder().applyMutation(streamingOutputOperationRequest)
1182-
.build(), filePath);
1182+
.build(), destinationPath);
11831183
}
11841184

11851185
/**

0 commit comments

Comments
 (0)