1 /*
2  * Copyright 2016 Google LLC
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
8  *     * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *     * Redistributions in binary form must reproduce the above
11  * copyright notice, this list of conditions and the following disclaimer
12  * in the documentation and/or other materials provided with the
13  * distribution.
14  *     * Neither the name of Google LLC nor the names of its
15  * contributors may be used to endorse or promote products derived from
16  * this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 package com.google.api.gax.rpc;
31 
32 import com.google.api.core.BetaApi;
33 import com.google.api.core.InternalExtensionOnly;
34 import com.google.auth.Credentials;
35 import java.io.IOException;
36 import java.util.Map;
37 import java.util.concurrent.Executor;
38 import java.util.concurrent.ScheduledExecutorService;
39 
40 /**
41  * Provides an interface to either build a TransportChannel or provide a fixed TransportChannel that
42  * will be used to make calls to a service.
43  *
44  * <p>Implementations of {@link TransportChannelProvider} may choose to create a new {@link
45  * TransportChannel} for each call to {@link #getTransportChannel}, or may return a fixed {@link
46  * TransportChannel} instance.
47  *
48  * <p>Callers should use the following pattern to get a channel:
49  *
50  * <pre><code>
51  * TransportChannelProvider transportChannelProvider = ...;
52  * if (transportChannelProvider.needsHeaders()) {
53  *   transportChannelProvider = transportChannelProvider.withHeaders(headers);
54  * }
55  * // optional: set executor for TransportChannel
56  * transportChannelProvider.withExecutor(executor);
57  * TransportChannel transportChannel = transportChannelProvider.getTransportChannel();
58  * </code></pre>
59  */
60 @InternalExtensionOnly
61 public interface TransportChannelProvider {
62   /** Indicates whether the TransportChannel should be closed by the containing client class. */
shouldAutoClose()63   boolean shouldAutoClose();
64 
65   /**
66    * True if the TransportProvider needs an executor.
67    *
68    * @deprecated Channel providers will have default executors if they need one.
69    */
70   @Deprecated
needsExecutor()71   boolean needsExecutor();
72 
73   /** Sets the executor to use when constructing a new {@link TransportChannel}. */
withExecutor(Executor executor)74   TransportChannelProvider withExecutor(Executor executor);
75 
76   /** @deprecated Please use {@link #withExecutor(Executor)}. */
77   @Deprecated
withExecutor(ScheduledExecutorService executor)78   TransportChannelProvider withExecutor(ScheduledExecutorService executor);
79 
80   /** True if the TransportProvider has no headers provided. */
needsHeaders()81   boolean needsHeaders();
82 
83   /**
84    * Sets the headers to use when constructing a new {@link TransportChannel}.
85    *
86    * <p>This method should only be called if {@link #needsHeaders()} returns true.
87    */
withHeaders(Map<String, String> headers)88   TransportChannelProvider withHeaders(Map<String, String> headers);
89 
90   /** True if the TransportProvider has no endpoint set. */
needsEndpoint()91   boolean needsEndpoint();
92 
93   /**
94    * Sets the endpoint to use when constructing a new {@link TransportChannel}.
95    *
96    * <p>This method should only be called if {@link #needsEndpoint()} returns true.
97    */
withEndpoint(String endpoint)98   TransportChannelProvider withEndpoint(String endpoint);
99 
100   /**
101    * Reports whether this provider allows pool size customization.
102    *
103    * @deprecated Pool settings should be configured on the builder of the specific implementation.
104    */
105   @Deprecated
acceptsPoolSize()106   boolean acceptsPoolSize();
107 
108   /**
109    * Number of underlying transport channels to open. Calls will be load balanced across them.
110    *
111    * @deprecated Pool settings should be configured on the builder of the specific implementation.
112    */
113   @Deprecated
withPoolSize(int size)114   TransportChannelProvider withPoolSize(int size);
115 
116   /** True if credentials are needed before channel creation. */
117   @BetaApi("The surface to customize credentials is not stable yet and may change in the future.")
needsCredentials()118   boolean needsCredentials();
119 
120   /** Sets the credentials that will be applied before channel creation. */
121   @BetaApi("The surface to customize credentials is not stable yet and may change in the future.")
withCredentials(Credentials credentials)122   TransportChannelProvider withCredentials(Credentials credentials);
123 
124   /**
125    * Provides a Transport, which could either be a new instance for every call, or the same
126    * instance, depending on the implementation.
127    *
128    * <p>If {@link #needsExecutor()} is true, then {@link #withExecutor(Executor)} needs to be called
129    * first to provide an executor.
130    *
131    * <p>If {@link #needsHeaders()} is true, then {@link #withHeaders(Map)} needs to be called first
132    * to provide headers.
133    *
134    * <p>if {@link #needsEndpoint()} is true, then {@link #withEndpoint(String)} needs to be called
135    * first to provide an endpoint.
136    */
getTransportChannel()137   TransportChannel getTransportChannel() throws IOException;
138 
139   /**
140    * The name of the transport.
141    *
142    * <p>This string can be used for identifying transports for switching logic.
143    */
getTransportName()144   String getTransportName();
145 }
146