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

…ceFactory` 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

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) {

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<Object> transportCallSettingsTemplateObjects,
       String callSettingsVariantName,
       List<Object> callSettingsTemplateObjects) {
+    return createGenericCallableMethod(
+        typeStore,
+        methodTemplateNames,
+        returnCallableKindName,
+        returnCallableTemplateNames,
+        methodVariantName,
+        transportCallSettingsTemplateObjects,
+        callSettingsVariantName,
+        callSettingsTemplateObjects,
+        Collections.emptyList());
+  }
+
+  protected MethodDefinition createGenericCallableMethod(
+      TypeStore typeStore,
+      List<String> methodTemplateNames,
+      String returnCallableKindName,
+      List<String> returnCallableTemplateNames,
+      String methodVariantName,
+      List<Object> transportCallSettingsTemplateObjects,
+      String callSettingsVariantName,
+      List<Object> callSettingsTemplateObjects,
+      List<AnnotationNode> 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();
   }
 

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<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.
+    //
+    // 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<TypeNode> createClassImplements(TypeStore typeStore) {
     return Arrays.asList(
@@ -63,6 +79,17 @@ 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.
+    //
+    // 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();
   }
 }

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 <RequestT, ResponseT, MetadataT>
       OperationCallable<RequestT, ResponseT, MetadataT> createOperationCallable(

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 @@
  * <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(

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 @@
  * <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(