Skip to content

Commit e0f2f61

Browse files
S-Saranya1S-Saranya1
committed
Review comments addressed
1 parent 657cb5d commit e0f2f61

File tree

7 files changed

+104
-128
lines changed

7 files changed

+104
-128
lines changed

‎.changes/next-release/feature-AWSSDKforJavav2-7930031.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"type": "feature",
3+
"category": "AWS SDK for Java v2",
4+
"contributor": "",
5+
"description": "Adds links to AWS Code Library examples in package summary documentation and to individual methods documentation in Java SDK API Reference guide."
6+
}

‎codegen/src/main/java/software/amazon/awssdk/codegen/emitters/tasks/PackageInfoGeneratorTasks.java‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
import software.amazon.awssdk.codegen.emitters.SimpleGeneratorTask;
2828
import software.amazon.awssdk.codegen.internal.ExampleMetadataProvider;
2929
import software.amazon.awssdk.codegen.model.intermediate.Metadata;
30+
import software.amazon.awssdk.utils.CollectionUtils;
3031

3132
/**
3233
* Emits the package-info.java for the base service package. Includes the service
@@ -126,7 +127,7 @@ private String generateCodeExamplesJavadoc(List<ExampleMetadataProvider.ExampleD
126127

127128
StringBuilder javadoc = new StringBuilder();
128129
javadoc.append("<h2>Code Examples</h2>").append(System.lineSeparator());
129-
javadoc.append("<p>The following code examples show how to use this service with the AWS SDK for Java v2:</p>")
130+
javadoc.append("<p>For code examples demonstrating how to use this service with the AWS SDK for Java v2, see:</p>")
130131
.append(System.lineSeparator());
131132

132133
appendPredefinedCategories(javadoc, categorizedExamples, CATEGORY_DISPLAY_MAPPING);
@@ -189,7 +190,7 @@ private void appendCategoryIfExists(StringBuilder javadoc,
189190
String category,
190191
String displayName) {
191192
List<ExampleMetadataProvider.ExampleData> categoryExamples = categorizedExamples.get(category);
192-
if (categoryExamples != null && !categoryExamples.isEmpty()) {
193+
if (!CollectionUtils.isNullOrEmpty(categoryExamples)) {
193194
appendCategorySection(javadoc, displayName, categoryExamples);
194195
}
195196
}

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

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -90,15 +90,10 @@ public Optional<String> createLinkToCodeExample(Metadata metadata, String operat
9090
return Optional.empty();
9191
}
9292

93-
String url = findExampleUrl(actualServiceKey, operationName);
94-
95-
if (url != null) {
96-
return Optional.of(String.format("<a href=\"%s\" target=\"_top\">Code Example</a>", url));
97-
}
98-
99-
return Optional.empty();
93+
return findExampleUrl(actualServiceKey, operationName)
94+
.map(url -> String.format("<a href=\"%s\" target=\"_top\">Code Example</a>", url));
10095
} catch (RuntimeException e) {
101-
log.debug(() -> "Failed to create code example link for "
96+
log.error(() -> "Failed to create code example link for "
10297
+ metadata.getServiceName() + "." + operationName, e);
10398
return Optional.empty();
10499
}
@@ -112,15 +107,15 @@ private String resolveActualServiceKey(Metadata metadata) {
112107
/**
113108
* Finds the URL for a code example given the service key and operation name.
114109
*/
115-
private String findExampleUrl(String serviceKey, String operationName) {
110+
private Optional<String> findExampleUrl(String serviceKey, String operationName) {
116111
JsonNode serviceNode = serviceNodeCache.getValue().get(serviceKey);
117112

118113
if (serviceNode != null) {
119114
String targetExampleId = serviceKey + "_" + operationName;
120115
return findOperationUrl(serviceNode, targetExampleId);
121116
}
122117

123-
return null;
118+
return Optional.empty();
124119
}
125120

126121
/**
@@ -197,7 +192,7 @@ private Map<String, String> buildNormalizedServiceKeyMap() {
197192
/**
198193
* Finds the URL for a specific operation ID within a service node.
199194
*/
200-
private String findOperationUrl(JsonNode serviceNode, String targetExampleId) {
195+
private Optional<String> findOperationUrl(JsonNode serviceNode, String targetExampleId) {
201196
JsonNode examplesNode = serviceNode.field("examples").orElse(null);
202197
if (examplesNode != null && examplesNode.isArray()) {
203198
for (JsonNode example : examplesNode.asArray()) {
@@ -207,12 +202,12 @@ private String findOperationUrl(JsonNode serviceNode, String targetExampleId) {
207202
if (idNode != null && urlNode != null) {
208203
String id = idNode.asString();
209204
if (targetExampleId.equals(id)) {
210-
return urlNode.asString();
205+
return Optional.of(urlNode.asString());
211206
}
212207
}
213208
}
214209
}
215-
return null;
210+
return Optional.empty();
216211
}
217212

218213
/**

‎codegen/src/test/java/software/amazon/awssdk/codegen/docs/OperationDocProviderTest.java‎

Lines changed: 27 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -19,37 +19,49 @@
1919
import static org.assertj.core.api.Assertions.assertThatThrownBy;
2020

2121
import java.util.Optional;
22-
import org.junit.jupiter.api.AfterEach;
22+
import java.util.stream.Stream;
23+
import org.junit.jupiter.api.AfterAll;
2324
import org.junit.jupiter.api.Test;
25+
import org.junit.jupiter.params.ParameterizedTest;
26+
import org.junit.jupiter.params.provider.Arguments;
27+
import org.junit.jupiter.params.provider.MethodSource;
2428
import software.amazon.awssdk.codegen.internal.ExampleMetadataProvider;
2529
import software.amazon.awssdk.codegen.model.intermediate.Metadata;
2630

2731
public class OperationDocProviderTest {
2832

2933
private static final String TEST_EXAMPLE_META_PATH = "software/amazon/awssdk/codegen/test-example-meta.json";
3034

31-
@AfterEach
32-
void cleanupCache() {
35+
@AfterAll
36+
static void cleanupCache() {
3337
ExampleMetadataProvider.clearCache();
3438
}
3539

36-
@Test
37-
public void exampleMetadataService_createLinkToCodeExample_withValidExample_returnsCorrectLink() {
40+
@ParameterizedTest
41+
@MethodSource("createLinkToCodeExampleTestCases")
42+
public void exampleMetadataService_createLinkToCodeExample_returnsExpectedResult(
43+
String serviceName, String operationName, String expectedUrl) {
3844
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance(TEST_EXAMPLE_META_PATH);
3945

40-
Optional<String> result = provider.createLinkToCodeExample(createTestMetadata("s3"), "GetObject");
46+
Optional<String> result = provider.createLinkToCodeExample(createTestMetadata(serviceName), operationName);
4147

42-
assertThat(result).isPresent();
43-
assertThat(result.get()).isEqualTo("<a href=\"https://docs.aws.amazon.com/code-library/latest/ug/s3_example_s3_GetObject_section.html\" target=\"_top\">Code Example</a>");
48+
if (expectedUrl == null) {
49+
assertThat(result).isEmpty();
50+
} else {
51+
assertThat(result).isPresent();
52+
assertThat(result.get()).isEqualTo(String.format("<a href=\"%s\" target=\"_top\">Code Example</a>", expectedUrl));
53+
}
4454
}
4555

46-
@Test
47-
public void exampleMetadataService_createLinkToCodeExample_withNonExistentExample_returnsEmpty() {
48-
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance(TEST_EXAMPLE_META_PATH);
49-
50-
Optional<String> result = provider.createLinkToCodeExample(createTestMetadata("s3"), "NonExistentOperation");
51-
52-
assertThat(result).isEmpty();
56+
private static Stream<Arguments> createLinkToCodeExampleTestCases() {
57+
return Stream.of(
58+
Arguments.of("s3", "GetObject",
59+
"https://docs.aws.amazon.com/code-library/latest/ug/s3_example_s3_GetObject_section.html"),
60+
Arguments.of("medicalimaging", "GetImageSet",
61+
"https://docs.aws.amazon.com/code-library/latest/ug/medical-imaging_example_medical-imaging_GetImageSet_section.html"),
62+
Arguments.of("s3", "NonExistentOperation", null),
63+
Arguments.of("nonexistent-service", "GetObject", null)
64+
);
5365
}
5466

5567
@Test
@@ -71,25 +83,6 @@ public void registryPattern_threadSafety_handlesNullPath() {
7183
.hasMessageContaining("exampleMetaPath cannot be null");
7284
}
7385

74-
@Test
75-
public void exampleMetadataService_createLinkToCodeExample_withMedicalImagingService_returnsCorrectLink() {
76-
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance(TEST_EXAMPLE_META_PATH);
77-
78-
Optional<String> result = provider.createLinkToCodeExample(createTestMetadata("medicalimaging"), "GetImageSet");
79-
80-
assertThat(result).isPresent();
81-
assertThat(result.get()).isEqualTo("<a href=\"https://docs.aws.amazon.com/code-library/latest/ug/medical-imaging_example_medical-imaging_GetImageSet_section.html\" target=\"_top\">Code Example</a>");
82-
}
83-
84-
@Test
85-
public void exampleMetadataService_createLinkToCodeExample_withNonExistentService_returnsEmpty() {
86-
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance(TEST_EXAMPLE_META_PATH);
87-
88-
Optional<String> result = provider.createLinkToCodeExample(createTestMetadata("nonexistent-service"), "GetObject");
89-
90-
assertThat(result).isEmpty();
91-
}
92-
9386
private Metadata createTestMetadata(String serviceName) {
9487
Metadata metadata = new Metadata();
9588
metadata.setServiceName(serviceName);

‎codegen/src/test/java/software/amazon/awssdk/codegen/emitters/tasks/PackageInfoGeneratorTasksTest.java‎

Lines changed: 58 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,11 @@
2121
import java.io.InputStream;
2222
import java.util.List;
2323
import java.util.Scanner;
24-
import org.junit.jupiter.api.AfterEach;
25-
import org.junit.jupiter.api.Test;
24+
import java.util.stream.Stream;
25+
import org.junit.jupiter.api.AfterAll;
26+
import org.junit.jupiter.params.ParameterizedTest;
27+
import org.junit.jupiter.params.provider.Arguments;
28+
import org.junit.jupiter.params.provider.MethodSource;
2629
import software.amazon.awssdk.codegen.emitters.GeneratorTaskParams;
2730
import software.amazon.awssdk.codegen.internal.ExampleMetadataProvider;
2831
import software.amazon.awssdk.codegen.model.intermediate.IntermediateModel;
@@ -32,92 +35,70 @@ public class PackageInfoGeneratorTasksTest {
3235

3336
private static final String TEST_EXAMPLE_META_PATH = "software/amazon/awssdk/codegen/test-example-meta.json";
3437

35-
@AfterEach
36-
void cleanupCache() {
38+
@AfterAll
39+
static void cleanupCache() {
3740
ExampleMetadataProvider.clearCache();
3841
}
3942

40-
@Test
41-
public void exampleMetadataService_withExamples_returnsCorrectExamples() {
42-
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance(TEST_EXAMPLE_META_PATH);
43-
44-
List<ExampleMetadataProvider.ExampleData> result = provider.getServiceCodeExamples(createTestMetadata("s3"));
45-
46-
assertThat(result).hasSize(5);
47-
assertThat(result.get(0).getTitle()).isEqualTo("Get an object from a bucket");
48-
assertThat(result.get(0).getCategory()).isEqualTo("Api");
49-
assertThat(result.get(0).getUrl()).contains("s3_example_s3_GetObject_section.html");
50-
}
51-
52-
@Test
53-
public void exampleMetadataService_withoutExamples_returnsEmptyList() {
54-
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance(TEST_EXAMPLE_META_PATH);
55-
56-
List<ExampleMetadataProvider.ExampleData> result = provider.getServiceCodeExamples(createTestMetadata("empty-service"));
57-
58-
assertThat(result).isEmpty();
59-
}
60-
61-
@Test
62-
public void exampleMetadataService_withNonExistentService_returnsEmptyList() {
63-
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance(TEST_EXAMPLE_META_PATH);
64-
65-
List<ExampleMetadataProvider.ExampleData> result = provider.getServiceCodeExamples(createTestMetadata("nonexistent"));
66-
67-
assertThat(result).isEmpty();
68-
}
69-
70-
@Test
71-
public void exampleMetadataService_withMissingExampleFile_returnsEmptyList() {
72-
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance("nonexistent/path.json");
73-
74-
List<ExampleMetadataProvider.ExampleData> result = provider.getServiceCodeExamples(createTestMetadata("s3"));
75-
76-
assertThat(result).isEmpty();
77-
}
78-
79-
@Test
80-
public void exampleMetadataService_withMedicalImagingService_returnsCorrectExamples() {
81-
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance(TEST_EXAMPLE_META_PATH);
82-
83-
List<ExampleMetadataProvider.ExampleData> result = provider.getServiceCodeExamples(createTestMetadata("medicalimaging"));
84-
85-
assertThat(result).hasSize(1);
86-
assertThat(result.get(0).getTitle()).isEqualTo("Get image set properties");
87-
assertThat(result.get(0).getCategory()).isEqualTo("Api");
88-
assertThat(result.get(0).getUrl()).contains("medical-imaging_example_medical-imaging_GetImageSet_section.html");
89-
}
90-
91-
@Test
92-
public void buildPackageInfoContent_withS3Examples_generatesExpectedContent() {
93-
String actualContent = generatePackageInfoContent("s3");
94-
String expectedContent = loadFixtureFile("s3-package-info.java");
95-
96-
assertThat(actualContent).isEqualToIgnoringWhitespace(expectedContent);
43+
@ParameterizedTest
44+
@MethodSource("getServiceCodeExamplesTestCases")
45+
public void exampleMetadataService_getServiceCodeExamples_returnsExpectedResult(
46+
String metadataPath, String serviceName,
47+
Integer expectedSize, String expectedFirstTitle, String expectedFirstCategory, String expectedFirstUrl) {
48+
ExampleMetadataProvider provider = ExampleMetadataProvider.getInstance(metadataPath);
49+
50+
List<ExampleMetadataProvider.ExampleData> result = provider.getServiceCodeExamples(createTestMetadata(serviceName));
51+
52+
if (expectedSize == null || expectedSize == 0) {
53+
assertThat(result).isEmpty();
54+
} else {
55+
assertThat(result).hasSize(expectedSize);
56+
if (expectedFirstTitle != null) {
57+
assertThat(result.get(0).getTitle()).isEqualTo(expectedFirstTitle);
58+
}
59+
if (expectedFirstCategory != null) {
60+
assertThat(result.get(0).getCategory()).isEqualTo(expectedFirstCategory);
61+
}
62+
if (expectedFirstUrl != null) {
63+
assertThat(result.get(0).getUrl()).isEqualTo(expectedFirstUrl);
64+
}
65+
}
9766
}
9867

99-
@Test
100-
public void buildPackageInfoContent_withMedicalImagingExamples_generatesExpectedContent() {
101-
String actualContent = generatePackageInfoContent("medicalimaging");
102-
String expectedContent = loadFixtureFile("medical-imaging-package-info.java");
103-
104-
assertThat(actualContent).isEqualToIgnoringWhitespace(expectedContent);
68+
private static Stream<Arguments> getServiceCodeExamplesTestCases() {
69+
return Stream.of(
70+
Arguments.of(TEST_EXAMPLE_META_PATH, "s3",
71+
5, "Get an object from a bucket", "Api",
72+
"https://docs.aws.amazon.com/code-library/latest/ug/s3_example_s3_GetObject_section.html"),
73+
Arguments.of(TEST_EXAMPLE_META_PATH, "medicalimaging",
74+
1, "Get image set properties", "Api",
75+
"https://docs.aws.amazon.com/code-library/latest/ug/medical-imaging_example_medical-imaging_GetImageSet_section.html"),
76+
Arguments.of(TEST_EXAMPLE_META_PATH, "empty-service",
77+
0, null, null, null),
78+
Arguments.of(TEST_EXAMPLE_META_PATH, "nonexistent",
79+
0, null, null, null),
80+
Arguments.of("nonexistent/path.json", "s3",
81+
0, null, null, null)
82+
);
10583
}
10684

107-
@Test
108-
public void buildPackageInfoContent_withNoExamples_generatesContentWithoutCodeExamples() {
109-
String actualContent = generatePackageInfoContent("empty-service");
110-
String expectedContent = loadFixtureFile("empty-service-package-info.java");
85+
@ParameterizedTest
86+
@MethodSource("buildPackageInfoContentTestCases")
87+
public void buildPackageInfoContent_generatesExpectedContent(
88+
String serviceName, String expectedFixtureFile) {
89+
String actualContent = generatePackageInfoContent(serviceName);
90+
String expectedContent = loadFixtureFile(expectedFixtureFile);
11191

11292
assertThat(actualContent).isEqualToIgnoringWhitespace(expectedContent);
11393
}
11494

115-
@Test
116-
public void buildPackageInfoContent_withNonExistentService_generatesContentWithoutCodeExamples() {
117-
String actualContent = generatePackageInfoContent("nonexistent");
118-
String expectedContent = loadFixtureFile("empty-service-package-info.java");
119-
120-
assertThat(actualContent).isEqualToIgnoringWhitespace(expectedContent);
95+
private static Stream<Arguments> buildPackageInfoContentTestCases() {
96+
return Stream.of(
97+
Arguments.of("s3", "s3-package-info.java"),
98+
Arguments.of("medicalimaging", "medical-imaging-package-info.java"),
99+
Arguments.of("empty-service", "empty-service-package-info.java"),
100+
Arguments.of("nonexistent", "empty-service-package-info.java")
101+
);
121102
}
122103

123104
private PackageInfoGeneratorTasks createTestGenerator() {

‎codegen/src/test/resources/software/amazon/awssdk/codegen/emitters/tasks/medical-imaging-package-info.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
* Test service documentation.
33
*
44
* <h2>Code Examples</h2>
5-
* <p>The following code examples show how to use this service with the AWS SDK for Java v2:</p>
5+
* <p>For code examples demonstrating how to use this service with the AWS SDK for Java v2, see:</p>
66
* <h3>API Actions</h3>
77
* <ul>
88
* <li><a href="https://docs.aws.amazon.com/code-library/latest/ug/medical-imaging_example_medical-imaging_GetImageSet_section.html" target="_top">Get image set properties</a></li>

‎codegen/src/test/resources/software/amazon/awssdk/codegen/emitters/tasks/s3-package-info.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
* Test service documentation.
33
*
44
* <h2>Code Examples</h2>
5-
* <p>The following code examples show how to use this service with the AWS SDK for Java v2:</p>
5+
* <p>For code examples demonstrating how to use this service with the AWS SDK for Java v2, see:</p>
66
* <h3>Getting Started</h3>
77
* <ul>
88
* <li><a href="https://docs.aws.amazon.com/code-library/latest/ug/s3_example_s3_HelloS3_section.html" target="_top">Hello Amazon S3</a></li>

0 commit comments

Comments
 (0)