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
28 package org.apache.hc.client5.http.classic;
29
30 import java.io.Closeable;
31 import java.io.IOException;
32
33 import org.apache.hc.core5.http.ClassicHttpRequest;
34 import org.apache.hc.core5.http.ClassicHttpResponse;
35 import org.apache.hc.core5.http.HttpHost;
36 import org.apache.hc.core5.http.HttpResponse;
37 import org.apache.hc.core5.http.io.HttpClientResponseHandler;
38 import org.apache.hc.core5.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.0
47 */
48 public interface HttpClient {
49
50 /**
51 * Executes HTTP request using the default context.
52 *
53 * @param request the request to execute
54 *
55 * @return the response to the request. This is always a final response,
56 * never an intermediate response with an 1xx status code.
57 * Whether redirects or authentication challenges will be returned
58 * or handled automatically depends on the implementation and
59 * configuration of this client.
60 * @throws IOException in case of a problem or the connection was aborted
61 *
62 * @deprecated It is strongly recommended to use execute methods with {@link HttpClientResponseHandler}
63 * such as {@link #execute(ClassicHttpRequest, HttpClientResponseHandler)} in order
64 * to ensure automatic resource deallocation by the client.
65 * For special cases one can still use {@link #executeOpen(HttpHost, ClassicHttpRequest, HttpContext)}
66 * to keep the response object open after the request execution.
67 *
68 * @see #execute(ClassicHttpRequest, HttpClientResponseHandler)
69 * @see #executeOpen(HttpHost, ClassicHttpRequest, HttpContext)
70 */
71 @Deprecated
72 HttpResponse execute(ClassicHttpRequest request) throws IOException;
73
74 /**
75 * Executes HTTP request using the given context.
76 *
77 * @param request the request to execute
78 * @param context the context to use for the execution, or
79 * {@code null} to use the default context
80 *
81 * @return the response to the request. This is always a final response,
82 * never an intermediate response with an 1xx status code.
83 * Whether redirects or authentication challenges will be returned
84 * or handled automatically depends on the implementation and
85 * configuration of this client.
86 * @throws IOException in case of a problem or the connection was aborted
87 *
88 * @deprecated It is strongly recommended to use execute methods with {@link HttpClientResponseHandler}
89 * such as {@link #execute(ClassicHttpRequest, HttpContext, HttpClientResponseHandler)} in order
90 * to ensure automatic resource deallocation by the client.
91 * For special cases one can still use {@link #executeOpen(HttpHost, ClassicHttpRequest, HttpContext)}
92 * to keep the response object open after the request execution.
93 *
94 * @see #execute(ClassicHttpRequest, HttpContext, HttpClientResponseHandler)
95 * @see #executeOpen(HttpHost, ClassicHttpRequest, HttpContext)
96 */
97 @Deprecated
98 HttpResponse execute(ClassicHttpRequest request, HttpContext context) throws IOException;
99
100 /**
101 * Executes HTTP request using the default context.
102 *
103 * @param target the target host for the request.
104 * Implementations may accept {@code null}
105 * if they can still determine a route, for example
106 * to a default target or by inspecting the request.
107 * @param request the request to execute
108 *
109 * @return the response to the request. This is always a final response,
110 * never an intermediate response with an 1xx status code.
111 * Whether redirects or authentication challenges will be returned
112 * or handled automatically depends on the implementation and
113 * configuration of this client.
114 * @throws IOException in case of a problem or the connection was aborted
115 *
116 * @deprecated It is strongly recommended to use execute methods with {@link HttpClientResponseHandler}
117 * such as {@link #execute(HttpHost, ClassicHttpRequest, HttpClientResponseHandler)} in order
118 * to ensure automatic resource deallocation by the client.
119 * For special cases one can still use {@link #executeOpen(HttpHost, ClassicHttpRequest, HttpContext)}
120 * to keep the response object open after the request execution.
121 *
122 * @see #execute(HttpHost, ClassicHttpRequest, HttpClientResponseHandler)
123 * @see #executeOpen(HttpHost, ClassicHttpRequest, HttpContext)
124 */
125 @Deprecated
126 ClassicHttpResponse execute(HttpHost target, ClassicHttpRequest request) throws IOException;
127
128 /**
129 * Executes HTTP request using the given context.
130 *
131 * @param target the target host for the request.
132 * Implementations may accept {@code null}
133 * if they can still determine a route, for example
134 * to a default target or by inspecting the request.
135 * @param request the request to execute
136 * @param context the context to use for the execution, or
137 * {@code null} to use the default context
138 *
139 * @return the response to the request. This is always a final response,
140 * never an intermediate response with an 1xx status code.
141 * Whether redirects or authentication challenges will be returned
142 * or handled automatically depends on the implementation and
143 * configuration of this client.
144 * @throws IOException in case of a problem or the connection was aborted
145 *
146 * @deprecated It is strongly recommended to use execute methods with {@link HttpClientResponseHandler}
147 * such as {@link #execute(HttpHost, ClassicHttpRequest, HttpContext, HttpClientResponseHandler)} in order
148 * to ensure automatic resource deallocation by the client.
149 * For special cases one can still use {@link #executeOpen(HttpHost, ClassicHttpRequest, HttpContext)}
150 * to keep the response object open after the request execution.
151 *
152 * @see #execute(HttpHost, ClassicHttpRequest, HttpContext, HttpClientResponseHandler)
153 * @see #executeOpen(HttpHost, ClassicHttpRequest, HttpContext)
154 */
155 @Deprecated
156 HttpResponse execute(HttpHost target, ClassicHttpRequest request, HttpContext context) throws IOException;
157
158 /**
159 * Executes the request and opens the response stream using the given context.
160 *
161 * @param target the target host for the request.
162 * Implementations may accept {@code null}
163 * if they can still determine a route, for example
164 * to a default target or by inspecting the request.
165 * @param request the request to execute
166 * @param context the context to use for the execution, or
167 * {@code null} to use the default context
168 *
169 * @return the response to the request. This is always a final response,
170 * never an intermediate response with an 1xx status code.
171 * Whether redirects or authentication challenges will be returned
172 * or handled automatically depends on the implementation and
173 * configuration of this client.
174 * The response returned by this method must be closed with
175 * {@link Closeable#close()} in order ensure deallocation
176 * of system resources.
177 * @throws IOException in case of a problem or the connection was aborted
178 *
179 * @since 5.2
180 */
181 @SuppressWarnings("deprecation")
182 default ClassicHttpResponse executeOpen(HttpHost target, ClassicHttpRequest request, HttpContext context) throws IOException {
183 return (ClassicHttpResponse) execute(target, request, context);
184 }
185
186 /**
187 * Executes HTTP request using the default context and processes the
188 * response using the given response handler.
189 * <p>
190 * Implementing classes are required to ensure that the content entity
191 * associated with the response is fully consumed and the underlying
192 * connection is released back to the connection manager automatically
193 * in all cases relieving individual {@link HttpClientResponseHandler}s from
194 * having to manage resource deallocation internally.
195 * </p>
196 *
197 * @param request the request to execute
198 * @param responseHandler the response handler
199 *
200 * @return the response object as generated by the response handler.
201 * @throws IOException in case of a problem or the connection was aborted
202 */
203 <T> T execute(ClassicHttpRequest request, HttpClientResponseHandler<? extends T> responseHandler) throws IOException;
204
205 /**
206 * Executes HTTP request using the given context and processes the
207 * response using the given response handler.
208 * <p>
209 * Implementing classes are required to ensure that the content entity
210 * associated with the response is fully consumed and the underlying
211 * connection is released back to the connection manager automatically
212 * in all cases relieving individual {@link HttpClientResponseHandler}s from
213 * having to manage resource deallocation internally.
214 * </p>
215 *
216 * @param request the request to execute
217 * @param context the context to use for the execution, or
218 * {@code null} to use the default context
219 * @param responseHandler the response handler
220 *
221 * @return the response object as generated by the response handler.
222 * @throws IOException in case of a problem or the connection was aborted
223 */
224 <T> T execute(
225 ClassicHttpRequest request,
226 HttpContext context,
227 HttpClientResponseHandler<? extends T> responseHandler) throws IOException;
228
229 /**
230 * Executes HTTP request to the target using the default context and
231 * processes the response using the given response handler.
232 * <p>
233 * Implementing classes are required to ensure that the content entity
234 * associated with the response is fully consumed and the underlying
235 * connection is released back to the connection manager automatically
236 * in all cases relieving individual {@link HttpClientResponseHandler}s from
237 * having to manage resource deallocation internally.
238 * </p>
239 *
240 * @param target the target host for the request.
241 * Implementations may accept {@code null}
242 * if they can still determine a route, for example
243 * to a default target or by inspecting the request.
244 * @param request the request to execute
245 * @param responseHandler the response handler
246 *
247 * @return the response object as generated by the response handler.
248 * @throws IOException in case of a problem or the connection was aborted
249 */
250 <T> T execute(
251 HttpHost target,
252 ClassicHttpRequest request,
253 HttpClientResponseHandler<? extends T> responseHandler) throws IOException;
254
255 /**
256 * Executes HTTP request to the target using the given context and
257 * processes the response using the given response handler.
258 * <p>
259 * Implementing classes are required to ensure that the content entity
260 * associated with the response is fully consumed and the underlying
261 * connection is released back to the connection manager automatically
262 * in all cases relieving individual {@link HttpClientResponseHandler}s from
263 * having to manage resource deallocation internally.
264 * </p>
265 *
266 * @param target the target host for the request.
267 * Implementations may accept {@code null}
268 * if they can still determine a route, for example
269 * to a default target or by inspecting the request.
270 * @param request the request to execute
271 * @param context the context to use for the execution, or
272 * {@code null} to use the default context
273 * @param responseHandler the response handler
274 *
275 * @return the response object as generated by the response handler.
276 * @throws IOException in case of a problem or the connection was aborted
277 */
278 <T> T execute(
279 HttpHost target,
280 ClassicHttpRequest request,
281 HttpContext context,
282 HttpClientResponseHandler<? extends T> responseHandler) throws IOException;
283
284 }