From 5206cd4f25477395a88e1c1389c9228e2f9f289b Mon Sep 17 00:00:00 2001
From: Jeff Ching <chingor@google.com>
Date: Mon, 1 Jul 2019 12:49:57 -0700
Subject: [PATCH] Deprecate BatchRequest constructor (#1333)

* Deprecate the BatchRequest public constructor

* Update Javadoc sample for batch request

* Log a warning if a user is using the global batch endpoint

* Fix equality check for Strings

* Swap equals comparison to avoid possible NPE

* Add URL to visit in the warning message
---
 .../client/googleapis/batch/BatchRequest.java | 29 +++++++++++++++++--
 .../services/AbstractGoogleClient.java        |  1 +
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/google-api-client/src/main/java/com/google/api/client/googleapis/batch/BatchRequest.java b/google-api-client/src/main/java/com/google/api/client/googleapis/batch/BatchRequest.java
index 3958b64e2..8a4f0f19f 100644
--- a/google-api-client/src/main/java/com/google/api/client/googleapis/batch/BatchRequest.java
+++ b/google-api-client/src/main/java/com/google/api/client/googleapis/batch/BatchRequest.java
@@ -33,6 +33,8 @@
 import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.logging.Level;
+import java.util.logging.Logger;
 
 /**
  * An instance of this class represents a single batch of requests.
@@ -42,7 +44,8 @@
  * </p>
  *
  * <pre>
-   BatchRequest batch = new BatchRequest(transport, httpRequestInitializer);
+   // client is a AbstractGoogleClient (e.g. com.google.api.services.books.Books)
+   BatchRequest batch = client.batch(httpRequestInitializer);
    batch.queue(volumesList, Volumes.class, GoogleJsonErrorContainer.class,
        new BatchCallback&lt;Volumes, GoogleJsonErrorContainer&gt;() {
 
@@ -96,8 +99,20 @@ public void onFailure(GoogleJsonErrorContainer e, HttpHeaders responseHeaders) {
 @SuppressWarnings("deprecation")
 public final class BatchRequest {
 
+  /**
+   * The deprecated global batch endpoint. Users should actually use the per-service batch endpoint
+   * declared by the service configuration.
+   */
+  private static final String GLOBAL_BATCH_ENDPOINT = "https://www.googleapis.com/batch";
+  private static final String GLOBAL_BATCH_ENDPOINT_WARNING = "You are using the global batch "
+      + "endpoint which will soon be shut down. Please instantiate your BatchRequest via your "
+      + "service client's `batch(HttpRequestInitializer)` method. For an example, please see "
+      + "https://github.com/googleapis/google-api-java-client#batching.";
+
+  private static final Logger LOGGER = Logger.getLogger(BatchRequest.class.getName());
+
   /** The URL where batch requests are sent. */
-  private GenericUrl batchUrl = new GenericUrl("https://www.googleapis.com/batch");
+  private GenericUrl batchUrl = new GenericUrl(GLOBAL_BATCH_ENDPOINT);
 
   /** The request factory for connections to the server. */
   private final HttpRequestFactory requestFactory;
@@ -130,7 +145,10 @@ static class RequestInfo<T, E> {
    * @param transport The transport to use for requests
    * @param httpRequestInitializer The initializer to use when creating an {@link HttpRequest} or
    *        {@code null} for none
+   * @deprecated Please use AbstractGoogleClient#batch(HttpRequestInitializer) to instantiate your
+   *        batch request.
    */
+  @Deprecated
   public BatchRequest(HttpTransport transport, HttpRequestInitializer httpRequestInitializer) {
     this.requestFactory = httpRequestInitializer == null
         ? transport.createRequestFactory() : transport.createRequestFactory(httpRequestInitializer);
@@ -215,6 +233,13 @@ public int size() {
   public void execute() throws IOException {
     boolean retryAllowed;
     Preconditions.checkState(!requestInfos.isEmpty());
+
+    // Log a warning if the user is using the global batch endpoint. In the future, we can turn this
+    // into a preconditions check.
+    if (GLOBAL_BATCH_ENDPOINT.equals(this.batchUrl.toString())) {
+      LOGGER.log(Level.WARNING, GLOBAL_BATCH_ENDPOINT_WARNING);
+    }
+
     HttpRequest batchRequest = requestFactory.buildPostRequest(this.batchUrl, null);
     // NOTE: batch does not support gzip encoding
     HttpExecuteInterceptor originalInterceptor = batchRequest.getInterceptor();
diff --git a/google-api-client/src/main/java/com/google/api/client/googleapis/services/AbstractGoogleClient.java b/google-api-client/src/main/java/com/google/api/client/googleapis/services/AbstractGoogleClient.java
index 439952cad..667668e10 100644
--- a/google-api-client/src/main/java/com/google/api/client/googleapis/services/AbstractGoogleClient.java
+++ b/google-api-client/src/main/java/com/google/api/client/googleapis/services/AbstractGoogleClient.java
@@ -232,6 +232,7 @@ public final BatchRequest batch() {
    * @return newly created Batch request
    */
   public final BatchRequest batch(HttpRequestInitializer httpRequestInitializer) {
+    @SuppressWarnings("deprecated")
     BatchRequest batch =
         new BatchRequest(getRequestFactory().getTransport(), httpRequestInitializer);
     if (Strings.isNullOrEmpty(batchPath)) {