feat: Selective gapic generation phase II

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

@@ -51,6 +51,7 @@ public abstract static class Builder {
     String throwsType = null;
     String throwsDescription = null;
     String deprecated = null;
+    String internalOnly = null;
     String returnDescription = null;
     List<String> paramsList = new ArrayList<>();
     List<String> componentsList = new ArrayList<>();
@@ -71,6 +72,11 @@ public Builder setDeprecated(String deprecatedText) {
       return this;
     }
 
+    public Builder setInternalOnly(String internalOnlyText) {
+      internalOnly = internalOnlyText;
+      return this;
+    }
+
     public Builder setReturn(String returnText) {
       returnDescription = returnText;
       return this;
@@ -136,6 +142,7 @@ public boolean emptyComments() {
       return Strings.isNullOrEmpty(throwsType)
           && Strings.isNullOrEmpty(throwsDescription)
           && Strings.isNullOrEmpty(deprecated)
+          && Strings.isNullOrEmpty(internalOnly)
           && Strings.isNullOrEmpty(returnDescription)
           && paramsList.isEmpty()
           && componentsList.isEmpty();
@@ -151,6 +158,9 @@ public JavaDocComment build() {
       if (!Strings.isNullOrEmpty(deprecated)) {
         componentsList.add(String.format("@deprecated %s", deprecated));
       }
+      if (!Strings.isNullOrEmpty(internalOnly)) {
+        componentsList.add(String.format("@InternalApi %s", internalOnly));
+      }
       if (!Strings.isNullOrEmpty(returnDescription)) {
         componentsList.add(String.format("@return %s", returnDescription));
       }

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

@@ -49,6 +49,9 @@ public class CommentComposer {
   static final String DEPRECATED_METHOD_STRING =
       "This method is deprecated and will be removed in the next major version update.";
 
+  static final String INTERNAL_ONLY_METHOD_STRING =
+      "This method is internal used only. Please do not use directly.";
+
   public static final CommentStatement APACHE_LICENSE_COMMENT =
       CommentStatement.withComment(BlockComment.withComment(APACHE_LICENSE_STRING));
 

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

@@ -202,6 +202,10 @@ public static List<CommentStatement> createRpcMethodHeaderComment(
       methodJavadocBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING);
     }
 
+    if (method.isInternalApi()) {
+      methodJavadocBuilder.setInternalOnly(CommentComposer.INTERNAL_ONLY_METHOD_STRING);
+    }
+
     List<CommentStatement> comments = new ArrayList<>();
     comments.add(CommentComposer.AUTO_GENERATED_METHOD_COMMENT);
     if (!methodJavadocBuilder.emptyComments()) {
@@ -345,6 +349,10 @@ public static List<CommentStatement> createRpcCallableMethodHeaderComment(
       methodJavadocBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING);
     }
 
+    if (method.isInternalApi()) {
+      methodJavadocBuilder.setInternalOnly(CommentComposer.INTERNAL_ONLY_METHOD_STRING);
+    }
+
     return Arrays.asList(
         CommentComposer.AUTO_GENERATED_METHOD_COMMENT,
         CommentStatement.withComment(methodJavadocBuilder.build()));

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

@@ -120,22 +120,22 @@ public CommentStatement getTransportProviderBuilderMethodComment() {
   }
 
   public static CommentStatement createCallSettingsGetterComment(
-      String javaMethodName, boolean isMethodDeprecated) {
-    String methodComment = String.format(CALL_SETTINGS_METHOD_DOC_PATTERN, javaMethodName);
-    return isMethodDeprecated
-        ? toDeprecatedSimpleComment(methodComment)
-        : toSimpleComment(methodComment);
+      String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
+    return toDeprecatedInternalSimpleComment(
+        String.format(CALL_SETTINGS_METHOD_DOC_PATTERN, javaMethodName),
+        isMethodDeprecated,
+        isMethodInternal);
   }
 
   public static CommentStatement createBuilderClassComment(String outerClassName) {
     return toSimpleComment(String.format(BUILDER_CLASS_DOC_PATTERN, outerClassName));
   }
 
   public static CommentStatement createCallSettingsBuilderGetterComment(
-      String javaMethodName, boolean isMethodDeprecated) {
+      String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
     String methodComment = String.format(CALL_SETTINGS_BUILDER_METHOD_DOC_PATTERN, javaMethodName);
-    return isMethodDeprecated
-        ? toDeprecatedSimpleComment(methodComment)
+    return isMethodDeprecated || isMethodInternal
+        ? toDeprecatedInternalSimpleComment(methodComment, isMethodDeprecated, isMethodInternal)
         : toSimpleComment(methodComment);
   }
 
@@ -205,11 +205,17 @@ private static CommentStatement toSimpleComment(String comment) {
     return CommentStatement.withComment(JavaDocComment.withComment(comment));
   }
 
-  private static CommentStatement toDeprecatedSimpleComment(String comment) {
-    return CommentStatement.withComment(
-        JavaDocComment.builder()
-            .addComment(comment)
-            .setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING)
-            .build());
+  private static CommentStatement toDeprecatedInternalSimpleComment(
+      String comment, boolean isDeprecated, boolean isInternal) {
+    JavaDocComment.Builder docBuilder = JavaDocComment.builder().addComment(comment);
+    docBuilder =
+        isDeprecated
+            ? docBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING)
+            : docBuilder;
+    docBuilder =
+        isInternal
+            ? docBuilder.setInternalOnly(CommentComposer.INTERNAL_ONLY_METHOD_STRING)
+            : docBuilder;
+    return CommentStatement.withComment(docBuilder.build());
   }
 }

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

@@ -18,6 +18,7 @@
 import com.google.api.core.ApiFuture;
 import com.google.api.core.ApiFutures;
 import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
 import com.google.api.gax.core.BackgroundResource;
 import com.google.api.gax.longrunning.OperationFuture;
 import com.google.api.gax.paging.AbstractFixedSizeCollection;
@@ -107,6 +108,8 @@ public abstract class AbstractServiceClientClassComposer implements ClassCompose
   private static final String CALLABLE_NAME_PATTERN = "%sCallable";
   private static final String PAGED_CALLABLE_NAME_PATTERN = "%sPagedCallable";
   private static final String OPERATION_CALLABLE_NAME_PATTERN = "%sOperationCallable";
+  private static final String INTERNAL_API_WARNING =
+      "Internal API. This API is not intended for public consumption.";
 
   private static final Reference LIST_REFERENCE = ConcreteReference.withClazz(List.class);
   private static final Reference MAP_REFERENCE = ConcreteReference.withClazz(Map.class);
@@ -136,7 +139,6 @@ public GapicClass generate(GapicContext context, Service service) {
     GapicClass.Kind kind = Kind.MAIN;
     String pakkage = service.pakkage();
     boolean hasLroClient = service.hasStandardLroMethods();
-
     List<Sample> samples = new ArrayList<>();
     Map<String, List<String>> grpcRpcsToJavaMethodNames = new HashMap<>();
     Map<String, List<String>> methodVariantsForClientHeader = new HashMap<>();
@@ -802,11 +804,18 @@ private static List<MethodDefinition> createMethodVariants(
             methodVariantBuilder.setReturnType(methodOutputType).setReturnExpr(rpcInvocationExpr);
       }
 
+      List<AnnotationNode> annotations = new ArrayList<>();
       if (method.isDeprecated()) {
-        methodVariantBuilder =
-            methodVariantBuilder.setAnnotations(
-                Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED)));
+        annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
+      }
+
+      if (method.isInternalApi()) {
+        annotations.add(
+            AnnotationNode.withTypeAndDescription(
+                typeStore.get("InternalApi"), INTERNAL_API_WARNING));
       }
+
+      methodVariantBuilder = methodVariantBuilder.setAnnotations(annotations);
       methodVariantBuilder = methodVariantBuilder.setBody(statements);
       javaMethods.add(methodVariantBuilder.build());
     }
