From ebe1aefbe860a41aabd8ced5268ccc6c7efdf791 Mon Sep 17 00:00:00 2001 From: Vadym Matsishevskyi <25311427+vam-google@users.noreply.github.com> Date: Tue, 13 Jul 2021 16:11:16 -0700 Subject: [PATCH] fix: (rest transport) Add `@BetaApi` to the generated `TransportServiceFactory` class and lro-specific method (#787) * fix: (rest transport) Add `@BetaApi` to the generated `TransportServiceFactory` class and lro-specific method This is to make implementing LRO post-GA safer. Note, `TransportServiceFactory` class is public for technical reasons, and is not supposed to be used by users directly. * address PR feedback --- .../generator/engine/ast/AnnotationNode.java | 9 +++--- ...ctServiceCallableFactoryClassComposer.java | 24 +++++++++++++++ ...onServiceCallableFactoryClassComposer.java | 30 ++++++++++++++++++- .../HttpJsonComplianceCallableFactory.golden | 2 ++ .../HttpJsonAddressesCallableFactory.java | 4 +++ ...tpJsonRegionOperationsCallableFactory.java | 4 +++ 6 files changed, 68 insertions(+), 5 deletions(-) diff --git a/src/main/java/com/google/api/generator/engine/ast/AnnotationNode.java b/src/main/java/com/google/api/generator/engine/ast/AnnotationNode.java index a7c69d8729..888262cbf4 100644 --- a/src/main/java/com/google/api/generator/engine/ast/AnnotationNode.java +++ b/src/main/java/com/google/api/generator/engine/ast/AnnotationNode.java @@ -41,11 +41,12 @@ public void accept(AstNodeVisitor visitor) { visitor.visit(this); } + public static AnnotationNode withTypeAndDescription(TypeNode type, String description) { + return AnnotationNode.builder().setType(type).setDescription(description).build(); + } + public static AnnotationNode withSuppressWarnings(String description) { - return AnnotationNode.builder() - .setType(annotationType(SuppressWarnings.class)) - .setDescription(description) - .build(); + return withTypeAndDescription(annotationType(SuppressWarnings.class), description); } public static AnnotationNode withType(TypeNode type) { diff --git a/src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceCallableFactoryClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceCallableFactoryClassComposer.java index efe6daf3d6..b3f4c7ee74 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceCallableFactoryClassComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceCallableFactoryClassComposer.java @@ -44,6 +44,7 @@ import com.google.api.generator.gapic.model.Service; import java.util.ArrayList; import java.util.Arrays; +import java.util.Collections; import java.util.List; import java.util.stream.Collectors; import javax.annotation.Generated; @@ -192,6 +193,28 @@ protected MethodDefinition createGenericCallableMethod( List transportCallSettingsTemplateObjects, String callSettingsVariantName, List callSettingsTemplateObjects) { + return createGenericCallableMethod( + typeStore, + methodTemplateNames, + returnCallableKindName, + returnCallableTemplateNames, + methodVariantName, + transportCallSettingsTemplateObjects, + callSettingsVariantName, + callSettingsTemplateObjects, + Collections.emptyList()); + } + + protected MethodDefinition createGenericCallableMethod( + TypeStore typeStore, + List methodTemplateNames, + String returnCallableKindName, + List returnCallableTemplateNames, + String methodVariantName, + List transportCallSettingsTemplateObjects, + String callSettingsVariantName, + List callSettingsTemplateObjects, + List annotations) { String methodName = String.format("create%sCallable", methodVariantName); String callSettingsTypeName = String.format("%sCallSettings", callSettingsVariantName); @@ -261,6 +284,7 @@ protected MethodDefinition createGenericCallableMethod( .setName(methodName) .setArguments(arguments) .setReturnExpr(returnExpr) + .setAnnotations(annotations) .build(); } diff --git a/src/main/java/com/google/api/generator/gapic/composer/rest/HttpJsonServiceCallableFactoryClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/rest/HttpJsonServiceCallableFactoryClassComposer.java index 435f9e63b3..f9c4045cb9 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/rest/HttpJsonServiceCallableFactoryClassComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/rest/HttpJsonServiceCallableFactoryClassComposer.java @@ -16,12 +16,14 @@ import com.google.api.gax.core.BackgroundResource; import com.google.api.gax.httpjson.ApiMessage; +import com.google.api.generator.engine.ast.AnnotationNode; import com.google.api.generator.engine.ast.ConcreteReference; import com.google.api.generator.engine.ast.MethodDefinition; import com.google.api.generator.engine.ast.TypeNode; import com.google.api.generator.engine.ast.ValueExpr; import com.google.api.generator.gapic.composer.common.AbstractServiceCallableFactoryClassComposer; import com.google.api.generator.gapic.composer.store.TypeStore; +import com.google.api.generator.gapic.model.Service; import java.util.Arrays; import java.util.List; import java.util.stream.Collectors; @@ -44,6 +46,20 @@ public static HttpJsonServiceCallableFactoryClassComposer instance() { return INSTANCE; } + @Override + protected List createClassAnnotations(Service service, TypeStore typeStore) { + List annotations = super.createClassAnnotations(service, typeStore); + // Always add @BetaApi annotation to the generated CallableFactory for now. It is a public class + // for technical reasons, end users are not expected to interact with it, but it may change + // when we add LRO support, that is why making it @BetaApi for now. + // + // Remove the @BetaApi annotation once the LRO feature is fully implemented and stabilized. + if (annotations.stream().noneMatch(a -> a.type().equals(typeStore.get("BetaApi")))) { + annotations.add(AnnotationNode.withType(typeStore.get("BetaApi"))); + } + return annotations; + } + @Override protected List createClassImplements(TypeStore typeStore) { return Arrays.asList( @@ -63,6 +79,17 @@ protected MethodDefinition createOperationCallableMethod(TypeStore typeStore) { String responseTemplateName = "ResponseT"; List methodTemplateNames = Arrays.asList(requestTemplateName, responseTemplateName, "MetadataT"); + + // Always add @BetaApi annotation to the generated createOperationCallable() method for now, + // until LRO is fully implemented. + // + // Remove the @BetaApi annotation once the LRO feature is fully implemented and stabilized. + AnnotationNode betaAnnotation = + AnnotationNode.withTypeAndDescription( + typeStore.get("BetaApi"), + "The surface for long-running operations is not stable yet and may change in the" + + " future."); + MethodDefinition method = createGenericCallableMethod( typeStore, @@ -75,7 +102,8 @@ protected MethodDefinition createOperationCallableMethod(TypeStore typeStore) { /*callSettingsVariantName=*/ methodVariantName, /*callSettingsTemplateObjects=*/ methodTemplateNames.stream() .map(n -> (Object) n) - .collect(Collectors.toList())); + .collect(Collectors.toList()), + Arrays.asList(betaAnnotation)); return method.toBuilder().setReturnExpr(ValueExpr.createNullExpr()).build(); } } diff --git a/src/test/java/com/google/api/generator/gapic/composer/rest/goldens/HttpJsonComplianceCallableFactory.golden b/src/test/java/com/google/api/generator/gapic/composer/rest/goldens/HttpJsonComplianceCallableFactory.golden index 2ddcef8135..7d6032778d 100644 --- a/src/test/java/com/google/api/generator/gapic/composer/rest/goldens/HttpJsonComplianceCallableFactory.golden +++ b/src/test/java/com/google/api/generator/gapic/composer/rest/goldens/HttpJsonComplianceCallableFactory.golden @@ -54,6 +54,8 @@ public class HttpJsonComplianceCallableFactory httpJsonCallSettings, callSettings, clientContext); } + @BetaApi( + "The surface for long-running operations is not stable yet and may change in the future.") @Override public OperationCallable createOperationCallable( diff --git a/test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonAddressesCallableFactory.java b/test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonAddressesCallableFactory.java index 98f81444ec..afa275a6f5 100644 --- a/test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonAddressesCallableFactory.java +++ b/test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonAddressesCallableFactory.java @@ -16,6 +16,7 @@ package com.google.cloud.compute.v1.stub; +import com.google.api.core.BetaApi; import com.google.api.gax.core.BackgroundResource; import com.google.api.gax.httpjson.ApiMessage; import com.google.api.gax.httpjson.HttpJsonCallSettings; @@ -37,6 +38,7 @@ *

This class is for advanced usage. */ @Generated("by gapic-generator-java") +@BetaApi public class HttpJsonAddressesCallableFactory implements HttpJsonStubCallableFactory { @@ -68,6 +70,8 @@ public UnaryCallable createBatchingCa httpJsonCallSettings, callSettings, clientContext); } + @BetaApi( + "The surface for long-running operations is not stable yet and may change in the future.") @Override public OperationCallable createOperationCallable( diff --git a/test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonRegionOperationsCallableFactory.java b/test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonRegionOperationsCallableFactory.java index 2694d1aa62..6dac14a84e 100644 --- a/test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonRegionOperationsCallableFactory.java +++ b/test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonRegionOperationsCallableFactory.java @@ -16,6 +16,7 @@ package com.google.cloud.compute.v1.stub; +import com.google.api.core.BetaApi; import com.google.api.gax.core.BackgroundResource; import com.google.api.gax.httpjson.ApiMessage; import com.google.api.gax.httpjson.HttpJsonCallSettings; @@ -37,6 +38,7 @@ *

This class is for advanced usage. */ @Generated("by gapic-generator-java") +@BetaApi public class HttpJsonRegionOperationsCallableFactory implements HttpJsonStubCallableFactory { @@ -68,6 +70,8 @@ public UnaryCallable createBatchingCa httpJsonCallSettings, callSettings, clientContext); } + @BetaApi( + "The surface for long-running operations is not stable yet and may change in the future.") @Override public OperationCallable createOperationCallable(