Make ServiceApiSettings provider interfaces public

src/main/java/com/google/api/gax/core/ConnectionSettings.java

@@ -56,18 +56,6 @@
 @AutoValue
 public abstract class ConnectionSettings {
 
-  /**
-   * Provides an interface to hold and acquire the credentials that will be used to call the
-   * service.
-   */
-  public interface CredentialsProvider {
-    /**
-     * Gets the credentials which will be used to call the service. If the credentials have not been
-     * acquired yet, then they will be acquired when this function is called.
-     */
-    Credentials getCredentials() throws IOException;
-  }
-
   /**
    * Gets the credentials which will be used to call the service. If the credentials have not been
    * acquired yet, then they will be acquired when this function is called.

src/main/java/com/google/api/gax/core/CredentialsProvider.java

@@ -0,0 +1,16 @@
+package com.google.api.gax.core;
+
+import com.google.auth.Credentials;
+
+import java.io.IOException;
+
+/**
+ * Provides an interface to hold and acquire the credentials that will be used to call the service.
+ */
+public interface CredentialsProvider {
+  /**
+   * Gets the credentials which will be used to call the service. If the credentials have not been
+   * acquired yet, then they will be acquired when this function is called.
+   */
+  Credentials getCredentials() throws IOException;
+}

src/main/java/com/google/api/gax/grpc/ApiCallSettingsTyped.java

@@ -39,13 +39,11 @@ protected ApiCallSettingsTyped(ImmutableSet<Status.Code> retryableCodes,
   }
 
   protected ApiCallable<RequestT, ResponseT> createBaseCallable(
-      ServiceApiSettings serviceSettings) throws IOException {
+      ManagedChannel channel, ScheduledExecutorService executor) throws IOException {
     ClientCallFactory<RequestT, ResponseT> clientCallFactory =
         new DescriptorClientCallFactory<>(methodDescriptor);
     ApiCallable<RequestT, ResponseT> callable =
         new ApiCallable<>(new DirectCallable<>(clientCallFactory), this);
-    ManagedChannel channel = serviceSettings.getOrBuildChannel();
-    ScheduledExecutorService executor = serviceSettings.getOrBuildExecutor();
     if (getRetryableCodes() != null) {
       callable = callable.retryableOn(ImmutableSet.copyOf(getRetryableCodes()));
     }

src/main/java/com/google/api/gax/grpc/ApiCallable.java

@@ -42,6 +42,7 @@
 import com.google.common.util.concurrent.UncheckedExecutionException;
 
 import io.grpc.Channel;
+import io.grpc.ManagedChannel;
 import io.grpc.Status;
 import io.grpc.StatusRuntimeException;
 
@@ -114,8 +115,8 @@ public final class ApiCallable<RequestT, ResponseT> {
    */
   public static <RequestT, ResponseT> ApiCallable<RequestT, ResponseT> create(
       SimpleCallSettings<RequestT, ResponseT> simpleCallSettings,
-      ServiceApiSettings serviceSettings) throws IOException {
-     return simpleCallSettings.create(serviceSettings);
+      ManagedChannel channel, ScheduledExecutorService executor) throws IOException {
+     return simpleCallSettings.create(channel, executor);
   }
 
   /**
@@ -131,8 +132,8 @@ public static <RequestT, ResponseT> ApiCallable<RequestT, ResponseT> create(
   public static <RequestT, ResponseT, ResourceT>
       ApiCallable<RequestT, PageAccessor<ResourceT>> createPagedVariant(
           PageStreamingCallSettings<RequestT, ResponseT, ResourceT> pageStreamingCallSettings,
-          ServiceApiSettings serviceSettings) throws IOException {
-    return pageStreamingCallSettings.createPagedVariant(serviceSettings);
+          ManagedChannel channel, ScheduledExecutorService executor) throws IOException {
+    return pageStreamingCallSettings.createPagedVariant(channel, executor);
   }
 
   /**
@@ -148,8 +149,8 @@ ApiCallable<RequestT, PageAccessor<ResourceT>> createPagedVariant(
   public static <RequestT, ResponseT, ResourceT>
       ApiCallable<RequestT, ResponseT> create(
           PageStreamingCallSettings<RequestT, ResponseT, ResourceT> pageStreamingCallSettings,
-          ServiceApiSettings serviceSettings) throws IOException {
-    return pageStreamingCallSettings.create(serviceSettings);
+          ManagedChannel channel, ScheduledExecutorService executor) throws IOException {
+    return pageStreamingCallSettings.create(channel, executor);
   }
 
   /**
@@ -164,8 +165,8 @@ ApiCallable<RequestT, ResponseT> create(
    */
   public static <RequestT, ResponseT> ApiCallable<RequestT, ResponseT> create(
       BundlingCallSettings<RequestT, ResponseT> bundlingCallSettings,
-      ServiceApiSettings serviceSettings) throws IOException {
-    return bundlingCallSettings.create(serviceSettings);
+      ManagedChannel channel, ScheduledExecutorService executor) throws IOException {
+    return bundlingCallSettings.create(channel, executor);
   }
 
   /**

src/main/java/com/google/api/gax/grpc/ApiException.java

@@ -38,7 +38,9 @@
 /**
  * Represents an exception thrown during an RPC call.
  *
- * <p>It stores information useful for functionalities in {@link ApiCallable}.
+ * <p>
+ * It stores information useful for functionalities in {@link ApiCallable}. For more information
+ * about the status codes returned by the underlying grpc exception see {@link Status}.
  */
 public class ApiException extends RuntimeException {
   private final Status.Code statusCode;
@@ -58,9 +60,9 @@ public boolean isRetryable() {
   }
 
   /**
-   * Returns the status code of the underlying grpc exception. In cases
-   * where the underlying exception is not of type StatusException or
-   * StatusRuntimeException, the status code will be Status.Code.UNKNOWN
+   * Returns the status code of the underlying grpc exception. In cases where the underlying
+   * exception is not of type StatusException or StatusRuntimeException, the status code will be
+   * Status.Code.UNKNOWN. For more information about status codes see {@link Status}.
    */
   public Status.Code getStatusCode() {
     return statusCode;

src/main/java/com/google/api/gax/grpc/BundlingCallSettings.java

@@ -3,11 +3,13 @@
 import com.google.api.gax.core.RetrySettings;
 import com.google.common.collect.ImmutableSet;
 
+import io.grpc.ManagedChannel;
 import io.grpc.MethodDescriptor;
 import io.grpc.Status;
 
 import java.io.IOException;
 import java.util.Set;
+import java.util.concurrent.ScheduledExecutorService;
 
 /**
  * A settings class to configure an ApiCallable for calls to an API method that supports
@@ -22,9 +24,9 @@ public final class BundlingCallSettings<RequestT, ResponseT>
   /**
    * Package-private, for use by ApiCallable.
    */
-  ApiCallable<RequestT, ResponseT> create(
-      ServiceApiSettings serviceSettings) throws IOException {
-    ApiCallable<RequestT, ResponseT> baseCallable = createBaseCallable(serviceSettings);
+  ApiCallable<RequestT, ResponseT> create(ManagedChannel channel, ScheduledExecutorService executor)
+      throws IOException {
+    ApiCallable<RequestT, ResponseT> baseCallable = createBaseCallable(channel, executor);
     bundlerFactory = new BundlerFactory<>(bundlingDescriptor, bundlingSettings);
     return baseCallable.bundling(bundlingDescriptor, bundlerFactory);
   }

src/main/java/com/google/api/gax/grpc/ChannelProvider.java

@@ -0,0 +1,49 @@
+package com.google.api.gax.grpc;
+
+import com.google.api.gax.core.ConnectionSettings;
+
+import io.grpc.ManagedChannel;
+
+import java.io.IOException;
+import java.util.concurrent.Executor;
+
+import javax.annotation.Nullable;
+import javax.naming.OperationNotSupportedException;
+
+/**
+ * Provides an interface to hold and build the channel that will be used. If the channel does not
+ * already exist, it will be constructed when {@link #getChannel} is called.
+ *
+ * Implementations of {@link ChannelProvider} may choose to create a new {@link ManagedChannel} for
+ * each call to {@link #getChannel}, or may return a fixed {@link ManagedChannel} instance. In cases
+ * where the same {@link ManagedChannel} instance is returned, for example by a
+ * {@link ChannelProvider} created using the
+ * {@link ServiceApiSettings#provideChannelWith(ManagedChannel, boolean)} method, and
+ * shouldAutoClose returns true, the {@link #getChannel} method will throw an
+ * {@link OperationNotSupportedException} if it is called more than once. This is to prevent the
+ * same {@link ManagedChannel} being closed prematurely when it is used by multiple client objects.
+ */
+public interface ChannelProvider {
+  /**
+   * Connection settings used to build the channel. If a channel is provided directly this will be
+   * set to null.
+   */
+  @Nullable
+  ConnectionSettings connectionSettings();
+
+  /**
+   * Indicates whether the channel should be closed by the containing API class.
+   */
+  boolean shouldAutoClose();
+
+  /**
+   * Get the channel to be used to connect to the service. The first time this is called, if the
+   * channel does not already exist, it will be created.
+   *
+   * If the {@link ChannelProvider} is configured to return a fixed {@link ManagedChannel} object
+   * and to return shouldAutoClose as true, then after the first call to {@link #getChannel},
+   * subsequent calls should throw an {@link OperationNotSupportedException}. See interface level
+   * docs for {@link ChannelProvider} for more details.
+   */
+  ManagedChannel getChannel(Executor executor) throws IOException, OperationNotSupportedException;
+}

src/main/java/com/google/api/gax/grpc/ExecutorProvider.java

@@ -0,0 +1,37 @@
+package com.google.api.gax.grpc;
+
+import java.util.concurrent.ScheduledExecutorService;
+
+import javax.naming.OperationNotSupportedException;
+
+/**
+ * Provides an interface to hold and create the Executor to be used. If the executor does not
+ * already exist, it will be constructed when {@link #getExecutor} is called.
+ *
+ * Implementations of ExecutorProvider may choose to create a new {@link ScheduledExecutorService}
+ * for each call to {@link #getExecutor}, or may return a fixed {@link ScheduledExecutorService}
+ * instance. In cases where the same {@link ScheduledExecutorService} instance is returned, for
+ * example by an {@link ExecutorProvider} created using the
+ * {@link ServiceApiSettings#provideExecutorWith(ScheduledExecutorService, boolean)} method, and
+ * shouldAutoClose returns true, the {@link #getExecutor} method will throw an
+ * {@link OperationNotSupportedException} if it is called more than once. This is to prevent the
+ * same {@link ScheduledExecutorService} being closed prematurely when it is used by multiple client
+ * objects.
+ */
+public interface ExecutorProvider {
+  /**
+   * Indicates whether the channel should be closed by the containing API class.
+   */
+  boolean shouldAutoClose();
+
+  /**
+   * Get the executor to be used to connect to the service. The first time this is called, if the
+   * executor does not already exist, it will be created.
+   *
+   * If the {@link ExecutorProvider} is configured to return a fixed
+   * {@link ScheduledExecutorService} object and to return shouldAutoClose as true, then after the
+   * first call to {@link #getExecutor}, subsequent calls should throw an {@link ExecutorProvider}.
+   * See interface level docs for {@link ExecutorProvider} for more details.
+   */
+  ScheduledExecutorService getExecutor() throws OperationNotSupportedException;
+}

src/main/java/com/google/api/gax/grpc/PageStreamingCallSettings.java

@@ -4,11 +4,13 @@
 import com.google.api.gax.core.RetrySettings;
 import com.google.common.collect.ImmutableSet;
 
+import io.grpc.ManagedChannel;
 import io.grpc.MethodDescriptor;
 import io.grpc.Status;
 
 import java.io.IOException;
 import java.util.Set;
+import java.util.concurrent.ScheduledExecutorService;
 
 
 /**
@@ -22,17 +24,17 @@ public final class PageStreamingCallSettings<RequestT, ResponseT, ResourceT>
   /**
    * Package-private, for use by ApiCallable.
    */
-  ApiCallable<RequestT, ResponseT> create(
-      ServiceApiSettings serviceSettings) throws IOException {
-    return createBaseCallable(serviceSettings);
+  ApiCallable<RequestT, ResponseT> create(ManagedChannel channel, ScheduledExecutorService executor)
+      throws IOException {
+    return createBaseCallable(channel, executor);
   }
 
   /**
    * Package-private, for use by ApiCallable.
    */
   ApiCallable<RequestT, PageAccessor<ResourceT>> createPagedVariant(
-      ServiceApiSettings serviceSettings) throws IOException {
-    ApiCallable<RequestT, ResponseT> baseCallable = createBaseCallable(serviceSettings);
+      ManagedChannel channel, ScheduledExecutorService executor) throws IOException {
+    ApiCallable<RequestT, ResponseT> baseCallable = createBaseCallable(channel, executor);
     return baseCallable.pageStreaming(pageDescriptor);
   }