org.apache.http.impl.client
Class AbstractHttpClient

java.lang.Object
  org.apache.http.impl.client.AbstractHttpClient

All Implemented Interfaces:

HttpClient

Direct Known Subclasses:

DefaultHttpClient

@ThreadSafe
public abstract class AbstractHttpClient
extends Object
implements HttpClient

Base class for HttpClient implementations. This class acts as a facade to a number of special purpose handler or strategy implementations responsible for handling of a particular aspect of the HTTP protocol such as redirect or authentication handling or making decision about connection persistence and keep alive duration. This enables the users to selectively replace default implementation of those aspects with custom, application specific ones. This class also provides factory methods to instantiate those objects:

• HttpRequestExecutor
object used to transmit messages over HTTP connections. The createRequestExecutor() must be implemented by concrete super classes to instantiate this object.
• BasicHttpProcessor
object to manage a list of protocol interceptors and apply cross-cutting protocol logic to all incoming and outgoing HTTP messages. The createHttpProcessor() must be implemented by concrete super classes to instantiate this object.
• HttpRequestRetryHandler
object used to decide whether or not a failed HTTP request is safe to retry automatically. The createHttpRequestRetryHandler() must be implemented by concrete super classes to instantiate this object.
• ClientConnectionManager
object used to manage persistent HTTP connections.
• ConnectionReuseStrategy
object used to decide whether or not a HTTP connection can be kept alive and re-used for subsequent HTTP requests. The createConnectionReuseStrategy() must be implemented by concrete super classes to instantiate this object.
• ConnectionKeepAliveStrategy
object used to decide how long a persistent HTTP connection can be kept alive. The createConnectionKeepAliveStrategy() must be implemented by concrete super classes to instantiate this object.
• CookieSpecRegistry
object used to maintain a list of supported cookie specifications. The createCookieSpecRegistry() must be implemented by concrete super classes to instantiate this object.
• CookieStore
object used to maintain a collection of cookies. The createCookieStore() must be implemented by concrete super classes to instantiate this object.
• AuthSchemeRegistry
object used to maintain a list of supported authentication schemes. The createAuthSchemeRegistry() must be implemented by concrete super classes to instantiate this object.
• CredentialsProvider
object used to maintain a collection user credentials. The createCredentialsProvider() must be implemented by concrete super classes to instantiate this object.
• AuthenticationHandler
object used to authenticate against the target host. The createTargetAuthenticationHandler() must be implemented by concrete super classes to instantiate this object.
• AuthenticationHandler
object used to authenticate against the proxy host. The createProxyAuthenticationHandler() must be implemented by concrete super classes to instantiate this object.
• HttpRoutePlanner
object used to calculate a route for establishing a connection to the target host. The route may involve multiple intermediate hops. The createHttpRoutePlanner() must be implemented by concrete super classes to instantiate this object.
• RedirectHandler
object used to determine if an HTTP request should be redirected to a new location in response to an HTTP response received from the target server. The createRedirectHandler() must be implemented by concrete super classes to instantiate this object.
• UserTokenHandler
object used to determine if the execution context is user identity specific. The createUserTokenHandler() must be implemented by concrete super classes to instantiate this object.

This class also maintains a list of protocol interceptors intended for processing outgoing requests and incoming responses and provides methods for managing those interceptors. New protocol interceptors can be introduced to the protocol processor chain or removed from it if needed. Internally protocol interceptors are stored in a simple ArrayList. They are executed in the same natural order as they are added to the list.

AbstractHttpClient is thread safe. It is recommended that the same instance of this class is reused for multiple request executions. When an instance of DefaultHttpClient is no longer needed and is about to go out of scope the connection manager associated with it must be shut down by calling ClientConnectionManager.shutdown()!

Since:

4.0

Constructor Summary

protected

AbstractHttpClient(ClientConnectionManager conman, HttpParams params) Creates a new HTTP client.

Method Summary

