Apache
/
httpcomponents-client
mirror of https://github.com/apache/httpcomponents-client.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HTTPCLIENT-1336: javadoc improvements 

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1464408 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Oleg Kalnichevski 2013-04-04 09:50:04 +00:00
parent fc298adb7c
commit aaf08cec5c
3 changed files with 113 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
httpclient/src/main/java/org/apache/http/client/HttpClient.java
View File

@ -211,6 +211,12 @@ public interface HttpClient {
/**
* Executes a request using the default context and processes the
* response using the given response handler.
* <p/>
* Implementing classes are required to ensure that the content entity
* associated with the response is fully consumed and the underlying
* connection is released back to the connection manager automatically
* in all cases relieving individual {@link ResponseHandler}s from
* having to manage resource deallocation internally.
*
* @param request the request to execute
* @param responseHandler the response handler
@ -227,9 +233,17 @@ public interface HttpClient {
/**
* Executes a request using the given context and processes the
* response using the given response handler.
* <p/>
* Implementing classes are required to ensure that the content entity
* associated with the response is fully consumed and the underlying
* connection is released back to the connection manager automatically
* in all cases relieving individual {@link ResponseHandler}s from
* having to manage resource deallocation internally.
*
* @param request the request to execute
* @param responseHandler the response handler
* @param context the context to use for the execution, or
* <code>null</code> to use the default context
*
* @return the response object as generated by the response handler.
* @throws IOException in case of a problem or the connection was aborted
@ -244,6 +258,12 @@ public interface HttpClient {
/**
* Executes a request to the target using the default context and
* processes the response using the given response handler.
* <p/>
* Implementing classes are required to ensure that the content entity
* associated with the response is fully consumed and the underlying
* connection is released back to the connection manager automatically
* in all cases relieving individual {@link ResponseHandler}s from
* having to manage resource deallocation internally.
*
* @param target the target host for the request.
* Implementations may accept <code>null</code>
@ -265,6 +285,12 @@ public interface HttpClient {
/**
* Executes a request to the target using the given context and
* processes the response using the given response handler.
* <p/>
* Implementing classes are required to ensure that the content entity
* associated with the response is fully consumed and the underlying
* connection is released back to the connection manager automatically
* in all cases relieving individual {@link ResponseHandler}s from
* having to manage resource deallocation internally.
*
* @param target the target host for the request.
* Implementations may accept <code>null</code>

84
httpclient/src/main/java/org/apache/http/impl/client/CloseableHttpClient.java
View File

@ -62,6 +62,9 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable {
protected abstract CloseableHttpResponse doExecute(HttpHost target, HttpRequest request,
HttpContext context) throws IOException, ClientProtocolException;
/**
* {@inheritDoc}
*/
public CloseableHttpResponse execute(
final HttpHost target,
final HttpRequest request,
@ -69,6 +72,9 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable {
return doExecute(target, request, context);
}
/**
* {@inheritDoc}
*/
public CloseableHttpResponse execute(
final HttpUriRequest request,
final HttpContext context) throws IOException, ClientProtocolException {
@ -92,23 +98,61 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable {
return target;
}
/**
* {@inheritDoc}
*/
public CloseableHttpResponse execute(
final HttpUriRequest request) throws IOException, ClientProtocolException {
return execute(request, (HttpContext) null);
}
/**
* {@inheritDoc}
*/
public CloseableHttpResponse execute(
final HttpHost target,
final HttpRequest request) throws IOException, ClientProtocolException {
return doExecute(target, request, (HttpContext) null);
}
/**
* Executes a request using the default context and processes the
* response using the given response handler. The content entity associated
* with the response is fully consumed and the underlying connection is
* released back to the connection manager automatically in all cases
* relieving individual {@link ResponseHandler}s from having to manage
* resource deallocation internally.
*
* @param request the request to execute
* @param responseHandler the response handler
*
* @return the response object as generated by the response handler.
* @throws IOException in case of a problem or the connection was aborted
* @throws ClientProtocolException in case of an http protocol error
*/
public <T> T execute(final HttpUriRequest request,
final ResponseHandler<? extends T> responseHandler) throws IOException,
ClientProtocolException {
return execute(request, responseHandler, null);
}
/**
* Executes a request using the default context and processes the
* response using the given response handler. The content entity associated
* with the response is fully consumed and the underlying connection is
* released back to the connection manager automatically in all cases
* relieving individual {@link ResponseHandler}s from having to manage
* resource deallocation internally.
*
* @param request the request to execute
* @param responseHandler the response handler
* @param context the context to use for the execution, or
* <code>null</code> to use the default context
*
* @return the response object as generated by the response handler.
* @throws IOException in case of a problem or the connection was aborted
* @throws ClientProtocolException in case of an http protocol error
*/
public <T> T execute(final HttpUriRequest request,
final ResponseHandler<? extends T> responseHandler, final HttpContext context)
throws IOException, ClientProtocolException {
@ -116,12 +160,52 @@ public abstract class CloseableHttpClient implements HttpClient, Closeable {
return execute(target, request, responseHandler, context);
}
/**
* Executes a request using the default context and processes the
* response using the given response handler. The content entity associated
* with the response is fully consumed and the underlying connection is
* released back to the connection manager automatically in all cases
* relieving individual {@link ResponseHandler}s from having to manage
* resource deallocation internally.
*
* @param target the target host for the request.
* Implementations may accept <code>null</code>
* if they can still determine a route, for example
* to a default target or by inspecting the request.
* @param request the request to execute
* @param responseHandler the response handler
*
* @return the response object as generated by the response handler.
* @throws IOException in case of a problem or the connection was aborted
* @throws ClientProtocolException in case of an http protocol error
*/
public <T> T execute(final HttpHost target, final HttpRequest request,
final ResponseHandler<? extends T> responseHandler) throws IOException,
ClientProtocolException {
return execute(target, request, responseHandler, null);
}
/**
* Executes a request using the default context and processes the
* response using the given response handler. The content entity associated
* with the response is fully consumed and the underlying connection is
* released back to the connection manager automatically in all cases
* relieving individual {@link ResponseHandler}s from having to manage
* resource deallocation internally.
*
* @param target the target host for the request.
* Implementations may accept <code>null</code>
* if they can still determine a route, for example
* to a default target or by inspecting the request.
* @param request the request to execute
* @param responseHandler the response handler
* @param context the context to use for the execution, or
* <code>null</code> to use the default context
*
* @return the response object as generated by the response handler.
* @throws IOException in case of a problem or the connection was aborted
* @throws ClientProtocolException in case of an http protocol error
*/
public <T> T execute(final HttpHost target, final HttpRequest request,
final ResponseHandler<? extends T> responseHandler, final HttpContext context)
throws IOException, ClientProtocolException {

6
src/site/apt/examples.apt
View File

@ -35,9 +35,9 @@ HttpClient Examples
This example demonstrates how to process HTTP responses using a response handler. This is
the recommended way of executing HTTP requests and processing HTTP responses. This approach
enables the caller to concentrate on the process of digesting HTTP responses and to delegate
the task of system resource deallocation to HttpClient. The use of an HTTP response guarantees
that the underlying HTTP connection will be released back to the connection manager automatically
in all cases.
the task of system resource deallocation to HttpClient. The use of an HTTP response handler
guarantees that the underlying HTTP connection will be released back to the connection manager
automatically in all cases.
* {{{./httpclient/examples/org/apache/http/examples/client/ClientConnectionRelease.java}Manual connection release}}