1 /*
2 * ====================================================================
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 * ====================================================================
20 *
21 * This software consists of voluntary contributions made by many
22 * individuals on behalf of the Apache Software Foundation. For more
23 * information on the Apache Software Foundation, please see
24 * <http://www.apache.org/>.
25 *
26 */
27 package org.apache.http.nio.client;
28
29 import java.util.List;
30 import java.util.concurrent.Future;
31
32 import org.apache.http.HttpHost;
33 import org.apache.http.HttpRequest;
34 import org.apache.http.HttpResponse;
35 import org.apache.http.concurrent.FutureCallback;
36 import org.apache.http.nio.protocol.HttpAsyncRequestProducer;
37 import org.apache.http.nio.protocol.HttpAsyncResponseConsumer;
38 import org.apache.http.protocol.HttpContext;
39
40 /**
41 * This interface represents only the most basic contract for HTTP request
42 * execution. It imposes no restrictions or particular details on the request
43 * execution process and leaves the specifics of state management,
44 * authentication and redirect handling up to individual implementations.
45 *
46 * @since 4.1
47 */
48 public interface HttpPipeliningClient extends HttpAsyncClient {
49
50 /**
51 * Initiates pipelined execution of a sequence of requests.
52 * <p>
53 * The request producers passed to this method will be used to generate
54 * a request message and stream out its content without buffering it
55 * in memory. The response consumers passed to this method will be used
56 * to process a response message without buffering its content in memory.
57 * <p>
58 * Please note it may be unsafe to interact with the context instance
59 * while the request is still being executed.
60 *
61 * @param <T> the result type of request execution.
62 * @param target the target host for the request.
63 * @param requestProducers list of request producers.
64 * @param responseConsumers list of response consumers.
65 * @param context HTTP context
66 * @param callback future callback.
67 * @return future representing pending completion of the operation.
68 */
69 <T> Future<List<T>> execute(
70 HttpHost target,
71 List<? extends HttpAsyncRequestProducer> requestProducers,
72 List<? extends HttpAsyncResponseConsumer<T>> responseConsumers,
73 HttpContext context,
74 FutureCallback<List<T>> callback);
75
76 /**
77 * Initiates pipelined execution of a sequence of requests.
78 * <p>
79 * The request producers passed to this method will be used to generate
80 * a request message and stream out its content without buffering it
81 * in memory. The response consumers passed to this method will be used
82 * to process a response message without buffering its content in memory.
83 *
84 * @param <T> the result type of request execution.
85 * @param target the target host for the request.
86 * @param requestProducers list of request producers.
87 * @param responseConsumers list of response consumers.
88 * @param callback future callback.
89 * @return future representing pending completion of the operation.
90 */
91 <T> Future<List<T>> execute(
92 HttpHost target,
93 List<? extends HttpAsyncRequestProducer> requestProducers,
94 List<? extends HttpAsyncResponseConsumer<T>> responseConsumers,
95 FutureCallback<List<T>> callback);
96
97 /**
98 * Initiates pipelined execution of a sequence of requests against
99 * the given target using the given context.
100 * <p>
101 * Please note it may be unsafe to interact with the context instance
102 * while the request is still being executed.
103 *
104 * @param target the target host for the requests.
105 * Implementations may accept {@code null}
106 * if they can still determine a route, for example
107 * to a default target or by inspecting the request.
108 * @param requests the requests to execute
109 * @param context the context to use for the execution, or
110 * {@code null} to use the default context
111 * @param callback future callback.
112 * @return future representing pending completion of the operation.
113 */
114 Future<List<HttpResponse>> execute(
115 HttpHost target,
116 List<HttpRequest> requests,
117 HttpContext context,
118 FutureCallback<List<HttpResponse>> callback);
119
120 /**
121 * Initiates pipelined execution of a sequence of requests against
122 * the given target.
123 *
124 * @param target the target host for the requests.
125 * Implementations may accept {@code null}
126 * if they can still determine a route, for example
127 * to a default target or by inspecting the request.
128 * @param requests the requests to execute
129 * @param callback future callback.
130 * @return future representing pending completion of the operation.
131 */
132 Future<List<HttpResponse>> execute(
133 HttpHost target,
134 List<HttpRequest> requests,
135 FutureCallback<List<HttpResponse>> callback);
136
137 }