Clarified semantic of Request.header().

2 files changed, 6 insertions, 0 deletions

diff --git a/jetty-client/src/main/java/org/eclipse/jetty/client/api/Request.java b/jetty-client/src/main/java/org/eclipse/jetty/client/api/Request.java
index 3e28e8e759..542d5fb53f 100644
--- a/jetty-client/src/main/java/org/eclipse/jetty/client/api/Request.java
+++ b/jetty-client/src/main/java/org/eclipse/jetty/client/api/Request.java
@@ -151,10 +151,15 @@ public interface Request
      * @param name the name of the header
      * @param value the value of the header
      * @return this request object
+     * @see #header(HttpHeader, String)
      */
     Request header(String name, String value);
 
     /**
+     * <p>Adds the given {@code value} to the specified {@code header}.</p>
+     * <p>Multiple calls with the same parameters will add multiple values;
+     * use the value {@code null} to remove the header completely.</p>
+     *
      * @param header the header name
      * @param value the value of the header
      * @return this request object
diff --git a/jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientTest.java b/jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientTest.java
index 93c98f61a4..79ab25a4f8 100644
--- a/jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientTest.java
+++ b/jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientTest.java
@@ -847,6 +847,7 @@ public class HttpClientTest extends AbstractHttpClientServerTest
 
         response = client.newRequest("localhost", connector.getLocalPort())
                 .scheme(scheme)
+                .header(HttpHeader.USER_AGENT, null)
                 .header(HttpHeader.USER_AGENT, userAgent)
                 .timeout(5, TimeUnit.SECONDS)
                 .send();