From 521aa1d566c28f78e75ce716f57caada6c314631 Mon Sep 17 00:00:00 2001
From: Simone Bordet <simone.bordet@gmail.com>
Date: Wed, 14 May 2014 09:57:48 +0200
Subject: [PATCH] Improved Javadocs.

---
 .../org/eclipse/jetty/client/HttpClient.java  | 35 +++++++++++--------
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/jetty-client/src/main/java/org/eclipse/jetty/client/HttpClient.java b/jetty-client/src/main/java/org/eclipse/jetty/client/HttpClient.java
index 8e323bc734a..31b550c9d25 100644
--- a/jetty-client/src/main/java/org/eclipse/jetty/client/HttpClient.java
+++ b/jetty-client/src/main/java/org/eclipse/jetty/client/HttpClient.java
@@ -825,6 +825,7 @@ public class HttpClient extends ContainerLifeCycle
 
     /**
      * @return whether request events must be strictly ordered
+     * @see #setStrictEventOrdering(boolean)
      */
     public boolean isStrictEventOrdering()
     {
@@ -832,26 +833,30 @@ public class HttpClient extends ContainerLifeCycle
     }
 
     /**
-     * Whether request events must be strictly ordered.
+     * Whether request/response events must be strictly ordered with respect to connection usage.
      * <p />
-     * {@link org.eclipse.jetty.client.api.Response.CompleteListener}s may send a second request.
-     * If the second request is for the same destination, there is an inherent race
-     * condition for the use of the connection: the first request may still be associated with the
-     * connection, so the second request cannot use that connection and is forced to open another one.
+     * From the point of view of connection usage, the connection can be reused just before the
+     * "complete" event notified to {@link org.eclipse.jetty.client.api.Response.CompleteListener}s
+     * (but after the "success" event).
      * <p />
-     * From the point of view of connection usage, the connection is reusable just before the "complete"
-     * event, so it would be possible to reuse that connection from {@link org.eclipse.jetty.client.api.Response.CompleteListener}s;
-     * but in this case the second request's events will fire before the "complete" events of the first
-     * request.
+     * When a request/response exchange is completing, the destination may have another request
+     * queued to be sent to the server.
+     * If the connection for that destination is reused for the second request before the "complete"
+     * event of the first exchange, it may happen that the "begin" event of the second request
+     * happens before the "complete" event of the first exchange.
      * <p />
-     * This setting enforces strict event ordering so that a "begin" event of a second request can never
-     * fire before the "complete" event of a first request, but at the expense of an increased usage
-     * of connections.
+     * Enforcing strict ordering of events so that a "begin" event of a request can never happen
+     * before the "complete" event of the previous exchange comes with the cost of increased
+     * connection usage.
+     * In case of HTTP redirects and strict event ordering, for example, the redirect request will
+     * be forced to open a new connection because it is typically sent from the complete listener
+     * when the connection cannot yet be reused.
+     * When strict event ordering is not enforced, the redirect request will reuse the already
+     * open connection making the system more efficient.
      * <p />
-     * When not enforced, a "begin" event of a second request may happen before the "complete" event of
-     * a first request and allow for better usage of connections.
+     * The default value for this property is {@code false}.
      *
-     * @param strictEventOrdering whether request events must be strictly ordered
+     * @param strictEventOrdering whether request/response events must be strictly ordered
      */
     public void setStrictEventOrdering(boolean strictEventOrdering)
     {