feat: Selective gapic generation phase II (#3730)

## Implement Selective GAPIC Generation (Phase II)

This PR implements Phase II of selective GAPIC generation within the
`gapic-generator-java` project. This allows for finer control over the
intended usage of generated client methods (public, internal, or hidden)
by providing selective gapic generation configuration in service yaml.

### Key Changes:

#### 1. Model Updates
* Added a `isInternalApi` attribute to the internal representation of
methods to track their intended visibility (e.g., public, internal).

#### 2. Parser Logic
* Introduced the `getMethodSelectiveGapicType()` method responsible for
parsing the selective generation configuration for each method.
* Modified service filtering logic: Service classes will not be
generated if the service definition contains no methods or includes only
methods marked as **`HIDDEN`**.
* Enhanced `parseService()` to determine and assign the appropriate
`SelectiveGapicType` to each service method and its corresponding
generated variants (e.g., overloaded methods).

#### 3. Composer (Code Generation) Updates
* **Method Annotations:** For all method variants designated as
`INTERNAL`, generate an `@InternalApi` annotation accompanied by a
warning message discouraging external use.
* **Method Header Comments:** For methods marked as `INTERNAL`, generate
a specific comment in the method's header indicating its intended
internal-only usage.
* **Sample Generation:** Adjusted the logic for generating
`package-info.java` samples to prevent the usage of any methods marked
as `INTERNAL`.

#### 4. Tests
* Added **unit tests** covering the new parser logic and comment
generation changes related to selective generation types.
* Added/updated **golden unit/integration tests** to verify the correct
code output for various selective generation scenarios, including
services with:
    * All public methods.
    * A mix of public, `INTERNAL`, and/or `HIDDEN` methods.
* No public methods (verifying that the service class is not generated).

Author: cindy-peng

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,13 +142,20 @@ public boolean emptyComments() {
       return Strings.isNullOrEmpty(throwsType)
           && Strings.isNullOrEmpty(throwsDescription)
           && Strings.isNullOrEmpty(deprecated)
+          && Strings.isNullOrEmpty(internalOnly)
           && Strings.isNullOrEmpty(returnDescription)
           && paramsList.isEmpty()
           && componentsList.isEmpty();
     }
 
     public JavaDocComment build() {
-      // @param, @throws, @return, and @deprecated should always get printed at the end.
+      // Add additional descriptive text before block tags.
+      if (!Strings.isNullOrEmpty(internalOnly)) {
+        componentsList.add(
+            String.format("<p> <b>Warning: </b>%s", HtmlEscaper.process(internalOnly)));
+      }
+      // @param, @throws, @return and @deprecated should always get printed at the
+      // end.
       componentsList.addAll(paramsList);
       if (!Strings.isNullOrEmpty(throwsType)) {
         componentsList.add(

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 for internal use only. Please do not use it 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

@@ -59,31 +59,31 @@ public class SettingsCommentComposer {
       "Retries are configured for idempotent methods but not for non-idempotent methods.";
 
   public static final CommentStatement DEFAULT_SCOPES_COMMENT =
-      toSimpleComment("The default scopes of the service.");
+      toCommentStatement("The default scopes of the service.");
 
   public static final CommentStatement DEFAULT_EXECUTOR_PROVIDER_BUILDER_METHOD_COMMENT =
-      toSimpleComment("Returns a builder for the default ExecutorProvider for this service.");
+      toCommentStatement("Returns a builder for the default ExecutorProvider for this service.");
 
   public static final CommentStatement DEFAULT_SERVICE_NAME_METHOD_COMMENT =
-      toSimpleComment("Returns the default service name.");
+      toCommentStatement("Returns the default service name.");
   public static final CommentStatement DEFAULT_SERVICE_ENDPOINT_METHOD_COMMENT =
-      toSimpleComment("Returns the default service endpoint.");
+      toCommentStatement("Returns the default service endpoint.");
   public static final CommentStatement DEFAULT_SERVICE_MTLS_ENDPOINT_METHOD_COMMENT =
-      toSimpleComment("Returns the default mTLS service endpoint.");
+      toCommentStatement("Returns the default mTLS service endpoint.");
   public static final CommentStatement DEFAULT_SERVICE_SCOPES_METHOD_COMMENT =
-      toSimpleComment("Returns the default service scopes.");
+      toCommentStatement("Returns the default service scopes.");
 
   public static final CommentStatement DEFAULT_CREDENTIALS_PROVIDER_BUILDER_METHOD_COMMENT =
-      toSimpleComment("Returns a builder for the default credentials for this service.");
+      toCommentStatement("Returns a builder for the default credentials for this service.");
 
   public static final CommentStatement DEFAULT_TRANSPORT_PROVIDER_BUILDER_METHOD_COMMENT =
-      toSimpleComment("Returns a builder for the default ChannelProvider for this service.");
+      toCommentStatement("Returns a builder for the default ChannelProvider for this service.");
 
   public static final CommentStatement NEW_BUILDER_METHOD_COMMENT =
-      toSimpleComment("Returns a new builder for this class.");
+      toCommentStatement("Returns a new builder for this class.");
 
   public static final CommentStatement TO_BUILDER_METHOD_COMMENT =
-      toSimpleComment("Returns a builder containing all the values of this settings class.");
+      toCommentStatement("Returns a builder containing all the values of this settings class.");
 
   public static final List<CommentStatement> APPLY_TO_ALL_UNARY_METHODS_METHOD_COMMENTS =
       Arrays.asList(
@@ -103,9 +103,10 @@ public class SettingsCommentComposer {
 
   public SettingsCommentComposer(String transportPrefix) {
     this.newTransportBuilderMethodComment =
-        toSimpleComment(String.format("Returns a new %s builder for this class.", transportPrefix));
+        toCommentStatement(
+            String.format("Returns a new %s builder for this class.", transportPrefix));
     this.transportProviderBuilderMethodComment =
-        toSimpleComment(
+        toCommentStatement(
             String.format(
                 "Returns a builder for the default %s ChannelProvider for this service.",
                 transportPrefix));
@@ -120,23 +121,21 @@ 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 toCommentStatement(
+        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));
+    return toCommentStatement(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)
-        : toSimpleComment(methodComment);
+    return toCommentStatement(methodComment, isMethodDeprecated, isMethodInternal);
   }
 
   public static List<CommentStatement> createClassHeaderComments(
@@ -201,15 +200,21 @@ public static List<CommentStatement> createClassHeaderComments(
         CommentStatement.withComment(javaDocCommentBuilder.build()));
   }
 
-  private static CommentStatement toSimpleComment(String comment) {
-    return CommentStatement.withComment(JavaDocComment.withComment(comment));
+  private static CommentStatement toCommentStatement(String comment) {
+    return toCommentStatement(comment, false, false);
   }
 
-  private static CommentStatement toDeprecatedSimpleComment(String comment) {
-    return CommentStatement.withComment(
-        JavaDocComment.builder()
-            .addComment(comment)
-            .setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING)
-            .build());
+  private static CommentStatement toCommentStatement(
+      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;
@@ -62,6 +63,7 @@
 import com.google.api.generator.gapic.composer.samplecode.ServiceClientMethodSampleComposer;
 import com.google.api.generator.gapic.composer.store.TypeStore;
 import com.google.api.generator.gapic.composer.utils.ClassNames;
+import com.google.api.generator.gapic.composer.utils.CommonStrings;
 import com.google.api.generator.gapic.composer.utils.PackageChecker;
 import com.google.api.generator.gapic.model.Field;
 import com.google.api.generator.gapic.model.GapicClass;
@@ -103,7 +105,6 @@
 import javax.annotation.Generated;
 
 public abstract class AbstractServiceClientClassComposer implements ClassComposer {
-  private static final String PAGED_RESPONSE_TYPE_NAME_PATTERN = "%sPagedResponse";
   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";
@@ -127,6 +128,21 @@ protected TransportContext getTransportContext() {
     return transportContext;
   }
 
+  private static List<AnnotationNode> createMethodAnnotations(Method method, TypeStore typeStore) {
+    List<AnnotationNode> annotations = new ArrayList<>();
+    if (method.isDeprecated()) {
+      annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
+    }
+
+    if (method.isInternalApi()) {
+      annotations.add(
+          AnnotationNode.withTypeAndDescription(
+              typeStore.get("InternalApi"), CommonStrings.INTERNAL_API_WARNING));
+    }
+
+    return annotations;
+  }
+
   @Override
   public GapicClass generate(GapicContext context, Service service) {
     Map<String, ResourceName> resourceNames = context.helperResourceNames();
@@ -136,7 +152,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<>();
@@ -713,7 +728,8 @@ private static List<MethodDefinition> createMethodVariants(
     TypeNode methodInputType = method.inputType();
     TypeNode methodOutputType =
         method.isPaged()
-            ? typeStore.get(String.format(PAGED_RESPONSE_TYPE_NAME_PATTERN, method.name()))
+            ? typeStore.get(
+                String.format(CommonStrings.PAGED_RESPONSE_TYPE_NAME_PATTERN, method.name()))
             : method.outputType();
     if (method.hasLro()) {
       LongrunningOperation lro = method.lro();
@@ -802,11 +818,8 @@ private static List<MethodDefinition> createMethodVariants(
             methodVariantBuilder.setReturnType(methodOutputType).setReturnExpr(rpcInvocationExpr);
       }
 
-      if (method.isDeprecated()) {
-        methodVariantBuilder =
-            methodVariantBuilder.setAnnotations(
-                Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED)));
-      }
+      methodVariantBuilder =
+          methodVariantBuilder.setAnnotations(createMethodAnnotations(method, typeStore));
       methodVariantBuilder = methodVariantBuilder.setBody(statements);
       javaMethods.add(methodVariantBuilder.build());
     }
@@ -826,9 +839,9 @@ private static MethodDefinition createMethodDefaultMethod(
     TypeNode methodInputType = method.inputType();
     TypeNode methodOutputType =
         method.isPaged()
-            ? typeStore.get(String.format(PAGED_RESPONSE_TYPE_NAME_PATTERN, method.name()))
+            ? typeStore.get(
+                String.format(CommonStrings.PAGED_RESPONSE_TYPE_NAME_PATTERN, method.name()))
             : method.outputType();
-    List<AnnotationNode> annotations = new ArrayList<>();
     if (method.hasLro()) {
       LongrunningOperation lro = method.lro();
       methodOutputType =
@@ -885,10 +898,6 @@ private static MethodDefinition createMethodDefaultMethod(
             .setName(String.format(method.hasLro() ? "%sAsync" : "%s", methodName))
             .setArguments(Arrays.asList(requestArgVarExpr));
 
-    if (method.isDeprecated()) {
-      annotations.add(AnnotationNode.withType(TypeNode.DEPRECATED));
-    }
-
     if (isProtoEmptyType(methodOutputType)) {
       methodBuilder =
           methodBuilder
@@ -899,8 +908,7 @@ private static MethodDefinition createMethodDefaultMethod(
           methodBuilder.setReturnExpr(callableMethodExpr).setReturnType(methodOutputType);
     }
 
-    methodBuilder.setAnnotations(annotations);
-
+    methodBuilder.setAnnotations(createMethodAnnotations(method, typeStore));
     return methodBuilder.build();
   }
 
@@ -1039,11 +1047,8 @@ private static MethodDefinition createCallableMethod(
     }
 
     MethodDefinition.Builder methodDefBuilder = MethodDefinition.builder();
-    if (method.isDeprecated()) {
-      methodDefBuilder =
-          methodDefBuilder.setAnnotations(
-              Arrays.asList(AnnotationNode.withType(TypeNode.DEPRECATED)));
-    }
+
+    methodDefBuilder = methodDefBuilder.setAnnotations(createMethodAnnotations(method, typeStore));
 
     return methodDefBuilder
         .setHeaderCommentStatements(
@@ -1774,6 +1779,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,
@@ -1828,7 +1834,7 @@ private static void createVaporTypes(Service service, TypeStore typeStore) {
         service.pakkage(),
         service.methods().stream()
             .filter(m -> m.isPaged())
-            .map(m -> String.format(PAGED_RESPONSE_TYPE_NAME_PATTERN, m.name()))
+            .map(m -> String.format(CommonStrings.PAGED_RESPONSE_TYPE_NAME_PATTERN, m.name()))
             .collect(Collectors.toList()),
         true,
         ClassNames.getServiceClientClassName(service));
@@ -1846,7 +1852,7 @@ private static List<Reference> getGenericsForCallable(
       return Arrays.asList(
           method.inputType().reference(),
           typeStore
-              .get(String.format(PAGED_RESPONSE_TYPE_NAME_PATTERN, method.name()))
+              .get(String.format(CommonStrings.PAGED_RESPONSE_TYPE_NAME_PATTERN, method.name()))
               .reference());
     }
     return Arrays.asList(method.inputType().reference(), method.outputType().reference());

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

@@ -47,6 +47,7 @@
 import com.google.api.generator.gapic.composer.defaultvalue.DefaultValueComposer;
 import com.google.api.generator.gapic.composer.store.TypeStore;
 import com.google.api.generator.gapic.composer.utils.ClassNames;
+import com.google.api.generator.gapic.composer.utils.CommonStrings;
 import com.google.api.generator.gapic.model.Field;
 import com.google.api.generator.gapic.model.GapicClass;
 import com.google.api.generator.gapic.model.GapicClass.Kind;
@@ -87,7 +88,6 @@ public abstract class AbstractServiceClientTestClassComposer implements ClassCom
 
   protected static final String CLIENT_VAR_NAME = "client";
   private static final String MOCK_SERVICE_VAR_NAME_PATTERN = "mock%s";
-  private static final String PAGED_RESPONSE_TYPE_NAME_PATTERN = "%sPagedResponse";
 
   protected static final TypeStore FIXED_TYPESTORE = createStaticTypes();
   protected static final AnnotationNode TEST_ANNOTATION =
@@ -944,7 +944,7 @@ private void addDynamicTypes(GapicContext context, Service service, TypeStore ty
         service.pakkage(),
         service.methods().stream()
             .filter(m -> m.isPaged())
-            .map(m -> String.format(PAGED_RESPONSE_TYPE_NAME_PATTERN, m.name()))
+            .map(m -> String.format(CommonStrings.PAGED_RESPONSE_TYPE_NAME_PATTERN, m.name()))
             .collect(Collectors.toList()),
         true,
         ClassNames.getServiceClientClassName(service));
@@ -956,7 +956,7 @@ private void addDynamicTypes(GapicContext context, Service service, TypeStore ty
         }
         typeStore.put(
             service.pakkage(),
-            String.format(PAGED_RESPONSE_TYPE_NAME_PATTERN, mixinMethod.name()),
+            String.format(CommonStrings.PAGED_RESPONSE_TYPE_NAME_PATTERN, mixinMethod.name()),
             true,
             ClassNames.getServiceClientClassName(service));
       }
@@ -995,7 +995,7 @@ protected static TypeNode getCallableType(Method protoMethod) {
   private static TypeNode getPagedResponseType(Method method, Service service) {
     return TypeNode.withReference(
         VaporReference.builder()
-            .setName(String.format(PAGED_RESPONSE_TYPE_NAME_PATTERN, method.name()))
+            .setName(String.format(CommonStrings.PAGED_RESPONSE_TYPE_NAME_PATTERN, method.name()))
             .setPakkage(service.pakkage())
             .setEnclosingClassNames(ClassNames.getServiceClientClassName(service))
             .setIsStaticImport(true)