Skip to content

Commit 595198b

Browse files
cindy-pengcindy-peng
committed
feat: Selective gapic generation phase II
1 parent f1f979d commit 595198b

File tree

43 files changed

+1121
-671
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+1121
-671
lines changed

‎gapic-generator-java/src/main/java/com/google/api/generator/engine/ast/JavaDocComment.java‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ public abstract static class Builder {
5151
String throwsType = null;
5252
String throwsDescription = null;
5353
String deprecated = null;
54+
String internalOnly = null;
5455
String returnDescription = null;
5556
List<String> paramsList = new ArrayList<>();
5657
List<String> componentsList = new ArrayList<>();
@@ -70,6 +71,11 @@ public Builder setDeprecated(String deprecatedText) {
7071
return this;
7172
}
7273

74+
public Builder setInternalOnly(String internalOnlyText) {
75+
internalOnly = internalOnlyText;
76+
return this;
77+
}
78+
7379
public Builder setReturn(String returnText) {
7480
returnDescription = returnText;
7581
return this;
@@ -135,6 +141,7 @@ public boolean emptyComments() {
135141
return Strings.isNullOrEmpty(throwsType)
136142
&& Strings.isNullOrEmpty(throwsDescription)
137143
&& Strings.isNullOrEmpty(deprecated)
144+
&& Strings.isNullOrEmpty(internalOnly)
138145
&& Strings.isNullOrEmpty(returnDescription)
139146
&& paramsList.isEmpty()
140147
&& componentsList.isEmpty();
@@ -150,6 +157,9 @@ public JavaDocComment build() {
150157
if (!Strings.isNullOrEmpty(deprecated)) {
151158
componentsList.add(String.format("@deprecated %s", deprecated));
152159
}
160+
if (!Strings.isNullOrEmpty(internalOnly)) {
161+
componentsList.add(String.format("@InternalApi %s", internalOnly));
162+
}
153163
if (!Strings.isNullOrEmpty(returnDescription)) {
154164
componentsList.add(String.format("@return %s", returnDescription));
155165
}

‎gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/CommentComposer.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ public class CommentComposer {
4949
static final String DEPRECATED_METHOD_STRING =
5050
"This method is deprecated and will be removed in the next major version update.";
5151

52+
static final String INTERNAL_ONLY_METHOD_STRING =
53+
"This method is internal used only. Please do not use directly.";
54+
5255
public static final CommentStatement APACHE_LICENSE_COMMENT =
5356
CommentStatement.withComment(BlockComment.withComment(APACHE_LICENSE_STRING));
5457

‎gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
import com.google.api.generator.gapic.composer.utils.ClassNames;
2323
import com.google.api.generator.gapic.composer.utils.CommentFormatter;
2424
import com.google.api.generator.gapic.model.Method;
25+
import com.google.api.generator.gapic.model.Method.SelectiveGapicType;
2526
import com.google.api.generator.gapic.model.MethodArgument;
2627
import com.google.api.generator.gapic.model.Service;
2728
import com.google.api.generator.gapic.utils.JavaStyle;
@@ -37,7 +38,7 @@ public class ServiceClientCommentComposer {
3738
// Tokens.
3839
private static final String EMPTY_STRING = "";
3940
private static final String API_EXCEPTION_TYPE_NAME = "com.google.api.gax.rpc.ApiException";
40-
private static final String EXCEPTION_CONDITION = "if the remote call fails";
41+
private static final String EXCEPTION_CONDITION = "if the remote call fails.";
4142

4243
// Constants.
4344
private static final String SERVICE_DESCRIPTION_INTRO_STRING =
@@ -202,6 +203,10 @@ public static List<CommentStatement> createRpcMethodHeaderComment(
202203
methodJavadocBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING);
203204
}
204205

206+
if (method.selectiveGapicType() == SelectiveGapicType.INTERNAL) {
207+
methodJavadocBuilder.setInternalOnly(CommentComposer.INTERNAL_ONLY_METHOD_STRING);
208+
}
209+
205210
List<CommentStatement> comments = new ArrayList<>();
206211
comments.add(CommentComposer.AUTO_GENERATED_METHOD_COMMENT);
207212
if (!methodJavadocBuilder.emptyComments()) {
@@ -345,6 +350,10 @@ public static List<CommentStatement> createRpcCallableMethodHeaderComment(
345350
methodJavadocBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING);
346351
}
347352

353+
if (method.selectiveGapicType() == SelectiveGapicType.INTERNAL) {
354+
methodJavadocBuilder.setInternalOnly(CommentComposer.INTERNAL_ONLY_METHOD_STRING);
355+
}
356+
348357
return Arrays.asList(
349358
CommentComposer.AUTO_GENERATED_METHOD_COMMENT,
350359
CommentStatement.withComment(methodJavadocBuilder.build()));

‎gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/SettingsCommentComposer.java‎

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -120,22 +120,22 @@ public CommentStatement getTransportProviderBuilderMethodComment() {
120120
}
121121

122122
public static CommentStatement createCallSettingsGetterComment(
123-
String javaMethodName, boolean isMethodDeprecated) {
124-
String methodComment = String.format(CALL_SETTINGS_METHOD_DOC_PATTERN, javaMethodName);
125-
return isMethodDeprecated
126-
? toDeprecatedSimpleComment(methodComment)
127-
: toSimpleComment(methodComment);
123+
String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
124+
return toDeprecatedInternalSimpleComment(
125+
String.format(CALL_SETTINGS_METHOD_DOC_PATTERN, javaMethodName),
126+
isMethodDeprecated,
127+
isMethodInternal);
128128
}
129129

130130
public static CommentStatement createBuilderClassComment(String outerClassName) {
131131
return toSimpleComment(String.format(BUILDER_CLASS_DOC_PATTERN, outerClassName));
132132
}
133133

134134
public static CommentStatement createCallSettingsBuilderGetterComment(
135-
String javaMethodName, boolean isMethodDeprecated) {
135+
String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
136136
String methodComment = String.format(CALL_SETTINGS_BUILDER_METHOD_DOC_PATTERN, javaMethodName);
137-
return isMethodDeprecated
138-
? toDeprecatedSimpleComment(methodComment)
137+
return isMethodDeprecated || isMethodInternal
138+
? toDeprecatedInternalSimpleComment(methodComment, isMethodDeprecated, isMethodInternal)
139139
: toSimpleComment(methodComment);
140140
}
141141

@@ -205,11 +205,17 @@ private static CommentStatement toSimpleComment(String comment) {
205205
return CommentStatement.withComment(JavaDocComment.withComment(comment));
206206
}
207207

208-
private static CommentStatement toDeprecatedSimpleComment(String comment) {
209-
return CommentStatement.withComment(
210-
JavaDocComment.builder()
211-
.addComment(comment)
212-
.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING)
213-
.build());
208+
private static CommentStatement toDeprecatedInternalSimpleComment(
209+
String comment, boolean isDeprecated, boolean isInternal) {
210+
JavaDocComment.Builder docBuilder = JavaDocComment.builder().addComment(comment);
211+
docBuilder =
212+
isDeprecated
213+
? docBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING)
214+
: docBuilder;
215+
docBuilder =
216+
isInternal
217+
? docBuilder.setInternalOnly(CommentComposer.INTERNAL_ONLY_METHOD_STRING)
218+
: docBuilder;
219+
return CommentStatement.withComment(docBuilder.build());
214220
}
215221
}

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

Lines changed: 30 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
import com.google.api.core.ApiFuture;
1919
import com.google.api.core.ApiFutures;
2020
import com.google.api.core.BetaApi;
21+
import com.google.api.core.InternalApi;
2122
import com.google.api.gax.core.BackgroundResource;
2223
import com.google.api.gax.longrunning.OperationFuture;
2324
import com.google.api.gax.paging.AbstractFixedSizeCollection;
@@ -70,6 +71,7 @@
7071
import com.google.api.generator.gapic.model.LongrunningOperation;
7172
import com.google.api.generator.gapic.model.Message;
7273
import com.google.api.generator.gapic.model.Method;
74+
import com.google.api.generator.gapic.model.Method.SelectiveGapicType;
7375
import com.google.api.generator.gapic.model.Method.Stream;
7476
import com.google.api.generator.gapic.model.MethodArgument;
7577
import com.google.api.generator.gapic.model.ResourceName;
@@ -107,6 +109,8 @@ public abstract class AbstractServiceClientClassComposer implements ClassCompose
107109
private static final String CALLABLE_NAME_PATTERN = "%sCallable";
108110
private static final String PAGED_CALLABLE_NAME_PATTERN = "%sPagedCallable";
109111
private static final String OPERATION_CALLABLE_NAME_PATTERN = "%sOperationCallable";
112+
private static final String INTERNAL_API_WARNING =
113+
"Internal API. This API is not intended for public consumption.";
110114

111115
private static final Reference LIST_REFERENCE = ConcreteReference.withClazz(List.class);
112116
private static final Reference MAP_REFERENCE = ConcreteReference.withClazz(Map.class);
@@ -136,7 +140,6 @@ public GapicClass generate(GapicContext context, Service service) {
136140
GapicClass.Kind kind = Kind.MAIN;
137141
String pakkage = service.pakkage();
138142
boolean hasLroClient = service.hasStandardLroMethods();
139-
140143
List<Sample> samples = new ArrayList<>();
141144
Map<String, List<String>> grpcRpcsToJavaMethodNames = new HashMap<>();
142145
Map<String, List<String>> methodVariantsForClientHeader = new HashMap<>();
@@ -802,11 +805,18 @@ private static List<MethodDefinition> createMethodVariants(
802805
methodVariantBuilder.setReturnType(methodOutputType).setReturnExpr(rpcInvocationExpr);
803806
}
804807

808+
List<AnnotationNode> annotations = new ArrayList<>();
805809
if (method.isDeprecated()) {
806-
methodVariantBuilder =
807-
methodVariantBuilder.setAnnotations(
808-
Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED)));
810+
annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
811+
}
812+
813+
if (method.selectiveGapicType() == SelectiveGapicType.INTERNAL) {
814+
annotations.add(
815+
AnnotationNode.withTypeAndDescription(
816+
typeStore.get("InternalApi"), INTERNAL_API_WARNING));
809817
}
818+
819+
methodVariantBuilder = methodVariantBuilder.setAnnotations(annotations);
810820
methodVariantBuilder = methodVariantBuilder.setBody(statements);
811821
javaMethods.add(methodVariantBuilder.build());
812822
}
@@ -889,6 +899,12 @@ private static MethodDefinition createMethodDefaultMethod(
889899
annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
890900
}
891901

902+
if (method.selectiveGapicType() == SelectiveGapicType.INTERNAL) {
903+
annotations.add(
904+
AnnotationNode.withTypeAndDescription(
905+
typeStore.get("InternalApi"), INTERNAL_API_WARNING));
906+
}
907+
892908
if (isProtoEmptyType(methodOutputType)) {
893909
methodBuilder =
894910
methodBuilder
@@ -1039,11 +1055,17 @@ private static MethodDefinition createCallableMethod(
10391055
}
10401056

10411057
MethodDefinition.Builder methodDefBuilder = MethodDefinition.builder();
1058+
List<AnnotationNode> annotations = new ArrayList<>();
10421059
if (method.isDeprecated()) {
1043-
methodDefBuilder =
1044-
methodDefBuilder.setAnnotations(
1045-
Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED)));
1060+
annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
10461061
}
1062+
if (method.selectiveGapicType() == SelectiveGapicType.INTERNAL) {
1063+
annotations.add(
1064+
AnnotationNode.withTypeAndDescription(
1065+
typeStore.get("InternalApi"), INTERNAL_API_WARNING));
1066+
}
1067+
1068+
methodDefBuilder = methodDefBuilder.setAnnotations(annotations);
10471069

