expanded ClientResponseHandler javadocs

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@672641 13f79535-47bb-0310-9956-ffa450edef68

module-client/src/main/java/org/apache/http/client/ClientResponseHandler.java

@@ -1,7 +1,7 @@
 /*
- * $HeadURL: $
- * $Revision: $
- * $Date: $
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  *
@@ -32,6 +32,7 @@ package org.apache.http.client;
 
 import java.io.IOException;
 
+import org.apache.http.HttpEntity;
 import org.apache.http.HttpResponse;
 
 /**
@@ -44,6 +45,21 @@ import org.apache.http.HttpResponse;
  */
 public interface ClientResponseHandler<T> {
 
+    /**
+     * Processes an {@link HttpResponse} and returns some value
+     * corresponding to that response.
+     * 
+     * Implementations should make an effort to ensure that the
+     * response {@link HttpEntity} is fully consumed before
+     * returning from this method or document that users
+     * must consume the entity.
+     * 
+     * @param response The response to process
+     * @return A value determined by the response
+     * 
+     * @throws ClientProtocolException in case of an http protocol error
+     * @throws IOException in case of a problem or the connection was aborted
+     */
     T handleResponse(HttpResponse response) throws ClientProtocolException, IOException;
     
 }

module-client/src/main/java/org/apache/http/impl/client/BasicResponseHandler.java

@@ -1,7 +1,7 @@
 /*
- * $HeadURL: $
- * $Revision: $
- * $Date: $
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  * Licensed to the Apache Software Foundation (ASF) under one
@@ -42,16 +42,28 @@ import org.apache.http.client.HttpResponseException;
 import org.apache.http.util.EntityUtils;
 
 /**
- * Default implementation of {@link ClientResponseHandler}.
+ * A {@link ClientResponseHandler} that returns the response body as a String
+ * for successful (2xx) responses. If the response code was >= 300, the response
+ * body is consumed and an {@link HttpResponseException} is thrown.
+ * 
+ * If this is used with
+ * {@link HttpClient#execute(org.apache.http.client.methods.HttpUriRequest, ClientResponseHandler),
+ * HttpClient may handle redirects (3xx responses) internally.
  * 
  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
- *
- * @version $Revision: $
- *
+ * 
+ * @version $Revision$
+ * 
  * @since 4.0
  */
 public class BasicResponseHandler implements ClientResponseHandler<String> {
 
+    /**
+     * Returns the response body as a String if the response was successful (a
+     * 2xx status code). If no response body exists, this returns null. If the
+     * response was unsuccessful (>= 300 status code), throws an
+     * {@link HttpResponseException}.
+     */
     public String handleResponse(
             final HttpResponse response) throws ClientProtocolException, IOException {
         HttpEntity entity = response.getEntity();