feat: Update Gapic generator and Gax to emit api-versioning via header (

#2671)

This is part 2, following changes in
#2630

Changes in this pr:
- ApiClientHeaderProvider: add key and token setter for api version.
- AbstractServiceStubSettingsClassComposer: add logic to set this header
when api-version is present (not null or empty)
- Unit and golden tests to reflect above changes. (This includeds a few
new golden files created for tests based on the dedicated proto created
in #2630)

This pr does not include gapic-showcased testing for now.
---
manual tested with
[gapic-showcase](https://github.com/googleapis/gapic-showcase) v0.33.0

steps: 
- Use gapic-showcase v0.33.0 (which includes update in 1484)
- use `gapic-showcase run -v` which prints the request header
- From showcase folder, run `mvn verify -P enable-integration-tests
-Dit.test=ITAutoPopulatedFields.java -pl=gapic-showcase`

Printed header in manual testing
Grpc
```
2024/04/16 10:26:41 Received Unary Request for Method: /google.showcase.v1beta1.Echo/Echo
2024/04/16 10:26:41     Request headers:
2024/04/16 10:26:41       grpc-accept-encoding: gzip
2024/04/16 10:26:41       content-type: application/grpc
2024/04/16 10:26:41       x-goog-api-version: v1_20240408
2024/04/16 10:26:41       :authority: localhost:7469
2024/04/16 10:26:41       user-agent: grpc-java-netty/1.62.2
2024/04/16 10:26:41       x-goog-api-client: gl-java/17.0.7__Eclipse-Adoptium__Temurin-17.0.7-7 gapic/0.0.1-SNAPSHOT gax/2.46.2-SNAPSHOT grpc/1.62.2
2024/04/16 10:26:41     Request:  error:{code:2}  request_id:"1e26ee16-ed07-4eeb-be0e-49b769678779"  other_request_id:"40883e5d-3b20-4add-854c-9808bd009260"
2024/04/16 10:26:41     Returning Error: rpc error: code = Unknown desc = 
```
Httpjson
```
2024/04/16 10:26:41 Received POST request matching '/v1beta1/echo:echo': "/v1beta1/echo:echo"                                                               
2024/04/16 10:26:41   urlPathParams (expect 0, have 0): map[]                 
2024/04/16 10:26:41   urlRequestHeaders:                                                                                                                    
    User-Agent: "Google-HTTP-Java-Client/1.44.1 (gzip)"                                                                                                     
    Content-Type: "application/json; charset=utf-8"                           
    Connection: "keep-alive"                                                                                                                                
    Accept-Encoding: "gzip"                                                   
    X-Goog-Api-Client: "gl-java/17.0.7__Eclipse-Adoptium__Temurin-17.0.7-7 gapic/0.0.1-SNAPSHOT gax/2.46.2-SNAPSHOT rest/"                                  
    X-Goog-Api-Version: "v1_20240408"                                                                                                                       
    Accept: "text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2"            
    Content-Length: "129"                                                     
2024/04/16 10:26:41   request: {                                                                                                                            
  "error":  {                                                                                                                                               
    "code":  500,                                                                                                                                           
    "message":  "",                                                                                                                                         
    "details":  []                                                            
  },                                                                                                                                                        
  "severity":  "UNNECESSARY",                                                                                                                               
  "header":  "",                                                                                                                                            
  "otherHeader":  "",                                                         
  "requestId":  "e690a84b-176d-421e-9e5d-ba752f68fec8",                       
  "otherRequestId":  "47e0fbde-056a-43ae-bba6-8b6770d861f7"                   
}    
```

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

@@ -370,6 +370,16 @@ protected MethodDefinition createApiClientHeaderProviderBuilderMethod(
             .setReturnType(returnType)
             .build();
 
+    if (service.hasApiVersion()) {
+
+      returnExpr =
+          MethodInvocationExpr.builder()
+              .setExprReferenceExpr(returnExpr)
+              .setMethodName("setApiVersionToken")
+              .setArguments(ValueExpr.withValue(StringObjectValue.withValue(service.apiVersion())))
+              .setReturnType(returnType)
+              .build();
+    }
     return MethodDefinition.builder()
         .setScope(ScopeNode.PUBLIC)
         .setIsStatic(true)

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/ServiceStubSettingsClassComposerTest.java

@@ -54,6 +54,12 @@ public static Collection<Object[]> data() {
             GrpcTestProtoLoader.instance().parseDeprecatedService(),
             "localhost:7469",
             "v1"
+          },
+          {
+            "ApiVersionTestingStubSettings",
+            GrpcTestProtoLoader.instance().parseApiVersionTesting(),
+            "localhost:7469",
+            "v1"
           }
         });
   }

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/ApiVersionTestingStubSettings.golden

@@ -0,0 +1,248 @@
+package com.google.api.version.test.stub;
+
+import com.google.api.core.ApiFunction;
+import com.google.api.gax.core.GaxProperties;
+import com.google.api.gax.core.GoogleCredentialsProvider;
+import com.google.api.gax.core.InstantiatingExecutorProvider;
+import com.google.api.gax.grpc.GaxGrpcProperties;
+import com.google.api.gax.grpc.GrpcTransportChannel;
+import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
+import com.google.api.gax.retrying.RetrySettings;
+import com.google.api.gax.rpc.ApiClientHeaderProvider;
+import com.google.api.gax.rpc.ClientContext;
+import com.google.api.gax.rpc.StatusCode;
+import com.google.api.gax.rpc.StubSettings;
+import com.google.api.gax.rpc.TransportChannelProvider;
+import com.google.api.gax.rpc.UnaryCallSettings;
+import com.google.api.version.test.EchoRequest;
+import com.google.api.version.test.EchoResponse;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.collect.Lists;
+import java.io.IOException;
+import java.util.List;
+import javax.annotation.Generated;
+
+// AUTO-GENERATED DOCUMENTATION AND CLASS.
+/**
+ * Settings class to configure an instance of {@link EchoWithVersionStub}.
+ *
+ * <p>The default instance has everything set to sensible defaults:
+ *
+ * <ul>
+ *   <li>The default service address (localhost) and default port (7469) are used.
+ *   <li>Credentials are acquired automatically through Application Default Credentials.
+ *   <li>Retries are configured for idempotent methods but not for non-idempotent methods.
+ * </ul>
+ *
+ * <p>The builder of this class is recursive, so contained classes are themselves builders. When
+ * build() is called, the tree of builders is called to create the complete settings object.
+ *
+ * <p>For example, to set the total timeout of echoWithVersionMethod to 30 seconds:
+ *
+ * <pre>{@code
+ * // This snippet has been automatically generated and should be regarded as a code template only.
+ * // It will require modifications to work:
+ * // - It may require correct/in-range values for request initialization.
+ * // - It may require specifying regional endpoints when creating the service client as shown in
+ * // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
+ * EchoWithVersionStubSettings.Builder echoWithVersionSettingsBuilder =
+ *     EchoWithVersionStubSettings.newBuilder();
+ * echoWithVersionSettingsBuilder
+ *     .echoWithVersionMethodSettings()
+ *     .setRetrySettings(
+ *         echoWithVersionSettingsBuilder
+ *             .echoWithVersionMethodSettings()
+ *             .getRetrySettings()
+ *             .toBuilder()
+ *             .setTotalTimeout(Duration.ofSeconds(30))
+ *             .build());
+ * EchoWithVersionStubSettings echoWithVersionSettings = echoWithVersionSettingsBuilder.build();
+ * }</pre>
+ */
+@Generated("by gapic-generator-java")
+public class EchoWithVersionStubSettings extends StubSettings<EchoWithVersionStubSettings> {
+  /** The default scopes of the service. */
+  private static final ImmutableList<String> DEFAULT_SERVICE_SCOPES =
+      ImmutableList.<String>builder().add("https://www.googleapis.com/auth/cloud-platform").build();
+
+  private final UnaryCallSettings<EchoRequest, EchoResponse> echoWithVersionMethodSettings;
+
+  /** Returns the object with the settings used for calls to echoWithVersionMethod. */
+  public UnaryCallSettings<EchoRequest, EchoResponse> echoWithVersionMethodSettings() {
+    return echoWithVersionMethodSettings;
+  }
+
+  public EchoWithVersionStub createStub() throws IOException {
+    if (getTransportChannelProvider()
+        .getTransportName()
+        .equals(GrpcTransportChannel.getGrpcTransportName())) {
+      return GrpcEchoWithVersionStub.create(this);
+    }
+    throw new UnsupportedOperationException(
+        String.format(
+            "Transport not supported: %s", getTransportChannelProvider().getTransportName()));
+  }
+
+  /** Returns a builder for the default ExecutorProvider for this service. */
+  public static InstantiatingExecutorProvider.Builder defaultExecutorProviderBuilder() {
+    return InstantiatingExecutorProvider.newBuilder();
+  }
+
+  /** Returns the default service endpoint. */
+  public static String getDefaultEndpoint() {
+    return "localhost:7469";
+  }
+
+  /** Returns the default mTLS service endpoint. */
+  public static String getDefaultMtlsEndpoint() {
+    return "localhost:7469";
+  }
+
+  /** Returns the default service scopes. */
+  public static List<String> getDefaultServiceScopes() {
+    return DEFAULT_SERVICE_SCOPES;
+  }
+
+  /** Returns a builder for the default credentials for this service. */
+  public static GoogleCredentialsProvider.Builder defaultCredentialsProviderBuilder() {
+    return GoogleCredentialsProvider.newBuilder()
+        .setScopesToApply(DEFAULT_SERVICE_SCOPES)
+        .setUseJwtAccessWithScope(true);
+  }
+
+  /** Returns a builder for the default ChannelProvider for this service. */
+  public static InstantiatingGrpcChannelProvider.Builder defaultGrpcTransportProviderBuilder() {
+    return InstantiatingGrpcChannelProvider.newBuilder()
+        .setMaxInboundMessageSize(Integer.MAX_VALUE);
+  }
+
+  public static TransportChannelProvider defaultTransportChannelProvider() {
+    return defaultGrpcTransportProviderBuilder().build();
+  }
+
+  public static ApiClientHeaderProvider.Builder defaultApiClientHeaderProviderBuilder() {
+    return ApiClientHeaderProvider.newBuilder()
+        .setGeneratedLibToken(
+            "gapic", GaxProperties.getLibraryVersion(EchoWithVersionStubSettings.class))
+        .setTransportToken(GaxGrpcProperties.getGrpcTokenName(), GaxGrpcProperties.getGrpcVersion())
+        .setApiVersionToken("fake_version");
+  }
+
+  /** Returns a new builder for this class. */
+  public static Builder newBuilder() {
+    return Builder.createDefault();
+  }
+
+  /** Returns a new builder for this class. */
+  public static Builder newBuilder(ClientContext clientContext) {
+    return new Builder(clientContext);
+  }
+
+  /** Returns a builder containing all the values of this settings class. */
+  public Builder toBuilder() {
+    return new Builder(this);
+  }
+
+  protected EchoWithVersionStubSettings(Builder settingsBuilder) throws IOException {
+    super(settingsBuilder);
+
+    echoWithVersionMethodSettings = settingsBuilder.echoWithVersionMethodSettings().build();
+  }
+
+  /** Builder for EchoWithVersionStubSettings. */
+  public static class Builder extends StubSettings.Builder<EchoWithVersionStubSettings, Builder> {
+    private final ImmutableList<UnaryCallSettings.Builder<?, ?>> unaryMethodSettingsBuilders;
+    private final UnaryCallSettings.Builder<EchoRequest, EchoResponse>
+        echoWithVersionMethodSettings;
+    private static final ImmutableMap<String, ImmutableSet<StatusCode.Code>>
+        RETRYABLE_CODE_DEFINITIONS;
+
+    static {
+      ImmutableMap.Builder<String, ImmutableSet<StatusCode.Code>> definitions =
+          ImmutableMap.builder();
+      definitions.put("no_retry_codes", ImmutableSet.copyOf(Lists.<StatusCode.Code>newArrayList()));
+      RETRYABLE_CODE_DEFINITIONS = definitions.build();
+    }
+
+    private static final ImmutableMap<String, RetrySettings> RETRY_PARAM_DEFINITIONS;
+
+    static {
+      ImmutableMap.Builder<String, RetrySettings> definitions = ImmutableMap.builder();
+      RetrySettings settings = null;
+      settings = RetrySettings.newBuilder().setRpcTimeoutMultiplier(1.0).build();
+      definitions.put("no_retry_params", settings);
+      RETRY_PARAM_DEFINITIONS = definitions.build();
+    }
+
+    protected Builder() {
+      this(((ClientContext) null));
+    }
+
+    protected Builder(ClientContext clientContext) {
+      super(clientContext);
+
+      echoWithVersionMethodSettings = UnaryCallSettings.newUnaryCallSettingsBuilder();
+
+      unaryMethodSettingsBuilders =
+          ImmutableList.<UnaryCallSettings.Builder<?, ?>>of(echoWithVersionMethodSettings);
+      initDefaults(this);
+    }
+
+    protected Builder(EchoWithVersionStubSettings settings) {
+      super(settings);
+
+      echoWithVersionMethodSettings = settings.echoWithVersionMethodSettings.toBuilder();
+
+      unaryMethodSettingsBuilders =
+          ImmutableList.<UnaryCallSettings.Builder<?, ?>>of(echoWithVersionMethodSettings);
+    }
+
+    private static Builder createDefault() {
+      Builder builder = new Builder(((ClientContext) null));
+
+      builder.setTransportChannelProvider(defaultTransportChannelProvider());
+      builder.setCredentialsProvider(defaultCredentialsProviderBuilder().build());
+      builder.setInternalHeaderProvider(defaultApiClientHeaderProviderBuilder().build());
+      builder.setMtlsEndpoint(getDefaultMtlsEndpoint());
+      builder.setSwitchToMtlsEndpointAllowed(true);
+
+      return initDefaults(builder);
+    }
+
+    private static Builder initDefaults(Builder builder) {
+      builder
+          .echoWithVersionMethodSettings()
+          .setRetryableCodes(RETRYABLE_CODE_DEFINITIONS.get("no_retry_codes"))
+          .setRetrySettings(RETRY_PARAM_DEFINITIONS.get("no_retry_params"));
+
+      return builder;
+    }
+
+    /**
+     * Applies the given settings updater function to all of the unary API methods in this service.
+     *
+     * <p>Note: This method does not support applying settings to streaming methods.
+     */
+    public Builder applyToAllUnaryMethods(
+        ApiFunction<UnaryCallSettings.Builder<?, ?>, Void> settingsUpdater) {
+      super.applyToAllUnaryMethods(unaryMethodSettingsBuilders, settingsUpdater);
+      return this;
+    }
+
+    public ImmutableList<UnaryCallSettings.Builder<?, ?>> unaryMethodSettingsBuilders() {
+      return unaryMethodSettingsBuilders;
+    }
+
+    /** Returns the builder for the settings used for calls to echoWithVersionMethod. */
+    public UnaryCallSettings.Builder<EchoRequest, EchoResponse> echoWithVersionMethodSettings() {
+      return echoWithVersionMethodSettings;
+    }
+
+    @Override
+    public EchoWithVersionStubSettings build() throws IOException {
+      return new EchoWithVersionStubSettings(this);
+    }
+  }
+}

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/samples/servicesettings/stub/SyncEchoWithVersionMethod.golden

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.api.version.test.stub.samples;
+
+// [START goldensample_generated_EchoWithVersionStubSettings_EchoWithVersionMethod_sync]
+import com.google.api.version.test.stub.EchoWithVersionStubSettings;
+import java.time.Duration;
+
+public class SyncEchoWithVersionMethod {
+
+  public static void main(String[] args) throws Exception {
+    syncEchoWithVersionMethod();
+  }
+
+  public static void syncEchoWithVersionMethod() throws Exception {
+    // This snippet has been automatically generated and should be regarded as a code template only.
+    // It will require modifications to work:
+    // - It may require correct/in-range values for request initialization.
+    // - It may require specifying regional endpoints when creating the service client as shown in
+    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
+    EchoWithVersionStubSettings.Builder echoWithVersionSettingsBuilder =
+        EchoWithVersionStubSettings.newBuilder();
+    echoWithVersionSettingsBuilder
+        .echoWithVersionMethodSettings()
+        .setRetrySettings(
+            echoWithVersionSettingsBuilder
+                .echoWithVersionMethodSettings()
+                .getRetrySettings()
+                .toBuilder()
+                .setTotalTimeout(Duration.ofSeconds(30))
+                .build());
+    EchoWithVersionStubSettings echoWithVersionSettings = echoWithVersionSettingsBuilder.build();
+  }
+}
+// [END goldensample_generated_EchoWithVersionStubSettings_EchoWithVersionMethod_sync]

gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/ServiceStubSettingsClassComposerTest.java

@@ -23,37 +23,38 @@
 import com.google.api.generator.test.protoloader.GrpcRestTestProtoLoader;
 import java.nio.file.Path;
 import java.nio.file.Paths;
+import java.util.Arrays;
+import java.util.Collection;
 import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.Parameterized;
 
+@RunWith(Parameterized.class)
 public class ServiceStubSettingsClassComposerTest {
+  @Parameterized.Parameters
+  public static Collection<Object[]> data() {
+    return Arrays.asList(
+        new Object[][] {
+          {"EchoStubSettings.golden", GrpcRestTestProtoLoader.instance().parseShowcaseEcho()},
+          {"WickedStubSettings.golden", GrpcRestTestProtoLoader.instance().parseShowcaseWicked()}
+        });
+  }
+
+  @Parameterized.Parameter public String goldenFileName;
+
+  @Parameterized.Parameter(1)
+  public GapicContext context;
+
   @Test
   public void generateServiceClasses() {
-    GapicContext context = GrpcRestTestProtoLoader.instance().parseShowcaseEcho();
     Service echoProtoService = context.services().get(0);
     GapicClass clazz =
         ServiceStubSettingsClassComposer.instance().generate(context, echoProtoService);
 
     JavaWriterVisitor visitor = new JavaWriterVisitor();
     clazz.classDefinition().accept(visitor);
-    GoldenFileWriter.saveCodegenToFile(this.getClass(), "EchoStubSettings.golden", visitor.write());
-    Path goldenFilePath =
-        Paths.get(GoldenFileWriter.getGoldenDir(this.getClass()), "EchoStubSettings.golden");
-    Assert.assertCodeEquals(goldenFilePath, visitor.write());
-  }
-
-  @Test
-  public void generateServiceClassesWicked() {
-    GapicContext context = GrpcRestTestProtoLoader.instance().parseShowcaseWicked();
-    Service wickedProtoService = context.services().get(0);
-    GapicClass clazz =
-        ServiceStubSettingsClassComposer.instance().generate(context, wickedProtoService);
-
-    JavaWriterVisitor visitor = new JavaWriterVisitor();
-    clazz.classDefinition().accept(visitor);
-    GoldenFileWriter.saveCodegenToFile(
-        this.getClass(), "WickedStubSettings.golden", visitor.write());
-    Path goldenFilePath =
-        Paths.get(GoldenFileWriter.getGoldenDir(this.getClass()), "WickedStubSettings.golden");
+    GoldenFileWriter.saveCodegenToFile(this.getClass(), goldenFileName, visitor.write());
+    Path goldenFilePath = Paths.get(GoldenFileWriter.getGoldenDir(this.getClass()), goldenFileName);
     Assert.assertCodeEquals(goldenFilePath, visitor.write());
   }
 }