10481070
return methodDefBuilder
10491071
.setHeaderCommentStatements(
@@ -1774,6 +1796,7 @@ private static TypeStore createTypes(Service service, Map<String, Message> messa
17741796
ApiFutures.class,
17751797
BackgroundResource.class,
17761798
BetaApi.class,
1799+
InternalApi.class,
17771800
BidiStreamingCallable.class,
17781801
ClientStreamingCallable.class,
17791802
Generated.class,

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

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

1717
import com.google.api.core.ApiFunction;
1818
import com.google.api.core.BetaApi;
19+
import com.google.api.core.InternalApi;
1920
import com.google.api.gax.core.GoogleCredentialsProvider;
2021
import com.google.api.gax.core.InstantiatingExecutorProvider;
2122
import com.google.api.gax.rpc.ApiClientHeaderProvider;
@@ -60,6 +61,7 @@
6061
import com.google.api.generator.gapic.model.GapicClass.Kind;
6162
import com.google.api.generator.gapic.model.GapicContext;
6263
import com.google.api.generator.gapic.model.Method;
64+
import com.google.api.generator.gapic.model.Method.SelectiveGapicType;
6365
import com.google.api.generator.gapic.model.Method.Stream;
6466
import com.google.api.generator.gapic.model.Sample;
6567
import com.google.api.generator.gapic.model.Service;
@@ -85,6 +87,8 @@ public abstract class AbstractServiceSettingsClassComposer implements ClassCompo
8587

8688
private static final String OPERATION_SETTINGS_LITERAL = "OperationSettings";
8789
private static final String SETTINGS_LITERAL = "Settings";
90+
private static final String INTERNAL_API_WARNING =
91+
"Internal API. This API is not intended for public consumption.";
8892
protected static final TypeStore FIXED_TYPESTORE = createStaticTypes();
8993

9094
private final TransportContext transportContext;
@@ -133,16 +137,21 @@ public GapicClass generate(GapicContext context, Service service) {
133137

134138
private static List<CommentStatement> createClassHeaderComments(
135139
Service service, TypeNode classType, List<Sample> samples) {
136-
// Pick the first pure unary rpc method, if no such method exists, then pick the first in the
140+
// Pick the first public pure unary rpc method, if no such method exists, then pick the first
141+
// public in the
137142
// list.
143+
List<Method> publicMethods =
144+
service.methods().stream()
145+
.filter(m -> m.selectiveGapicType() == SelectiveGapicType.PUBLIC)
146+
.collect(Collectors.toList());
138147
Optional<Method> methodOpt =
139-
service.methods().isEmpty()
148+
publicMethods.isEmpty()
140149
? Optional.empty()
141150
: Optional.of(
142-
service.methods().stream()
151+
publicMethods.stream()
143152
.filter(m -> m.stream() == Stream.NONE && !m.hasLro() && !m.isPaged())
144153
.findFirst()
145-
.orElse(service.methods().get(0)));
154+
.orElse(publicMethods.get(0)));
146155
Optional<String> methodNameOpt =
147156
methodOpt.isPresent() ? Optional.of(methodOpt.get().name()) : Optional.empty();
148157
Optional<Sample> sampleCode =
@@ -156,9 +165,9 @@ private static List<CommentStatement> createClassHeaderComments(
156165
// Create a sample for a LRO method using LRO-specific RetrySettings, if one exists in the
157166
// service.
158167
Optional<Method> lroMethodOpt =
159-
service.methods().isEmpty()
168+
publicMethods.isEmpty()
160169
? Optional.empty()
161-
: service.methods().stream()
170+
: publicMethods.stream()
162171
.filter(m -> m.stream() == Stream.NONE && m.hasLro())
163172
.findFirst();
164173
Optional<String> lroMethodNameOpt =
@@ -270,40 +279,44 @@ private static List<MethodDefinition> createSettingsGetterMethods(
270279
List<MethodDefinition> javaMethods = new ArrayList<>();
271280
for (Method protoMethod : service.methods()) {
272281
String javaStyleName = JavaStyle.toLowerCamelCase(protoMethod.name());
273-
String javaMethodName =
274-
String.format("%sSettings", JavaStyle.toLowerCamelCase(protoMethod.name()));
282+
String javaMethodName = String.format("%sSettings", javaStyleName);
275283
MethodDefinition.Builder methodBuilder =
276284
methodMakerFn.apply(getCallSettingsType(protoMethod, typeStore), javaMethodName);
277-
javaMethods.add(
278-
methodBuilder
279-
.setHeaderCommentStatements(
280-
SettingsCommentComposer.createCallSettingsGetterComment(
281-
getMethodNameFromSettingsVarName(javaMethodName), protoMethod.isDeprecated()))
282-
.setAnnotations(
283-
protoMethod.isDeprecated()
284-
? Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED))
285-
: Collections.emptyList())
286-
.build());
285+
javaMethods.add(methodBuilderHelper(protoMethod, methodBuilder, javaMethodName));
287286
if (protoMethod.hasLro()) {
288287
javaMethodName = String.format("%sOperationSettings", javaStyleName);
289288
methodBuilder =
290289
methodMakerFn.apply(getOperationCallSettingsType(protoMethod), javaMethodName);
291-
javaMethods.add(
292-
methodBuilder
293-
.setHeaderCommentStatements(
294-
SettingsCommentComposer.createCallSettingsGetterComment(
295-
getMethodNameFromSettingsVarName(javaMethodName),
296-
protoMethod.isDeprecated()))
297-
.setAnnotations(
298-
protoMethod.isDeprecated()
299-
? Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED))
300-
: Collections.emptyList())
301-
.build());
290+
javaMethods.add(methodBuilderHelper(protoMethod, methodBuilder, javaMethodName));
302291
}
303292
}
304293
return javaMethods;
305294
}
306295