@@ -889,6 +898,12 @@ private static MethodDefinition createMethodDefaultMethod(
       annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
     }
 
+    if (method.isInternalApi()) {
+      annotations.add(
+          AnnotationNode.withTypeAndDescription(
+              typeStore.get("InternalApi"), INTERNAL_API_WARNING));
+    }
+
     if (isProtoEmptyType(methodOutputType)) {
       methodBuilder =
           methodBuilder
@@ -1039,11 +1054,17 @@ private static MethodDefinition createCallableMethod(
     }
 
     MethodDefinition.Builder methodDefBuilder = MethodDefinition.builder();
+    List<AnnotationNode> annotations = new ArrayList<>();
     if (method.isDeprecated()) {
-      methodDefBuilder =
-          methodDefBuilder.setAnnotations(
-              Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED)));
+      annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
     }
+    if (method.isInternalApi()) {
+      annotations.add(
+          AnnotationNode.withTypeAndDescription(
+              typeStore.get("InternalApi"), INTERNAL_API_WARNING));
+    }
+
+    methodDefBuilder = methodDefBuilder.setAnnotations(annotations);
 
     return methodDefBuilder
         .setHeaderCommentStatements(
@@ -1774,6 +1795,7 @@ private static TypeStore createTypes(Service service, Map<String, Message> messa
             ApiFutures.class,
             BackgroundResource.class,
             BetaApi.class,
+            InternalApi.class,
             BidiStreamingCallable.class,
             ClientStreamingCallable.class,
             Generated.class,

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

@@ -16,6 +16,7 @@
 
 import com.google.api.core.ApiFunction;
 import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
 import com.google.api.gax.core.GoogleCredentialsProvider;
 import com.google.api.gax.core.InstantiatingExecutorProvider;
 import com.google.api.gax.rpc.ApiClientHeaderProvider;
@@ -85,6 +86,8 @@ public abstract class AbstractServiceSettingsClassComposer implements ClassCompo
 
   private static final String OPERATION_SETTINGS_LITERAL = "OperationSettings";
   private static final String SETTINGS_LITERAL = "Settings";
+  private static final String INTERNAL_API_WARNING =
+      "Internal API. This API is not intended for public consumption.";
   protected static final TypeStore FIXED_TYPESTORE = createStaticTypes();
 
   private final TransportContext transportContext;
@@ -133,16 +136,21 @@ public GapicClass generate(GapicContext context, Service service) {
 
   private static List<CommentStatement> createClassHeaderComments(
       Service service, TypeNode classType, List<Sample> samples) {
-    // Pick the first pure unary rpc method, if no such method exists, then pick the first in the
+    // Pick the first public pure unary rpc method, if no such method exists, then pick the first
+    // public in the
     // list.
+    List<Method> publicMethods =
+        service.methods().stream()
+            .filter(m -> m.isInternalApi() == false)
+            .collect(Collectors.toList());
     Optional<Method> methodOpt =
-        service.methods().isEmpty()
+        publicMethods.isEmpty()
             ? Optional.empty()
             : Optional.of(
-                service.methods().stream()
+                publicMethods.stream()
                     .filter(m -> m.stream() == Stream.NONE && !m.hasLro() && !m.isPaged())
                     .findFirst()
-                    .orElse(service.methods().get(0)));
+                    .orElse(publicMethods.get(0)));
     Optional<String> methodNameOpt =
         methodOpt.isPresent() ? Optional.of(methodOpt.get().name()) : Optional.empty();
     Optional<Sample> sampleCode =
@@ -156,9 +164,9 @@ private static List<CommentStatement> createClassHeaderComments(
     // Create a sample for a LRO method using LRO-specific RetrySettings, if one exists in the
     // service.
     Optional<Method> lroMethodOpt =
-        service.methods().isEmpty()
+        publicMethods.isEmpty()
             ? Optional.empty()
-            : service.methods().stream()
+            : publicMethods.stream()
                 .filter(m -> m.stream() == Stream.NONE && m.hasLro())
                 .findFirst();
     Optional<String> lroMethodNameOpt =
@@ -270,40 +278,44 @@ private static List<MethodDefinition> createSettingsGetterMethods(
     List<MethodDefinition> javaMethods = new ArrayList<>();
     for (Method protoMethod : service.methods()) {
       String javaStyleName = JavaStyle.toLowerCamelCase(protoMethod.name());
-      String javaMethodName =
-          String.format("%sSettings", JavaStyle.toLowerCamelCase(protoMethod.name()));
+      String javaMethodName = String.format("%sSettings", javaStyleName);
       MethodDefinition.Builder methodBuilder =
           methodMakerFn.apply(getCallSettingsType(protoMethod, typeStore), javaMethodName);
-      javaMethods.add(
-          methodBuilder
-              .setHeaderCommentStatements(
-                  SettingsCommentComposer.createCallSettingsGetterComment(
-                      getMethodNameFromSettingsVarName(javaMethodName), protoMethod.isDeprecated()))
-              .setAnnotations(
-                  protoMethod.isDeprecated()
-                      ? Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED))
-                      : Collections.emptyList())
-              .build());
+      javaMethods.add(methodBuilderHelper(protoMethod, methodBuilder, javaMethodName));
       if (protoMethod.hasLro()) {
         javaMethodName = String.format("%sOperationSettings", javaStyleName);
         methodBuilder =
             methodMakerFn.apply(getOperationCallSettingsType(protoMethod), javaMethodName);
-        javaMethods.add(
-            methodBuilder
-                .setHeaderCommentStatements(
-                    SettingsCommentComposer.createCallSettingsGetterComment(
-                        getMethodNameFromSettingsVarName(javaMethodName),
-                        protoMethod.isDeprecated()))
-                .setAnnotations(
-                    protoMethod.isDeprecated()
-                        ? Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED))
-                        : Collections.emptyList())
-                .build());
+        javaMethods.add(methodBuilderHelper(protoMethod, methodBuilder, javaMethodName));
       }
     }
     return javaMethods;
   }
 
