svn commit: r672641 - in /httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http: client/ClientResponseHandler.java impl/client/BasicResponseHandler.java

[sb...@apache.org]

Author: sberlin
Date: Sun Jun 29 10:03:08 2008
New Revision: 672641

URL: http://svn.apache.org/viewvc?rev=672641&view=rev
Log:
expanded ClientResponseHandler javadocs

Modified:
    httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/ClientResponseHandler.java
    httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/impl/client/BasicResponseHandler.java

Modified: httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/ClientResponseHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/ClientResponseHandler.java?rev=672641&r1=672640&r2=672641&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/ClientResponseHandler.java (original)
+++ httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/client/ClientResponseHandler.java Sun Jun 29 10:03:08 2008
@@ -1,7 +1,7 @@
 /*
- * $HeadURL: $
- * $Revision: $
- * $Date: $
+ * $HeadURL$
+ * $Revision$
+ * $Date$
  *
  * ====================================================================
  *
@@ -32,6 +32,7 @@
 
 import java.io.IOException;
 
+import org.apache.http.HttpEntity;
 import org.apache.http.HttpResponse;
 
 /**
@@ -44,6 +45,21 @@
  */
 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;
     
 }

Modified: httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/impl/client/BasicResponseHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/impl/client/BasicResponseHandler.java?rev=672641&r1=672640&r2=672641&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/impl/client/BasicResponseHandler.java (original)
+++ httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/impl/client/BasicResponseHandler.java Sun Jun 29 10:03:08 2008
@@ -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.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();