Skip to content

Commit ebe1aef

Browse files
vam-googlevam-google
authored
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
1 parent 043fc86 commit ebe1aef

6 files changed

Lines changed: 68 additions & 5 deletions

File tree

‎src/main/java/com/google/api/generator/engine/ast/AnnotationNode.java‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,12 @@ public void accept(AstNodeVisitor visitor) {
4141
visitor.visit(this);
4242
}
4343

44+
public static AnnotationNode withTypeAndDescription(TypeNode type, String description) {
45+
return AnnotationNode.builder().setType(type).setDescription(description).build();
46+
}
47+
4448
public static AnnotationNode withSuppressWarnings(String description) {
45-
return AnnotationNode.builder()
46-
.setType(annotationType(SuppressWarnings.class))
47-
.setDescription(description)
48-
.build();
49+
return withTypeAndDescription(annotationType(SuppressWarnings.class), description);
4950
}
5051

5152
public static AnnotationNode withType(TypeNode type) {

‎src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceCallableFactoryClassComposer.java‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@
4444
import com.google.api.generator.gapic.model.Service;
4545
import java.util.ArrayList;
4646
import java.util.Arrays;
47+
import java.util.Collections;
4748
import java.util.List;
4849
import java.util.stream.Collectors;
4950
import javax.annotation.Generated;
@@ -192,6 +193,28 @@ protected MethodDefinition createGenericCallableMethod(
192193
List<Object> transportCallSettingsTemplateObjects,
193194
String callSettingsVariantName,
194195
List<Object> callSettingsTemplateObjects) {
196+
return createGenericCallableMethod(
197+
typeStore,
198+
methodTemplateNames,
199+
returnCallableKindName,
200+
returnCallableTemplateNames,
201+
methodVariantName,
202+
transportCallSettingsTemplateObjects,
203+
callSettingsVariantName,
204+
callSettingsTemplateObjects,
205+
Collections.emptyList());
206+
}
207+
208+
protected MethodDefinition createGenericCallableMethod(
209+
TypeStore typeStore,
210+
List<String> methodTemplateNames,
211+
String returnCallableKindName,
212+
List<String> returnCallableTemplateNames,
213+
String methodVariantName,
214+
List<Object> transportCallSettingsTemplateObjects,
215+
String callSettingsVariantName,
216+
List<Object> callSettingsTemplateObjects,
217+
List<AnnotationNode> annotations) {
195218

196219
String methodName = String.format("create%sCallable", methodVariantName);
197220
String callSettingsTypeName = String.format("%sCallSettings", callSettingsVariantName);
@@ -261,6 +284,7 @@ protected MethodDefinition createGenericCallableMethod(
261284
.setName(methodName)
262285
.setArguments(arguments)
263286
.setReturnExpr(returnExpr)
287+
.setAnnotations(annotations)
264288
.build();
265289
}
266290

‎src/main/java/com/google/api/generator/gapic/composer/rest/HttpJsonServiceCallableFactoryClassComposer.java‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,14 @@
1616

1717
import com.google.api.gax.core.BackgroundResource;
1818
import com.google.api.gax.httpjson.ApiMessage;
19+
import com.google.api.generator.engine.ast.AnnotationNode;
1920
import com.google.api.generator.engine.ast.ConcreteReference;
2021
import com.google.api.generator.engine.ast.MethodDefinition;
2122
import com.google.api.generator.engine.ast.TypeNode;
2223
import com.google.api.generator.engine.ast.ValueExpr;
2324
import com.google.api.generator.gapic.composer.common.AbstractServiceCallableFactoryClassComposer;
2425
import com.google.api.generator.gapic.composer.store.TypeStore;
26+
import com.google.api.generator.gapic.model.Service;
2527
import java.util.Arrays;
2628
import java.util.List;
2729
import java.util.stream.Collectors;
@@ -44,6 +46,20 @@ public static HttpJsonServiceCallableFactoryClassComposer instance() {
4446
return INSTANCE;
4547
}
4648

49+
@Override
50+
protected List<AnnotationNode> createClassAnnotations(Service service, TypeStore typeStore) {
51+
List<AnnotationNode> annotations = super.createClassAnnotations(service, typeStore);
52+
// Always add @BetaApi annotation to the generated CallableFactory for now. It is a public class
53+
// for technical reasons, end users are not expected to interact with it, but it may change
54+
// when we add LRO support, that is why making it @BetaApi for now.
55+
//
56+
// Remove the @BetaApi annotation once the LRO feature is fully implemented and stabilized.
57+
if (annotations.stream().noneMatch(a -> a.type().equals(typeStore.get("BetaApi")))) {
58+
annotations.add(AnnotationNode.withType(typeStore.get("BetaApi")));
59+
}
60+
return annotations;
61+
}
62+
4763
@Override
4864
protected List<TypeNode> createClassImplements(TypeStore typeStore) {
4965
return Arrays.asList(
@@ -63,6 +79,17 @@ protected MethodDefinition createOperationCallableMethod(TypeStore typeStore) {
6379
String responseTemplateName = "ResponseT";
6480
List<String> methodTemplateNames =
6581
Arrays.asList(requestTemplateName, responseTemplateName, "MetadataT");
82+
83+
// Always add @BetaApi annotation to the generated createOperationCallable() method for now,
84+
// until LRO is fully implemented.
85+
//
86+
// Remove the @BetaApi annotation once the LRO feature is fully implemented and stabilized.
87+
AnnotationNode betaAnnotation =
88+
AnnotationNode.withTypeAndDescription(
89+
typeStore.get("BetaApi"),
90+
"The surface for long-running operations is not stable yet and may change in the"
91+
+ " future.");
92+
6693
MethodDefinition method =
6794
createGenericCallableMethod(
6895
typeStore,
@@ -75,7 +102,8 @@ protected MethodDefinition createOperationCallableMethod(TypeStore typeStore) {
75102
/*callSettingsVariantName=*/ methodVariantName,
76103
/*callSettingsTemplateObjects=*/ methodTemplateNames.stream()
77104
.map(n -> (Object) n)
78-
.collect(Collectors.toList()));
105+
.collect(Collectors.toList()),
106+
Arrays.asList(betaAnnotation));
79107
return method.toBuilder().setReturnExpr(ValueExpr.createNullExpr()).build();
80108
}
81109
}

‎src/test/java/com/google/api/generator/gapic/composer/rest/goldens/HttpJsonComplianceCallableFactory.golden‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ public class HttpJsonComplianceCallableFactory
5454
httpJsonCallSettings, callSettings, clientContext);
5555
}
5656

57+
@BetaApi(
58+
"The surface for long-running operations is not stable yet and may change in the future.")
5759
@Override
5860
public <RequestT, ResponseT, MetadataT>
5961
OperationCallable<RequestT, ResponseT, MetadataT> createOperationCallable(

‎test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonAddressesCallableFactory.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616

1717
package com.google.cloud.compute.v1.stub;
1818

19+
import com.google.api.core.BetaApi;
1920
import com.google.api.gax.core.BackgroundResource;
2021
import com.google.api.gax.httpjson.ApiMessage;
2122
import com.google.api.gax.httpjson.HttpJsonCallSettings;
@@ -37,6 +38,7 @@
3738
* <p>This class is for advanced usage.
3839
*/
3940
@Generated("by gapic-generator-java")
41+
@BetaApi
4042
public class HttpJsonAddressesCallableFactory
4143
implements HttpJsonStubCallableFactory<ApiMessage, BackgroundResource> {
4244

@@ -68,6 +70,8 @@ public <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createBatchingCa
6870
httpJsonCallSettings, callSettings, clientContext);
6971
}
7072

73+
@BetaApi(
74+
"The surface for long-running operations is not stable yet and may change in the future.")
7175
@Override
7276
public <RequestT, ResponseT, MetadataT>
7377
OperationCallable<RequestT, ResponseT, MetadataT> createOperationCallable(

‎test/integration/goldens/compute/com/google/cloud/compute/v1/stub/HttpJsonRegionOperationsCallableFactory.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616

1717
package com.google.cloud.compute.v1.stub;
1818

19+
import com.google.api.core.BetaApi;
1920
import com.google.api.gax.core.BackgroundResource;
2021
import com.google.api.gax.httpjson.ApiMessage;
2122
import com.google.api.gax.httpjson.HttpJsonCallSettings;
@@ -37,6 +38,7 @@
3738
* <p>This class is for advanced usage.
3839
*/
3940
@Generated("by gapic-generator-java")
41+
@BetaApi
4042
public class HttpJsonRegionOperationsCallableFactory
4143
implements HttpJsonStubCallableFactory<ApiMessage, BackgroundResource> {
4244

@@ -68,6 +70,8 @@ public <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createBatchingCa
6870
httpJsonCallSettings, callSettings, clientContext);
6971
}
7072

73+
@BetaApi(
74+
"The surface for long-running operations is not stable yet and may change in the future.")
7175
@Override
7276
public <RequestT, ResponseT, MetadataT>
7377
OperationCallable<RequestT, ResponseT, MetadataT> createOperationCallable(

0 commit comments

Comments
 (0)