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 32 package org.apache.http.client; 33 34 import java.io.IOException; 35 36 import org.apache.http.HttpHost; 37 import org.apache.http.HttpRequest; 38 import org.apache.http.HttpResponse; 39 import org.apache.http.params.HttpParams; 40 import org.apache.http.protocol.HttpContext; 41 import org.apache.http.client.methods.HttpUriRequest; 42 import 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 */ 60 public 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
