1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/client/HttpClient.java Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,281 @@
1.4 +/*
1.5 + * ====================================================================
1.6 + * Licensed to the Apache Software Foundation (ASF) under one
1.7 + * or more contributor license agreements. See the NOTICE file
1.8 + * distributed with this work for additional information
1.9 + * regarding copyright ownership. The ASF licenses this file
1.10 + * to you under the Apache License, Version 2.0 (the
1.11 + * "License"); you may not use this file except in compliance
1.12 + * with the License. You may obtain a copy of the License at
1.13 + *
1.14 + * http://www.apache.org/licenses/LICENSE-2.0
1.15 + *
1.16 + * Unless required by applicable law or agreed to in writing,
1.17 + * software distributed under the License is distributed on an
1.18 + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1.19 + * KIND, either express or implied. See the License for the
1.20 + * specific language governing permissions and limitations
1.21 + * under the License.
1.22 + * ====================================================================
1.23 + *
1.24 + * This software consists of voluntary contributions made by many
1.25 + * individuals on behalf of the Apache Software Foundation. For more
1.26 + * information on the Apache Software Foundation, please see
1.27 + * <http://www.apache.org/>.
1.28 + *
1.29 + */
1.30 +
1.31 +package ch.boye.httpclientandroidlib.client;
1.32 +
1.33 +import java.io.IOException;
1.34 +
1.35 +import ch.boye.httpclientandroidlib.HttpHost;
1.36 +import ch.boye.httpclientandroidlib.HttpRequest;
1.37 +import ch.boye.httpclientandroidlib.HttpResponse;
1.38 +import ch.boye.httpclientandroidlib.client.methods.HttpUriRequest;
1.39 +import ch.boye.httpclientandroidlib.conn.ClientConnectionManager;
1.40 +import ch.boye.httpclientandroidlib.params.HttpParams;
1.41 +import ch.boye.httpclientandroidlib.protocol.HttpContext;
1.42 +
1.43 +/**
1.44 + * This interface represents only the most basic contract for HTTP request
1.45 + * execution. It imposes no restrictions or particular details on the request
1.46 + * execution process and leaves the specifics of state management,
1.47 + * authentication and redirect handling up to individual implementations.
1.48 + * This should make it easier to decorate the interface with additional
1.49 + * functionality such as response content caching.
1.50 + * <p/>
1.51 + * The usual execution flow can be demonstrated by the code snippet below:
1.52 + * <PRE>
1.53 + * HttpClient httpclient = new DefaultHttpClient();
1.54 + *
1.55 + * // Prepare a request object
1.56 + * HttpGet httpget = new HttpGet("http://www.apache.org/");
1.57 + *
1.58 + * // Execute the request
1.59 + * HttpResponse response = httpclient.execute(httpget);
1.60 + *
1.61 + * // Examine the response status
1.62 + * System.out.println(response.getStatusLine());
1.63 + *
1.64 + * // Get hold of the response entity
1.65 + * HttpEntity entity = response.getEntity();
1.66 + *
1.67 + * // If the response does not enclose an entity, there is no need
1.68 + * // to worry about connection release
1.69 + * if (entity != null) {
1.70 + * InputStream instream = entity.getContent();
1.71 + * try {
1.72 + *
1.73 + * BufferedReader reader = new BufferedReader(
1.74 + * new InputStreamReader(instream));
1.75 + * // do something useful with the response
1.76 + * System.out.println(reader.readLine());
1.77 + *
1.78 + * } catch (IOException ex) {
1.79 + *
1.80 + * // In case of an IOException the connection will be released
1.81 + * // back to the connection manager automatically
1.82 + * throw ex;
1.83 + *
1.84 + * } catch (RuntimeException ex) {
1.85 + *
1.86 + * // In case of an unexpected exception you may want to abort
1.87 + * // the HTTP request in order to shut down the underlying
1.88 + * // connection and release it back to the connection manager.
1.89 + * httpget.abort();
1.90 + * throw ex;
1.91 + *
1.92 + * } finally {
1.93 + *
1.94 + * // Closing the input stream will trigger connection release
1.95 + * instream.close();
1.96 + *
1.97 + * }
1.98 + *
1.99 + * // When HttpClient instance is no longer needed,
1.100 + * // shut down the connection manager to ensure
1.101 + * // immediate deallocation of all system resources
1.102 + * httpclient.getConnectionManager().shutdown();
1.103 + * }
1.104 + * </PRE>
1.105 + *
1.106 + * @since 4.0
1.107 + */
1.108 +public interface HttpClient {
1.109 +
1.110 +
1.111 + /**
1.112 + * Obtains the parameters for this client.
1.113 + * These parameters will become defaults for all requests being
1.114 + * executed with this client, and for the parameters of
1.115 + * dependent objects in this client.
1.116 + *
1.117 + * @return the default parameters
1.118 + */
1.119 + HttpParams getParams();
1.120 +
1.121 + /**
1.122 + * Obtains the connection manager used by this client.
1.123 + *
1.124 + * @return the connection manager
1.125 + */
1.126 + ClientConnectionManager getConnectionManager();
1.127 +
1.128 + /**
1.129 + * Executes a request using the default context.
1.130 + *
1.131 + * @param request the request to execute
1.132 + *
1.133 + * @return the response to the request. This is always a final response,
1.134 + * never an intermediate response with an 1xx status code.
1.135 + * Whether redirects or authentication challenges will be returned
1.136 + * or handled automatically depends on the implementation and
1.137 + * configuration of this client.
1.138 + * @throws IOException in case of a problem or the connection was aborted
1.139 + * @throws ClientProtocolException in case of an http protocol error
1.140 + */
1.141 + HttpResponse execute(HttpUriRequest request)
1.142 + throws IOException, ClientProtocolException;
1.143 +
1.144 + /**
1.145 + * Executes a request using the given context.
1.146 + * The route to the target will be determined by the HTTP client.
1.147 + *
1.148 + * @param request the request to execute
1.149 + * @param context the context to use for the execution, or
1.150 + * <code>null</code> to use the default context
1.151 + *
1.152 + * @return the response to the request. This is always a final response,
1.153 + * never an intermediate response with an 1xx status code.
1.154 + * Whether redirects or authentication challenges will be returned
1.155 + * or handled automatically depends on the implementation and
1.156 + * configuration of this client.
1.157 + * @throws IOException in case of a problem or the connection was aborted
1.158 + * @throws ClientProtocolException in case of an http protocol error
1.159 + */
1.160 + HttpResponse execute(HttpUriRequest request, HttpContext context)
1.161 + throws IOException, ClientProtocolException;
1.162 +
1.163 + /**
1.164 + * Executes a request to the target using the default context.
1.165 + *
1.166 + * @param target the target host for the request.
1.167 + * Implementations may accept <code>null</code>
1.168 + * if they can still determine a route, for example
1.169 + * to a default target or by inspecting the request.
1.170 + * @param request the request to execute
1.171 + *
1.172 + * @return the response to the request. This is always a final response,
1.173 + * never an intermediate response with an 1xx status code.
1.174 + * Whether redirects or authentication challenges will be returned
1.175 + * or handled automatically depends on the implementation and
1.176 + * configuration of this client.
1.177 + * @throws IOException in case of a problem or the connection was aborted
1.178 + * @throws ClientProtocolException in case of an http protocol error
1.179 + */
1.180 + HttpResponse execute(HttpHost target, HttpRequest request)
1.181 + throws IOException, ClientProtocolException;
1.182 +
1.183 + /**
1.184 + * Executes a request to the target using the given context.
1.185 + *
1.186 + * @param target the target host for the request.
1.187 + * Implementations may accept <code>null</code>
1.188 + * if they can still determine a route, for example
1.189 + * to a default target or by inspecting the request.
1.190 + * @param request the request to execute
1.191 + * @param context the context to use for the execution, or
1.192 + * <code>null</code> to use the default context
1.193 + *
1.194 + * @return the response to the request. This is always a final response,
1.195 + * never an intermediate response with an 1xx status code.
1.196 + * Whether redirects or authentication challenges will be returned
1.197 + * or handled automatically depends on the implementation and
1.198 + * configuration of this client.
1.199 + * @throws IOException in case of a problem or the connection was aborted
1.200 + * @throws ClientProtocolException in case of an http protocol error
1.201 + */
1.202 + HttpResponse execute(HttpHost target, HttpRequest request,
1.203 + HttpContext context)
1.204 + throws IOException, ClientProtocolException;
1.205 +
1.206 + /**
1.207 + * Executes a request using the default context and processes the
1.208 + * response using the given response handler.
1.209 + *
1.210 + * @param request the request to execute
1.211 + * @param responseHandler the response handler
1.212 + *
1.213 + * @return the response object as generated by the response handler.
1.214 + * @throws IOException in case of a problem or the connection was aborted
1.215 + * @throws ClientProtocolException in case of an http protocol error
1.216 + */
1.217 + <T> T execute(
1.218 + HttpUriRequest request,
1.219 + ResponseHandler<? extends T> responseHandler)
1.220 + throws IOException, ClientProtocolException;
1.221 +
1.222 + /**
1.223 + * Executes a request using the given context and processes the
1.224 + * response using the given response handler.
1.225 + *
1.226 + * @param request the request to execute
1.227 + * @param responseHandler the response handler
1.228 + *
1.229 + * @return the response object as generated by the response handler.
1.230 + * @throws IOException in case of a problem or the connection was aborted
1.231 + * @throws ClientProtocolException in case of an http protocol error
1.232 + */
1.233 + <T> T execute(
1.234 + HttpUriRequest request,
1.235 + ResponseHandler<? extends T> responseHandler,
1.236 + HttpContext context)
1.237 + throws IOException, ClientProtocolException;
1.238 +
1.239 + /**
1.240 + * Executes a request to the target using the default context and
1.241 + * processes the response using the given response handler.
1.242 + *
1.243 + * @param target the target host for the request.
1.244 + * Implementations may accept <code>null</code>
1.245 + * if they can still determine a route, for example
1.246 + * to a default target or by inspecting the request.
1.247 + * @param request the request to execute
1.248 + * @param responseHandler the response handler
1.249 + *
1.250 + * @return the response object as generated by the response handler.
1.251 + * @throws IOException in case of a problem or the connection was aborted
1.252 + * @throws ClientProtocolException in case of an http protocol error
1.253 + */
1.254 + <T> T execute(
1.255 + HttpHost target,
1.256 + HttpRequest request,
1.257 + ResponseHandler<? extends T> responseHandler)
1.258 + throws IOException, ClientProtocolException;
1.259 +
1.260 + /**
1.261 + * Executes a request to the target using the given context and
1.262 + * processes the response using the given response handler.
1.263 + *
1.264 + * @param target the target host for the request.
1.265 + * Implementations may accept <code>null</code>
1.266 + * if they can still determine a route, for example
1.267 + * to a default target or by inspecting the request.
1.268 + * @param request the request to execute
1.269 + * @param responseHandler the response handler
1.270 + * @param context the context to use for the execution, or
1.271 + * <code>null</code> to use the default context
1.272 + *
1.273 + * @return the response object as generated by the response handler.
1.274 + * @throws IOException in case of a problem or the connection was aborted
1.275 + * @throws ClientProtocolException in case of an http protocol error
1.276 + */
1.277 + <T> T execute(
1.278 + HttpHost target,
1.279 + HttpRequest request,
1.280 + ResponseHandler<? extends T> responseHandler,
1.281 + HttpContext context)
1.282 + throws IOException, ClientProtocolException;
1.283 +
1.284 +}
