1/*
2 * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/HttpClient.java $
3 * $Revision: 676020 $
4 * $Date: 2008-07-11 09:38:49 -0700 (Fri, 11 Jul 2008) $
5 *
6 * ====================================================================
7 * Licensed to the Apache Software Foundation (ASF) under one
8 * or more contributor license agreements.  See the NOTICE file
9 * distributed with this work for additional information
10 * regarding copyright ownership.  The ASF licenses this file
11 * to you under the Apache License, Version 2.0 (the
12 * "License"); you may not use this file except in compliance
13 * with the License.  You may obtain a copy of the License at
14 *
15 *   http://www.apache.org/licenses/LICENSE-2.0
16 *
17 * Unless required by applicable law or agreed to in writing,
18 * software distributed under the License is distributed on an
19 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20 * KIND, either express or implied.  See the License for the
21 * specific language governing permissions and limitations
22 * under the License.
23 * ====================================================================
24 *
25 * This software consists of voluntary contributions made by many
26 * individuals on behalf of the Apache Software Foundation.  For more
27 * information on the Apache Software Foundation, please see
28 * <http://www.apache.org/>.
29 *
30 */
31
32package org.apache.http.client;
33
34import java.io.IOException;
35
36import org.apache.http.HttpHost;
37import org.apache.http.HttpRequest;
38import org.apache.http.HttpResponse;
39import org.apache.http.params.HttpParams;
40import org.apache.http.protocol.HttpContext;
41import org.apache.http.client.methods.HttpUriRequest;
42import org.apache.http.conn.ClientConnectionManager;
43
44/**
45 * Interface for an HTTP client.
46 * HTTP clients encapsulate a smorgasbord of objects required to
47 * execute HTTP requests while handling cookies, authentication,
48 * connection management, and other features.
49 * Thread safety of HTTP clients depends on the implementation
50 * and configuration of the specific client.
51 *
52 * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
53 *
54 *
55 * <!-- empty lines to avoid svn diff problems -->
56 * @version   $Revision: 676020 $
57 *
58 * @since 4.0
59 */
60public interface HttpClient {
61
62
63    /**
64     * Obtains the parameters for this client.
65     * These parameters will become defaults for all requests being
66     * executed with this client, and for the parameters of
67     * dependent objects in this client.
68     *
69     * @return  the default parameters
70     */
71    HttpParams getParams()
72        ;
73
74
75    /**
76     * Obtains the connection manager used by this client.
77     *
78     * @return  the connection manager
79     */
80    ClientConnectionManager getConnectionManager()
81        ;
82
83    /**
84     * Executes a request using the default context.
85     *
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     * @throws ClientProtocolException in case of an http protocol error
95     */
96    HttpResponse execute(HttpUriRequest request)
97        throws IOException, ClientProtocolException
98        ;
99
100
101    /**
102     * Executes a request using the given context.
103     * The route to the target will be determined by the HTTP client.
104     *
105     * @param request   the request to execute
106     * @param context   the context to use for the execution, or
107     *                  <code>null</code> to use the default context
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     * @throws ClientProtocolException in case of an http protocol error
116     */
117    HttpResponse execute(HttpUriRequest request, HttpContext context)
118        throws IOException, ClientProtocolException
119        ;
120
121
122    /**
123     * Executes a request to the target using the default context.
124     *
125     * @param target    the target host for the request.
126     *                  Implementations may accept <code>null</code>
127     *                  if they can still determine a route, for example
128     *                  to a default target or by inspecting the request.
129     * @param request   the request to execute
130     *
131     * @return  the response to the request. This is always a final response,
132     *          never an intermediate response with an 1xx status code.
133     *          Whether redirects or authentication challenges will be returned
134     *          or handled automatically depends on the implementation and
135     *          configuration of this client.
136     * @throws IOException in case of a problem or the connection was aborted
137     * @throws ClientProtocolException in case of an http protocol error
138     */
139    HttpResponse execute(HttpHost target, HttpRequest request)
140        throws IOException, ClientProtocolException
141        ;
142
143    /**
144     * Executes a request to the target using the given context.
145     *
146     * @param target    the target host for the request.
147     *                  Implementations may accept <code>null</code>
148     *                  if they can still determine a route, for example
149     *                  to a default target or by inspecting the request.
150     * @param request   the request to execute
151     * @param context   the context to use for the execution, or
152     *                  <code>null</code> to use the default context
153     *
154     * @return  the response to the request. This is always a final response,
155     *          never an intermediate response with an 1xx status code.
156     *          Whether redirects or authentication challenges will be returned
157     *          or handled automatically depends on the implementation and
158     *          configuration of this client.
159     * @throws IOException in case of a problem or the connection was aborted
160     * @throws ClientProtocolException in case of an http protocol error
161     */
162    HttpResponse execute(HttpHost target, HttpRequest request,
163                         HttpContext context)
164        throws IOException, ClientProtocolException
165        ;
166
167    /**
168     * Executes a request using the default context and processes the
169     * response using the given response handler.
170     *
171     * @param request   the request to execute
172     * @param responseHandler the response handler
173     *
174     * @return  the response object as generated by the response handler.
175     * @throws IOException in case of a problem or the connection was aborted
176     * @throws ClientProtocolException in case of an http protocol error
177     */
178    <T> T execute(
179            HttpUriRequest request,
180            ResponseHandler<? extends T> responseHandler)
181        throws IOException, ClientProtocolException
182        ;
183
184    /**
185     * Executes a request using the given context and processes the
186     * response using the given response handler.
187     *
188     * @param request   the request to execute
189     * @param responseHandler the response handler
190     *
191     * @return  the response object as generated by the response handler.
192     * @throws IOException in case of a problem or the connection was aborted
193     * @throws ClientProtocolException in case of an http protocol error
194     */
195    <T> T execute(
196            HttpUriRequest request,
197            ResponseHandler<? extends T> responseHandler,
198            HttpContext context)
199        throws IOException, ClientProtocolException
200        ;
201
202    /**
203     * Executes a request to the target using the default context and
204     * processes the response using the given response handler.
205     *
206     * @param target    the target host for the request.
207     *                  Implementations may accept <code>null</code>
208     *                  if they can still determine a route, for example
209     *                  to a default target or by inspecting the request.
210     * @param request   the request to execute
211     * @param responseHandler the response handler
212     *
213     * @return  the response object as generated by the response handler.
214     * @throws IOException in case of a problem or the connection was aborted
215     * @throws ClientProtocolException in case of an http protocol error
216     */
217    <T> T execute(
218            HttpHost target,
219            HttpRequest request,
220            ResponseHandler<? extends T> responseHandler)
221        throws IOException, ClientProtocolException
222        ;
223
224    /**
225     * Executes a request to the target using the given context and
226     * processes the response using the given response handler.
227     *
228     * @param target    the target host for the request.
229     *                  Implementations may accept <code>null</code>
230     *                  if they can still determine a route, for example
231     *                  to a default target or by inspecting the request.
232     * @param request   the request to execute
233     * @param responseHandler the response handler
234     * @param context   the context to use for the execution, or
235     *                  <code>null</code> to use the default context
236     *
237     * @return  the response object as generated by the response handler.
238     * @throws IOException in case of a problem or the connection was aborted
239     * @throws ClientProtocolException in case of an http protocol error
240     */
241    <T> T execute(
242            HttpHost target,
243            HttpRequest request,
244            ResponseHandler<? extends T> responseHandler,
245            HttpContext context)
246        throws IOException, ClientProtocolException
247        ;
248
249} // interface HttpClient
250