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.http.client;
29
30 import java.io.IOException;
31
32 import org.apache.http.HttpHost;
33 import org.apache.http.HttpRequest;
34 import org.apache.http.HttpResponse;
35 import org.apache.http.client.methods.HttpUriRequest;
36 import org.apache.http.conn.ClientConnectionManager;
37 import org.apache.http.params.HttpParams;
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 * This should make it easier to decorate the interface with additional
46 * functionality such as response content caching.
47 * <p/>
48 * The usual execution flow can be demonstrated by the code snippet below:
49 * <PRE>
50 * HttpClient httpclient = new DefaultHttpClient();
51 *
52 * // Prepare a request object
53 * HttpGet httpget = new HttpGet("http://www.apache.org/");
54 *
55 * // Execute the request
56 * HttpResponse response = httpclient.execute(httpget);
57 *
58 * // Examine the response status
59 * System.out.println(response.getStatusLine());
60 *
61 * // Get hold of the response entity
62 * HttpEntity entity = response.getEntity();
63 *
64 * // If the response does not enclose an entity, there is no need
65 * // to worry about connection release
66 * if (entity != null) {
67 * InputStream instream = entity.getContent();
68 * try {
69 *
70 * BufferedReader reader = new BufferedReader(
71 * new InputStreamReader(instream));
72 * // do something useful with the response
73 * System.out.println(reader.readLine());
74 *
75 * } catch (IOException ex) {
76 *
77 * // In case of an IOException the connection will be released
78 * // back to the connection manager automatically
79 * throw ex;
80 *
81 * } catch (RuntimeException ex) {
82 *
83 * // In case of an unexpected exception you may want to abort
84 * // the HTTP request in order to shut down the underlying
85 * // connection and release it back to the connection manager.
86 * httpget.abort();
87 * throw ex;
88 *
89 * } finally {
90 *
91 * // Closing the input stream will trigger connection release
92 * instream.close();
93 *
94 * }
95 *
96 * // When HttpClient instance is no longer needed,
97 * // shut down the connection manager to ensure
98 * // immediate deallocation of all system resources
99 * httpclient.getConnectionManager().shutdown();
100 * }
101 * </PRE>
102 *
103 * @since 4.0
104 */
105 public interface HttpClient {
106
107
108 /**
109 * Obtains the parameters for this client.
110 * These parameters will become defaults for all requests being
111 * executed with this client, and for the parameters of
112 * dependent objects in this client.
113 *
114 * @return the default parameters
115 */
116 HttpParams getParams();
117
118 /**
119 * Obtains the connection manager used by this client.
120 *
121 * @return the connection manager
122 */
123 ClientConnectionManager getConnectionManager();
124
125 /**
126 * Executes a request using the default context.
127 *
128 * @param request the request to execute
129 *
130 * @return the response to the request. This is always a final response,
131 * never an intermediate response with an 1xx status code.
132 * Whether redirects or authentication challenges will be returned
133 * or handled automatically depends on the implementation and
134 * configuration of this client.
135 * @throws IOException in case of a problem or the connection was aborted
136 * @throws ClientProtocolException in case of an http protocol error
137 */
138 HttpResponse execute(HttpUriRequest request)
139 throws IOException, ClientProtocolException;
140
141 /**
142 * Executes a request using the given context.
143 * The route to the target will be determined by the HTTP client.
144 *
145 * @param request the request to execute
146 * @param context the context to use for the execution, or
147 * <code>null</code> to use the default context
148 *
149 * @return the response to the request. This is always a final response,
150 * never an intermediate response with an 1xx status code.
151 * Whether redirects or authentication challenges will be returned
152 * or handled automatically depends on the implementation and
153 * configuration of this client.
154 * @throws IOException in case of a problem or the connection was aborted
155 * @throws ClientProtocolException in case of an http protocol error
156 */
157 HttpResponse execute(HttpUriRequest request, HttpContext context)
158 throws IOException, ClientProtocolException;
159
160 /**
161 * Executes a request to the target using the default context.
162 *
163 * @param target the target host for the request.
164 * Implementations may accept <code>null</code>
165 * if they can still determine a route, for example
166 * to a default target or by inspecting the request.
167 * @param request the request to execute
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 * @throws IOException in case of a problem or the connection was aborted
175 * @throws ClientProtocolException in case of an http protocol error
176 */
177 HttpResponse execute(HttpHost target, HttpRequest request)
178 throws IOException, ClientProtocolException;
179
180 /**
181 * Executes a request to the target using the given context.
182 *
183 * @param target the target host for the request.
184 * Implementations may accept <code>null</code>
185 * if they can still determine a route, for example
186 * to a default target or by inspecting the request.
187 * @param request the request to execute
188 * @param context the context to use for the execution, or
189 * <code>null</code> to use the default context
190 *
191 * @return the response to the request. This is always a final response,
192 * never an intermediate response with an 1xx status code.
193 * Whether redirects or authentication challenges will be returned
194 * or handled automatically depends on the implementation and
195 * configuration of this client.
196 * @throws IOException in case of a problem or the connection was aborted
197 * @throws ClientProtocolException in case of an http protocol error
198 */
199 HttpResponse execute(HttpHost target, HttpRequest request,
200 HttpContext context)
201 throws IOException, ClientProtocolException;
202
203 /**
204 * Executes a request using the default context and processes the
205 * response using the given response handler.
206 * <p/>
207 * Implementing classes are required to ensure that the content entity
208 * associated with the response is fully consumed and the underlying
209 * connection is released back to the connection manager automatically
210 * in all cases relieving individual {@link ResponseHandler} from
211 * having to manage resource deallocation internally.
212 *
213 * @param request the request to execute
214 * @param responseHandler the response handler
215 *
216 * @return the response object as generated by the response handler.
217 * @throws IOException in case of a problem or the connection was aborted
218 * @throws ClientProtocolException in case of an http protocol error
219 */
220 <T> T execute(
221 HttpUriRequest request,
222 ResponseHandler<? extends T> responseHandler)
223 throws IOException, ClientProtocolException;
224
225 /**
226 * Executes a request using the given context and processes the
227 * response using the given response handler.
228 * <p/>
229 * Implementing classes are required to ensure that the content entity
230 * associated with the response is fully consumed and the underlying
231 * connection is released back to the connection manager automatically
232 * in all cases relieving individual {@link ResponseHandler} from
233 * having to manage resource deallocation internally.
234 *
235 * @param request the request to execute
236 * @param responseHandler the response handler
237 * @param context the context to use for the execution, or
238 * <code>null</code> to use the default context
239 *
240 * @return the response object as generated by the response handler.
241 * @throws IOException in case of a problem or the connection was aborted
242 * @throws ClientProtocolException in case of an http protocol error
243 */
244 <T> T execute(
245 HttpUriRequest request,
246 ResponseHandler<? extends T> responseHandler,
247 HttpContext context)
248 throws IOException, ClientProtocolException;
249
250 /**
251 * Executes a request to the target using the default context and
252 * processes the response using the given response handler.
253 * <p/>
254 * Implementing classes are required to ensure that the content entity
255 * associated with the response is fully consumed and the underlying
256 * connection is released back to the connection manager automatically
257 * in all cases relieving individual {@link ResponseHandler} from
258 * having to manage resource deallocation internally.
259 *
260 * @param target the target host for the request.
261 * Implementations may accept <code>null</code>
262 * if they can still determine a route, for example
263 * to a default target or by inspecting the request.
264 * @param request the request to execute
265 * @param responseHandler the response handler
266 *
267 * @return the response object as generated by the response handler.
268 * @throws IOException in case of a problem or the connection was aborted
269 * @throws ClientProtocolException in case of an http protocol error
270 */
271 <T> T execute(
272 HttpHost target,
273 HttpRequest request,
274 ResponseHandler<? extends T> responseHandler)
275 throws IOException, ClientProtocolException;
276
277 /**
278 * Executes a request to the target using the given context and
279 * processes the response using the given response handler.
280 * <p/>
281 * Implementing classes are required to ensure that the content entity
282 * associated with the response is fully consumed and the underlying
283 * connection is released back to the connection manager automatically
284 * in all cases relieving individual {@link ResponseHandler} from
285 * having to manage resource deallocation internally.
286 *
287 * @param target the target host for the request.
288 * Implementations may accept <code>null</code>
289 * if they can still determine a route, for example
290 * to a default target or by inspecting the request.
291 * @param request the request to execute
292 * @param responseHandler the response handler
293 * @param context the context to use for the execution, or
294 * <code>null</code> to use the default context
295 *
296 * @return the response object as generated by the response handler.
297 * @throws IOException in case of a problem or the connection was aborted
298 * @throws ClientProtocolException in case of an http protocol error
299 */
300 <T> T execute(
301 HttpHost target,
302 HttpRequest request,
303 ResponseHandler<? extends T> responseHandler,
304 HttpContext context)
305 throws IOException, ClientProtocolException;
306
307 }