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

Author: chingor13

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();

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)) {