296+
// Add method header comment statements and annotations.
297+
private static MethodDefinition methodBuilderHelper(
298+
Method protoMethod, MethodDefinition.Builder methodBuilder, String javaMethodName) {
299+
List<AnnotationNode> annotations = new ArrayList<>();
300+
if (protoMethod.isDeprecated()) {
301+
annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
302+
}
303+
304+
if (protoMethod.selectiveGapicType() == SelectiveGapicType.INTERNAL) {
305+
annotations.add(
306+
AnnotationNode.withTypeAndDescription(
307+
FIXED_TYPESTORE.get("InternalApi"), INTERNAL_API_WARNING));
308+
}
309+
310+
return methodBuilder
311+
.setHeaderCommentStatements(
312+
SettingsCommentComposer.createCallSettingsGetterComment(
313+
getMethodNameFromSettingsVarName(javaMethodName),
314+
protoMethod.isDeprecated(),
315+
protoMethod.selectiveGapicType() == SelectiveGapicType.INTERNAL))
316+
.setAnnotations(annotations)
317+
.build();
318+
}
319+
307320
private static MethodDefinition createCreatorMethod(Service service, TypeStore typeStore) {
308321
TypeNode stubClassType = typeStore.get(ClassNames.getServiceStubSettingsClassName(service));
309322
VariableExpr stubVarExpr =
@@ -771,7 +784,9 @@ private static List<MethodDefinition> createNestedBuilderSettingsGetterMethods(
771784
methodBuilder
772785
.setHeaderCommentStatements(
773786
SettingsCommentComposer.createCallSettingsBuilderGetterComment(
774-
getMethodNameFromSettingsVarName(javaMethodName), protoMethod.isDeprecated()))
787+
getMethodNameFromSettingsVarName(javaMethodName),
788+
protoMethod.isDeprecated(),
789+
protoMethod.selectiveGapicType() == SelectiveGapicType.INTERNAL))
775790
.setAnnotations(
776791
protoMethod.isDeprecated()
777792
? Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED))
@@ -787,7 +802,8 @@ private static List<MethodDefinition> createNestedBuilderSettingsGetterMethods(
787802
.setHeaderCommentStatements(
788803
SettingsCommentComposer.createCallSettingsBuilderGetterComment(
789804
getMethodNameFromSettingsVarName(javaMethodName),
790-
protoMethod.isDeprecated()))
805+
protoMethod.isDeprecated(),
806+
protoMethod.selectiveGapicType() == SelectiveGapicType.INTERNAL))
791807
.setAnnotations(
792808
protoMethod.isDeprecated()
793809
? Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED))
@@ -822,6 +838,7 @@ private static TypeStore createStaticTypes() {
822838
ApiClientHeaderProvider.class,
823839
ApiFunction.class,
824840
BetaApi.class,
841+
InternalApi.class,
825842
ClientContext.class,
826843
ClientSettings.class,
827844
Generated.class,

0 commit comments

Comments
 (0)