You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2013/04/04 11:50:04 UTC
svn commit: r1464408 - in /httpcomponents/httpclient/trunk:
httpclient/src/main/java/org/apache/http/client/HttpClient.java
httpclient/src/main/java/org/apache/http/impl/client/CloseableHttpClient.java
src/site/apt/examples.apt
Author: olegk
Date: Thu Apr 4 09:50:04 2013
New Revision: 1464408
URL: http://svn.apache.org/r1464408
Log:
HTTPCLIENT-1336: javadoc improvements
Modified:
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java
httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/CloseableHttpClient.java
httpcomponents/httpclient/trunk/src/site/apt/examples.apt
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java?rev=1464408&r1=1464407&r2=1464408&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/client/HttpClient.java Thu Apr 4 09:50:04 2013
@@ -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>
Modified: httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/CloseableHttpClient.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/CloseableHttpClient.java?rev=1464408&r1=1464407&r2=1464408&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/CloseableHttpClient.java (original)
+++ httpcomponents/httpclient/trunk/httpclient/src/main/java/org/apache/http/impl/client/CloseableHttpClient.java Thu Apr 4 09:50:04 2013
@@ -62,6 +62,9 @@ public abstract class CloseableHttpClien
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 CloseableHttpClien
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 CloseableHttpClien
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 CloseableHttpClien
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 {
Modified: httpcomponents/httpclient/trunk/src/site/apt/examples.apt
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/site/apt/examples.apt?rev=1464408&r1=1464407&r2=1464408&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/src/site/apt/examples.apt (original)
+++ httpcomponents/httpclient/trunk/src/site/apt/examples.apt Thu Apr 4 09:50:04 2013
@@ -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}}