001/* 002 * ==================================================================== 003 * Licensed to the Apache Software Foundation (ASF) under one 004 * or more contributor license agreements. See the NOTICE file 005 * distributed with this work for additional information 006 * regarding copyright ownership. The ASF licenses this file 007 * to you under the Apache License, Version 2.0 (the 008 * "License"); you may not use this file except in compliance 009 * with the License. You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, 014 * software distributed under the License is distributed on an 015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 016 * KIND, either express or implied. See the License for the 017 * specific language governing permissions and limitations 018 * under the License. 019 * ==================================================================== 020 * 021 * This software consists of voluntary contributions made by many 022 * individuals on behalf of the Apache Software Foundation. For more 023 * information on the Apache Software Foundation, please see 024 * <http://www.apache.org/>. 025 * 026 */ 027 028package org.apache.http.client; 029 030import org.apache.http.HttpHost; 031import org.apache.http.HttpRequest; 032import org.apache.http.HttpResponse; 033import org.apache.http.client.methods.HttpUriRequest; 034import org.apache.http.conn.ClientConnectionManager; 035import org.apache.http.params.HttpParams; 036import org.apache.http.protocol.HttpContext; 037 038import java.io.IOException; 039 040/** 041 * This interface represents only the most basic contract for HTTP request 042 * execution. It imposes no restrictions or particular details on the request 043 * execution process and leaves the specifics of state management, 044 * authentication and redirect handling up to individual implementations. 045 * 046 * @since 4.0 047 */ 048@SuppressWarnings("deprecation") 049public interface HttpClient { 050 051 052 /** 053 * Obtains the parameters for this client. 054 * These parameters will become defaults for all requests being 055 * executed with this client, and for the parameters of 056 * dependent objects in this client. 057 * 058 * @return the default parameters 059 * 060 * @deprecated (4.3) use 061 * {@link org.apache.http.client.config.RequestConfig}. 062 */ 063 @Deprecated 064 HttpParams getParams(); 065 066 /** 067 * Obtains the connection manager used by this client. 068 * 069 * @return the connection manager 070 * 071 * @deprecated (4.3) use 072 * {@link org.apache.http.impl.client.HttpClientBuilder}. 073 */ 074 @Deprecated 075 ClientConnectionManager getConnectionManager(); 076 077 /** 078 * Executes HTTP request using the default context. 079 * 080 * @param request the request to execute 081 * 082 * @return the response to the request. This is always a final response, 083 * never an intermediate response with an 1xx status code. 084 * Whether redirects or authentication challenges will be returned 085 * or handled automatically depends on the implementation and 086 * configuration of this client. 087 * @throws IOException in case of a problem or the connection was aborted 088 * @throws ClientProtocolException in case of an http protocol error 089 */ 090 HttpResponse execute(HttpUriRequest request) 091 throws IOException, ClientProtocolException; 092 093 /** 094 * Executes HTTP request using the given context. 095 * 096 * @param request the request to execute 097 * @param context the context to use for the execution, or 098 * {@code null} to use the default context 099 * 100 * @return the response to the request. This is always a final response, 101 * never an intermediate response with an 1xx status code. 102 * Whether redirects or authentication challenges will be returned 103 * or handled automatically depends on the implementation and 104 * configuration of this client. 105 * @throws IOException in case of a problem or the connection was aborted 106 * @throws ClientProtocolException in case of an http protocol error 107 */ 108 HttpResponse execute(HttpUriRequest request, HttpContext context) 109 throws IOException, ClientProtocolException; 110 111 /** 112 * Executes HTTP request using the default context. 113 * 114 * @param target the target host for the request. 115 * Implementations may accept {@code null} 116 * if they can still determine a route, for example 117 * to a default target or by inspecting the request. 118 * @param request the request to execute 119 * 120 * @return the response to the request. This is always a final response, 121 * never an intermediate response with an 1xx status code. 122 * Whether redirects or authentication challenges will be returned 123 * or handled automatically depends on the implementation and 124 * configuration of this client. 125 * @throws IOException in case of a problem or the connection was aborted 126 * @throws ClientProtocolException in case of an http protocol error 127 */ 128 HttpResponse execute(HttpHost target, HttpRequest request) 129 throws IOException, ClientProtocolException; 130 131 /** 132 * Executes HTTP request using the given context. 133 * 134 * @param target the target host for the request. 135 * Implementations may accept {@code null} 136 * if they can still determine a route, for example 137 * to a default target or by inspecting the request. 138 * @param request the request to execute 139 * @param context the context to use for the execution, or 140 * {@code null} to use the default context 141 * 142 * @return the response to the request. This is always a final response, 143 * never an intermediate response with an 1xx status code. 144 * Whether redirects or authentication challenges will be returned 145 * or handled automatically depends on the implementation and 146 * configuration of this client. 147 * @throws IOException in case of a problem or the connection was aborted 148 * @throws ClientProtocolException in case of an http protocol error 149 */ 150 HttpResponse execute(HttpHost target, HttpRequest request, 151 HttpContext context) 152 throws IOException, ClientProtocolException; 153 154 /** 155 * Executes HTTP request using the default context and processes the 156 * response using the given response handler. 157 * <p> 158 * Implementing classes are required to ensure that the content entity 159 * associated with the response is fully consumed and the underlying 160 * connection is released back to the connection manager automatically 161 * in all cases relieving individual {@link ResponseHandler}s from 162 * having to manage resource deallocation internally. 163 * </p> 164 * 165 * @param request the request to execute 166 * @param responseHandler the response handler 167 * 168 * @return the response object as generated by the response handler. 169 * @throws IOException in case of a problem or the connection was aborted 170 * @throws ClientProtocolException in case of an http protocol error 171 */ 172 <T> T execute( 173 HttpUriRequest request, 174 ResponseHandler<? extends T> responseHandler) 175 throws IOException, ClientProtocolException; 176 177 /** 178 * Executes HTTP request using the given context and processes the 179 * response using the given response handler. 180 * <p> 181 * Implementing classes are required to ensure that the content entity 182 * associated with the response is fully consumed and the underlying 183 * connection is released back to the connection manager automatically 184 * in all cases relieving individual {@link ResponseHandler}s from 185 * having to manage resource deallocation internally. 186 * </p> 187 * 188 * @param request the request to execute 189 * @param responseHandler the response handler 190 * @param context the context to use for the execution, or 191 * {@code null} to use the default context 192 * 193 * @return the response object as generated by the response handler. 194 * @throws IOException in case of a problem or the connection was aborted 195 * @throws ClientProtocolException in case of an http protocol error 196 */ 197 <T> T execute( 198 HttpUriRequest request, 199 ResponseHandler<? extends T> responseHandler, 200 HttpContext context) 201 throws IOException, ClientProtocolException; 202 203 /** 204 * Executes HTTP request to the target using the default context and 205 * processes the 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}s from 211 * having to manage resource deallocation internally. 212 * </p> 213 * 214 * @param target the target host for the request. 215 * Implementations may accept {@code null} 216 * if they can still determine a route, for example 217 * to a default target or by inspecting the request. 218 * @param request the request to execute 219 * @param responseHandler the response handler 220 * 221 * @return the response object as generated by the response handler. 222 * @throws IOException in case of a problem or the connection was aborted 223 * @throws ClientProtocolException in case of an http protocol error 224 */ 225 <T> T execute( 226 HttpHost target, 227 HttpRequest request, 228 ResponseHandler<? extends T> responseHandler) 229 throws IOException, ClientProtocolException; 230 231 /** 232 * Executes HTTP request to the target using the given context and 233 * processes the response using the given response handler. 234 * <p> 235 * Implementing classes are required to ensure that the content entity 236 * associated with the response is fully consumed and the underlying 237 * connection is released back to the connection manager automatically 238 * in all cases relieving individual {@link ResponseHandler}s from 239 * having to manage resource deallocation internally. 240 * </p> 241 * 242 * @param target the target host for the request. 243 * Implementations may accept {@code null} 244 * if they can still determine a route, for example 245 * to a default target or by inspecting the request. 246 * @param request the request to execute 247 * @param responseHandler the response handler 248 * @param context the context to use for the execution, or 249 * {@code null} to use the default context 250 * 251 * @return the response object as generated by the response handler. 252 * @throws IOException in case of a problem or the connection was aborted 253 * @throws ClientProtocolException in case of an http protocol error 254 */ 255 <T> T execute( 256 HttpHost target, 257 HttpRequest request, 258 ResponseHandler<? extends T> responseHandler, 259 HttpContext context) 260 throws IOException, ClientProtocolException; 261 262}