From fa6b5e8c8ad2de89e819ecbca8ef185d32401c0a Mon Sep 17 00:00:00 2001 From: Mira Leung Date: Tue, 24 Nov 2020 01:03:05 -0800 Subject: [PATCH] [ggj][codegen] fix: use gapic.yaml override names in comments (#560) * feat: add parsing for language_settings in gapic.yaml * fix: restructure GapicServiceConfig table-processing into ctor * fix: refactor {LRO,Batching} settings out of GapicServiceConfig's required creation params * build: support file deletion in integration test update Bazel rules * feat: support gapic.yaml Java name overrides for Service{Client,Settings} * fix: use gapic.yaml override names in comments * fix: Use the right file --- .../composer/ServiceClientClassComposer.java | 10 ++++--- .../ServiceClientCommentComposer.java | 26 ++++++++----------- .../composer/SettingsCommentComposer.java | 1 - .../gapic/composer/goldens/EchoClient.golden | 2 +- .../composer/goldens/IdentityClient.golden | 2 +- .../goldens/asset/AssetServiceClient.java | 2 +- .../goldens/logging/ConfigClient.java | 24 ++++++++--------- .../goldens/logging/LoggingClient.java | 24 ++++++++--------- .../goldens/logging/MetricsClient.java | 24 ++++++++--------- .../goldens/redis/CloudRedisClient.java | 2 +- 10 files changed, 54 insertions(+), 63 deletions(-) diff --git a/src/main/java/com/google/api/generator/gapic/composer/ServiceClientClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/ServiceClientClassComposer.java index 312c3bb5d0..5f6a00f4d8 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/ServiceClientClassComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/ServiceClientClassComposer.java @@ -229,7 +229,7 @@ private static List createStaticCreatorMethods( MethodDefinition createMethodOne = MethodDefinition.builder() .setHeaderCommentStatements( - ServiceClientCommentComposer.createMethodNoArgComment(service.name())) + ServiceClientCommentComposer.createMethodNoArgComment(getClientClassName(service))) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setIsFinal(true) @@ -248,7 +248,8 @@ private static List createStaticCreatorMethods( methods.add( MethodDefinition.builder() .setHeaderCommentStatements( - ServiceClientCommentComposer.createMethodSettingsArgComment(service.name())) + ServiceClientCommentComposer.createMethodSettingsArgComment( + getClientClassName(service))) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setIsFinal(true) @@ -280,7 +281,7 @@ private static List createStaticCreatorMethods( MethodDefinition.builder() .setHeaderCommentStatements( ServiceClientCommentComposer.createCreateMethodStubArgComment( - service.name(), settingsVarExpr.type())) + getClientClassName(service), settingsVarExpr.type())) .setAnnotations(Arrays.asList(betaAnnotation)) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) @@ -371,7 +372,8 @@ private static List createConstructorMethods( methods.add( MethodDefinition.constructorBuilder() .setHeaderCommentStatements( - ServiceClientCommentComposer.createProtectedCtorSettingsArgComment(service.name())) + ServiceClientCommentComposer.createProtectedCtorSettingsArgComment( + getClientClassName(service))) .setScope(ScopeNode.PROTECTED) .setReturnType(thisClassType) .setArguments(settingsVarExpr.toBuilder().setIsDecl(true).build()) diff --git a/src/main/java/com/google/api/generator/gapic/composer/ServiceClientCommentComposer.java b/src/main/java/com/google/api/generator/gapic/composer/ServiceClientCommentComposer.java index b0c2420928..09507cd30f 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/ServiceClientCommentComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/ServiceClientCommentComposer.java @@ -20,7 +20,6 @@ import com.google.api.generator.gapic.model.Method; import com.google.api.generator.gapic.model.MethodArgument; import com.google.api.generator.gapic.model.Service; -import com.google.api.generator.gapic.utils.JavaStyle; import com.google.common.base.Strings; import java.util.ArrayList; import java.util.Arrays; @@ -78,11 +77,11 @@ class ServiceClientCommentComposer { // Patterns. private static final String CREATE_METHOD_STUB_ARG_PATTERN = - "Constructs an instance of %sClient, using the given stub for making calls. This is for" + "Constructs an instance of %s, using the given stub for making calls. This is for" + " advanced usage - prefer using create(%s)."; private static final String SERVICE_DESCRIPTION_CLOSE_PATTERN = - "Note: close() needs to be called on the %sClient object to clean up resources such as " + "Note: close() needs to be called on the %s object to clean up resources such as " + "threads. In the example above, try-with-resources is used, which automatically calls " + "close()."; @@ -93,15 +92,15 @@ class ServiceClientCommentComposer { private static final String SERVICE_DESCRIPTION_SUMMARY_PATTERN = "Service Description: %s"; private static final String CREATE_METHOD_NO_ARG_PATTERN = - "Constructs an instance of %sClient with default settings."; + "Constructs an instance of %s with default settings."; private static final String CREATE_METHOD_SETTINGS_ARG_PATTERN = - "Constructs an instance of %sClient, using the given settings. The channels are" + "Constructs an instance of %s, using the given settings. The channels are" + " created based on the settings passed in, or defaults for any settings that are" + " not set."; private static final String PROTECTED_CONSTRUCTOR_SETTINGS_ARG_PATTERN = - "Constructs an instance of %sClient, using the given settings. This is protected so" + "Constructs an instance of %s, using the given settings. This is protected so" + " that it is easy to make a subclass, but otherwise, the static factory methods" + " should be preferred."; @@ -128,8 +127,7 @@ static List createClassHeaderComments( // API surface description. classHeaderJavadocBuilder.addParagraph( - String.format( - SERVICE_DESCRIPTION_CLOSE_PATTERN, JavaStyle.toLowerCamelCase(service.name()))); + String.format(SERVICE_DESCRIPTION_CLOSE_PATTERN, getClientClassName(service))); classHeaderJavadocBuilder.addParagraph(SERVICE_DESCRIPTION_SURFACE_SUMMARY_STRING); classHeaderJavadocBuilder.addOrderedList(SERVICE_DESCRIPTION_SURFACE_DESCRIPTION); classHeaderJavadocBuilder.addParagraph(SERVICE_DESCRIPTION_SURFACE_CODA_STRING); @@ -139,9 +137,7 @@ static List createClassHeaderComments( // Customization examples. classHeaderJavadocBuilder.addParagraph( - String.format( - SERVICE_DESCRIPTION_CUSTOMIZE_SUMMARY_PATTERN, - String.format("%sSettings", JavaStyle.toUpperCamelCase(service.name())))); + String.format(SERVICE_DESCRIPTION_CUSTOMIZE_SUMMARY_PATTERN, getSettingsName(service))); classHeaderJavadocBuilder.addParagraph(SERVICE_DESCRIPTION_CREDENTIALS_SUMMARY_STRING); classHeaderJavadocBuilder.addSampleCode( ServiceClientSampleCodeComposer.composeClassHeaderCredentialsSampleCode( @@ -273,11 +269,11 @@ private static JavaDocComment.Builder processProtobufComment( return commentBuilder; } - private static String getSettingsName(String serviceName) { - return String.format(SETTINGS_NAME_PATTERN, serviceName); + private static String getSettingsName(Service service) { + return String.format(SETTINGS_NAME_PATTERN, service.overriddenName()); } - private static String getClientClassName(String serviceName) { - return String.format(CLASS_NAME_PATTERN, serviceName); + private static String getClientClassName(Service service) { + return String.format(CLASS_NAME_PATTERN, service.overriddenName()); } } diff --git a/src/main/java/com/google/api/generator/gapic/composer/SettingsCommentComposer.java b/src/main/java/com/google/api/generator/gapic/composer/SettingsCommentComposer.java index cc8cc94d15..5c49d38058 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/SettingsCommentComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/SettingsCommentComposer.java @@ -29,7 +29,6 @@ class SettingsCommentComposer { private static final String COLON = ":"; - private static final String CLIENT_CLASS_NAME_PATTERN = "%sClient"; private static final String STUB_PATTERN = "%sStub"; private static final String BUILDER_CLASS_DOC_PATTERN = "Builder for %s."; private static final String CALL_SETTINGS_METHOD_DOC_PATTERN = diff --git a/src/test/java/com/google/api/generator/gapic/composer/goldens/EchoClient.golden b/src/test/java/com/google/api/generator/gapic/composer/goldens/EchoClient.golden index 39b4cbc8a6..2accd6e59d 100644 --- a/src/test/java/com/google/api/generator/gapic/composer/goldens/EchoClient.golden +++ b/src/test/java/com/google/api/generator/gapic/composer/goldens/EchoClient.golden @@ -35,7 +35,7 @@ import javax.annotation.Generated; * This class provides the ability to make remote calls to the backing service through method calls * that map to API methods. Sample code to get started: * - *

Note: close() needs to be called on the echoClient object to clean up resources such as + *

Note: close() needs to be called on the EchoClient object to clean up resources such as * threads. In the example above, try-with-resources is used, which automatically calls close(). * *

The surface of this class includes several types of Java methods for each of the API's diff --git a/src/test/java/com/google/api/generator/gapic/composer/goldens/IdentityClient.golden b/src/test/java/com/google/api/generator/gapic/composer/goldens/IdentityClient.golden index ac197d5dcf..091e335eee 100644 --- a/src/test/java/com/google/api/generator/gapic/composer/goldens/IdentityClient.golden +++ b/src/test/java/com/google/api/generator/gapic/composer/goldens/IdentityClient.golden @@ -25,7 +25,7 @@ import javax.annotation.Generated; * This class provides the ability to make remote calls to the backing service through method calls * that map to API methods. Sample code to get started: * - *

Note: close() needs to be called on the identityClient object to clean up resources such as + *

Note: close() needs to be called on the IdentityClient object to clean up resources such as * threads. In the example above, try-with-resources is used, which automatically calls close(). * *

The surface of this class includes several types of Java methods for each of the API's diff --git a/test/integration/goldens/asset/AssetServiceClient.java b/test/integration/goldens/asset/AssetServiceClient.java index 5a37e2acf2..dad79b7391 100644 --- a/test/integration/goldens/asset/AssetServiceClient.java +++ b/test/integration/goldens/asset/AssetServiceClient.java @@ -47,7 +47,7 @@ *

This class provides the ability to make remote calls to the backing service through method * calls that map to API methods. Sample code to get started: * - *

Note: close() needs to be called on the assetServiceClient object to clean up resources such + *

Note: close() needs to be called on the AssetServiceClient object to clean up resources such * as threads. In the example above, try-with-resources is used, which automatically calls close(). * *

The surface of this class includes several types of Java methods for each of the API's diff --git a/test/integration/goldens/logging/ConfigClient.java b/test/integration/goldens/logging/ConfigClient.java index 74850634d5..14f8749dc1 100644 --- a/test/integration/goldens/logging/ConfigClient.java +++ b/test/integration/goldens/logging/ConfigClient.java @@ -76,9 +76,8 @@ *

This class provides the ability to make remote calls to the backing service through method * calls that map to API methods. Sample code to get started: * - *

Note: close() needs to be called on the configServiceV2Client object to clean up resources - * such as threads. In the example above, try-with-resources is used, which automatically calls - * close(). + *

Note: close() needs to be called on the ConfigClient object to clean up resources such as + * threads. In the example above, try-with-resources is used, which automatically calls close(). * *

The surface of this class includes several types of Java methods for each of the API's * methods: @@ -100,8 +99,8 @@ * these names, this class includes a format method for each type of name, and additionally a parse * method to extract the individual identifiers contained within names that are returned. * - *

This class can be customized by passing in a custom instance of ConfigServiceV2Settings to - * create(). For example: + *

This class can be customized by passing in a custom instance of ConfigSettings to create(). + * For example: * *

To customize credentials: * @@ -128,22 +127,22 @@ public class ConfigClient implements BackgroundResource { private final ConfigSettings settings; private final ConfigServiceV2Stub stub; - /** Constructs an instance of ConfigServiceV2Client with default settings. */ + /** Constructs an instance of ConfigClient with default settings. */ public static final ConfigClient create() throws IOException { return create(ConfigSettings.newBuilder().build()); } /** - * Constructs an instance of ConfigServiceV2Client, using the given settings. The channels are - * created based on the settings passed in, or defaults for any settings that are not set. + * Constructs an instance of ConfigClient, using the given settings. The channels are created + * based on the settings passed in, or defaults for any settings that are not set. */ public static final ConfigClient create(ConfigSettings settings) throws IOException { return new ConfigClient(settings); } /** - * Constructs an instance of ConfigServiceV2Client, using the given stub for making calls. This is - * for advanced usage - prefer using create(ConfigSettings). + * Constructs an instance of ConfigClient, using the given stub for making calls. This is for + * advanced usage - prefer using create(ConfigSettings). */ @BetaApi("A restructuring of stub classes is planned, so this may break in the future") public static final ConfigClient create(ConfigServiceV2Stub stub) { @@ -151,9 +150,8 @@ public static final ConfigClient create(ConfigServiceV2Stub stub) { } /** - * Constructs an instance of ConfigServiceV2Client, using the given settings. This is protected so - * that it is easy to make a subclass, but otherwise, the static factory methods should be - * preferred. + * Constructs an instance of ConfigClient, using the given settings. This is protected so that it + * is easy to make a subclass, but otherwise, the static factory methods should be preferred. */ protected ConfigClient(ConfigSettings settings) throws IOException { this.settings = settings; diff --git a/test/integration/goldens/logging/LoggingClient.java b/test/integration/goldens/logging/LoggingClient.java index 39cc711385..8b80772613 100644 --- a/test/integration/goldens/logging/LoggingClient.java +++ b/test/integration/goldens/logging/LoggingClient.java @@ -61,9 +61,8 @@ *

This class provides the ability to make remote calls to the backing service through method * calls that map to API methods. Sample code to get started: * - *

Note: close() needs to be called on the loggingServiceV2Client object to clean up resources - * such as threads. In the example above, try-with-resources is used, which automatically calls - * close(). + *

Note: close() needs to be called on the LoggingClient object to clean up resources such as + * threads. In the example above, try-with-resources is used, which automatically calls close(). * *

The surface of this class includes several types of Java methods for each of the API's * methods: @@ -85,8 +84,8 @@ * these names, this class includes a format method for each type of name, and additionally a parse * method to extract the individual identifiers contained within names that are returned. * - *

This class can be customized by passing in a custom instance of LoggingServiceV2Settings to - * create(). For example: + *

This class can be customized by passing in a custom instance of LoggingSettings to create(). + * For example: * *

To customize credentials: * @@ -113,22 +112,22 @@ public class LoggingClient implements BackgroundResource { private final LoggingSettings settings; private final LoggingServiceV2Stub stub; - /** Constructs an instance of LoggingServiceV2Client with default settings. */ + /** Constructs an instance of LoggingClient with default settings. */ public static final LoggingClient create() throws IOException { return create(LoggingSettings.newBuilder().build()); } /** - * Constructs an instance of LoggingServiceV2Client, using the given settings. The channels are - * created based on the settings passed in, or defaults for any settings that are not set. + * Constructs an instance of LoggingClient, using the given settings. The channels are created + * based on the settings passed in, or defaults for any settings that are not set. */ public static final LoggingClient create(LoggingSettings settings) throws IOException { return new LoggingClient(settings); } /** - * Constructs an instance of LoggingServiceV2Client, using the given stub for making calls. This - * is for advanced usage - prefer using create(LoggingSettings). + * Constructs an instance of LoggingClient, using the given stub for making calls. This is for + * advanced usage - prefer using create(LoggingSettings). */ @BetaApi("A restructuring of stub classes is planned, so this may break in the future") public static final LoggingClient create(LoggingServiceV2Stub stub) { @@ -136,9 +135,8 @@ public static final LoggingClient create(LoggingServiceV2Stub stub) { } /** - * Constructs an instance of LoggingServiceV2Client, using the given settings. This is protected - * so that it is easy to make a subclass, but otherwise, the static factory methods should be - * preferred. + * Constructs an instance of LoggingClient, using the given settings. This is protected so that it + * is easy to make a subclass, but otherwise, the static factory methods should be preferred. */ protected LoggingClient(LoggingSettings settings) throws IOException { this.settings = settings; diff --git a/test/integration/goldens/logging/MetricsClient.java b/test/integration/goldens/logging/MetricsClient.java index 4295940815..ab7d4fde63 100644 --- a/test/integration/goldens/logging/MetricsClient.java +++ b/test/integration/goldens/logging/MetricsClient.java @@ -52,9 +52,8 @@ *

This class provides the ability to make remote calls to the backing service through method * calls that map to API methods. Sample code to get started: * - *

Note: close() needs to be called on the metricsServiceV2Client object to clean up resources - * such as threads. In the example above, try-with-resources is used, which automatically calls - * close(). + *

Note: close() needs to be called on the MetricsClient object to clean up resources such as + * threads. In the example above, try-with-resources is used, which automatically calls close(). * *

The surface of this class includes several types of Java methods for each of the API's * methods: @@ -76,8 +75,8 @@ * these names, this class includes a format method for each type of name, and additionally a parse * method to extract the individual identifiers contained within names that are returned. * - *

This class can be customized by passing in a custom instance of MetricsServiceV2Settings to - * create(). For example: + *

This class can be customized by passing in a custom instance of MetricsSettings to create(). + * For example: * *

To customize credentials: * @@ -104,22 +103,22 @@ public class MetricsClient implements BackgroundResource { private final MetricsSettings settings; private final MetricsServiceV2Stub stub; - /** Constructs an instance of MetricsServiceV2Client with default settings. */ + /** Constructs an instance of MetricsClient with default settings. */ public static final MetricsClient create() throws IOException { return create(MetricsSettings.newBuilder().build()); } /** - * Constructs an instance of MetricsServiceV2Client, using the given settings. The channels are - * created based on the settings passed in, or defaults for any settings that are not set. + * Constructs an instance of MetricsClient, using the given settings. The channels are created + * based on the settings passed in, or defaults for any settings that are not set. */ public static final MetricsClient create(MetricsSettings settings) throws IOException { return new MetricsClient(settings); } /** - * Constructs an instance of MetricsServiceV2Client, using the given stub for making calls. This - * is for advanced usage - prefer using create(MetricsSettings). + * Constructs an instance of MetricsClient, using the given stub for making calls. This is for + * advanced usage - prefer using create(MetricsSettings). */ @BetaApi("A restructuring of stub classes is planned, so this may break in the future") public static final MetricsClient create(MetricsServiceV2Stub stub) { @@ -127,9 +126,8 @@ public static final MetricsClient create(MetricsServiceV2Stub stub) { } /** - * Constructs an instance of MetricsServiceV2Client, using the given settings. This is protected - * so that it is easy to make a subclass, but otherwise, the static factory methods should be - * preferred. + * Constructs an instance of MetricsClient, using the given settings. This is protected so that it + * is easy to make a subclass, but otherwise, the static factory methods should be preferred. */ protected MetricsClient(MetricsSettings settings) throws IOException { this.settings = settings; diff --git a/test/integration/goldens/redis/CloudRedisClient.java b/test/integration/goldens/redis/CloudRedisClient.java index bc41aebf84..a65989a9f7 100644 --- a/test/integration/goldens/redis/CloudRedisClient.java +++ b/test/integration/goldens/redis/CloudRedisClient.java @@ -67,7 +67,7 @@ *

This class provides the ability to make remote calls to the backing service through method * calls that map to API methods. Sample code to get started: * - *

Note: close() needs to be called on the cloudRedisClient object to clean up resources such as + *

Note: close() needs to be called on the CloudRedisClient object to clean up resources such as * threads. In the example above, try-with-resources is used, which automatically calls close(). * *

The surface of this class includes several types of Java methods for each of the API's