void	addRequestInterceptor(HttpRequestInterceptor itcp)
void	addRequestInterceptor(HttpRequestInterceptor itcp, int index)
void	addResponseInterceptor(HttpResponseInterceptor itcp)
void	addResponseInterceptor(HttpResponseInterceptor itcp, int index)
void	clearRequestInterceptors()
void	clearResponseInterceptors()
protected abstract AuthSchemeRegistry	createAuthSchemeRegistry()
protected abstract ClientConnectionManager	createClientConnectionManager()
protected RequestDirector	createClientRequestDirector(HttpRequestExecutor requestExec, ClientConnectionManager conman, ConnectionReuseStrategy reustrat, ConnectionKeepAliveStrategy kastrat, HttpRoutePlanner rouplan, HttpProcessor httpProcessor, HttpRequestRetryHandler retryHandler, RedirectHandler redirectHandler, AuthenticationHandler targetAuthHandler, AuthenticationHandler proxyAuthHandler, UserTokenHandler stateHandler, HttpParams params)
protected abstract ConnectionKeepAliveStrategy	createConnectionKeepAliveStrategy()
protected abstract ConnectionReuseStrategy	createConnectionReuseStrategy()
protected abstract CookieSpecRegistry	createCookieSpecRegistry()
protected abstract CookieStore	createCookieStore()
protected abstract CredentialsProvider	createCredentialsProvider()
protected abstract HttpContext	createHttpContext()
protected abstract HttpParams	createHttpParams()
protected abstract BasicHttpProcessor	createHttpProcessor()
protected abstract HttpRequestRetryHandler	createHttpRequestRetryHandler()
protected abstract HttpRoutePlanner	createHttpRoutePlanner()
protected abstract AuthenticationHandler	createProxyAuthenticationHandler()
protected abstract RedirectHandler	createRedirectHandler()
protected abstract HttpRequestExecutor	createRequestExecutor()
protected abstract AuthenticationHandler	createTargetAuthenticationHandler()
protected abstract UserTokenHandler	createUserTokenHandler()
protected HttpParams	determineParams(HttpRequest req) Obtains parameters for executing a request.
HttpResponse	execute(HttpHost target, HttpRequest request) Executes a request to the target using the default context.
HttpResponse	execute(HttpHost target, HttpRequest request, HttpContext context) Executes a request to the target using the given context.
<T> T	execute(HttpHost target, HttpRequest request, ResponseHandler<? extends T> responseHandler) Executes a request to the target using the default context and processes the response using the given response handler.
<T> T	execute(HttpHost target, HttpRequest request, ResponseHandler<? extends T> responseHandler, HttpContext context) Executes a request to the target using the given context and processes the response using the given response handler.
HttpResponse	execute(HttpUriRequest request) Executes a request using the default context.
HttpResponse	execute(HttpUriRequest request, HttpContext context) Maps to execute(target, request, context).
<T> T	execute(HttpUriRequest request, ResponseHandler<? extends T> responseHandler) Executes a request using the default context and processes the response using the given response handler.
<T> T	execute(HttpUriRequest request, ResponseHandler<? extends T> responseHandler, HttpContext context) Executes a request using the given context and processes the response using the given response handler.
AuthSchemeRegistry	getAuthSchemes()
ConnectionKeepAliveStrategy	getConnectionKeepAliveStrategy()
ClientConnectionManager	getConnectionManager() Obtains the connection manager used by this client.
ConnectionReuseStrategy	getConnectionReuseStrategy()
CookieSpecRegistry	getCookieSpecs()
CookieStore	getCookieStore()
CredentialsProvider	getCredentialsProvider()
protected BasicHttpProcessor	getHttpProcessor()
HttpRequestRetryHandler	getHttpRequestRetryHandler()
HttpParams	getParams() Obtains the parameters for this client.
AuthenticationHandler	getProxyAuthenticationHandler()
RedirectHandler	getRedirectHandler()
HttpRequestExecutor	getRequestExecutor()
HttpRequestInterceptor	getRequestInterceptor(int index)
int	getRequestInterceptorCount()
HttpResponseInterceptor	getResponseInterceptor(int index)
int	getResponseInterceptorCount()
HttpRoutePlanner	getRoutePlanner()
AuthenticationHandler	getTargetAuthenticationHandler()
UserTokenHandler	getUserTokenHandler()
void	removeRequestInterceptorByClass(Class<? extends HttpRequestInterceptor> clazz)
void	removeResponseInterceptorByClass(Class<? extends HttpResponseInterceptor> clazz)
void	setAuthSchemes(AuthSchemeRegistry authSchemeRegistry)
void	setCookieSpecs(CookieSpecRegistry cookieSpecRegistry)
void	setCookieStore(CookieStore cookieStore)
void	setCredentialsProvider(CredentialsProvider credsProvider)
void	setHttpRequestRetryHandler(HttpRequestRetryHandler retryHandler)
void	setKeepAliveStrategy(ConnectionKeepAliveStrategy keepAliveStrategy)
void	setParams(HttpParams params) Replaces the parameters.
void	setProxyAuthenticationHandler(AuthenticationHandler proxyAuthHandler)
void	setRedirectHandler(RedirectHandler redirectHandler)
void	setReuseStrategy(ConnectionReuseStrategy reuseStrategy)
void	setRoutePlanner(HttpRoutePlanner routePlanner)
void	setTargetAuthenticationHandler(AuthenticationHandler targetAuthHandler)
void	setUserTokenHandler(UserTokenHandler userTokenHandler)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractHttpClient

