Merged branch 'jetty-10.0.x' into 'jetty-11.0.x'.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc

@@ -48,6 +48,9 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
 You first create a request object using `httpClient.newRequest(...)`, and then you customize it using the fluent API style (that is, a chained invocation of methods on the request object).
 When the request object is customized, you call `request.send()` that produces the `ContentResponse` when the request/response conversation is complete.
 
+IMPORTANT: The `Request` object, despite being mutable, cannot be reused for other requests.
+This is true also when trying to send two or more identical requests: you have to create two or more `Request` objects.
+
 Simple `POST` requests also have a shortcut method:
 
 [source,java,indent=0]

jetty-client/src/main/java/org/eclipse/jetty/client/ProxyConfiguration.java

@@ -41,10 +41,18 @@ public class ProxyConfiguration
     private final List<Proxy> proxies = new BlockingArrayQueue<>();
 
     /**
+     * <p>Returns the list of proxies added to this configuration.</p>
+     * <p>This method is deprecated because it has historically been
+     * used to add/remove proxies directly to/from the returned list,
+     * but this has now been replaced by {@link #addProxy(Proxy)} and
+     * {@link #removeProxy(Proxy)} instead.</p>
+     * <p>In the future, this method will return an unmodifiable
+     * list of proxies just for querying purposes.</p>
+     *
      * @deprecated use {@link #addProxy(Proxy)} and {@link #removeProxy(Proxy)} instead
      * @return the forward proxies to use
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated
     public List<Proxy> getProxies()
     {
         return proxies;

jetty-client/src/main/java/org/eclipse/jetty/client/api/Request.java

@@ -43,6 +43,8 @@ import org.eclipse.jetty.util.Fields;
  * <p>You can create {@link Request} objects via {@link HttpClient#newRequest(String)} and
  * you can send them using either {@link #send()} for a blocking semantic, or
  * {@link #send(Response.CompleteListener)} for an asynchronous semantic.</p>
+ * <p>{@link Request} objects cannot be reused for other requests, not even for requests
+ * that have identical URI and headers.</p>
  *
  * @see Response
  */