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)