protected AbstractHttpClient(ClientConnectionManager conman,
                             HttpParams params)

Creates a new HTTP client.

Parameters:

conman - the connection manager

params - the parameters

Method Detail

createHttpParams

protected abstract HttpParams createHttpParams()

createHttpContext

protected abstract HttpContext createHttpContext()

createRequestExecutor

protected abstract HttpRequestExecutor createRequestExecutor()

createClientConnectionManager

protected abstract ClientConnectionManager createClientConnectionManager()

createAuthSchemeRegistry

protected abstract AuthSchemeRegistry createAuthSchemeRegistry()

createCookieSpecRegistry

protected abstract CookieSpecRegistry createCookieSpecRegistry()

createConnectionReuseStrategy

protected abstract ConnectionReuseStrategy createConnectionReuseStrategy()

createConnectionKeepAliveStrategy

protected abstract ConnectionKeepAliveStrategy createConnectionKeepAliveStrategy()

createHttpProcessor

protected abstract BasicHttpProcessor createHttpProcessor()

createHttpRequestRetryHandler

protected abstract HttpRequestRetryHandler createHttpRequestRetryHandler()

createRedirectHandler

protected abstract RedirectHandler createRedirectHandler()

createTargetAuthenticationHandler

protected abstract AuthenticationHandler createTargetAuthenticationHandler()

createProxyAuthenticationHandler

protected abstract AuthenticationHandler createProxyAuthenticationHandler()

createCookieStore

protected abstract CookieStore createCookieStore()

createCredentialsProvider

protected abstract CredentialsProvider createCredentialsProvider()

createHttpRoutePlanner

protected abstract HttpRoutePlanner createHttpRoutePlanner()

createUserTokenHandler

protected abstract UserTokenHandler createUserTokenHandler()

getParams

public final HttpParams getParams()

Description copied from interface: HttpClient

Obtains the parameters for this client. These parameters will become defaults for all requests being executed with this client, and for the parameters of dependent objects in this client.

Specified by:

getParams in interface HttpClient

Returns:

the default parameters

setParams

public void setParams(HttpParams params)

Replaces the parameters. The implementation here does not update parameters of dependent objects.

Parameters:

params - the new default parameters

getConnectionManager

public final ClientConnectionManager getConnectionManager()

Description copied from interface: HttpClient

Obtains the connection manager used by this client.

Specified by:

getConnectionManager in interface HttpClient

Returns:

the connection manager

getRequestExecutor

public final HttpRequestExecutor getRequestExecutor()

getAuthSchemes

public final AuthSchemeRegistry getAuthSchemes()

setAuthSchemes

public void setAuthSchemes(AuthSchemeRegistry authSchemeRegistry)

getCookieSpecs

public final CookieSpecRegistry getCookieSpecs()

setCookieSpecs

public void setCookieSpecs(CookieSpecRegistry cookieSpecRegistry)

getConnectionReuseStrategy

public final ConnectionReuseStrategy getConnectionReuseStrategy()

setReuseStrategy

public void setReuseStrategy(ConnectionReuseStrategy reuseStrategy)

getConnectionKeepAliveStrategy

public final ConnectionKeepAliveStrategy getConnectionKeepAliveStrategy()

setKeepAliveStrategy

public void setKeepAliveStrategy(ConnectionKeepAliveStrategy keepAliveStrategy)

getHttpRequestRetryHandler

public final HttpRequestRetryHandler getHttpRequestRetryHandler()

setHttpRequestRetryHandler

