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.IOException;
31
32 import org.apache.hc.core5.http.ClassicHttpRequest;
33 import org.apache.hc.core5.http.ClassicHttpResponse;
34 import org.apache.hc.core5.http.HttpHost;
35 import org.apache.hc.core5.http.HttpResponse;
36 import org.apache.hc.core5.http.io.HttpClientResponseHandler;
37 import org.apache.hc.core5.http.protocol.HttpContext;
38
39 /**
40 * This interface represents only the most basic contract for HTTP request
41 * execution. It imposes no restrictions or particular details on the request
42 * execution process and leaves the specifics of state management,
43 * authentication and redirect handling up to individual implementations.
44 *
45 * @since 4.0
46 */
47 public interface HttpClient {
48
49 /**
50 * Executes HTTP request using the default context.
51 *
52 * @param request the request to execute
53 *
54 * @return the response to the request. This is always a final response,
55 * never an intermediate response with an 1xx status code.
56 * Whether redirects or authentication challenges will be returned
57 * or handled automatically depends on the implementation and
58 * configuration of this client.
59 * @throws IOException in case of a problem or the connection was aborted
60 */
61 HttpResponse execute(ClassicHttpRequest request) throws IOException;
62
63 /**
64 * Executes HTTP request using the given context.
65 *
66 * @param request the request to execute
67 * @param context the context to use for the execution, or
68 * {@code null} to use the default context
69 *
70 * @return the response to the request. This is always a final response,
71 * never an intermediate response with an 1xx status code.
72 * Whether redirects or authentication challenges will be returned
73 * or handled automatically depends on the implementation and
74 * configuration of this client.
75 * @throws IOException in case of a problem or the connection was aborted
76 */
77 HttpResponse execute(ClassicHttpRequest request, HttpContext context) throws IOException;
78
79 /**
80 * Executes HTTP request using the default context.
81 *
82 * @param target the target host for the request.
83 * Implementations may accept {@code null}
84 * if they can still determine a route, for example
85 * to a default target or by inspecting the request.
86 * @param request the request to execute
87 *
88 * @return the response to the request. This is always a final response,
89 * never an intermediate response with an 1xx status code.
90 * Whether redirects or authentication challenges will be returned
91 * or handled automatically depends on the implementation and
92 * configuration of this client.
93 * @throws IOException in case of a problem or the connection was aborted
94 */
95 ClassicHttpResponse execute(HttpHost target, ClassicHttpRequest request) throws IOException;
96
97 /**
98 * Executes HTTP request using the given context.
99 *
100 * @param target the target host for the request.
101 * Implementations may accept {@code null}
102 * if they can still determine a route, for example
103 * to a default target or by inspecting the request.
104 * @param request the request to execute
105 * @param context the context to use for the execution, or
106 * {@code null} to use the default context
107 *
108 * @return the response to the request. This is always a final response,
109 * never an intermediate response with an 1xx status code.
110 * Whether redirects or authentication challenges will be returned
111 * or handled automatically depends on the implementation and
112 * configuration of this client.
113 * @throws IOException in case of a problem or the connection was aborted
114 */
115 HttpResponse execute(HttpHost target, ClassicHttpRequest request, HttpContext context) throws IOException;
116
117 /**
118 * Executes HTTP request using the default context and processes the
119 * response using the given response handler.
120 * <p>
121 * Implementing classes are required to ensure that the content entity
122 * associated with the response is fully consumed and the underlying
123 * connection is released back to the connection manager automatically
124 * in all cases relieving individual {@link HttpClientResponseHandler}s from
125 * having to manage resource deallocation internally.
126 * </p>
127 *
128 * @param request the request to execute
129 * @param responseHandler the response handler
130 *
131 * @return the response object as generated by the response handler.
132 * @throws IOException in case of a problem or the connection was aborted
133 */
134 <T> T execute(ClassicHttpRequest request, HttpClientResponseHandler<? extends T> responseHandler) throws IOException;
135
136 /**
137 * Executes HTTP request using the given context and processes the
138 * response using the given response handler.
139 * <p>
140 * Implementing classes are required to ensure that the content entity
141 * associated with the response is fully consumed and the underlying
142 * connection is released back to the connection manager automatically
143 * in all cases relieving individual {@link HttpClientResponseHandler}s from
144 * having to manage resource deallocation internally.
145 * </p>
146 *
147 * @param request the request to execute
148 * @param context the context to use for the execution, or
149 * {@code null} to use the default context
150 * @param responseHandler the response handler
151 *
152 * @return the response object as generated by the response handler.
153 * @throws IOException in case of a problem or the connection was aborted
154 */
155 <T> T execute(
156 ClassicHttpRequest request,
157 HttpContext context,
158 HttpClientResponseHandler<? extends T> responseHandler) throws IOException;
159
160 /**
161 * Executes HTTP request to the target using the default context and
162 * processes the response using the given response handler.
163 * <p>
164 * Implementing classes are required to ensure that the content entity
165 * associated with the response is fully consumed and the underlying
166 * connection is released back to the connection manager automatically
167 * in all cases relieving individual {@link HttpClientResponseHandler}s from
168 * having to manage resource deallocation internally.
169 * </p>
170 *
171 * @param target the target host for the request.
172 * Implementations may accept {@code null}
173 * if they can still determine a route, for example
174 * to a default target or by inspecting the request.
175 * @param request the request to execute
176 * @param responseHandler the response handler
177 *
178 * @return the response object as generated by the response handler.
179 * @throws IOException in case of a problem or the connection was aborted
180 */
181 <T> T execute(
182 HttpHost target,
183 ClassicHttpRequest request,
184 HttpClientResponseHandler<? extends T> responseHandler) throws IOException;
185
186 /**
187 * Executes HTTP request to the target using the given context and
188 * processes the 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 target the target host for the request.
198 * Implementations may accept {@code null}
199 * if they can still determine a route, for example
200 * to a default target or by inspecting the request.
201 * @param request the request to execute
202 * @param context the context to use for the execution, or
203 * {@code null} to use the default context
204 * @param responseHandler the response handler
205 *
206 * @return the response object as generated by the response handler.
207 * @throws IOException in case of a problem or the connection was aborted
208 */
209 <T> T execute(
210 HttpHost target,
211 ClassicHttpRequest request,
212 HttpContext context,
213 HttpClientResponseHandler<? extends T> responseHandler) throws IOException;
214
215 }