fix: (rest transport) Add @BetaApi to the generated `TransportServi…

…ceFactory` 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.
googleapis · Jul 9, 2021 · 7d1b833 · 7d1b833
1 parent a705654
commit 7d1b833
Show file tree

Hide file tree

Showing 7 changed files with 63 additions and 15 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
@@ -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/...ogle/api/generator/gapic/composer/common/AbstractServiceCallableFactoryClassComposer.java b/...ogle/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;
@@ -136,7 +137,8 @@ protected MethodDefinition createUnaryCallableMethod(TypeStore typeStore) {
         /*callSettingsVariantName=*/ methodVariantName,
         /*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
             .map(n -> (Object) n)
-            .collect(Collectors.toList()));
+            .collect(Collectors.toList()),
+        Collections.emptyList());
   }
 
   protected MethodDefinition createPagedCallableMethod(TypeStore typeStore) {
@@ -158,7 +160,8 @@ protected MethodDefinition createPagedCallableMethod(TypeStore typeStore) {
         /*callSettingsVariantName=*/ methodVariantName,
         /*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
             .map(n -> (Object) n)
-            .collect(Collectors.toList()));
+            .collect(Collectors.toList()),
+        Collections.emptyList());
   }
 
   protected MethodDefinition createBatchingCallableMethod(TypeStore typeStore) {
@@ -178,7 +181,8 @@ protected MethodDefinition createBatchingCallableMethod(TypeStore typeStore) {
         /*callSettingsVariantName=*/ methodVariantName,
         /*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
             .map(n -> (Object) n)
-            .collect(Collectors.toList()));
+            .collect(Collectors.toList()),
+        Collections.emptyList());
   }
 
   protected abstract MethodDefinition createOperationCallableMethod(TypeStore typeStore);
@@ -191,7 +195,8 @@ protected MethodDefinition createGenericCallableMethod(
       String methodVariantName,
       List<Object> transportCallSettingsTemplateObjects,
       String callSettingsVariantName,
-      List<Object> callSettingsTemplateObjects) {
+      List<Object> callSettingsTemplateObjects,
+      List<AnnotationNode> annotations) {
 
     String methodName = String.format("create%sCallable", methodVariantName);
     String callSettingsTypeName = String.format("%sCallSettings", callSettingsVariantName);
@@ -261,6 +266,7 @@ protected MethodDefinition createGenericCallableMethod(
         .setName(methodName)
         .setArguments(arguments)
         .setReturnExpr(returnExpr)
+        .setAnnotations(annotations)
         .build();
   }
 

diff --git a/...com/google/api/generator/gapic/composer/grpc/GrpcServiceCallableFactoryClassComposer.java b/...com/google/api/generator/gapic/composer/grpc/GrpcServiceCallableFactoryClassComposer.java
@@ -22,6 +22,7 @@
 import com.google.longrunning.Operation;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.List;
 import java.util.stream.Collectors;
 
@@ -72,7 +73,8 @@ protected MethodDefinition createUnaryCallableMethod(TypeStore typeStore) {
         /*callSettingsVariantName=*/ methodVariantName,
         /*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
             .map(n -> (Object) n)
-            .collect(Collectors.toList()));
+            .collect(Collectors.toList()),
+        Collections.emptyList());
   }
 
   protected MethodDefinition createPagedCallableMethod(TypeStore typeStore) {
@@ -94,7 +96,8 @@ protected MethodDefinition createPagedCallableMethod(TypeStore typeStore) {
         /*callSettingsVariantName=*/ methodVariantName,
         /*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
             .map(n -> (Object) n)
-            .collect(Collectors.toList()));
+            .collect(Collectors.toList()),
+        Collections.emptyList());
   }
 
   @Override
@@ -114,7 +117,8 @@ protected MethodDefinition createOperationCallableMethod(TypeStore typeStore) {
         /*callSettingsVariantName=*/ methodVariantName,
         /*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
             .map(n -> (Object) n)
-            .collect(Collectors.toList()));
+            .collect(Collectors.toList()),
+        Collections.emptyList());
   }
 
   private MethodDefinition createBidiStreamingCallableMethod(TypeStore typeStore) {
@@ -134,7 +138,8 @@ private MethodDefinition createBidiStreamingCallableMethod(TypeStore typeStore)
         /*callSettingsVariantName=*/ "Streaming",
         /*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
             .map(n -> (Object) n)
-            .collect(Collectors.toList()));
+            .collect(Collectors.toList()),
+        Collections.emptyList());
   }
 
   private MethodDefinition createServerStreamingCallableMethod(TypeStore typeStore) {
@@ -154,7 +159,8 @@ private MethodDefinition createServerStreamingCallableMethod(TypeStore typeStore
         /*callSettingsVariantName=*/ methodVariantName,
         /*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
             .map(n -> (Object) n)
-            .collect(Collectors.toList()));
+            .collect(Collectors.toList()),
+        Collections.emptyList());
   }
 
   private MethodDefinition createClientStreamingCallableMethod(TypeStore typeStore) {
@@ -174,6 +180,7 @@ private MethodDefinition createClientStreamingCallableMethod(TypeStore typeStore
         /*callSettingsVariantName=*/ "Streaming",
         /*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
             .map(n -> (Object) n)
-            .collect(Collectors.toList()));
+            .collect(Collectors.toList()),
+        Collections.emptyList());
   }
 }
diff --git a/...google/api/generator/gapic/composer/rest/HttpJsonServiceCallableFactoryClassComposer.java b/...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,18 @@ public static HttpJsonServiceCallableFactoryClassComposer instance() {
     return INSTANCE;
   }
 
+  @Override
+  protected List<AnnotationNode> createClassAnnotations(Service service, TypeStore typeStore) {
+    List<AnnotationNode> 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.
+    if (annotations.stream().noneMatch(a -> a.type().equals(typeStore.get("BetaApi")))) {
+      annotations.add(AnnotationNode.withType(typeStore.get("BetaApi")));
+    }
+    return annotations;
+  }
+
   @Override
   protected List<TypeNode> createClassImplements(TypeStore typeStore) {
     return Arrays.asList(
@@ -63,6 +77,15 @@ protected MethodDefinition createOperationCallableMethod(TypeStore typeStore) {
     String responseTemplateName = "ResponseT";
     List<String> methodTemplateNames =
         Arrays.asList(requestTemplateName, responseTemplateName, "MetadataT");
+
+    // Always add @BetaApi annotation to the generated createOperationCallable()method for now,
+    // until LRO is fully implemented.
+    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 +98,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/...google/api/generator/gapic/composer/rest/goldens/HttpJsonComplianceCallableFactory.golden b/...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 <RequestT, ResponseT, MetadataT>
       OperationCallable<RequestT, ResponseT, MetadataT> createOperationCallable(

diff --git a/...on/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonAddressesCallableFactory.java b/...on/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 @@
  * <p>This class is for advanced usage.
  */
 @Generated("by gapic-generator-java")
+@BetaApi
 public class HttpJsonAddressesCallableFactory
     implements HttpJsonStubCallableFactory<ApiMessage, BackgroundResource> {
 
@@ -68,6 +70,8 @@ public <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createBatchingCa
         httpJsonCallSettings, callSettings, clientContext);
   }
 
+  @BetaApi(
+      "The surface for long-running operations is not stable yet and may change in the future.")
   @Override
   public <RequestT, ResponseT, MetadataT>
       OperationCallable<RequestT, ResponseT, MetadataT> createOperationCallable(

diff --git a/...ens/compute/com/google/cloud/compute/v1/stub/HttpJsonRegionOperationsCallableFactory.java b/...ens/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 @@
  * <p>This class is for advanced usage.
  */
 @Generated("by gapic-generator-java")
+@BetaApi
 public class HttpJsonRegionOperationsCallableFactory
     implements HttpJsonStubCallableFactory<ApiMessage, BackgroundResource> {
 
@@ -68,6 +70,8 @@ public <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createBatchingCa
         httpJsonCallSettings, callSettings, clientContext);
   }
 
+  @BetaApi(
+      "The surface for long-running operations is not stable yet and may change in the future.")
   @Override
   public <RequestT, ResponseT, MetadataT>
       OperationCallable<RequestT, ResponseT, MetadataT> createOperationCallable(