public void setHttpRequestRetryHandler(HttpRequestRetryHandler retryHandler)

getRedirectHandler

public final RedirectHandler getRedirectHandler()

setRedirectHandler

public void setRedirectHandler(RedirectHandler redirectHandler)

getTargetAuthenticationHandler

public final AuthenticationHandler getTargetAuthenticationHandler()

setTargetAuthenticationHandler

public void setTargetAuthenticationHandler(AuthenticationHandler targetAuthHandler)

getProxyAuthenticationHandler

public final AuthenticationHandler getProxyAuthenticationHandler()

setProxyAuthenticationHandler

public void setProxyAuthenticationHandler(AuthenticationHandler proxyAuthHandler)

getCookieStore

public final CookieStore getCookieStore()

setCookieStore

public void setCookieStore(CookieStore cookieStore)

getCredentialsProvider

public final CredentialsProvider getCredentialsProvider()

setCredentialsProvider

public void setCredentialsProvider(CredentialsProvider credsProvider)

getRoutePlanner

public final HttpRoutePlanner getRoutePlanner()

setRoutePlanner

public void setRoutePlanner(HttpRoutePlanner routePlanner)

getUserTokenHandler

public final UserTokenHandler getUserTokenHandler()

setUserTokenHandler

public void setUserTokenHandler(UserTokenHandler userTokenHandler)

getHttpProcessor

protected final BasicHttpProcessor getHttpProcessor()

addResponseInterceptor

public void addResponseInterceptor(HttpResponseInterceptor itcp)

addResponseInterceptor

public void addResponseInterceptor(HttpResponseInterceptor itcp,
                                   int index)

getResponseInterceptor

public HttpResponseInterceptor getResponseInterceptor(int index)

getResponseInterceptorCount

public int getResponseInterceptorCount()

clearResponseInterceptors

public void clearResponseInterceptors()

removeResponseInterceptorByClass

public void removeResponseInterceptorByClass(Class<? extends HttpResponseInterceptor> clazz)

addRequestInterceptor

public void addRequestInterceptor(HttpRequestInterceptor itcp)

addRequestInterceptor

public void addRequestInterceptor(HttpRequestInterceptor itcp,
                                  int index)

getRequestInterceptor

public HttpRequestInterceptor getRequestInterceptor(int index)

getRequestInterceptorCount

public int getRequestInterceptorCount()

clearRequestInterceptors

public void clearRequestInterceptors()

removeRequestInterceptorByClass

public void removeRequestInterceptorByClass(Class<? extends HttpRequestInterceptor> clazz)

execute

public final HttpResponse execute(HttpUriRequest request)
                           throws IOException,
                                  ClientProtocolException

Description copied from interface: HttpClient

Executes a request using the default context.

Specified by:

execute in interface HttpClient

Parameters:

request - the request to execute

Returns:

the response to the request. This is always a final response, never an intermediate response with an 1xx status code. Whether redirects or authentication challenges will be returned or handled automatically depends on the implementation and configuration of this client.

Throws:

IOException - in case of a problem or the connection was aborted

ClientProtocolException - in case of an http protocol error

execute

public final HttpResponse execute(HttpUriRequest request,
                                  HttpContext context)
                           throws IOException,
                                  ClientProtocolException

Maps to execute(target, request, context). The target is determined from the URI of the request.

Specified by:

execute in interface HttpClient

Parameters:

request - the request to execute

context - the request-specific execution context, or null to use a default context

Returns:

the response to the request. This is always a final response, never an intermediate response with an 1xx status code. Whether redirects or authentication challenges will be returned or handled automatically depends on the implementation and configuration of this client.

Throws:

IOException - in case of a problem or the connection was aborted

ClientProtocolException - in case of an http protocol error

execute

public final HttpResponse execute(HttpHost target,
                                  HttpRequest request)
                           throws IOException,
                                  ClientProtocolException

Description copied from interface: HttpClient

Executes a request to the target using the default context.

Specified by:

execute in interface HttpClient

Parameters:

target - the target host for the request. Implementations may accept null if they can still determine a route, for example to a default target or by inspecting the request.

request - the request to execute

Returns:

the response to the request. This is always a final response, never an intermediate response with an 1xx status code. Whether redirects or authentication challenges will be returned or handled automatically depends on the implementation and configuration of this client.

Throws:

