MultiAddressClientBuilder execution strategy control

servicetalk-http-api/src/main/java/io/servicetalk/http/api/DefaultHttpExecutionStrategy.java

@@ -49,7 +49,7 @@ enum DefaultHttpExecutionStrategy implements HttpExecutionStrategy {
     OFFLOAD_SEND_EVENT_STRATEGY(EnumSet.of(OFFLOAD_SEND, OFFLOAD_EVENT)),
     OFFLOAD_RECEIVE_META_AND_SEND_EVENT_STRATEGY(EnumSet.of(OFFLOAD_RECEIVE_META, OFFLOAD_SEND, OFFLOAD_EVENT)),
     OFFLOAD_RECEIVE_DATA_AND_SEND_EVENT_STRATEGY(EnumSet.of(OFFLOAD_RECEIVE_DATA, OFFLOAD_SEND, OFFLOAD_EVENT)),
-    OFFLOADD_ALL_REQRESP_EVENT_STRATEGY(
+    OFFLOAD_ALL_REQRESP_EVENT_STRATEGY(
             EnumSet.of(OFFLOAD_RECEIVE_META, OFFLOAD_RECEIVE_DATA, OFFLOAD_SEND, OFFLOAD_EVENT)),
 
     OFFLOAD_CLOSE_STRATEGY(EnumSet.of(OFFLOAD_CLOSE)),

servicetalk-http-api/src/main/java/io/servicetalk/http/api/HttpApiConversions.java

@@ -39,6 +39,7 @@ private HttpApiConversions() {
      * @return The conversion result.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static ReservedHttpConnection toReservedConnection(ReservedStreamingHttpConnection original,
                                                               HttpExecutionStrategyInfluencer influencer) {
@@ -66,6 +67,7 @@ public static ReservedHttpConnection toReservedConnection(ReservedStreamingHttpC
      * @return The conversion result.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static ReservedBlockingHttpConnection toReservedBlockingConnection(
             ReservedStreamingHttpConnection original, HttpExecutionStrategyInfluencer influencer) {
@@ -94,6 +96,7 @@ public static ReservedBlockingHttpConnection toReservedBlockingConnection(
      * @return The conversion result.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static ReservedBlockingStreamingHttpConnection toReservedBlockingStreamingConnection(
             ReservedStreamingHttpConnection original, HttpExecutionStrategyInfluencer influencer) {
@@ -122,6 +125,7 @@ public static ReservedBlockingStreamingHttpConnection toReservedBlockingStreamin
      * @return The conversion result.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static HttpConnection toConnection(StreamingHttpConnection original,
                                               HttpExecutionStrategyInfluencer influencer) {
@@ -148,6 +152,7 @@ public static HttpConnection toConnection(StreamingHttpConnection original, Http
      * @return The conversion result.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static BlockingHttpConnection toBlockingConnection(StreamingHttpConnection original,
                                                               HttpExecutionStrategyInfluencer influencer) {
@@ -175,6 +180,7 @@ public static BlockingHttpConnection toBlockingConnection(StreamingHttpConnectio
      * @return The conversion result.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static BlockingStreamingHttpConnection toBlockingStreamingConnection(
             StreamingHttpConnection original, HttpExecutionStrategyInfluencer influencer) {
@@ -203,6 +209,7 @@ public static BlockingStreamingHttpConnection toBlockingStreamingConnection(
      * @return The conversion result.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static HttpClient toClient(StreamingHttpClient original, HttpExecutionStrategyInfluencer influencer) {
         return toClient(original, influencer.requiredOffloads());
@@ -228,6 +235,7 @@ public static HttpClient toClient(StreamingHttpClient original, HttpExecutionStr
      * @return The conversion result.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static BlockingHttpClient toBlockingClient(StreamingHttpClient original,
                                                       HttpExecutionStrategyInfluencer influencer) {
@@ -254,6 +262,7 @@ public static BlockingHttpClient toBlockingClient(StreamingHttpClient original,
      * @return The conversion result.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static BlockingStreamingHttpClient toBlockingStreamingClient(StreamingHttpClient original,
                                                                         HttpExecutionStrategyInfluencer influencer) {
@@ -281,6 +290,7 @@ public static BlockingStreamingHttpClient toBlockingStreamingClient(StreamingHtt
      * @return {@link ServiceAdapterHolder} containing the service adapted to the streaming programming model.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static ServiceAdapterHolder toStreamingHttpService(HttpService service,
                                                               HttpExecutionStrategyInfluencer influencer) {
@@ -307,6 +317,7 @@ public static ServiceAdapterHolder toStreamingHttpService(HttpService service, H
      * @return {@link ServiceAdapterHolder} containing the service adapted to the streaming programming model.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static ServiceAdapterHolder toStreamingHttpService(BlockingStreamingHttpService service,
                                                               HttpExecutionStrategyInfluencer influencer) {
@@ -334,6 +345,7 @@ public static ServiceAdapterHolder toStreamingHttpService(BlockingStreamingHttpS
      * @return {@link ServiceAdapterHolder} containing the service adapted to the streaming programming model.
      * @deprecated Use overload with {@link HttpExecutionStrategy} rather than {@link HttpExecutionStrategyInfluencer}
      */
+    // FIXME: 0.43 - remove deprecated method
     @Deprecated
     public static ServiceAdapterHolder toStreamingHttpService(BlockingHttpService service,
                                                               HttpExecutionStrategyInfluencer influencer) {

servicetalk-http-api/src/main/java/io/servicetalk/http/api/HttpClientBuilder.java

@@ -30,31 +30,31 @@
 interface HttpClientBuilder<U, R, SDE extends ServiceDiscovererEvent<R>> {
 
     /**
-     * Sets the {@link Executor} for all connections created from this builder.
+     * Sets the {@link Executor} for all clients created from this builder.
      *
      * @param executor {@link IoExecutor} to use.
      * @return {@code this}.
      */
     HttpClientBuilder<U, R, SDE> executor(Executor executor);
 
     /**
-     * Sets the {@link IoExecutor} for all connections created from this builder.
+     * Sets the {@link IoExecutor} for all clients created from this builder.
      *
      * @param ioExecutor {@link IoExecutor} to use.
      * @return {@code this}.
      */
     HttpClientBuilder<U, R, SDE> ioExecutor(IoExecutor ioExecutor);
 
     /**
-     * Sets the {@link BufferAllocator} for all connections created from this builder.
+     * Sets the {@link BufferAllocator} for all clients created from this builder.
      *
      * @param allocator {@link BufferAllocator} to use.
      * @return {@code this}.
      */
     HttpClientBuilder<U, R, SDE> bufferAllocator(BufferAllocator allocator);
 
     /**
-     * Sets the {@link HttpExecutionStrategy} for all connections created from this builder.
+     * Sets the {@link HttpExecutionStrategy} for all clients created from this builder.
      *
      * @param strategy {@link HttpExecutionStrategy} to use.
      * @return {@code this}.

servicetalk-http-api/src/main/java/io/servicetalk/http/api/MultiAddressHttpClientBuilder.java

@@ -69,6 +69,34 @@ default SingleAddressInitializer<U, R> append(SingleAddressInitializer<U, R> toA
     @Override
     MultiAddressHttpClientBuilder<U, R> executor(Executor executor);
 
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Provides the base execution strategy for all clients created from this builder and the default strategy for
+     * the {@link SingleAddressHttpClientBuilder} used to construct client instances. The
+     * {@link #initializer(SingleAddressInitializer)} may be used for some customization of the execution strategy for a
+     * specific client. Unless {@link HttpExecutionStrategies#offloadNone()} is specified as the execution strategy on
+     * this builder then the single client computed execution strategy will be merged with this builder strategy.
+     *
+     * <dl>
+     *     <dt>unspecified or {@link HttpExecutionStrategies#defaultStrategy()}
+     *     <dd>Effective execution strategy will be appropriate for the API (async/blocking streaming/aggregate) of the
+     *     client used and will be be merged with the computed execution strategy of the single address client produced
+     *     by {@link SingleAddressHttpClientBuilder}.
+     *
+     *
+     *     <dt>{@link HttpExecutionStrategies#offloadNone()}
+     *     (or deprecated {@link HttpExecutionStrategies#offloadNever()}),
+     *     a custom execution strategy ({@link HttpExecutionStrategies#customStrategyBuilder()}), or
+     *     {@link HttpExecutionStrategies#offloadAll()}
+     *     <dd>Will be used, as specified, without regard to the API of the client used and will be merged with the
+     *     computed execution strategy of the single address client produced by
+     *     {@link SingleAddressHttpClientBuilder}.
+     * </dl>
+     *
+     * @param strategy {@inheritDoc}
+     * @return {@inheritDoc}
+     */
     @Override
     MultiAddressHttpClientBuilder<U, R> executionStrategy(HttpExecutionStrategy strategy);
 

servicetalk-http-api/src/main/java/io/servicetalk/http/api/SingleAddressHttpClientBuilder.java

@@ -172,6 +172,34 @@ SingleAddressHttpClientBuilder<U, R> appendConnectionFilter(
     @Override
     SingleAddressHttpClientBuilder<U, R> executor(Executor executor);
 
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Unless {@link HttpExecutionStrategies#offloadNone()} is specified as the execution strategy on
+     * this builder, the actual execution strategy used will be influenced by the execution strategy required by filters
+     * added via {@link #appendClientFilter(StreamingHttpClientFilterFactory)},
+     * {@link #appendConnectionFilter(StreamingHttpConnectionFilterFactory)}, and
+     * {@link #appendConnectionFactoryFilter(ConnectionFactoryFilter)}</p>, etc.
+     *
+     * <dl>
+     *     <dt>unspecified or {@link HttpExecutionStrategies#defaultStrategy()}
+     *     <dd>Effective execution strategy will be appropriate for the API (async/blocking streaming/aggregate) of the
+     *     client used and will be {@linkplain HttpExecutionStrategyInfluencer influenced} by required strategies of
+     *     any filters.
+     *
+     *     <dt>{@link HttpExecutionStrategies#offloadNone()}
+     *     (or deprecated {@link HttpExecutionStrategies#offloadNever()})
+     *     <dd>No offloading will be used regardless of the client API used or the influence of the filters.
+     *
+     *     <dt>A custom execution strategy ({@link HttpExecutionStrategies#customStrategyBuilder()}) or
+     *     {@link HttpExecutionStrategies#offloadAll()}
+     *     <dd>Will be used, as specified, without regard to the API of the client used. Effective execution strategy
+     *     will be specified value plus any additional offloads required by any filters.
+     * </dl>
+     *
+     * @param strategy {@inheritDoc}
+     * @return {@inheritDoc}
+     */
     @Override
     SingleAddressHttpClientBuilder<U, R> executionStrategy(HttpExecutionStrategy strategy);
 

servicetalk-http-api/src/main/java/io/servicetalk/http/api/StreamingHttpClientToBlockingHttpClient.java

@@ -31,8 +31,7 @@ final class StreamingHttpClientToBlockingHttpClient implements BlockingHttpClien
     private final HttpRequestResponseFactory reqRespFactory;
 
     StreamingHttpClientToBlockingHttpClient(final StreamingHttpClient client, final HttpExecutionStrategy strategy) {
-        this.strategy = defaultStrategy() == strategy ?
-                DEFAULT_BLOCKING_CONNECTION_STRATEGY : strategy;
+        this.strategy = defaultStrategy() == strategy ? DEFAULT_BLOCKING_CONNECTION_STRATEGY : strategy;
         this.client = client;
         context = new DelegatingHttpExecutionContext(client.executionContext()) {
             @Override

servicetalk-http-api/src/main/java/io/servicetalk/http/api/StreamingHttpClientToHttpClient.java

@@ -22,7 +22,7 @@
 import static io.servicetalk.http.api.HttpContextKeys.HTTP_EXECUTION_STRATEGY_KEY;
 import static io.servicetalk.http.api.HttpExecutionStrategies.defaultStrategy;
 import static io.servicetalk.http.api.RequestResponseFactories.toAggregated;
-import static io.servicetalk.http.api.StreamingHttpConnectionToHttpConnection.DEFAULT_CONNECTION_STRATEGY;
+import static io.servicetalk.http.api.StreamingHttpConnectionToHttpConnection.DEFAULT_ASYNC_CONNECTION_STRATEGY;
 import static java.util.Objects.requireNonNull;
 
 final class StreamingHttpClientToHttpClient implements HttpClient {
@@ -32,7 +32,7 @@ final class StreamingHttpClientToHttpClient implements HttpClient {
     private final HttpRequestResponseFactory reqRespFactory;
 
     StreamingHttpClientToHttpClient(final StreamingHttpClient client, final HttpExecutionStrategy strategy) {
-        this.strategy = defaultStrategy() == strategy ? DEFAULT_CONNECTION_STRATEGY : strategy;
+        this.strategy = defaultStrategy() == strategy ? DEFAULT_ASYNC_CONNECTION_STRATEGY : strategy;
         this.client = client;
         context = new DelegatingHttpExecutionContext(client.executionContext()) {
             @Override
@@ -118,7 +118,7 @@ static final class ReservedStreamingHttpConnectionToReservedHttpConnection imple
 
         ReservedStreamingHttpConnectionToReservedHttpConnection(final ReservedStreamingHttpConnection connection,
                                                                 final HttpExecutionStrategy strategy) {
-            this(connection, defaultStrategy() == strategy ? DEFAULT_CONNECTION_STRATEGY : strategy,
+            this(connection, defaultStrategy() == strategy ? DEFAULT_ASYNC_CONNECTION_STRATEGY : strategy,
                     toAggregated(connection));
         }
 

servicetalk-http-api/src/main/java/io/servicetalk/http/api/StreamingHttpConnectionToHttpConnection.java

@@ -28,7 +28,7 @@ final class StreamingHttpConnectionToHttpConnection implements HttpConnection {
      * For aggregation, we invoke the user callback (Single from client#request()) after the payload is completed,
      * hence we need to offload data.
      */
-    static final HttpExecutionStrategy DEFAULT_CONNECTION_STRATEGY = OFFLOAD_RECEIVE_DATA_EVENT_STRATEGY;
+    static final HttpExecutionStrategy DEFAULT_ASYNC_CONNECTION_STRATEGY = OFFLOAD_RECEIVE_DATA_EVENT_STRATEGY;
     private final StreamingHttpConnection connection;
     private final HttpExecutionStrategy strategy;
     private final HttpConnectionContext context;
@@ -37,7 +37,7 @@ final class StreamingHttpConnectionToHttpConnection implements HttpConnection {
 
     StreamingHttpConnectionToHttpConnection(final StreamingHttpConnection connection,
                                             final HttpExecutionStrategy strategy) {
-        this.strategy = defaultStrategy() == strategy ? DEFAULT_CONNECTION_STRATEGY : strategy;
+        this.strategy = defaultStrategy() == strategy ? DEFAULT_ASYNC_CONNECTION_STRATEGY : strategy;
         this.connection = connection;
         final HttpConnectionContext originalCtx = connection.connectionContext();
         executionContext = new DelegatingHttpExecutionContext(connection.executionContext()) {

servicetalk-http-netty/src/main/java/io/servicetalk/http/netty/ClientStrategyInfluencerChainBuilder.java

@@ -126,7 +126,7 @@ void add(StreamingHttpConnectionFilterFactory connectionFilter) {
         }
     }
 
-    HttpExecutionStrategy buildForClient(HttpExecutionStrategy transportStrategy) {
+    HttpExecutionStrategy buildForClient(HttpExecutionStrategy builderStrategy) {
         HttpExecutionStrategy chainStrategy = clientChain;
         if (null != connFilterChain) {
             chainStrategy = null != chainStrategy ? chainStrategy.merge(connFilterChain) : connFilterChain;
@@ -138,9 +138,10 @@ HttpExecutionStrategy buildForClient(HttpExecutionStrategy transportStrategy) {
         }
 
         return (null == chainStrategy || !chainStrategy.hasOffloads()) ?
-                transportStrategy :
-                defaultStrategy() == transportStrategy || !transportStrategy.hasOffloads() ?
-                        chainStrategy : chainStrategy.merge(transportStrategy);
+                builderStrategy :
+                defaultStrategy() == builderStrategy ?
+                        chainStrategy : builderStrategy.hasOffloads() ?
+                            chainStrategy.merge(builderStrategy) : builderStrategy;
     }
 
     ExecutionStrategy buildForConnectionFactory() {