Upgraded HttpCore to version 4.1-beta2; updated HttpClient tutorial

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

httpclient-cache/src/test/java/org/apache/http/impl/client/cache/OKStatus.java

@@ -32,6 +32,8 @@
 
 public class OKStatus extends BasicStatusLine {
 
+    private static final long serialVersionUID = -1639872615816850272L;
+
     public OKStatus() {
         super(HttpVersion.HTTP_1_1, HttpStatus.SC_OK, "OK");
     }

httpclient/src/main/java/org/apache/http/conn/BasicManagedEntity.java

@@ -35,6 +35,7 @@
 
 import org.apache.http.HttpEntity;
 import org.apache.http.entity.HttpEntityWrapper;
+import org.apache.http.util.EntityUtils;
 
 /**
  * An entity that releases a {@link ManagedClientConnection connection}.
@@ -87,15 +88,14 @@ public InputStream getContent() throws IOException {
         return new EofSensorInputStream(wrappedEntity.getContent(), this);
     }
 
-    @Override
+    private void ensureConsumed() throws IOException {
-    public void consumeContent() throws IOException {
         if (managedConn == null)
             return;
 
         try {
             if (attemptReuse) {
                 // this will not trigger a callback from EofSensorInputStream
-                wrappedEntity.consumeContent();
+                EntityUtils.consume(wrappedEntity);
                 managedConn.markReusable();
             }
         } finally {
@@ -103,14 +103,20 @@ public void consumeContent() throws IOException {
         }
     }
 
+    @Deprecated
+    @Override
+    public void consumeContent() throws IOException {
+        ensureConsumed();
+    }
+
     @Override
     public void writeTo(final OutputStream outstream) throws IOException {
         super.writeTo(outstream);
-        consumeContent();
+        ensureConsumed();
     }
 
     public void releaseConnection() throws IOException {
-        this.consumeContent();
+        ensureConsumed();
     }
 
     public void abortConnection() throws IOException {

httpclient/src/main/java/org/apache/http/impl/client/DefaultRequestDirector.java

@@ -89,6 +89,7 @@
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.protocol.HttpProcessor;
 import org.apache.http.protocol.HttpRequestExecutor;
+import org.apache.http.util.EntityUtils;
 
 /**
  * Default implementation of {@link RequestDirector}.
@@ -485,9 +486,7 @@ public HttpResponse execute(HttpHost target, HttpRequest request,
                     if (reuse) {
                         // Make sure the response body is fully consumed, if present
                         HttpEntity entity = response.getEntity();
-                        if (entity != null) {
+                        EntityUtils.consume(entity);
-                            entity.consumeContent();
-                        }
                         // entity consumed above is not an auto-release entity,
                         // need to mark the connection re-usable explicitly
                         managedConn.markReusable();
@@ -875,9 +874,7 @@ protected boolean createTunnelToTarget(HttpRoute route,
                             this.log.debug("Connection kept alive");
                             // Consume response content
                             HttpEntity entity = response.getEntity();
-                            if (entity != null) {
+                            EntityUtils.consume(entity);
-                                entity.consumeContent();
-                            }
                         } else {
                             this.managedConn.close();
                         }

httpclient/src/main/java/org/apache/http/impl/client/EntityEnclosingRequestWrapper.java

@@ -89,6 +89,7 @@ class EntityWrapper extends HttpEntityWrapper {
             super(entity);
         }
 
+        @Deprecated
         @Override
         public void consumeContent() throws IOException {
             consumed = true;

httpclient/src/test/java/org/apache/http/client/protocol/TestCookie2Support.java

@@ -52,6 +52,7 @@
 import org.apache.http.protocol.ExecutionContext;
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.protocol.HttpRequestHandler;
+import org.apache.http.util.EntityUtils;
 import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Test;
@@ -98,9 +99,7 @@ public void testCookieVersionSupportHeader1() throws Exception {
 
         HttpResponse response1 = client.execute(getServerHttp(), httpget, context);
         HttpEntity e1 = response1.getEntity();
-        if (e1 != null) {
+        EntityUtils.consume(e1);
-            e1.consumeContent();
-        }
 
         List<Cookie> cookies = cookieStore.getCookies();
         Assert.assertNotNull(cookies);
@@ -108,9 +107,7 @@ public void testCookieVersionSupportHeader1() throws Exception {
 
         HttpResponse response2 = client.execute(getServerHttp(), httpget, context);
         HttpEntity e2 = response2.getEntity();
-        if (e2 != null) {
+        EntityUtils.consume(e2);
-            e2.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(ExecutionContext.HTTP_REQUEST);
 
@@ -150,9 +147,7 @@ public void testCookieVersionSupportHeader2() throws Exception {
 
         HttpResponse response1 = client.execute(getServerHttp(), httpget, context);
         HttpEntity e1 = response1.getEntity();
-        if (e1 != null) {
+        EntityUtils.consume(e1);
-            e1.consumeContent();
-        }
 
         List<Cookie> cookies = cookieStore.getCookies();
         Assert.assertNotNull(cookies);
@@ -160,9 +155,7 @@ public void testCookieVersionSupportHeader2() throws Exception {
 
         HttpResponse response2 = client.execute(getServerHttp(), httpget, context);
         HttpEntity e2 = response2.getEntity();
-        if (e2 != null) {
+        EntityUtils.consume(e2);
-            e2.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(ExecutionContext.HTTP_REQUEST);
 
@@ -201,9 +194,7 @@ public void testCookieVersionSupportHeader3() throws Exception {
 
         HttpResponse response1 = client.execute(getServerHttp(), httpget, context);
         HttpEntity e1 = response1.getEntity();
-        if (e1 != null) {
+        EntityUtils.consume(e1);
-            e1.consumeContent();
-        }
 
         List<Cookie> cookies = cookieStore.getCookies();
         Assert.assertNotNull(cookies);
@@ -211,9 +202,7 @@ public void testCookieVersionSupportHeader3() throws Exception {
 
         HttpResponse response2 = client.execute(getServerHttp(), httpget, context);
         HttpEntity e2 = response2.getEntity();
-        if (e2 != null) {
+        EntityUtils.consume(e2);
-            e2.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(ExecutionContext.HTTP_REQUEST);
 
@@ -253,9 +242,7 @@ public void testSetCookieVersionMix() throws Exception {
 
         HttpResponse response1 = client.execute(getServerHttp(), httpget, context);
         HttpEntity e1 = response1.getEntity();
-        if (e1 != null) {
+        EntityUtils.consume(e1);
-            e1.consumeContent();
-        }
 
         List<Cookie> cookies = cookieStore.getCookies();
         Assert.assertNotNull(cookies);

httpclient/src/test/java/org/apache/http/client/protocol/TestRedirects.java

@@ -32,7 +32,6 @@
 import java.util.List;
 
 import org.apache.http.Header;
-import org.apache.http.HttpEntity;
 import org.apache.http.HttpException;
 import org.apache.http.HttpHost;
 import org.apache.http.HttpRequest;
@@ -60,6 +59,7 @@
 import org.apache.http.protocol.HTTP;
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.protocol.HttpRequestHandler;
+import org.apache.http.util.EntityUtils;
 import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Test;
@@ -231,10 +231,7 @@ public void testBasicRedirect300() throws Exception {
         HttpGet httpget = new HttpGet("/oldlocation/");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -257,10 +254,7 @@ public void testBasicRedirect301() throws Exception {
         HttpGet httpget = new HttpGet("/oldlocation/");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -287,10 +281,7 @@ public void testBasicRedirect302() throws Exception {
         HttpGet httpget = new HttpGet("/oldlocation/");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -325,10 +316,7 @@ public void handle(
         HttpGet httpget = new HttpGet("/oldlocation/");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -355,10 +343,7 @@ public void testBasicRedirect303() throws Exception {
         HttpGet httpget = new HttpGet("/oldlocation/");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -385,10 +370,7 @@ public void testBasicRedirect304() throws Exception {
         HttpGet httpget = new HttpGet("/oldlocation/");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -411,10 +393,7 @@ public void testBasicRedirect305() throws Exception {
         HttpGet httpget = new HttpGet("/oldlocation/");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -437,10 +416,7 @@ public void testBasicRedirect307() throws Exception {
         HttpGet httpget = new HttpGet("/oldlocation/");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -501,10 +477,7 @@ public void testPostNoRedirect() throws Exception {
         httppost.setEntity(new StringEntity("stuff"));
 
         HttpResponse response = client.execute(getServerHttp(), httppost, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -529,10 +502,7 @@ public void testPostRedirectSeeOther() throws Exception {
         httppost.setEntity(new StringEntity("stuff"));
 
         HttpResponse response = client.execute(getServerHttp(), httppost, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -557,10 +527,7 @@ public void testRelativeRedirect() throws Exception {
         HttpGet httpget = new HttpGet("/oldlocation/");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -588,10 +555,7 @@ public void testRelativeRedirect2() throws Exception {
         HttpGet httpget = new HttpGet("/test/oldlocation");
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -678,10 +642,7 @@ public void testRedirectWithCookie() throws Exception {
 
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -714,10 +675,7 @@ public void testDefaultHeadersRedirect() throws Exception {
 
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);

httpclient/src/test/java/org/apache/http/client/protocol/TestUriEscapes.java

@@ -42,6 +42,7 @@
 import org.apache.http.localserver.LocalTestServer;
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.protocol.HttpRequestHandler;
+import org.apache.http.util.EntityUtils;
 import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Test;
@@ -89,12 +90,12 @@ private void doTest(String uri, boolean relative) throws Exception {
             String request = "http://" + host + ":" + port + uri;
             HttpGet httpget = new HttpGet(request);
             response = client.execute(httpget);
-            response.getEntity().consumeContent();
+            EntityUtils.consume(response.getEntity());
         } else {
             HttpHost target = new HttpHost(host, port);
             HttpGet httpget = new HttpGet(uri);
             response = client.execute(target, httpget);
-            response.getEntity().consumeContent();
+            EntityUtils.consume(response.getEntity());
         }
 
         Assert.assertEquals(HttpStatus.SC_OK, response.getStatusLine().getStatusCode());

httpclient/src/test/java/org/apache/http/conn/TestConnectionAutoRelease.java

@@ -87,7 +87,7 @@ public void testReleaseOnEntityConsumeContent() throws Exception {
 
         HttpEntity e = response.getEntity();
         Assert.assertNotNull(e);
-        e.consumeContent();
+        EntityUtils.consume(e);
 
         // Expect one connection in the pool
         Assert.assertEquals(1, mgr.getConnectionsInPool());

httpclient/src/test/java/org/apache/http/conn/TestConnectionReuse.java

@@ -32,7 +32,6 @@
 import java.net.URI;
 
 import org.apache.http.Header;
-import org.apache.http.HttpEntity;
 import org.apache.http.HttpException;
 import org.apache.http.HttpHost;
 import org.apache.http.HttpResponse;
@@ -59,6 +58,7 @@
 import org.apache.http.protocol.ResponseContent;
 import org.apache.http.protocol.ResponseDate;
 import org.apache.http.protocol.ResponseServer;
+import org.apache.http.util.EntityUtils;
 import org.junit.After;
 import org.junit.Assert;
 import org.junit.Test;
@@ -301,15 +301,13 @@ public void testKeepAliveHeaderRespected() throws Exception {
         HttpHost target = new HttpHost(saddress.getHostName(), saddress.getPort(), "http");
 
         HttpResponse response = client.execute(target, new HttpGet("/random/2000"));
-        if(response.getEntity() != null)
+        EntityUtils.consume(response.getEntity());
-            response.getEntity().consumeContent();
 
         Assert.assertEquals(1, mgr.getConnectionsInPool());
         Assert.assertEquals(1, localServer.getAcceptedConnectionCount());
 
         response = client.execute(target, new HttpGet("/random/2000"));
-        if(response.getEntity() != null)
+        EntityUtils.consume(response.getEntity());
-            response.getEntity().consumeContent();
 
         Assert.assertEquals(1, mgr.getConnectionsInPool());
         Assert.assertEquals(1, localServer.getAcceptedConnectionCount());
@@ -317,8 +315,7 @@ public void testKeepAliveHeaderRespected() throws Exception {
         // Now sleep for 1.1 seconds and let the timeout do its work
         Thread.sleep(1100);
         response = client.execute(target, new HttpGet("/random/2000"));
-        if(response.getEntity() != null)
+        EntityUtils.consume(response.getEntity());
-            response.getEntity().consumeContent();
 
         Assert.assertEquals(1, mgr.getConnectionsInPool());
         Assert.assertEquals(2, localServer.getAcceptedConnectionCount());
@@ -327,8 +324,7 @@ public void testKeepAliveHeaderRespected() throws Exception {
         // sure we reuse that connection.
         Thread.sleep(500);
         response = client.execute(target, new HttpGet("/random/2000"));
-        if(response.getEntity() != null)
+        EntityUtils.consume(response.getEntity());
-            response.getEntity().consumeContent();
 
         Assert.assertEquals(1, mgr.getConnectionsInPool());
         Assert.assertEquals(2, localServer.getAcceptedConnectionCount());
@@ -372,10 +368,7 @@ public void run() {
                     if (this.forceClose) {
                         httpget.abort();
                     } else {
-                        HttpEntity entity = response.getEntity();
+                        EntityUtils.consume(response.getEntity());
-                        if (entity != null) {
-                            entity.consumeContent();
-                        }
                     }
                 }
             } catch (Exception ex) {

httpclient/src/test/java/org/apache/http/impl/auth/TestNegotiateScheme.java

@@ -29,9 +29,6 @@
 import java.io.IOException;
 import java.security.Principal;
 
-import junit.framework.Assert;
-
-import org.apache.http.HttpEntity;
 import org.apache.http.HttpException;
 import org.apache.http.HttpHost;
 import org.apache.http.HttpRequest;
@@ -51,12 +48,14 @@
 import org.apache.http.params.HttpParams;
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.protocol.HttpRequestHandler;
+import org.apache.http.util.EntityUtils;
 
 import org.ietf.jgss.GSSContext;
 import org.ietf.jgss.GSSCredential;
 import org.ietf.jgss.GSSManager;
 import org.ietf.jgss.GSSName;
 import org.ietf.jgss.Oid;
+import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Test;
 
@@ -188,10 +187,7 @@ public void testDontTryToAuthenticateEndlessly() throws Exception {
         String s = "/path";
         HttpGet httpget = new HttpGet(s);
         HttpResponse response = client.execute(httpget);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         ((NegotiateSchemeFactoryWithMockGssManager)nsf).scheme.verify();
 
@@ -222,10 +218,7 @@ public void testNoTokenGeneratedError() throws Exception {
         String s = "/path";
         HttpGet httpget = new HttpGet(s);
         HttpResponse response = client.execute(httpget);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         nsf.scheme.verify();
         Assert.assertEquals(HttpStatus.SC_UNAUTHORIZED, response.getStatusLine().getStatusCode());

httpclient/src/test/java/org/apache/http/impl/client/TestClientAuthentication.java

@@ -60,6 +60,7 @@
 import org.apache.http.protocol.ResponseContent;
 import org.apache.http.protocol.ResponseDate;
 import org.apache.http.protocol.ResponseServer;
+import org.apache.http.util.EntityUtils;
 import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Test;
@@ -166,7 +167,7 @@ public void testBasicAuthenticationNoCreds() throws Exception {
         HttpEntity entity = response.getEntity();
         Assert.assertEquals(HttpStatus.SC_UNAUTHORIZED, response.getStatusLine().getStatusCode());
         Assert.assertNotNull(entity);
-        entity.consumeContent();
+        EntityUtils.consume(entity);
         AuthScope authscope = credsProvider.getAuthScope();
         Assert.assertNotNull(authscope);
         Assert.assertEquals("test realm", authscope.getRealm());
@@ -189,7 +190,7 @@ public void testBasicAuthenticationFailure() throws Exception {
         HttpEntity entity = response.getEntity();
         Assert.assertEquals(HttpStatus.SC_UNAUTHORIZED, response.getStatusLine().getStatusCode());
         Assert.assertNotNull(entity);
-        entity.consumeContent();
+        EntityUtils.consume(entity);
         AuthScope authscope = credsProvider.getAuthScope();
         Assert.assertNotNull(authscope);
         Assert.assertEquals("test realm", authscope.getRealm());
@@ -212,7 +213,7 @@ public void testBasicAuthenticationSuccess() throws Exception {
         HttpEntity entity = response.getEntity();
         Assert.assertEquals(HttpStatus.SC_OK, response.getStatusLine().getStatusCode());
         Assert.assertNotNull(entity);
-        entity.consumeContent();
+        EntityUtils.consume(entity);
         AuthScope authscope = credsProvider.getAuthScope();
         Assert.assertNotNull(authscope);
         Assert.assertEquals("test realm", authscope.getRealm());
@@ -298,7 +299,7 @@ public void testBasicAuthenticationSuccessOnRepeatablePost() throws Exception {
         HttpEntity entity = response.getEntity();
         Assert.assertEquals(HttpStatus.SC_OK, response.getStatusLine().getStatusCode());
         Assert.assertNotNull(entity);
-        entity.consumeContent();
+        EntityUtils.consume(entity);
         AuthScope authscope = credsProvider.getAuthScope();
         Assert.assertNotNull(authscope);
         Assert.assertEquals("test realm", authscope.getRealm());
@@ -384,13 +385,13 @@ public void testBasicAuthenticationCredentialsCaching() throws Exception {
         HttpEntity entity1 = response1.getEntity();
         Assert.assertEquals(HttpStatus.SC_OK, response1.getStatusLine().getStatusCode());
         Assert.assertNotNull(entity1);
-        entity1.consumeContent();
+        EntityUtils.consume(entity1);
 
         HttpResponse response2 = httpclient.execute(getServerHttp(), httpget, context);
         HttpEntity entity2 = response1.getEntity();
         Assert.assertEquals(HttpStatus.SC_OK, response2.getStatusLine().getStatusCode());
         Assert.assertNotNull(entity2);
-        entity1.consumeContent();
+        EntityUtils.consume(entity2);
 
         Assert.assertEquals(1, authHandler.getCount());
     }

httpclient/src/test/java/org/apache/http/impl/client/TestDefaultClientRequestDirector.java

@@ -34,7 +34,6 @@
 
 import org.apache.http.Header;
 import org.apache.http.HttpClientConnection;
-import org.apache.http.HttpEntity;
 import org.apache.http.HttpException;
 import org.apache.http.HttpHost;
 import org.apache.http.HttpRequest;
@@ -74,6 +73,7 @@
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.protocol.HttpRequestExecutor;
 import org.apache.http.protocol.HttpRequestHandler;
+import org.apache.http.util.EntityUtils;
 import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Test;
@@ -607,10 +607,7 @@ public void testDefaultHostAtClientLevel() throws Exception {
         HttpGet httpget = new HttpGet(s);
 
         HttpResponse response = client.execute(httpget);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
         Assert.assertEquals(HttpStatus.SC_OK, response.getStatusLine().getStatusCode());
     }
 
@@ -630,10 +627,7 @@ public void testDefaultHostAtRequestLevel() throws Exception {
         httpget.getParams().setParameter(ClientPNames.DEFAULT_HOST, target2);
 
         HttpResponse response = client.execute(httpget);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
         Assert.assertEquals(HttpStatus.SC_OK, response.getStatusLine().getStatusCode());
     }
 
@@ -717,10 +711,7 @@ public boolean retryRequest(
         HttpGet httpget = new HttpGet(s);
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);

httpclient/src/test/java/org/apache/http/impl/client/TestRequestWrapper.java

@@ -28,7 +28,6 @@
 
 import java.io.IOException;
 
-import org.apache.http.HttpEntity;
 import org.apache.http.HttpException;
 import org.apache.http.HttpRequest;
 import org.apache.http.HttpResponse;
@@ -41,6 +40,7 @@
 import org.apache.http.protocol.ExecutionContext;
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.protocol.HttpRequestHandler;
+import org.apache.http.util.EntityUtils;
 import org.junit.Assert;
 import org.junit.Before;
 import org.junit.Test;
@@ -85,10 +85,7 @@ public void testRequestURIRewriting() throws Exception {
         HttpGet httpget = new HttpGet(s);
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);
@@ -111,10 +108,7 @@ public void testRequestURIRewritingEmptyPath() throws Exception {
         HttpGet httpget = new HttpGet(s);
 
         HttpResponse response = client.execute(getServerHttp(), httpget, context);
-        HttpEntity e = response.getEntity();
+        EntityUtils.consume(response.getEntity());
-        if (e != null) {
-            e.consumeContent();
-        }
 
         HttpRequest reqWrapper = (HttpRequest) context.getAttribute(
                 ExecutionContext.HTTP_REQUEST);

httpclient/src/test/java/org/apache/http/impl/client/TestStatefulConnManagement.java

@@ -27,7 +27,6 @@
 
 import java.io.IOException;
 
-import org.apache.http.HttpEntity;
 import org.apache.http.HttpException;
 import org.apache.http.HttpHost;
 import org.apache.http.HttpRequest;
@@ -47,6 +46,7 @@
 import org.apache.http.protocol.ExecutionContext;
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.protocol.HttpRequestHandler;
+import org.apache.http.util.EntityUtils;
 import org.junit.Assert;
 import org.junit.Test;
 
@@ -185,10 +185,7 @@ public void run() {
 
                     this.context.setAttribute("r" + r, conn.getState());
 
-                    HttpEntity entity = response.getEntity();
+                    EntityUtils.consume(response.getEntity());
-                    if (entity != null) {
-                        entity.consumeContent();
-                    }
                 }
 
             } catch (Exception ex) {
@@ -229,10 +226,7 @@ public Object getUserToken(final HttpContext context) {
         context1.setAttribute("user", "stuff");
         HttpResponse response1 = client.execute(
                 new HttpHost("localhost", port), new HttpGet("/"), context1);
-        HttpEntity entity1 = response1.getEntity();
+        EntityUtils.consume(response1.getEntity());
-        if (entity1 != null) {
-            entity1.consumeContent();
-        }
 
         // The ConnPoolByRoute now has 1 free connection, out of 2 max
         // The ConnPoolByRoute has one RouteSpcfcPool, that has one free connection
@@ -245,10 +239,7 @@ public Object getUserToken(final HttpContext context) {
         HttpContext context2 = new BasicHttpContext();
         HttpResponse response2 = client.execute(
                 new HttpHost("127.0.0.1", port), new HttpGet("/"), context2);
-        HttpEntity entity2 = response2.getEntity();
+        EntityUtils.consume(response2.getEntity());
-        if (entity2 != null) {
-            entity2.consumeContent();
-        }
         // ConnPoolByRoute now has 2 free connexions, out of its 2 max.
         // The [localhost][stuff] RouteSpcfcPool is the same as earlier
         // And there is a [127.0.0.1][null] pool with 1 free connection
@@ -267,10 +258,7 @@ public Object getUserToken(final HttpContext context) {
         // If the ConnPoolByRoute did not behave coherently with the RouteSpecificPool
         // this may fail. Ex : if the ConnPool discared the route pool because it was empty,
         // but still used it to build the request3 connection.
-        HttpEntity entity3 = response3.getEntity();
+        EntityUtils.consume(response3.getEntity());
-        if (entity3 != null) {
-            entity3.consumeContent();
-        }
 
     }
 

httpclient/src/test/java/org/apache/http/impl/conn/TestIdleConnectionEviction.java

@@ -30,7 +30,6 @@
 import java.net.InetSocketAddress;
 import java.util.concurrent.TimeUnit;
 
-import org.apache.http.HttpEntity;
 import org.apache.http.HttpHost;
 import org.apache.http.HttpResponse;
 import org.apache.http.client.ClientProtocolException;
@@ -48,6 +47,7 @@
 import org.apache.http.params.BasicHttpParams;
 import org.apache.http.params.HttpConnectionParams;
 import org.apache.http.params.HttpParams;
+import org.apache.http.util.EntityUtils;
 import org.junit.Before;
 import org.junit.Test;
 
@@ -128,10 +128,7 @@ public void run() {
                         this.request.abort();
                         throw new ClientProtocolException("Unexpected status code: " + status);
                     }
-                    HttpEntity entity = response.getEntity();
+                    EntityUtils.consume(response.getEntity());
-                    if (entity != null) {
-                        entity.consumeContent();
-                    }
                     Thread.sleep(10);
                 }
             } catch (Exception ex) {

pom.xml

@@ -68,7 +68,7 @@
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
-    <httpcore.version>4.1-beta1</httpcore.version>
+    <httpcore.version>4.1-beta2</httpcore.version>
     <commons-logging.version>1.1.1</commons-logging.version>
     <commons-codec.version>1.4</commons-codec.version>
     <ehcache.version>2.2.0</ehcache.version>

src/docbkx/fundamentals.xml

@@ -296,16 +296,30 @@ important message
         </section>
         <section>
             <title>Ensuring release of low level resources</title>
-            <para>When finished with a response entity, it's important to ensure that all entity
+            <para> In order to ensure proper release of system resources one must close the content
-                content has been fully consumed, so that the connection could be safely returned to
+                stream associated with the entity.</para>
-                the connection pool and re-used by the connection manager for subsequent requests.
+            <programlisting><![CDATA[
-                The easiest way to do so is to call the
+HttpResponse response;
-                    <methodname>HttpEntity#consumeContent(</methodname>) method to consume any
+HttpEntity entity = response.getEntity();
-                available content on the stream. HttpClient will automatically release the
+if (entity != null) {
-                underlying connection back to the connection manager as soon as it detects that the
+    InputStream instream = entity.getContent();
-                end of the content stream has been reached. The
+    try {
-                    <methodname>HttpEntity#consumeContent()</methodname> method is safe to call more
+        // do something useful
-                than once.</para>
+    } finally {
+        instream.close();
+    }
+}
+]]></programlisting>
+            <para>Please note that <methodname>HttpEntity#writeTo(OutputStream)</methodname> 
+                method is also required to ensure proper release of system resources once the 
+                entity has been fully written out. If this method obtains an instance of 
+                <classname>java.io.InputStream</classname> by calling 
+                <methodname>HttpEntity#getContent()</methodname>, it is also expected to close
+                the stream in a finally clause.</para>
+            <para>When working with streaming entities, one can use the
+                <methodname>EntityUtils#consume(HttpEntity)</methodname> method to ensure that
+                the entity content has been fully consumed and the underlying stream has been
+                closed.</para>
             <para>There can be situations, however, when only a small portion of the entire response
                 content needs to be retrieved and the performance penalty for consuming the
                 remaining content and making the connection reusable is too high, one can simply