diff --git a/src/main/java/com/google/api/generator/engine/ast/ClassDefinition.java b/src/main/java/com/google/api/generator/engine/ast/ClassDefinition.java index 3098d5e32f..f5f9f0feb1 100644 --- a/src/main/java/com/google/api/generator/engine/ast/ClassDefinition.java +++ b/src/main/java/com/google/api/generator/engine/ast/ClassDefinition.java @@ -173,9 +173,9 @@ public ClassDefinition build() { for (Statement statement : classDef.statements()) { Preconditions.checkState( - statement instanceof ExprStatement - || statement instanceof BlockStatement - || statement instanceof CommentStatement, + statement instanceof CommentStatement + || statement instanceof ExprStatement + || statement instanceof BlockStatement, "Class statement type must be either an expression, block, or comment statement"); if (statement instanceof ExprStatement) { Expr expr = ((ExprStatement) statement).expression(); diff --git a/src/main/java/com/google/api/generator/gapic/composer/ServiceSettingsClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/ServiceSettingsClassComposer.java index dd5d08cd2f..070e860fe5 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/ServiceSettingsClassComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/ServiceSettingsClassComposer.java @@ -32,6 +32,7 @@ import com.google.api.generator.engine.ast.AnnotationNode; import com.google.api.generator.engine.ast.CastExpr; import com.google.api.generator.engine.ast.ClassDefinition; +import com.google.api.generator.engine.ast.CommentStatement; import com.google.api.generator.engine.ast.ConcreteReference; import com.google.api.generator.engine.ast.Expr; import com.google.api.generator.engine.ast.ExprStatement; @@ -61,9 +62,9 @@ import java.util.ArrayList; import java.util.Arrays; import java.util.HashMap; -import java.util.LinkedHashMap; import java.util.List; import java.util.Map; +import java.util.Optional; import java.util.function.BiFunction; import java.util.function.Function; import java.util.stream.Collectors; @@ -72,10 +73,14 @@ public class ServiceSettingsClassComposer implements ClassComposer { private static final String BUILDER_CLASS_NAME = "Builder"; private static final String CLASS_NAME_PATTERN = "%sSettings"; + private static final String CLIENT_CLASS_NAME_PATTERN = "%sClient"; private static final String CALL_SETTINGS_TYPE_NAME_PATTERN = "%sCallSettings"; private static final String PAGED_RESPONSE_TYPE_NAME_PATTERN = "%sPagedResponse"; private static final String STUB_SETTINGS_PATTERN = "%sStubSettings"; + private static final String OPERATION_SETTINGS_LITERAL = "OperationSettings"; + private static final String SETTINGS_LITERAL = "Settings"; + private static final ServiceSettingsClassComposer INSTANCE = new ServiceSettingsClassComposer(); private static final Map staticTypes = createStaticTypes(); @@ -96,6 +101,7 @@ public GapicClass generate(Service service, Map ignore) { ClassDefinition classDef = ClassDefinition.builder() .setPackageString(pakkage) + .setHeaderCommentStatements(createClassHeaderComments(service)) .setAnnotations(createClassAnnotations()) .setScope(ScopeNode.PUBLIC) .setName(className) @@ -113,6 +119,13 @@ public GapicClass generate(Service service, Map ignore) { return GapicClass.create(kind, classDef); } + private static List createClassHeaderComments(Service service) { + Optional methodOpt = + service.methods().isEmpty() ? Optional.empty() : Optional.of(service.methods().get(0)); + return SettingsCommentComposer.createClassHeaderComments( + getClientClassName(service.name()), service.defaultHost(), methodOpt); + } + private static List createClassAnnotations() { return Arrays.asList( AnnotationNode.builder() @@ -162,6 +175,9 @@ private static List createSettingsGetterMethods( BiFunction methodMakerFn = (retType, methodName) -> MethodDefinition.builder() + .setHeaderCommentStatements( + SettingsCommentComposer.createCallSettingsGetterComment( + getMethodNameFromSettingsVarName(methodName))) .setScope(ScopeNode.PUBLIC) .setReturnType(retType) .setName(methodName) @@ -242,9 +258,7 @@ private static MethodDefinition createCreatorMethod( private static List createDefaultGetterMethods( Service service, Map types) { - Map javaMethodNameToReturnType = createDefaultMethodNamesToTypes(); - - BiFunction methodMakerFn = + BiFunction methodStarterFn = (mName, retType) -> MethodDefinition.builder() .setScope(ScopeNode.PUBLIC) @@ -256,20 +270,59 @@ private static List createDefaultGetterMethods( .setStaticReferenceType(types.get(getStubSettingsClassName(service.name()))) .setMethodName(mName) .setReturnType(retType) - .build()) - .build(); + .build()); + BiFunction methodMakerFn = + (methodDefBuilder, comment) -> methodDefBuilder.setHeaderCommentStatements(comment).build(); + Function typeMakerFn = + c -> TypeNode.withReference(ConcreteReference.withClazz(c)); + List javaMethods = new ArrayList<>(); - javaMethods.addAll( - javaMethodNameToReturnType.entrySet().stream() - .map(e -> methodMakerFn.apply(e.getKey(), e.getValue())) - .collect(Collectors.toList())); javaMethods.add( - methodMakerFn + methodMakerFn.apply( + methodStarterFn.apply( + "defaultExecutorProviderBuilder", + typeMakerFn.apply(InstantiatingExecutorProvider.Builder.class)), + SettingsCommentComposer.DEFAULT_EXECUTOR_PROVIDER_BUILDER_METHOD_COMMENT)); + javaMethods.add( + methodMakerFn.apply( + methodStarterFn.apply("getDefaultEndpoint", TypeNode.STRING), + SettingsCommentComposer.DEFAULT_SERVICE_ENDPOINT_METHOD_COMMENT)); + javaMethods.add( + methodMakerFn.apply( + methodStarterFn.apply( + "getDefaultServiceScopes", + TypeNode.withReference( + ConcreteReference.builder() + .setClazz(List.class) + .setGenerics(Arrays.asList(TypeNode.STRING.reference())) + .build())), + SettingsCommentComposer.DEFAULT_SERVICE_SCOPES_METHOD_COMMENT)); + javaMethods.add( + methodMakerFn.apply( + methodStarterFn.apply( + "defaultCredentialsProviderBuilder", + typeMakerFn.apply(GoogleCredentialsProvider.Builder.class)), + SettingsCommentComposer.DEFAULT_CREDENTIALS_PROVIDER_BUILDER_METHOD_COMMENT)); + javaMethods.add( + methodMakerFn.apply( + methodStarterFn.apply( + "defaultGrpcTransportProviderBuilder", + typeMakerFn.apply(InstantiatingGrpcChannelProvider.Builder.class)), + SettingsCommentComposer.DEFAULT_GRPC_TRANSPORT_PROVIDER_BUILDER_METHOD_COMMENT)); + + javaMethods.add( + methodStarterFn + .apply( + "defaultTransportChannelProvider", + typeMakerFn.apply(TransportChannelProvider.class)) + .build()); + + javaMethods.add( + methodStarterFn .apply( "defaultApiClientHeaderProviderBuilder", TypeNode.withReference( ConcreteReference.withClazz(ApiClientHeaderProvider.Builder.class))) - .toBuilder() .setAnnotations( Arrays.asList( AnnotationNode.builder() @@ -287,6 +340,7 @@ private static List createBuilderHelperMethods( TypeNode builderType = types.get(BUILDER_CLASS_NAME); MethodDefinition newBuilderMethodOne = MethodDefinition.builder() + .setHeaderCommentStatements(SettingsCommentComposer.NEW_BUILDER_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setReturnType(builderType) @@ -308,6 +362,7 @@ private static List createBuilderHelperMethods( MethodDefinition newBuilderMethodTwo = MethodDefinition.builder() + .setHeaderCommentStatements(SettingsCommentComposer.NEW_BUILDER_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setReturnType(builderType) @@ -322,6 +377,7 @@ private static List createBuilderHelperMethods( MethodDefinition toBuilderMethod = MethodDefinition.builder() + .setHeaderCommentStatements(SettingsCommentComposer.TO_BUILDER_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setReturnType(builderType) .setName("toBuilder") @@ -340,6 +396,8 @@ private static List createBuilderHelperMethods( private static ClassDefinition createNestedBuilderClass( Service service, Map types) { return ClassDefinition.builder() + .setHeaderCommentStatements( + SettingsCommentComposer.createBuilderClassComment(getThisClassName(service.name()))) .setIsNested(true) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) @@ -531,6 +589,8 @@ private static MethodDefinition createNestedBuilderApplyToAllUnaryMethod( .build(); return MethodDefinition.builder() + .setHeaderCommentStatements( + SettingsCommentComposer.APPLY_TO_ALL_UNARY_METHODS_METHOD_COMMENTS) .setScope(ScopeNode.PUBLIC) .setReturnType(builderType) .setName(javaMethodName) @@ -547,6 +607,9 @@ private static List createNestedBuilderSettingsGetterMethods( BiFunction methodMakerFn = (retType, methodName) -> MethodDefinition.builder() + .setHeaderCommentStatements( + SettingsCommentComposer.createCallSettingsBuilderGetterComment( + getMethodNameFromSettingsVarName(methodName))) .setScope(ScopeNode.PUBLIC) .setReturnType(retType) .setName(methodName) @@ -623,32 +686,6 @@ private static Map createStaticTypes() { c -> TypeNode.withReference(ConcreteReference.withClazz(c)))); } - private static Map createDefaultMethodNamesToTypes() { - Function typeMakerFn = - c -> TypeNode.withReference(ConcreteReference.withClazz(c)); - Map javaMethodNameToReturnType = new LinkedHashMap<>(); - javaMethodNameToReturnType.put( - "defaultExecutorProviderBuilder", - typeMakerFn.apply(InstantiatingExecutorProvider.Builder.class)); - javaMethodNameToReturnType.put("getDefaultEndpoint", TypeNode.STRING); - javaMethodNameToReturnType.put( - "getDefaultServiceScopes", - TypeNode.withReference( - ConcreteReference.builder() - .setClazz(List.class) - .setGenerics(Arrays.asList(TypeNode.STRING.reference())) - .build())); - javaMethodNameToReturnType.put( - "defaultCredentialsProviderBuilder", - typeMakerFn.apply(GoogleCredentialsProvider.Builder.class)); - javaMethodNameToReturnType.put( - "defaultGrpcTransportProviderBuilder", - typeMakerFn.apply(InstantiatingGrpcChannelProvider.Builder.class)); - javaMethodNameToReturnType.put( - "defaultTransportChannelProvider", staticTypes.get("TransportChannelProvider")); - return javaMethodNameToReturnType; - } - private static Map createDynamicTypes(Service service) { Map types = new HashMap<>(); @@ -692,7 +729,7 @@ private static Map createDynamicTypes(Service service) { VaporReference.builder() .setName(String.format(PAGED_RESPONSE_TYPE_NAME_PATTERN, m.name())) .setPakkage(service.pakkage()) - .setEnclosingClassName(String.format("%sClient", service.name())) + .setEnclosingClassName(getClientClassName(service.name())) .setIsStaticImport(true) .build())))); return types; @@ -777,6 +814,11 @@ private static String getThisClassName(String serviceName) { return String.format(CLASS_NAME_PATTERN, serviceName); } + private static String getClientClassName(String serviceName) { + + return String.format(CLIENT_CLASS_NAME_PATTERN, serviceName); + } + private static String getStubSettingsClassName(String serviceName) { return String.format(STUB_SETTINGS_PATTERN, serviceName); } @@ -789,4 +831,17 @@ private static TypeNode getStubSettingsBuilderType(Service service) { .setEnclosingClassName(getStubSettingsClassName(service.name())) .build()); } + + /** Turns a name like "waitSettings" or "waitOperationSettings" into "wait". */ + private static String getMethodNameFromSettingsVarName(String settingsVarName) { + BiFunction methodNameSubstrFn = + (s, literal) -> s.substring(0, s.length() - literal.length()); + if (settingsVarName.endsWith(OPERATION_SETTINGS_LITERAL)) { + return methodNameSubstrFn.apply(settingsVarName, OPERATION_SETTINGS_LITERAL); + } + if (settingsVarName.endsWith(SETTINGS_LITERAL)) { + return methodNameSubstrFn.apply(settingsVarName, SETTINGS_LITERAL); + } + return settingsVarName; + } } diff --git a/src/main/java/com/google/api/generator/gapic/composer/ServiceStubSettingsClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/ServiceStubSettingsClassComposer.java index 713dd68753..9e80c622c9 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/ServiceStubSettingsClassComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/ServiceStubSettingsClassComposer.java @@ -191,10 +191,8 @@ private static List createClassAnnotations() { private static List createClassHeaderComments(Service service) { Optional methodOpt = service.methods().isEmpty() ? Optional.empty() : Optional.of(service.methods().get(0)); - return Arrays.asList( - CommentComposer.AUTO_GENERATED_CLASS_COMMENT, - ServiceStubSettingsCommentComposer.createClassHeaderComment( - String.format(STUB_PATTERN, service.name()), service.defaultHost(), methodOpt)); + return SettingsCommentComposer.createClassHeaderComments( + String.format(STUB_PATTERN, service.name()), service.defaultHost(), methodOpt); } private static TypeNode createExtendsType(Service service, Map types) { @@ -248,7 +246,7 @@ private static List createClassStatements( List statements = new ArrayList<>(); // Assign DEFAULT_SERVICE_SCOPES. - statements.add(ServiceStubSettingsCommentComposer.DEFAULT_SCOPES_COMMENT); + statements.add(SettingsCommentComposer.DEFAULT_SCOPES_COMMENT); VariableExpr defaultServiceScopesDeclVarExpr = DEFAULT_SERVICE_SCOPES_VAR_EXPR .toBuilder() @@ -733,7 +731,7 @@ private static List createMethodSettingsGetterMethods( e -> MethodDefinition.builder() .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.createCallSettingsGetterComment( + SettingsCommentComposer.createCallSettingsGetterComment( getMethodNameFromSettingsVarName(e.getKey()))) .setScope(ScopeNode.PUBLIC) .setReturnType(e.getValue().type()) @@ -830,7 +828,7 @@ private static List createDefaultHelperAndGetterMethods( javaMethods.add( MethodDefinition.builder() .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.DEFAULT_EXECUTOR_PROVIDER_BUILDER_METHOD_COMMENT) + SettingsCommentComposer.DEFAULT_EXECUTOR_PROVIDER_BUILDER_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setReturnType(returnType) @@ -848,7 +846,7 @@ private static List createDefaultHelperAndGetterMethods( javaMethods.add( MethodDefinition.builder() .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.DEFAULT_SERVICE_ENDPOINT_METHOD_COMMENT) + SettingsCommentComposer.DEFAULT_SERVICE_ENDPOINT_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setReturnType(returnType) @@ -866,7 +864,7 @@ private static List createDefaultHelperAndGetterMethods( javaMethods.add( MethodDefinition.builder() .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.DEFAULT_SERVICE_SCOPES_METHOD_COMMENT) + SettingsCommentComposer.DEFAULT_SERVICE_SCOPES_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setReturnType(returnType) @@ -893,8 +891,7 @@ private static List createDefaultHelperAndGetterMethods( javaMethods.add( MethodDefinition.builder() .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer - .DEFAULT_CREDENTIALS_PROVIDER_BUILDER_METHOD_COMMENT) + SettingsCommentComposer.DEFAULT_CREDENTIALS_PROVIDER_BUILDER_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setReturnType(returnType) @@ -926,8 +923,7 @@ private static List createDefaultHelperAndGetterMethods( javaMethods.add( MethodDefinition.builder() .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer - .DEFAULT_GRPC_TRANSPORT_PROVIDER_BUILDER_METHOD_COMMENT) + SettingsCommentComposer.DEFAULT_GRPC_TRANSPORT_PROVIDER_BUILDER_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setReturnType(returnType) @@ -1028,8 +1024,7 @@ private static List createBuilderHelperMethods( final TypeNode builderReturnType = types.get(NESTED_BUILDER_CLASS_NAME); javaMethods.add( MethodDefinition.builder() - .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.NEW_BUILDER_METHOD_COMMENT) + .setHeaderCommentStatements(SettingsCommentComposer.NEW_BUILDER_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setReturnType(builderReturnType) @@ -1053,8 +1048,7 @@ private static List createBuilderHelperMethods( .build()); javaMethods.add( MethodDefinition.builder() - .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.NEW_BUILDER_METHOD_COMMENT) + .setHeaderCommentStatements(SettingsCommentComposer.NEW_BUILDER_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setReturnType(builderReturnType) @@ -1066,8 +1060,7 @@ private static List createBuilderHelperMethods( // Create the toBuilder method. javaMethods.add( MethodDefinition.builder() - .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.TO_BUILDER_METHOD_COMMENT) + .setHeaderCommentStatements(SettingsCommentComposer.TO_BUILDER_METHOD_COMMENT) .setScope(ScopeNode.PUBLIC) .setReturnType(builderReturnType) .setName("toBuilder") @@ -1158,8 +1151,7 @@ private static ClassDefinition createNestedBuilderClass( return ClassDefinition.builder() .setIsNested(true) .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.createBuilderClassComment( - getThisClassName(service.name()))) + SettingsCommentComposer.createBuilderClassComment(getThisClassName(service.name()))) .setScope(ScopeNode.PUBLIC) .setIsStatic(true) .setName(className) @@ -1665,7 +1657,7 @@ private static MethodDefinition createNestedClassApplyToAllUnaryMethodsMethod( return MethodDefinition.builder() .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.APPLY_TO_ALL_UNARY_METHODS_METHOD_COMMENTS) + SettingsCommentComposer.APPLY_TO_ALL_UNARY_METHODS_METHOD_COMMENTS) .setScope(ScopeNode.PUBLIC) .setReturnType(returnType) .setName(methodName) @@ -1713,7 +1705,7 @@ private static List createNestedClassSettingsBuilderGetterMeth javaMethods.add( MethodDefinition.builder() .setHeaderCommentStatements( - ServiceStubSettingsCommentComposer.createCallSettingsBuilderGetterComment( + SettingsCommentComposer.createCallSettingsBuilderGetterComment( getMethodNameFromSettingsVarName(varName))) .setAnnotations(isOperationCallSettings ? lroBetaAnnotations : ImmutableList.of()) .setScope(ScopeNode.PUBLIC) 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 new file mode 100644 index 0000000000..e47822c870 --- /dev/null +++ b/src/main/java/com/google/api/generator/gapic/composer/SettingsCommentComposer.java @@ -0,0 +1,146 @@ +// Copyright 2020 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.gapic.composer; + +import com.google.api.generator.engine.ast.CommentStatement; +import com.google.api.generator.engine.ast.JavaDocComment; +import com.google.api.generator.engine.ast.LineComment; +import com.google.api.generator.gapic.model.Method; +import com.google.api.generator.gapic.utils.JavaStyle; +import com.google.common.base.Preconditions; +import java.util.Arrays; +import java.util.List; +import java.util.Optional; +import java.util.stream.Collectors; + +class SettingsCommentComposer { + private static final String COLON = ":"; + + private static final String BUILDER_CLASS_DOC_PATTERN = "Builder for %s."; + private static final String CALL_SETTINGS_METHOD_DOC_PATTERN = + "Returns the object with the settings used for calls to %s."; + private static final String CALL_SETTINGS_BUILDER_METHOD_DOC_PATTERN = + "Returns the builder for the settings used for calls to %s."; + + // Class header patterns. + private static final String CLASS_HEADER_SUMMARY_PATTERN = + "Settings class to configure an instance of {@link %s}."; + private static final String CLASS_HEADER_DEFAULT_ADDRESS_PORT_PATTERN = + "The default service address (%s) and default port (%d) are used."; + private static final String CLASS_HEADER_SAMPLE_CODE_PATTERN = + "For example, to set the total timeout of %s to 30 seconds:"; + + private static final String CLASS_HEADER_BUILDER_DESCRIPTION = + "The builder of this class is recursive, so contained classes are themselves builders. When" + + " build() is called, the tree of builders is called to create the complete settings" + + " object."; + 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_RETRIES_DESCRIPTION = + "Retries are configured for idempotent methods but not for non-idempotent methods."; + + static final CommentStatement DEFAULT_SCOPES_COMMENT = + toSimpleComment("The default scopes of the service."); + + static final CommentStatement DEFAULT_EXECUTOR_PROVIDER_BUILDER_METHOD_COMMENT = + toSimpleComment("Returns a builder for the default ExecutorProvider for this service."); + static final CommentStatement DEFAULT_SERVICE_ENDPOINT_METHOD_COMMENT = + toSimpleComment("Returns the default service endpoint."); + static final CommentStatement DEFAULT_SERVICE_SCOPES_METHOD_COMMENT = + toSimpleComment("Returns the default service scopes."); + + static final CommentStatement DEFAULT_CREDENTIALS_PROVIDER_BUILDER_METHOD_COMMENT = + toSimpleComment("Returns a builder for the default credentials for this service."); + + static final CommentStatement DEFAULT_GRPC_TRANSPORT_PROVIDER_BUILDER_METHOD_COMMENT = + toSimpleComment("Returns a builder for the default ChannelProvider for this service."); + + static final CommentStatement NEW_BUILDER_METHOD_COMMENT = + toSimpleComment("Returns a new builder for this class."); + + static final CommentStatement TO_BUILDER_METHOD_COMMENT = + toSimpleComment("Returns a builder containing all the values of this settings class."); + + static final List APPLY_TO_ALL_UNARY_METHODS_METHOD_COMMENTS = + Arrays.asList( + LineComment.withComment("NEXT_MAJOR_VER: remove 'throws Exception'."), + JavaDocComment.builder() + .addComment( + "Applies the given settings updater function to all of the unary API methods" + + " in this service.") + .addParagraph( + "Note: This method does not support applying settings to streaming methods.") + .build()) + .stream() + .map(c -> CommentStatement.withComment(c)) + .collect(Collectors.toList()); + + static CommentStatement createCallSettingsGetterComment(String javaMethodName) { + return toSimpleComment(String.format(CALL_SETTINGS_METHOD_DOC_PATTERN, javaMethodName)); + } + + static CommentStatement createBuilderClassComment(String outerClassName) { + return toSimpleComment(String.format(BUILDER_CLASS_DOC_PATTERN, outerClassName)); + } + + static CommentStatement createCallSettingsBuilderGetterComment(String javaMethodName) { + return toSimpleComment(String.format(CALL_SETTINGS_BUILDER_METHOD_DOC_PATTERN, javaMethodName)); + } + + static List createClassHeaderComments( + String configuredClassName, String defaultHost, Optional methodOpt) { + // Split default address and port. + int colonIndex = defaultHost.indexOf(COLON); + Preconditions.checkState( + colonIndex > 0 && colonIndex < defaultHost.length() - 1, + String.format( + "No valid address and port found for %s, expected a string formatted like" + + " localhost:8888", + defaultHost)); + String defaultAddress = defaultHost.substring(0, colonIndex); + int defaultPort = Integer.parseInt(defaultHost.substring(colonIndex + 1)); + + JavaDocComment.Builder javaDocCommentBuilder = + JavaDocComment.builder() + .addUnescapedComment(String.format(CLASS_HEADER_SUMMARY_PATTERN, configuredClassName)) + .addParagraph(CLASS_HEADER_DEFAULTS_DESCRIPTION) + .addUnorderedList( + Arrays.asList( + String.format( + CLASS_HEADER_DEFAULT_ADDRESS_PORT_PATTERN, defaultAddress, defaultPort), + CLASS_HEADER_DEFAULTS_CREDENTIALS_DESCRIPTION, + CLASS_HEADER_DEFAULTS_RETRIES_DESCRIPTION)) + .addParagraph(CLASS_HEADER_BUILDER_DESCRIPTION); + + if (methodOpt.isPresent()) { + javaDocCommentBuilder = + javaDocCommentBuilder.addParagraph( + String.format( + CLASS_HEADER_SAMPLE_CODE_PATTERN, + JavaStyle.toLowerCamelCase(methodOpt.get().name()))); + // TODO(summerji): Add sample code here. + } + + return Arrays.asList( + CommentComposer.AUTO_GENERATED_CLASS_COMMENT, + CommentStatement.withComment(javaDocCommentBuilder.build())); + } + + private static CommentStatement toSimpleComment(String comment) { + return CommentStatement.withComment(JavaDocComment.withComment(comment)); + } +} diff --git a/src/test/java/com/google/api/generator/gapic/composer/ServiceSettingsClassComposerTest.java b/src/test/java/com/google/api/generator/gapic/composer/ServiceSettingsClassComposerTest.java index 6490109316..110d54f7d5 100644 --- a/src/test/java/com/google/api/generator/gapic/composer/ServiceSettingsClassComposerTest.java +++ b/src/test/java/com/google/api/generator/gapic/composer/ServiceSettingsClassComposerTest.java @@ -87,45 +87,75 @@ public void generateServiceClasses() { + "import java.util.List;\n" + "import javax.annotation.Generated;\n" + "\n" + + "// AUTO-GENERATED DOCUMENTATION AND CLASS.\n" + + "/**\n" + + " * Settings class to configure an instance of {@link EchoClient}.\n" + + " *\n" + + " *

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

    \n" + + " *
  • The default service address (localhost) and default port (7469) are used.\n" + + " *
  • Credentials are acquired automatically through Application Default" + + " Credentials.\n" + + " *
  • Retries are configured for idempotent methods but not for non-idempotent" + + " methods.\n" + + " *
\n" + + " *\n" + + " *

The builder of this class is recursive, so contained classes are themselves" + + " builders. When\n" + + " * build() is called, the tree of builders is called to create the complete settings" + + " object.\n" + + " *\n" + + " *

For example, to set the total timeout of echo to 30 seconds:\n" + + " */\n" + "@Generated(\"by gapic-generator-java\")\n" + "public class EchoSettings extends ClientSettings {\n" + "\n" + + " /** Returns the object with the settings used for calls to echo. */\n" + " public UnaryCallSettings echoSettings() {\n" + " return ((EchoStubSettings) getStubSettings()).echoSettings();\n" + " }\n" + "\n" + + " /** Returns the object with the settings used for calls to expand. */\n" + " public ServerStreamingCallSettings expandSettings()" + " {\n" + " return ((EchoStubSettings) getStubSettings()).expandSettings();\n" + " }\n" + "\n" + + " /** Returns the object with the settings used for calls to collect. */\n" + " public StreamingCallSettings collectSettings() {\n" + " return ((EchoStubSettings) getStubSettings()).collectSettings();\n" + " }\n" + "\n" + + " /** Returns the object with the settings used for calls to chat. */\n" + " public StreamingCallSettings chatSettings() {\n" + " return ((EchoStubSettings) getStubSettings()).chatSettings();\n" + " }\n" + "\n" + + " /** Returns the object with the settings used for calls to chatAgain. */\n" + " public StreamingCallSettings chatAgainSettings() {\n" + " return ((EchoStubSettings) getStubSettings()).chatAgainSettings();\n" + " }\n" + "\n" + + " /** Returns the object with the settings used for calls to pagedExpand. */\n" + " public PagedCallSettings\n" + " pagedExpandSettings() {\n" + " return ((EchoStubSettings) getStubSettings()).pagedExpandSettings();\n" + " }\n" + "\n" + + " /** Returns the object with the settings used for calls to wait. */\n" + " public UnaryCallSettings waitSettings() {\n" + " return ((EchoStubSettings) getStubSettings()).waitSettings();\n" + " }\n" + "\n" + + " /** Returns the object with the settings used for calls to wait. */\n" + " public OperationCallSettings" + " waitOperationSettings() {\n" + " return ((EchoStubSettings) getStubSettings()).waitOperationSettings();\n" + " }\n" + "\n" + + " /** Returns the object with the settings used for calls to block. */\n" + " public UnaryCallSettings blockSettings() {\n" + " return ((EchoStubSettings) getStubSettings()).blockSettings();\n" + " }\n" @@ -135,24 +165,29 @@ public void generateServiceClasses() { + " return new EchoStubSettings.Builder(stub.toBuilder()).build();\n" + " }\n" + "\n" + + " /** Returns a builder for the default ExecutorProvider for this service. */\n" + " public static InstantiatingExecutorProvider.Builder" + " defaultExecutorProviderBuilder() {\n" + " return EchoStubSettings.defaultExecutorProviderBuilder();\n" + " }\n" + "\n" + + " /** Returns the default service endpoint. */\n" + " public static String getDefaultEndpoint() {\n" + " return EchoStubSettings.getDefaultEndpoint();\n" + " }\n" + "\n" + + " /** Returns the default service scopes. */\n" + " public static List getDefaultServiceScopes() {\n" + " return EchoStubSettings.getDefaultServiceScopes();\n" + " }\n" + "\n" + + " /** Returns a builder for the default credentials for this service. */\n" + " public static GoogleCredentialsProvider.Builder defaultCredentialsProviderBuilder()" + " {\n" + " return EchoStubSettings.defaultCredentialsProviderBuilder();\n" + " }\n" + "\n" + + " /** Returns a builder for the default ChannelProvider for this service. */\n" + " public static InstantiatingGrpcChannelProvider.Builder" + " defaultGrpcTransportProviderBuilder() {\n" + " return EchoStubSettings.defaultGrpcTransportProviderBuilder();\n" @@ -169,14 +204,17 @@ public void generateServiceClasses() { + " return EchoStubSettings.defaultApiClientHeaderProviderBuilder();\n" + " }\n" + "\n" + + " /** Returns a new builder for this class. */\n" + " public static Builder newBuilder() {\n" + " return Builder.createDefault();\n" + " }\n" + "\n" + + " /** Returns a new builder for this class. */\n" + " public static Builder newBuilder(ClientContext clientContext) {\n" + " return new Builder(clientContext);\n" + " }\n" + "\n" + + " /** Returns a builder containing all the values of this settings class. */\n" + " public Builder toBuilder() {\n" + " return new Builder(this);\n" + " }\n" @@ -185,6 +223,7 @@ public void generateServiceClasses() { + " super(settingsBuilder);\n" + " }\n" + "\n" + + " /** Builder for EchoSettings. */\n" + " public static class Builder extends ClientSettings.Builder" + " {\n" + "\n" @@ -212,6 +251,14 @@ public void generateServiceClasses() { + " return ((EchoStubSettings.Builder) getStubSettings());\n" + " }\n" + "\n" + + " // NEXT_MAJOR_VER: remove 'throws Exception'.\n" + + " /**\n" + + " * Applies the given settings updater function to all of the unary API methods in" + + " this service.\n" + + " *\n" + + " *

Note: This method does not support applying settings to streaming" + + " methods.\n" + + " */\n" + " public Builder applyToAllUnaryMethods(\n" + " ApiFunction, Void> settingsUpdater) throws" + " Exception {\n" @@ -220,45 +267,54 @@ public void generateServiceClasses() { + " return this;\n" + " }\n" + "\n" + + " /** Returns the builder for the settings used for calls to echo. */\n" + " public UnaryCallSettings.Builder echoSettings() {\n" + " return getStubSettingsBuilder().echoSettings();\n" + " }\n" + "\n" + + " /** Returns the builder for the settings used for calls to expand. */\n" + " public ServerStreamingCallSettings.Builder" + " expandSettings() {\n" + " return getStubSettingsBuilder().expandSettings();\n" + " }\n" + "\n" + + " /** Returns the builder for the settings used for calls to collect. */\n" + " public StreamingCallSettings.Builder collectSettings()" + " {\n" + " return getStubSettingsBuilder().collectSettings();\n" + " }\n" + "\n" + + " /** Returns the builder for the settings used for calls to chat. */\n" + " public StreamingCallSettings.Builder chatSettings()" + " {\n" + " return getStubSettingsBuilder().chatSettings();\n" + " }\n" + "\n" + + " /** Returns the builder for the settings used for calls to chatAgain. */\n" + " public StreamingCallSettings.Builder" + " chatAgainSettings() {\n" + " return getStubSettingsBuilder().chatAgainSettings();\n" + " }\n" + "\n" + + " /** Returns the builder for the settings used for calls to pagedExpand. */\n" + " public PagedCallSettings.Builder<\n" + " PagedExpandRequest, PagedExpandResponse, PagedExpandPagedResponse>\n" + " pagedExpandSettings() {\n" + " return getStubSettingsBuilder().pagedExpandSettings();\n" + " }\n" + "\n" + + " /** Returns the builder for the settings used for calls to wait. */\n" + " public UnaryCallSettings.Builder waitSettings() {\n" + " return getStubSettingsBuilder().waitSettings();\n" + " }\n" + "\n" + + " /** Returns the builder for the settings used for calls to wait. */\n" + " public OperationCallSettings.Builder\n" + " waitOperationSettings() {\n" + " return getStubSettingsBuilder().waitOperationSettings();\n" + " }\n" + "\n" + + " /** Returns the builder for the settings used for calls to block. */\n" + " public UnaryCallSettings.Builder blockSettings() {\n" + " return getStubSettingsBuilder().blockSettings();\n" + " }\n"