hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject 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
Date Thu, 04 Apr 2013 09:50:04 GMT
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}}
     



Mime
View raw message