From 57c323a09db57d0724e5435e5e81da02b49ef5ec Mon Sep 17 00:00:00 2001
From: Oleg Kalnichevski <olegk@apache.org>
Date: Wed, 26 Sep 2012 08:12:40 +0000
Subject: [PATCH] =?UTF-8?q?HTTPCLIENT-1235:=20Add=20javadoc=20to=20Executo?=
 =?UTF-8?q?r=20to=20explain=20that=20response=20must=20be=20handled=20to?=
 =?UTF-8?q?=20avoid=20connection=20leakage=20Contributed=20by=20Alf=20H?=
 =?UTF-8?q?=C3=B8gemark=20<alf=20at=20i100.no>?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1390314 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/http/client/fluent/Executor.java    | 14 ++++++++++++++
 .../org/apache/http/client/fluent/Response.java    |  6 ++++++
 2 files changed, 20 insertions(+)

diff --git a/fluent-hc/src/main/java/org/apache/http/client/fluent/Executor.java b/fluent-hc/src/main/java/org/apache/http/client/fluent/Executor.java
index c76bfa68d..b2cc3a6f0 100644
--- a/fluent-hc/src/main/java/org/apache/http/client/fluent/Executor.java
+++ b/fluent-hc/src/main/java/org/apache/http/client/fluent/Executor.java
@@ -58,6 +58,12 @@ import org.apache.http.impl.client.HttpClientBuilder;
 import org.apache.http.impl.conn.PoolingClientConnectionManager;
 import org.apache.http.protocol.BasicHttpContext;
 
+/**
+ * An Executor for fluent requests
+ * <p/>
+ * A {@link PoolingClientConnectionManager} with maximum 100 connections per route and
+ * a total maximum of 200 connections is used internally.
+ */
 public class Executor {
 
     final static PoolingClientConnectionManager CONNMGR;
@@ -178,6 +184,14 @@ public class Executor {
         return this;
     }
 
+    /**
+     * Executes the request. Please Note that response content must be processed 
+     * or discarded using {@link Response#discardContent()}, otherwise the
+     * connection used for the request might not be released to the pool.
+     * 
+     * @see Response#handleResponse(org.apache.http.client.ResponseHandler)
+     * @see Response#discardContent()
+     */
     public Response execute(
             final Request request) throws ClientProtocolException, IOException {
         this.localContext.setAttribute(ClientContext.CREDS_PROVIDER, this.credentialsProvider);
diff --git a/fluent-hc/src/main/java/org/apache/http/client/fluent/Response.java b/fluent-hc/src/main/java/org/apache/http/client/fluent/Response.java
index 3d7345bf6..946a6f2de 100644
--- a/fluent-hc/src/main/java/org/apache/http/client/fluent/Response.java
+++ b/fluent-hc/src/main/java/org/apache/http/client/fluent/Response.java
@@ -68,10 +68,16 @@ public class Response {
         }
     }
 
+    /**
+     * Discards response content and deallocates all resources associated with it.
+     */
     public void discardContent() {
         dispose();
     }
 
+    /**
+     * Handles the response using the specified {@link ResponseHandler}
+     */
     public <T> T handleResponse(
             final ResponseHandler<T> handler) throws ClientProtocolException, IOException {
         assertNotConsumed();