diff --git a/src/main/java/com/google/api/generator/spring/composer/SpringAutoConfigClassComposer.java b/src/main/java/com/google/api/generator/spring/composer/SpringAutoConfigClassComposer.java index b45d858bb3..952d79335e 100644 --- a/src/main/java/com/google/api/generator/spring/composer/SpringAutoConfigClassComposer.java +++ b/src/main/java/com/google/api/generator/spring/composer/SpringAutoConfigClassComposer.java @@ -48,6 +48,7 @@ import com.google.api.generator.gapic.model.GapicContext; import com.google.api.generator.gapic.model.GapicServiceConfig; import com.google.api.generator.gapic.model.Service; +import com.google.api.generator.spring.composer.comment.SpringAutoconfigCommentComposer; import com.google.api.generator.spring.utils.LoggerUtils; import com.google.api.generator.spring.utils.Utils; import com.google.common.base.CaseFormat; @@ -100,6 +101,8 @@ public GapicClass generate(GapicContext context, Service service) { .setPackageString(packageName) .setName(className) .setScope(ScopeNode.PUBLIC) + .setHeaderCommentStatements( + SpringAutoconfigCommentComposer.createClassHeaderComments(className, serviceName)) .setStatements(createMemberVariables(service, packageName, types, gapicServiceConfig)) .setMethods( Arrays.asList( @@ -331,6 +334,8 @@ private static MethodDefinition createCredentialsProviderBeanMethod( return MethodDefinition.builder() .setName(methodName) + .setHeaderCommentStatements( + SpringAutoconfigCommentComposer.createCredentialsProviderBeanComment()) .setScope(ScopeNode.PUBLIC) .setReturnType(types.get("CredentialsProvider")) .setAnnotations( @@ -359,6 +364,8 @@ private static MethodDefinition createTransportChannelProviderBeanMethod( .build(); return MethodDefinition.builder() + .setHeaderCommentStatements( + SpringAutoconfigCommentComposer.createTransportChannelProviderComment()) .setName(methodName) .setScope(ScopeNode.PUBLIC) .setReturnType(STATIC_TYPES.get("TransportChannelProvider")) @@ -780,8 +787,15 @@ private static MethodDefinition createClientBeanMethod( .setArguments(serviceSettingsBuilt) .build(); + String methodName = + CaseFormat.UPPER_CAMEL.to(CaseFormat.LOWER_CAMEL, service.name()) + "Client"; + String propertiesClassName = service.name() + "Properties"; + return MethodDefinition.builder() - .setName(clientName) + .setHeaderCommentStatements( + SpringAutoconfigCommentComposer.createClientBeanComment( + service.name(), propertiesClassName, transportChannelProviderName)) + .setName(methodName) .setScope(ScopeNode.PUBLIC) .setReturnType(types.get("ServiceClient")) .setArguments( diff --git a/src/main/java/com/google/api/generator/spring/composer/SpringPropertiesClassComposer.java b/src/main/java/com/google/api/generator/spring/composer/SpringPropertiesClassComposer.java index 00c1c3557f..618f6f933b 100644 --- a/src/main/java/com/google/api/generator/spring/composer/SpringPropertiesClassComposer.java +++ b/src/main/java/com/google/api/generator/spring/composer/SpringPropertiesClassComposer.java @@ -41,6 +41,7 @@ import com.google.api.generator.gapic.model.GapicContext; import com.google.api.generator.gapic.model.GapicServiceConfig; import com.google.api.generator.gapic.model.Service; +import com.google.api.generator.spring.composer.comment.SpringPropertiesCommentComposer; import com.google.api.generator.spring.utils.Utils; import com.google.common.base.CaseFormat; import com.google.common.base.Joiner; @@ -80,6 +81,9 @@ public GapicClass generate(GapicContext context, Service service) { ClassDefinition classDef = ClassDefinition.builder() + .setHeaderCommentStatements( + SpringPropertiesCommentComposer.createClassHeaderComments( + className, service.name())) .setPackageString(packageName) .setName(className) .setScope(ScopeNode.PUBLIC) diff --git a/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java b/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java new file mode 100644 index 0000000000..171ae79909 --- /dev/null +++ b/src/main/java/com/google/api/generator/spring/composer/comment/SpringAutoconfigCommentComposer.java @@ -0,0 +1,106 @@ +// Copyright 2022 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package com.google.api.generator.spring.composer.comment; + +import com.google.api.generator.engine.ast.CommentStatement; +import com.google.api.generator.engine.ast.JavaDocComment; +import com.google.api.generator.gapic.composer.comment.CommentComposer; +import com.google.common.base.CaseFormat; +import java.util.Arrays; +import java.util.List; + +public class SpringAutoconfigCommentComposer { + + private static final String CLASS_HEADER_SUMMARY_PATTERN = + "Auto-configuration for {@link %sClient}."; + private static final String CLASS_HEADER_GENERAL_DESCRIPTION = + "Provides auto-configuration for Spring Boot"; + private static final String CLASS_HEADER_DEFAULTS_DESCRIPTION = + "The default instance has everything set to sensible defaults:"; + private static final String CLASS_HEADER_DEFAULTS_CREDENTIALS_DESCRIPTION = + "Credentials are acquired automatically through Application Default Credentials."; + private static final String CLASS_HEADER_DEFAULTS_TRANSPORT_DESCRIPTION = + "The default transport provider is used."; + private static final String CLASS_HEADER_DEFAULTS_RETRIES_DESCRIPTION = + "Retries are configured for idempotent methods but not for non-idempotent methods."; + + public static final String CREDENTIALS_PROVIDER_GENERAL_DESCRIPTION = + "Obtains the default credentials provider. The used key will be obtained from Spring Boot " + + "configuration data files."; + + public static final String TRANSPORT_CHANNEL_PROVIDER_GENERAL_DESCRIPTION = + "Returns the default channel provider. The default is gRPC and will default to it unless the " + + "useRest option is provided to use HTTP transport instead"; + public static final String CLIENT_BEAN_GENERAL_DESCRIPTION = + "Provides a %sClient bean configured to " + + "use the default credentials provider (obtained with %sCredentials()) and its default " + + "transport channel provider (%s()). It also configures the quota project ID if provided. It " + + "will configure an executor provider in case there is more than one thread configured " + + "in the client "; + + public static final String CLIENT_BEAN_RETRY_SETTINGS_DESCRIPTION = + "Individual retry settings " + + "are configured as well. It will use the relevant client library's default retry " + + "settings when they are not specified in %s."; + + public SpringAutoconfigCommentComposer() {} + + public static List createClassHeaderComments( + String configuredClassName, String serviceName) { + + JavaDocComment.Builder javaDocCommentBuilder = + JavaDocComment.builder() + .addUnescapedComment(String.format(CLASS_HEADER_SUMMARY_PATTERN, serviceName)) + .addParagraph(CLASS_HEADER_GENERAL_DESCRIPTION) + .addParagraph(CLASS_HEADER_DEFAULTS_DESCRIPTION) + .addUnorderedList( + Arrays.asList( + CLASS_HEADER_DEFAULTS_TRANSPORT_DESCRIPTION, + CLASS_HEADER_DEFAULTS_CREDENTIALS_DESCRIPTION, + CLASS_HEADER_DEFAULTS_RETRIES_DESCRIPTION)); + + return Arrays.asList( + CommentComposer.AUTO_GENERATED_CLASS_COMMENT, + CommentStatement.withComment(javaDocCommentBuilder.build())); + } + + public static CommentStatement createCredentialsProviderBeanComment() { + return CommentStatement.withComment( + JavaDocComment.builder().addParagraph(CREDENTIALS_PROVIDER_GENERAL_DESCRIPTION).build()); + } + + public static CommentStatement createTransportChannelProviderComment() { + return CommentStatement.withComment( + JavaDocComment.builder() + .addParagraph(TRANSPORT_CHANNEL_PROVIDER_GENERAL_DESCRIPTION) + .build()); + } + + public static CommentStatement createClientBeanComment( + String serviceName, String propertiesClazzName, String channelProviderName) { + String credentialsBaseName = CaseFormat.UPPER_CAMEL.to(CaseFormat.LOWER_CAMEL, serviceName); + return CommentStatement.withComment( + JavaDocComment.builder() + .addParagraph( + String.format( + CLIENT_BEAN_GENERAL_DESCRIPTION, + serviceName, + credentialsBaseName, + channelProviderName)) + .addParagraph( + String.format(CLIENT_BEAN_RETRY_SETTINGS_DESCRIPTION, propertiesClazzName)) + .build()); + } +} diff --git a/src/main/java/com/google/api/generator/spring/composer/comment/SpringPropertiesCommentComposer.java b/src/main/java/com/google/api/generator/spring/composer/comment/SpringPropertiesCommentComposer.java new file mode 100644 index 0000000000..6d05240eea --- /dev/null +++ b/src/main/java/com/google/api/generator/spring/composer/comment/SpringPropertiesCommentComposer.java @@ -0,0 +1,37 @@ +// Copyright 2022 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package com.google.api.generator.spring.composer.comment; + +import com.google.api.generator.engine.ast.CommentStatement; +import com.google.api.generator.engine.ast.JavaDocComment; +import com.google.api.generator.gapic.composer.comment.CommentComposer; +import java.util.Arrays; +import java.util.List; + +public class SpringPropertiesCommentComposer { + private static final String CLASS_HEADER_GENERAL_DESCRIPTION = + "Provides default property values for %s client bean"; + + public static List createClassHeaderComments( + String configuredClassName, String serviceName) { + + JavaDocComment.Builder javaDocCommentBuilder = + JavaDocComment.builder() + .addParagraph(String.format(CLASS_HEADER_GENERAL_DESCRIPTION, serviceName)); + return Arrays.asList( + CommentComposer.AUTO_GENERATED_CLASS_COMMENT, + CommentStatement.withComment(javaDocCommentBuilder.build())); + } +} diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfiguration.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfiguration.golden index 6800a70f8c..95cfa7bff9 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfiguration.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfiguration.golden @@ -19,6 +19,20 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties import org.springframework.context.annotation.Bean; import org.threeten.bp.Duration; +// AUTO-GENERATED DOCUMENTATION AND CLASS. +/** + * Auto-configuration for {@link EchoClient}. + * + *

Provides auto-configuration for Spring Boot + * + *

The default instance has everything set to sensible defaults: + * + *

+ */ @AutoConfiguration @ConditionalOnClass(EchoClient.class) @ConditionalOnProperty( @@ -33,18 +47,36 @@ public class EchoSpringAutoConfiguration { this.clientProperties = clientProperties; } + /** + * Obtains the default credentials provider. The used key will be obtained from Spring Boot + * configuration data files. + */ @Bean @ConditionalOnMissingBean public CredentialsProvider echoCredentials() throws IOException { return ((CredentialsProvider) new DefaultCredentialsProvider(this.clientProperties)); } + /** + * Returns the default channel provider. The default is gRPC and will default to it unless the + * useRest option is provided to use HTTP transport instead + */ @Bean @ConditionalOnMissingBean public TransportChannelProvider defaultEchoTransportChannelProvider() { return EchoSettings.defaultTransportChannelProvider(); } + /** + * Provides a EchoClient bean configured to use the default credentials provider (obtained with + * echoCredentials()) and its default transport channel provider + * (defaultEchoTransportChannelProvider()). It also configures the quota project ID if provided. + * It will configure an executor provider in case there is more than one thread configured in the + * client + * + *

Individual retry settings are configured as well. It will use the relevant client library's + * default retry settings when they are not specified in EchoProperties. + */ @Bean @ConditionalOnMissingBean public EchoClient echoClient( diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden index 25df0158b4..fea5f436ba 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringAutoConfigurationFull.golden @@ -37,6 +37,20 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties import org.springframework.context.annotation.Bean; import org.threeten.bp.Duration; +// AUTO-GENERATED DOCUMENTATION AND CLASS. +/** + * Auto-configuration for {@link EchoClient}. + * + *

Provides auto-configuration for Spring Boot + * + *

The default instance has everything set to sensible defaults: + * + *

+ */ @Generated("by gapic-generator-java") @BetaApi("Autogenerated Spring autoconfiguration is not yet stable") @AutoConfiguration @@ -53,18 +67,36 @@ public class EchoSpringAutoConfiguration { this.clientProperties = clientProperties; } + /** + * Obtains the default credentials provider. The used key will be obtained from Spring Boot + * configuration data files. + */ @Bean @ConditionalOnMissingBean public CredentialsProvider echoCredentials() throws IOException { return ((CredentialsProvider) new DefaultCredentialsProvider(this.clientProperties)); } + /** + * Returns the default channel provider. The default is gRPC and will default to it unless the + * useRest option is provided to use HTTP transport instead + */ @Bean @ConditionalOnMissingBean public TransportChannelProvider defaultEchoTransportChannelProvider() { return EchoSettings.defaultTransportChannelProvider(); } + /** + * Provides a EchoClient bean configured to use the default credentials provider (obtained with + * echoCredentials()) and its default transport channel provider + * (defaultEchoTransportChannelProvider()). It also configures the quota project ID if provided. + * It will configure an executor provider in case there is more than one thread configured in the + * client + * + *

Individual retry settings are configured as well. It will use the relevant client library's + * default retry settings when they are not specified in EchoProperties. + */ @Bean @ConditionalOnMissingBean public EchoClient echoClient( diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringProperties.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringProperties.golden index 5fe2406751..28f0e8612d 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringProperties.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringProperties.golden @@ -5,6 +5,8 @@ import com.google.cloud.spring.core.CredentialsSupplier; import org.springframework.boot.context.properties.ConfigurationProperties; import org.threeten.bp.Duration; +// AUTO-GENERATED DOCUMENTATION AND CLASS. +/** Provides default property values for Echo client bean */ @ConfigurationProperties("com.google.showcase.v1beta1.spring.auto.echo") public class EchoSpringProperties implements CredentialsSupplier { @NestedConfigurationProperty diff --git a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringPropertiesFull.golden b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringPropertiesFull.golden index c0a5400e7e..fe1ab2fb5f 100644 --- a/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringPropertiesFull.golden +++ b/src/test/java/com/google/api/generator/spring/composer/goldens/EchoSpringPropertiesFull.golden @@ -23,6 +23,8 @@ import javax.annotation.Generated; import org.springframework.boot.context.properties.ConfigurationProperties; import org.threeten.bp.Duration; +// AUTO-GENERATED DOCUMENTATION AND CLASS. +/** Provides default property values for Echo client bean */ @Generated("by gapic-generator-java") @BetaApi("Autogenerated Spring autoconfiguration is not yet stable") @ConfigurationProperties("com.google.showcase.v1beta1.spring.auto.echo")