+  // Add method header comment statements and annotations.
+  private static MethodDefinition methodBuilderHelper(
+      Method protoMethod, MethodDefinition.Builder methodBuilder, String javaMethodName) {
+    List<AnnotationNode> annotations = new ArrayList<>();
+    if (protoMethod.isDeprecated()) {
+      annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
+    }
+
+    if (protoMethod.isInternalApi()) {
+      annotations.add(
+          AnnotationNode.withTypeAndDescription(
+              FIXED_TYPESTORE.get("InternalApi"), INTERNAL_API_WARNING));
+    }
+
+    return methodBuilder
+        .setHeaderCommentStatements(
+            SettingsCommentComposer.createCallSettingsGetterComment(
+                getMethodNameFromSettingsVarName(javaMethodName),
+                protoMethod.isDeprecated(),
+                protoMethod.isInternalApi()))
+        .setAnnotations(annotations)
+        .build();
+  }
+
   private static MethodDefinition createCreatorMethod(Service service, TypeStore typeStore) {
     TypeNode stubClassType = typeStore.get(ClassNames.getServiceStubSettingsClassName(service));
     VariableExpr stubVarExpr =
@@ -771,7 +783,9 @@ private static List<MethodDefinition> createNestedBuilderSettingsGetterMethods(
           methodBuilder
               .setHeaderCommentStatements(
                   SettingsCommentComposer.createCallSettingsBuilderGetterComment(
-                      getMethodNameFromSettingsVarName(javaMethodName), protoMethod.isDeprecated()))
+                      getMethodNameFromSettingsVarName(javaMethodName),
+                      protoMethod.isDeprecated(),
+                      protoMethod.isInternalApi()))
               .setAnnotations(
                   protoMethod.isDeprecated()
                       ? Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED))
@@ -787,7 +801,8 @@ private static List<MethodDefinition> createNestedBuilderSettingsGetterMethods(
                 .setHeaderCommentStatements(
                     SettingsCommentComposer.createCallSettingsBuilderGetterComment(
                         getMethodNameFromSettingsVarName(javaMethodName),
-                        protoMethod.isDeprecated()))
+                        protoMethod.isDeprecated(),
+                        protoMethod.isInternalApi()))
                 .setAnnotations(
                     protoMethod.isDeprecated()
                         ? Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED))
@@ -822,6 +837,7 @@ private static TypeStore createStaticTypes() {
             ApiClientHeaderProvider.class,
             ApiFunction.class,
             BetaApi.class,
+            InternalApi.class,
             ClientContext.class,
             ClientSettings.class,
             Generated.class,