[Runtime] deprecate the "builder" methods on ApolloCall and add them on the Builder instead

apollo-runtime/api.txt

@@ -6,6 +6,12 @@ package com.apollographql.apollo {
     method public abstract com.apollographql.apollo.ApolloCall<T> clone();
     method public abstract void enqueue(com.apollographql.apollo.ApolloCall.Callback<T>);
     method public abstract Operation operation();
+    method public abstract com.apollographql.apollo.ApolloCall.Builder<T> toBuilder();
+  }
+
+  public static abstract interface ApolloCall.Builder<T> {
+    method public abstract com.apollographql.apollo.ApolloCall<T> build();
+    method public abstract com.apollographql.apollo.ApolloCall.Builder<T> cacheHeaders(CacheHeaders);
   }
 
   public static abstract class ApolloCall.Callback<T> {
@@ -96,6 +102,14 @@ package com.apollographql.apollo {
     method public abstract com.apollographql.apollo.ApolloMutationCall<T> requestHeaders(com.apollographql.apollo.request.RequestHeaders);
   }
 
+  public static abstract interface ApolloMutationCall.Builder<T> implements com.apollographql.apollo.ApolloCall.Builder {
+    method public abstract com.apollographql.apollo.ApolloMutationCall<T> build();
+    method public abstract com.apollographql.apollo.ApolloMutationCall.Builder<T> cacheHeaders(CacheHeaders);
+    method public abstract com.apollographql.apollo.ApolloMutationCall.Builder<T> refetchQueries(List<Query>);
+    method public abstract com.apollographql.apollo.ApolloMutationCall.Builder<T> refetchQueryNames(List<OperationName>);
+    method public abstract com.apollographql.apollo.ApolloMutationCall.Builder<T> requestHeaders(com.apollographql.apollo.request.RequestHeaders);
+  }
+
   public static abstract interface ApolloMutationCall.Factory {
     method public abstract <D extends Mutation.Data, T, V extends Mutation.Variables> com.apollographql.apollo.ApolloMutationCall<T> mutate(Mutation<D, T, V>);
     method public abstract <D extends Mutation.Data, T, V extends Mutation.Variables> com.apollographql.apollo.ApolloMutationCall<T> mutate(Mutation<D, T, V>, D);
@@ -127,9 +141,18 @@ package com.apollographql.apollo {
     method public abstract com.apollographql.apollo.ApolloQueryCall<T> httpCachePolicy(HttpCachePolicy.Policy);
     method public abstract com.apollographql.apollo.ApolloQueryCall<T> requestHeaders(com.apollographql.apollo.request.RequestHeaders);
     method public abstract com.apollographql.apollo.ApolloQueryCall<T> responseFetcher(com.apollographql.apollo.fetcher.ResponseFetcher);
+    method public abstract com.apollographql.apollo.ApolloQueryCall.Builder<T> toBuilder();
     method public abstract com.apollographql.apollo.ApolloQueryWatcher<T> watcher();
   }
 
+  public static abstract interface ApolloQueryCall.Builder<T> implements com.apollographql.apollo.ApolloCall.Builder {
+    method public abstract com.apollographql.apollo.ApolloQueryCall<T> build();
+    method public abstract com.apollographql.apollo.ApolloQueryCall.Builder<T> cacheHeaders(CacheHeaders);
+    method public abstract com.apollographql.apollo.ApolloQueryCall.Builder<T> httpCachePolicy(HttpCachePolicy.Policy);
+    method public abstract com.apollographql.apollo.ApolloQueryCall.Builder<T> requestHeaders(com.apollographql.apollo.request.RequestHeaders);
+    method public abstract com.apollographql.apollo.ApolloQueryCall.Builder<T> responseFetcher(com.apollographql.apollo.fetcher.ResponseFetcher);
+  }
+
   public static abstract interface ApolloQueryCall.Factory {
     method public abstract <D extends Query.Data, T, V extends Query.Variables> com.apollographql.apollo.ApolloQueryCall<T> query(Query<D, T, V>);
   }

apollo-runtime/src/main/java/com/apollographql/apollo/ApolloCall.java

@@ -40,14 +40,14 @@ public interface ApolloCall<T> extends Cancelable {
    *                     defined in {@link ApolloCacheHeaders}.
    * @return The ApolloCall object with the provided {@link CacheHeaders}.
    */
-  @NotNull ApolloCall<T> cacheHeaders(@NotNull CacheHeaders cacheHeaders);
+  @Deprecated @NotNull ApolloCall<T> cacheHeaders(@NotNull CacheHeaders cacheHeaders);
 
   /**
    * Creates a new, identical call to this one which can be enqueued or executed even if this call has already been.
    *
    * @return The cloned ApolloCall object.
    */
-  @NotNull ApolloCall<T> clone();
+  @Deprecated @NotNull ApolloCall<T> clone();
 
   /**
    * Returns GraphQL operation this call executes
@@ -63,6 +63,23 @@ public interface ApolloCall<T> extends Cancelable {
    */
   @Override void cancel();
 
+  @NotNull Builder<T> toBuilder();
+
+  interface Builder<T> {
+    @NotNull ApolloCall<T> build();
+
+    /**
+     * Sets the {@link CacheHeaders} to use for this call. {@link com.apollographql.apollo.interceptor.FetchOptions} will
+     * be configured with this headers, and will be accessible from the {@link ResponseFetcher} used for this call.
+     *
+     * @param cacheHeaders the {@link CacheHeaders} that will be passed with records generated from this request to {@link
+     *                     com.apollographql.apollo.cache.normalized.NormalizedCache}. Standardized cache headers are
+     *                     defined in {@link ApolloCacheHeaders}.
+     * @return The builder
+     */
+    @NotNull Builder<T> cacheHeaders(@NotNull CacheHeaders cacheHeaders);
+  }
+
   /**
    * Communicates responses from a server or offline requests.
    */

apollo-runtime/src/main/java/com/apollographql/apollo/ApolloMutationCall.java

@@ -5,14 +5,17 @@
 import com.apollographql.apollo.api.Query;
 import com.apollographql.apollo.cache.CacheHeaders;
 import com.apollographql.apollo.request.RequestHeaders;
-
 import org.jetbrains.annotations.NotNull;
 
+import java.util.List;
+
 /**
  * A call prepared to execute GraphQL mutation operation.
  */
 public interface ApolloMutationCall<T> extends ApolloCall<T> {
 
+  @NotNull @Override ApolloMutationCall<T> cacheHeaders(@NotNull CacheHeaders cacheHeaders);
+
   /**
    * <p>Sets a list of {@link ApolloQueryWatcher} query names to be re-fetched once this mutation completed.</p>
    *
@@ -29,8 +32,6 @@ public interface ApolloMutationCall<T> extends ApolloCall<T> {
    */
   @NotNull ApolloMutationCall<T> refetchQueries(@NotNull Query... queries);
 
-  @NotNull @Override ApolloMutationCall<T> cacheHeaders(@NotNull CacheHeaders cacheHeaders);
-
   /**
    * Sets the {@link RequestHeaders} to use for this call. These headers will be added to the HTTP request when
    * it is issued. These headers will be applied after any headers applied by application-level interceptors
@@ -43,6 +44,38 @@ public interface ApolloMutationCall<T> extends ApolloCall<T> {
 
   @NotNull @Override ApolloMutationCall<T> clone();
 
+  interface Builder<T> extends ApolloCall.Builder<T> {
+    @NotNull @Override ApolloMutationCall<T> build();
+
+    @NotNull @Override Builder<T> cacheHeaders(@NotNull CacheHeaders cacheHeaders);
+
+    /**
+     * <p>Sets a list of {@link ApolloQueryWatcher} query names to be re-fetched once this mutation completed.</p>
+     *
+     * @param operationNames array of {@link OperationName} query names to be re-fetched
+     * @return The Builder
+     */
+    @NotNull Builder<T> refetchQueryNames(@NotNull List<OperationName> operationNames);
+
+    /**
+     * <p>Sets a list of {@link Query} to be re-fetched once this mutation completed.</p>
+     *
+     * @param queries array of {@link Query} to be re-fetched
+     * @return The Builder
+     */
+    @NotNull Builder<T> refetchQueries(@NotNull List<Query> queries);
+
+    /**
+     * Sets the {@link RequestHeaders} to use for this call. These headers will be added to the HTTP request when
+     * it is issued. These headers will be applied after any headers applied by application-level interceptors
+     * and will override those if necessary.
+     *
+     * @param requestHeaders The {@link RequestHeaders} to use for this request.
+     * @return The Builder
+     */
+    @NotNull Builder<T> requestHeaders(@NotNull RequestHeaders requestHeaders);
+
+  }
   /**
    * Factory for creating {@link ApolloMutationCall} calls.
    */

apollo-runtime/src/main/java/com/apollographql/apollo/ApolloQueryCall.java

@@ -2,11 +2,10 @@
 
 import com.apollographql.apollo.api.OperationName;
 import com.apollographql.apollo.api.Query;
-import com.apollographql.apollo.cache.CacheHeaders;
 import com.apollographql.apollo.api.cache.http.HttpCachePolicy;
+import com.apollographql.apollo.cache.CacheHeaders;
 import com.apollographql.apollo.fetcher.ResponseFetcher;
 import com.apollographql.apollo.request.RequestHeaders;
-
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -46,7 +45,7 @@ public interface ApolloQueryCall<T> extends ApolloCall<T> {
    * @param fetcher the {@link ResponseFetcher} to use.
    * @return The ApolloCall object with the provided CacheControl strategy
    */
-  @NotNull ApolloQueryCall<T> responseFetcher(@NotNull ResponseFetcher fetcher);
+  @Deprecated @NotNull ApolloQueryCall<T> responseFetcher(@NotNull ResponseFetcher fetcher);
 
   /**
    * Sets the {@link RequestHeaders} to use for this call. These headers will be added to the HTTP request when
@@ -56,10 +55,53 @@ public interface ApolloQueryCall<T> extends ApolloCall<T> {
    * @param requestHeaders The {@link RequestHeaders} to use for this request.
    * @return The ApolloCall object with the provided {@link RequestHeaders}.
    */
-  @NotNull ApolloQueryCall<T> requestHeaders(@NotNull RequestHeaders requestHeaders);
+  @Deprecated @NotNull ApolloQueryCall<T> requestHeaders(@NotNull RequestHeaders requestHeaders);
 
   @NotNull @Override ApolloQueryCall<T> clone();
 
+  @NotNull @Override Builder<T> toBuilder();
+
+  interface Builder<T> extends ApolloCall.Builder<T> {
+    @NotNull @Override ApolloQueryCall<T> build();
+
+    /**
+     * Sets the {@link CacheHeaders} to use for this call. {@link com.apollographql.apollo.interceptor.FetchOptions} will
+     * be configured with this headers, and will be accessible from the {@link ResponseFetcher} used for this call.
+     *
+     * @param cacheHeaders the {@link CacheHeaders} that will be passed with records generated from this request to {@link
+     *                     com.apollographql.apollo.cache.normalized.NormalizedCache}. Standardized cache headers are
+     *                     defined in {@link com.apollographql.apollo.cache.ApolloCacheHeaders}.
+     * @return The ApolloCall object with the provided {@link CacheHeaders}.
+     */
+    @NotNull @Override Builder<T> cacheHeaders(@NotNull CacheHeaders cacheHeaders);
+
+    /**
+     * Sets the http cache policy for response/request cache.
+     *
+     * @param httpCachePolicy {@link HttpCachePolicy.Policy} to set
+     * @return {@link ApolloQueryCall} with the provided {@link HttpCachePolicy.Policy}
+     */
+    @NotNull Builder<T> httpCachePolicy(@NotNull HttpCachePolicy.Policy httpCachePolicy);
+
+    /**
+     * Sets the {@link ResponseFetcher} strategy for an ApolloCall object.
+     *
+     * @param fetcher the {@link ResponseFetcher} to use.
+     * @return The ApolloCall object with the provided CacheControl strategy
+     */
+    @NotNull Builder<T> responseFetcher(@NotNull ResponseFetcher fetcher);
+
+    /**
+     * Sets the {@link RequestHeaders} to use for this call. These headers will be added to the HTTP request when
+     * it is issued. These headers will be applied after any headers applied by application-level interceptors
+     * and will override those if necessary.
+     *
+     * @param requestHeaders The {@link RequestHeaders} to use for this request.
+     * @return The Builder
+     */
+    @NotNull Builder<T> requestHeaders(@NotNull RequestHeaders requestHeaders);
+  }
+
   /**
    * Factory for creating {@link ApolloQueryCall} calls.
    */

apollo-runtime/src/main/java/com/apollographql/apollo/internal/RealApolloCall.java

@@ -36,7 +36,6 @@
 
 import java.util.ArrayList;
 import java.util.Arrays;
-import java.util.Collections;
 import java.util.List;
 import java.util.concurrent.Executor;
 import java.util.concurrent.atomic.AtomicReference;
@@ -300,7 +299,7 @@ private ApolloInterceptor.CallBack interceptorCallbackProxy() {
     };
   }
 
-  public Builder<T> toBuilder() {
+  @NotNull public Builder<T> toBuilder() {
     return RealApolloCall.<T>builder()
         .operation(operation)
         .serverUrl(serverUrl)
@@ -420,7 +419,7 @@ private ApolloInterceptorChain prepareInterceptorChain(Operation operation) {
     return new RealApolloInterceptorChain(interceptors);
   }
 
-  public static final class Builder<T> {
+  public static final class Builder<T> implements ApolloQueryCall.Builder<T>, ApolloMutationCall.Builder<T> {
     Operation operation;
     HttpUrl serverUrl;
     Call.Factory httpCallFactory;
@@ -466,11 +465,6 @@ public Builder<T> httpCache(HttpCache httpCache) {
       return this;
     }
 
-    public Builder<T> httpCachePolicy(HttpCachePolicy.Policy httpCachePolicy) {
-      this.httpCachePolicy = httpCachePolicy;
-      return this;
-    }
-
     public Builder<T> responseFieldMapperFactory(ResponseFieldMapperFactory responseFieldMapperFactory) {
       this.responseFieldMapperFactory = responseFieldMapperFactory;
       return this;
@@ -486,21 +480,36 @@ public Builder<T> apolloStore(ApolloStore apolloStore) {
       return this;
     }
 
-    public Builder<T> responseFetcher(ResponseFetcher responseFetcher) {
-      this.responseFetcher = responseFetcher;
+    @NotNull @Override public Builder<T> cacheHeaders(@NotNull CacheHeaders cacheHeaders) {
+      this.cacheHeaders = cacheHeaders;
       return this;
     }
 
-    public Builder<T> cacheHeaders(CacheHeaders cacheHeaders) {
-      this.cacheHeaders = cacheHeaders;
+    @NotNull @Override public Builder<T> httpCachePolicy(@NotNull HttpCachePolicy.Policy httpCachePolicy) {
+      this.httpCachePolicy = httpCachePolicy;
+      return this;
+    }
+
+    @NotNull @Override public Builder<T> responseFetcher(@NotNull ResponseFetcher responseFetcher) {
+      this.responseFetcher = responseFetcher;
       return this;
     }
 
-    public Builder<T> requestHeaders(RequestHeaders requestHeaders) {
+    @NotNull @Override public Builder<T> requestHeaders(@NotNull RequestHeaders requestHeaders) {
       this.requestHeaders = requestHeaders;
       return this;
     }
 
+    @NotNull @Override public Builder<T> refetchQueryNames(@NotNull List<OperationName> refetchQueryNames) {
+      this.refetchQueryNames = new ArrayList<>(refetchQueryNames);
+      return this;
+    }
+
+    @NotNull @Override public Builder<T> refetchQueries(@NotNull List<Query> refetchQueries) {
+      this.refetchQueries = new ArrayList<>(refetchQueries);
+      return this;
+    }
+
     public Builder<T> dispatcher(Executor dispatcher) {
       this.dispatcher = dispatcher;
       return this;
@@ -530,16 +539,6 @@ public Builder<T> autoPersistedOperationsInterceptorFactory(ApolloInterceptorFac
       this.autoPersistedOperationsInterceptorFactory = interceptorFactory;
       return this;
     }
-    public Builder<T> refetchQueryNames(List<OperationName> refetchQueryNames) {
-      this.refetchQueryNames = refetchQueryNames != null ? new ArrayList<>(refetchQueryNames)
-          : Collections.<OperationName>emptyList();
-      return this;
-    }
-
-    public Builder<T> refetchQueries(List<Query> refetchQueries) {
-      this.refetchQueries = refetchQueries != null ? new ArrayList<>(refetchQueries) : Collections.<Query>emptyList();
-      return this;
-    }
 
     public Builder<T> enableAutoPersistedQueries(boolean enableAutoPersistedQueries) {
       this.enableAutoPersistedQueries = enableAutoPersistedQueries;
@@ -569,7 +568,7 @@ public Builder<T> writeToNormalizedCacheAsynchronously(boolean writeToNormalized
     Builder() {
     }
 
-    public RealApolloCall<T> build() {
+    @NotNull public RealApolloCall<T> build() {
       return new RealApolloCall<>(this);
     }
   }