IOException - in case of a problem or the connection was aborted

ClientProtocolException - in case of an http protocol error

execute

public final HttpResponse execute(HttpHost target,
                                  HttpRequest request,
                                  HttpContext context)
                           throws IOException,
                                  ClientProtocolException

Description copied from interface: HttpClient

Executes a request to the target using the given context.

Specified by:

execute in interface HttpClient

Parameters:

target - the target host for the request. Implementations may accept null if they can still determine a route, for example to a default target or by inspecting the request.

request - the request to execute

context - the context to use for the execution, or null to use the default context

Returns:

the response to the request. This is always a final response, never an intermediate response with an 1xx status code. Whether redirects or authentication challenges will be returned or handled automatically depends on the implementation and configuration of this client.

Throws:

IOException - in case of a problem or the connection was aborted

ClientProtocolException - in case of an http protocol error

createClientRequestDirector

protected RequestDirector createClientRequestDirector(HttpRequestExecutor requestExec,
                                                      ClientConnectionManager conman,
                                                      ConnectionReuseStrategy reustrat,
                                                      ConnectionKeepAliveStrategy kastrat,
                                                      HttpRoutePlanner rouplan,
                                                      HttpProcessor httpProcessor,
                                                      HttpRequestRetryHandler retryHandler,
                                                      RedirectHandler redirectHandler,
                                                      AuthenticationHandler targetAuthHandler,
                                                      AuthenticationHandler proxyAuthHandler,
                                                      UserTokenHandler stateHandler,
                                                      HttpParams params)

determineParams

protected HttpParams determineParams(HttpRequest req)

Obtains parameters for executing a request. The default implementation in this class creates a new ClientParamsStack from the request parameters and the client parameters.
This method is called by the default implementation of execute(HttpHost,HttpRequest,HttpContext) to obtain the parameters for the DefaultRequestDirector.

Parameters:

req - the request that will be executed

Returns:

the parameters to use

execute

public <T> T execute(HttpUriRequest request,
                     ResponseHandler<? extends T> responseHandler)
          throws IOException,
                 ClientProtocolException

Description copied from interface: HttpClient

Executes a request using the default context and processes the response using the given response handler.

Specified by:

execute in interface HttpClient

Parameters:

request - the request to execute

responseHandler - the response handler

Returns:

the response object as generated by the response handler.

Throws:

IOException - in case of a problem or the connection was aborted

ClientProtocolException - in case of an http protocol error

execute

public <T> T execute(HttpUriRequest request,
                     ResponseHandler<? extends T> responseHandler,
                     HttpContext context)
          throws IOException,
                 ClientProtocolException

Description copied from interface: HttpClient

Executes a request using the given context and processes the response using the given response handler.

Specified by:

execute in interface HttpClient

Parameters:

request - the request to execute

responseHandler - the response handler

Returns:

the response object as generated by the response handler.

Throws:

IOException - in case of a problem or the connection was aborted

ClientProtocolException - in case of an http protocol error

execute

public <T> T execute(HttpHost target,
                     HttpRequest request,
                     ResponseHandler<? extends T> responseHandler)
          throws IOException,
                 ClientProtocolException

Description copied from interface: HttpClient

Executes a request to the target using the default context and processes the response using the given response handler.

Specified by:

execute in interface HttpClient

Parameters:

target - the target host for the request. Implementations may accept null if they can still determine a route, for example to a default target or by inspecting the request.

request - the request to execute

responseHandler - the response handler

Returns:

the response object as generated by the response handler.

Throws:

IOException - in case of a problem or the connection was aborted

ClientProtocolException - in case of an http protocol error

execute

public <T> T execute(HttpHost target,
                     HttpRequest request,
                     ResponseHandler<? extends T> responseHandler,
                     HttpContext context)
          throws IOException,
                 ClientProtocolException

Description copied from interface: HttpClient

Executes a request to the target using the given context and processes the response using the given response handler.

Specified by:

execute in interface HttpClient

Parameters:

target - the target host for the request. Implementations may accept null if they can still determine a route, for example to a default target or by inspecting the request.

request - the request to execute

responseHandler - the response handler

context - the context to use for the execution, or null to use the default context

Returns:

the response object as generated by the response handler.

Throws:

IOException - in case of a problem or the connection was aborted

ClientProtocolException - in case of an http protocol error