Extensible client options (#1263)

* Add ability to set requestReason and userAgent when configuring the client.

Introduces the builder pattern for these common configuration options so that it is extensible in the future.

* Fix lint

* Fix lint

* javadoc linting

* Add userProject configuration

* Add test for setting user project, request reason, user agent

Author: chingor13

google-api-client/src/main/java/com/google/api/client/googleapis/services/CommonGoogleClientRequestInitializer.java

@@ -25,7 +25,9 @@
  *
  * <pre>
   public static final GoogleClientRequestInitializer KEY_INITIALIZER =
-      new CommonGoogleClientRequestInitializer(KEY);
+      CommonGoogleClientRequestInitializer.newBuilder()
+          .setKey(KEY)
+          .build();
  * </pre>
  *
  * <p>
@@ -34,7 +36,10 @@
  *
  * <pre>
   public static final GoogleClientRequestInitializer INITIALIZER =
-      new CommonGoogleClientRequestInitializer(KEY, USER_IP);
+      CommonGoogleClientRequestInitializer.newBuilder()
+          .setKey(KEY)
+          .setUserIp(USER_IP)
+          .build();
  * </pre>
  *
  * <p>
@@ -81,30 +86,73 @@ public void initialize(AbstractGoogleClientRequest{@literal <}?{@literal >} requ
  */
 public class CommonGoogleClientRequestInitializer implements GoogleClientRequestInitializer {
 
+  /**
+   * Contains a reason for making the request, which is intended to be recorded in audit logging.
+   * An example reason would be a support-case ticket number.
+   */
+  private static final String REQUEST_REASON_HEADER_NAME = "X-Goog-Request-Reason";
+
+  /**
+   * A caller-specified project for quota and billing purposes. The caller must have
+   * serviceusage.services.use permission on the project.
+   */
+  private static final String USER_PROJECT_HEADER_NAME = "X-Goog-User-Project";
+
   /** API key or {@code null} to leave it unchanged. */
   private final String key;
 
   /** User IP or {@code null} to leave it unchanged. */
   private final String userIp;
 
+  /** User Agent or {@code null} to leave it unchanged. */
+  private final String userAgent;
+
+  /** Reason for request or {@code null} to leave it unchanged. */
+  private final String requestReason;
+
+  /** Project for quota and billing purposes of {@code null} to leave it unchanged. */
+  private final String userProject;
+
+  /**
+   * @deprecated Please use the builder interface
+   */
+  @Deprecated
   public CommonGoogleClientRequestInitializer() {
-    this(null);
+    this(newBuilder());
   }
 
   /**
    * @param key API key or {@code null} to leave it unchanged
+   * @deprecated Please use the builder interface
    */
+  @Deprecated
   public CommonGoogleClientRequestInitializer(String key) {
     this(key, null);
   }
 
   /**
    * @param key API key or {@code null} to leave it unchanged
    * @param userIp user IP or {@code null} to leave it unchanged
+   * @deprecated Please use the builder interface
    */
+  @Deprecated
   public CommonGoogleClientRequestInitializer(String key, String userIp) {
-    this.key = key;
-    this.userIp = userIp;
+    this(newBuilder().setKey(key).setUserIp(userIp));
+  }
+
+  protected CommonGoogleClientRequestInitializer(Builder builder) {
+    this.key = builder.getKey();
+    this.userIp = builder.getUserIp();
+    this.userAgent = builder.getUserAgent();
+    this.requestReason = builder.getRequestReason();
+    this.userProject = builder.getUserProject();
+  }
+
+  /**
+   * Returns new builder.
+   */
+  public static Builder newBuilder() {
+    return new Builder();
   }
 
   /**
@@ -119,6 +167,15 @@ public void initialize(AbstractGoogleClientRequest<?> request) throws IOExceptio
     if (userIp != null) {
       request.put("userIp", userIp);
     }
+    if (userAgent != null) {
+      request.getRequestHeaders().setUserAgent(userAgent);
+    }
+    if (requestReason != null) {
+      request.getRequestHeaders().set(REQUEST_REASON_HEADER_NAME, requestReason);
+    }
+    if (userProject != null) {
+      request.getRequestHeaders().set(USER_PROJECT_HEADER_NAME, userProject);
+    }
   }
 
   /** Returns the API key or {@code null} to leave it unchanged. */
@@ -130,4 +187,147 @@ public final String getKey() {
   public final String getUserIp() {
     return userIp;
   }
+
+  /** Returns the user agent or {@code null} to leave it unchanged. */
+  public final String getUserAgent() {
+    return userAgent;
+  }
+
+  /** Returns the request reason or {@code null} to leave it unchanged. */
+  public final String getRequestReason() {
+    return requestReason;
+  }
+
+  /** Returns the user project of {@code null} */
+  public final String getUserProject() {
+    return userProject;
+  }
+
+  /**
+   * Builder for {@code CommonGoogleClientRequestInitializer}.
+   */
+  public static class Builder {
+    private String key;
+    private String userIp;
+    private String userAgent;
+    private String requestReason;
+    private String userProject;
+
+    /**
+     * Set the API Key for outgoing requests.
+     *
+     * @param key the API key
+     * @return the builder
+     */
+    public Builder setKey(String key) {
+      this.key = key;
+      return self();
+    }
+
+    /**
+     * Returns the API key.
+     *
+     * @return the API key
+     */
+    public String getKey() {
+      return key;
+    }
+
+    /**
+     * Set the IP address of the end user for whom the API call is being made.
+     *
+     * @param userIp the user's IP address
+     * @return the builder
+     */
+    public Builder setUserIp(String userIp) {
+      this.userIp = userIp;
+      return self();
+    }
+
+    /**
+     * Returns the configured userIp.
+     *
+     * @return the userIp
+     */
+    public String getUserIp() {
+      return userIp;
+    }
+
+    /**
+     * Set the user agent.
+     *
+     * @param userAgent the user agent
+     * @return the builder
+     */
+    public Builder setUserAgent(String userAgent) {
+      this.userAgent = userAgent;
+      return self();
+    }
+
+    /**
+     * Returns the configured user agent.
+     *
+     * @return the user agent
+     */
+    public String getUserAgent() {
+      return userAgent;
+    }
+
+    /**
+     * Set the reason for making the request, which is intended to be recorded in audit logging. An
+     * example reason would be a support-case ticket number.
+     *
+     * @param requestReason the reason for making the request
+     * @return the builder
+     */
+    public Builder setRequestReason(String requestReason) {
+      this.requestReason = requestReason;
+      return self();
+    }
+
+    /**
+     * Get the configured request reason.
+     *
+     * @return the request reason
+     */
+    public String getRequestReason() {
+      return requestReason;
+    }
+
+    /**
+     * Set the user project for the request. This is a caller-specified project for quota and
+     * billing purposes. The caller must have serviceusage.services.use permission on the project.
+     *
+     * @param userProject the user project
+     * @return the builder
+     */
+    public Builder setUserProject(String userProject) {
+      this.userProject = userProject;
+      return self();
+    }
+
+    /**
+     * Get the configured user project.
+     *
+     * @return the user project
+     */
+    public String getUserProject() {
+      return userProject;
+    }
+
+    /**
+     * Returns the constructed CommonGoogleClientRequestInitializer instance.
+     *
+     * @return the constructed CommonGoogleClientRequestInitializer instance
+     */
+    public CommonGoogleClientRequestInitializer build() {
+      return new CommonGoogleClientRequestInitializer(this);
+    }
+
+    protected Builder self() {
+      return this;
+    }
+
+    protected Builder() {}
+  }
 }

google-api-client/src/main/java/com/google/api/client/googleapis/services/json/CommonGoogleJsonClientRequestInitializer.java

@@ -28,7 +28,9 @@
  *
  * <pre>
   public static final GoogleClientRequestInitializer KEY_INITIALIZER =
-      new CommonGoogleJsonClientRequestInitializer(KEY);
+      CommonGoogleJsonClientRequestInitializer.newBuilder()
+          .setKey(KEY)
+          .build();
  * </pre>
  *
  * <p>
@@ -37,7 +39,10 @@
  *
  * <pre>
   public static final GoogleClientRequestInitializer INITIALIZER =
-      new CommonGoogleJsonClientRequestInitializer(KEY, USER_IP);
+      CommonGoogleJsonClientRequestInitializer.newBuilder()
+          .setKey(KEY)
+          .setUserIp(USER_IP)
+          .build();
  * </pre>
  *
  * <p>
@@ -83,21 +88,29 @@ public void initializeJsonRequest(
  */
 public class CommonGoogleJsonClientRequestInitializer extends CommonGoogleClientRequestInitializer {
 
+  /**
+   * @deprecated Please use the builder interface
+   */
+  @Deprecated
   public CommonGoogleJsonClientRequestInitializer() {
     super();
   }
 
   /**
    * @param key API key or {@code null} to leave it unchanged
+   * @deprecated Please use the builder interface
    */
+  @Deprecated
   public CommonGoogleJsonClientRequestInitializer(String key) {
     super(key);
   }
 
   /**
    * @param key API key or {@code null} to leave it unchanged
    * @param userIp user IP or {@code null} to leave it unchanged
+   * @deprecated Please use the builder interface
    */
+  @Deprecated
   public CommonGoogleJsonClientRequestInitializer(String key, String userIp) {
     super(key, userIp);
   }
@@ -121,4 +134,14 @@ public final void initialize(AbstractGoogleClientRequest<?> request) throws IOEx
   protected void initializeJsonRequest(AbstractGoogleJsonClientRequest<?> request)
       throws IOException {
   }
+
+  /**
+   * Builder for {@code CommonGoogleJsonClientRequestInitializer}.
+   */
+  public static class Builder extends CommonGoogleClientRequestInitializer.Builder {
+    @Override
+    protected Builder self() {
+      return this;
+    }
+  }
 }

google-api-client/src/test/java/com/google/api/client/googleapis/services/CommonGoogleClientRequestInitializerTest.java

@@ -14,10 +14,12 @@
 
 import com.google.api.client.googleapis.testing.services.MockGoogleClient;
 import com.google.api.client.http.HttpContent;
+import com.google.api.client.http.HttpHeaders;
 import com.google.api.client.testing.http.HttpTesting;
 import com.google.api.client.testing.http.MockHttpTransport;
 import com.google.api.client.util.Key;
 
+import java.io.IOException;
 import junit.framework.TestCase;
 
 /**
@@ -46,4 +48,46 @@ public void testInitialize() throws Exception {
     key.initialize(request);
     assertEquals("foo", request.key);
   }
+
+  public void testInitializeSetsUserAgent() throws IOException {
+    GoogleClientRequestInitializer requestInitializer = CommonGoogleClientRequestInitializer.newBuilder()
+        .setUserAgent("test user agent")
+        .build();
+    MockGoogleClient client = new MockGoogleClient.Builder(new MockHttpTransport(), HttpTesting.SIMPLE_URL, "test/", null, null)
+        .setGoogleClientRequestInitializer(requestInitializer)
+        .setApplicationName("My Application")
+        .build();
+    MyRequest request = new MyRequest(client, "GET", "", null, String.class);
+    requestInitializer.initialize(request);
+    HttpHeaders headers = request.getRequestHeaders();
+    assertEquals("test user agent", headers.getUserAgent());
+  }
+
+  public void testInitializeSetsUserProject() throws IOException {
+    GoogleClientRequestInitializer requestInitializer = CommonGoogleClientRequestInitializer.newBuilder()
+        .setUserProject("my quota project")
+        .build();
+    MockGoogleClient client = new MockGoogleClient.Builder(new MockHttpTransport(), HttpTesting.SIMPLE_URL, "test/", null, null)
+        .setGoogleClientRequestInitializer(requestInitializer)
+        .setApplicationName("My Application")
+        .build();
+    MyRequest request = new MyRequest(client, "GET", "", null, String.class);
+    requestInitializer.initialize(request);
+    HttpHeaders headers = request.getRequestHeaders();
+    assertEquals("my quota project", headers.get("X-Goog-User-Project"));
+  }
+
+  public void testInitializeSetsRequestReason() throws IOException {
+    GoogleClientRequestInitializer requestInitializer = CommonGoogleClientRequestInitializer.newBuilder()
+        .setRequestReason("some request reason")
+        .build();
+    MockGoogleClient client = new MockGoogleClient.Builder(new MockHttpTransport(), HttpTesting.SIMPLE_URL, "test/", null, null)
+        .setGoogleClientRequestInitializer(requestInitializer)
+        .setApplicationName("My Application")
+        .build();
+    MyRequest request = new MyRequest(client, "GET", "", null, String.class);
+    requestInitializer.initialize(request);
+    HttpHeaders headers = request.getRequestHeaders();
+    assertEquals("some request reason", headers.get("X-Goog-Request-Reason"));
+  }
 }