jetty-9 - HTTP client: javadocs.

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

@@ -27,7 +27,6 @@ import java.nio.file.Path;
 import java.util.concurrent.Future;
 import java.util.concurrent.atomic.AtomicLong;
 
-import org.eclipse.jetty.client.api.ContentDecoder;
 import org.eclipse.jetty.client.api.ContentProvider;
 import org.eclipse.jetty.client.api.ContentResponse;
 import org.eclipse.jetty.client.api.Request;
@@ -199,9 +198,9 @@ public class HttpRequest implements Request
     }
 
     @Override
-    public Request agent(String userAgent)
+    public Request agent(String agent)
     {
-        headers.put(HttpHeader.USER_AGENT, userAgent);
+        headers.put(HttpHeader.USER_AGENT, agent);
         return this;
     }
 
@@ -261,11 +260,11 @@ public class HttpRequest implements Request
         return content(new PathContentProvider(file));
     }
 
-    @Override
+//    @Override
-    public Request decoder(ContentDecoder decoder)
+//    public Request decoder(ContentDecoder decoder)
-    {
+//    {
-        return this;
+//        return this;
-    }
+//    }
 
     @Override
     public Request followRedirects(boolean follow)

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

@@ -22,88 +22,252 @@ import java.io.IOException;
 import java.nio.file.Path;
 import java.util.concurrent.Future;
 
+import org.eclipse.jetty.client.HttpClient;
+import org.eclipse.jetty.client.util.StreamingResponseListener;
 import org.eclipse.jetty.http.HttpFields;
 import org.eclipse.jetty.http.HttpMethod;
 import org.eclipse.jetty.http.HttpVersion;
 import org.eclipse.jetty.util.Fields;
 
+/**
+ * <p>{@link Request} represents a HTTP request, and offers a fluent interface to customize
+ * various attributes such as the path, the headers, the content, etc.</p>
+ * <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.Listener)} for an asynchronous semantic.</p>
+ */
 public interface Request
 {
+    /**
+     * @return the conversation id
+     */
     long id();
 
+    /**
+     * @return the scheme of this request, such as "http" or "https"
+     */
     String scheme();
 
+    /**
+     * @param scheme the scheme of this request, such as "http" or "https"
+     * @return this request object
+     */
     Request scheme(String scheme);
 
+    /**
+     * @return the host of this request, such as "127.0.0.1" or "google.com"
+     */
     String host();
 
+    /**
+     * @return the port of this request such as 80 or 443
+     */
     int port();
 
+    /**
+     * @return the method of this request, such as GET or POST
+     */
     HttpMethod method();
 
+    /**
+     * @param method the method of this request, such as GET or POST
+     * @return this request object
+     */
     Request method(HttpMethod method);
 
+    /**
+     * @return the path of this request, such as "/"
+     */
     String path();
 
+    /**
+     * @param path the path of this request, such as "/"
+     * @return this request object
+     */
     Request path(String path);
 
+    /**
+     * @return the full URI of this request such as "http://host:port/path"
+     */
     String uri();
 
+    /**
+     * @return the HTTP version of this request, such as "HTTP/1.1"
+     */
     HttpVersion version();
 
+    /**
+     * @param version the HTTP version of this request, such as "HTTP/1.1"
+     * @return this request object
+     */
     Request version(HttpVersion version);
 
+    /**
+     * @return the query parameters of this request
+     */
     Fields params();
 
+    /**
+     * @param name the name of the query parameter
+     * @param value the value of the query parameter
+     * @return this request object
+     */
     Request param(String name, String value);
 
+    /**
+     * @return the headers of this request
+     */
     HttpFields headers();
 
+    /**
+     * @param name the name of the header
+     * @param value the value of the header
+     * @return this request object
+     */
     Request header(String name, String value);
 
+    /**
+     * @return the content provider of this request
+     */
     ContentProvider content();
 
-    Request content(ContentProvider buffer);
+    /**
+     * @param content the content provider of this request
+     * @return this request object
+     */
+    Request content(ContentProvider content);
 
+    /**
+     * Shortcut method to specify a file as a content for this request, with the default content type of
+     * "application/octect-stream".
+     *
+     * @param file the file to upload
+     * @return this request object
+     * @throws IOException if the file does not exist or cannot be read
+     */
     Request file(Path file) throws IOException;
 
+    /**
+     * Shortcut method to specify a file as a content for this request, with the given content type.
+     *
+     * @param file the file to upload
+     * @param contentType the content type of the file
+     * @return this request object
+     * @throws IOException if the file does not exist or cannot be read
+     */
     Request file(Path file, String contentType) throws IOException;
 
-    Request decoder(ContentDecoder decoder);
+//    Request decoder(ContentDecoder decoder);
 
+    /**
+     * @return the user agent for this request
+     */
     String agent();
 
-    Request agent(String userAgent);
+    /**
+     * @param agent the user agent for this request
+     * @return this request object
+     */
+    Request agent(String agent);
 
+    /**
+     * @return the idle timeout for this request
+     */
     long idleTimeout();
 
+    /**
+     * @param timeout the idle timeout for this request
+     * @return this request object
+     */
     Request idleTimeout(long timeout);
 
+    // TODO
     Request followRedirects(boolean follow);
 
+    /**
+     * @return the listener for request events
+     */
     Listener listener();
 
+    /**
+     * @param listener the listener for request events
+     * @return this request object
+     */
     Request listener(Listener listener);
 
+    /**
+     * Sends this request and returns a {@link Future} that can be used to wait for the
+     * request and the response to be completed (either with a success or a failure).
+     * <p />
+     * This method should be used when a simple blocking semantic is needed, and when it is known
+     * that the response content can be buffered without exceeding memory constraints.
+     * For example, this method is not appropriate to download big files from a server; consider using
+     * {@link #send(Response.Listener)} instead, passing your own {@link Response.Listener} or a utility
+     * listener such as {@link StreamingResponseListener}.
+     * <p />
+     * The future will return when {@link Response.Listener#onComplete(Result)} is invoked.
+     *
+     * @return a {@link Future} to wait on for request and response completion
+     * @see Response.Listener#onComplete(Result)
+     */
     Future<ContentResponse> send();
 
+    /**
+     * Sends this request and asynchronously notifies the given listener for response events.
+     * <p />
+     * This method should be used when the application needs to be notified of the various response events
+     * as they happen, or when the application needs to efficiently manage the response content.
+     *
+     * @param listener the listener that receives response events
+     */
     void send(Response.Listener listener);
 
+    /**
+     * Listener for request events
+     */
     public interface Listener
     {
+        /**
+         * Callback method invoked when the request is queued, waiting to be sent
+         *
+         * @param request the request being queued
+         */
         public void onQueued(Request request);
 
+        /**
+         * Callback method invoked when the request begins being processed in order to be sent.
+         * This is the last opportunity to modify the request.
+         *
+         * @param request the request that begins being processed
+         */
         public void onBegin(Request request);
 
+        /**
+         * Callback method invoked when the request headers (and perhaps small content) have been sent.
+         * The request is now committed, and in transit to the server, and further modifications to the
+         * request may have no effect.
+         * @param request the request that has been committed
+         */
         public void onHeaders(Request request);
 
-        public void onFlush(Request request, int bytes);
+        /**
-
+         * Callback method invoked when the request has been successfully sent.
+         *
+         * @param request the request sent
+         */
         public void onSuccess(Request request);
 
+        /**
+         * Callback method invoked when the request has failed to be sent
+         * @param request the request that failed
+         * @param failure the failure
+         */
         public void onFailure(Request request, Throwable failure);
 
-        public static class Adapter implements Listener
+        /**
+         * An empty implementation of {@link Listener}
+         */
+        public static class Empty implements Listener
         {
             @Override
             public void onQueued(Request request)
@@ -120,11 +284,6 @@ public interface Request
             {
             }
 
-            @Override
-            public void onFlush(Request request, int bytes)
-            {
-            }
-
             @Override
             public void onSuccess(Request request)
             {

jetty-client/src/main/java/org/eclipse/jetty/client/package-info.java

@@ -0,0 +1,50 @@
+//
+//  ========================================================================
+//  Copyright (c) 1995-2012 Mort Bay Consulting Pty. Ltd.
+//  ------------------------------------------------------------------------
+//  All rights reserved. This program and the accompanying materials
+//  are made available under the terms of the Eclipse Public License v1.0
+//  and Apache License v2.0 which accompanies this distribution.
+//
+//      The Eclipse Public License is available at
+//      http://www.eclipse.org/legal/epl-v10.html
+//
+//      The Apache License v2.0 is available at
+//      http://www.opensource.org/licenses/apache2.0.php
+//
+//  You may elect to redistribute this code under either of these licenses.
+//  ========================================================================
+//
+
+/**
+ * This package provides APIs, utility classes and implementation class of an asynchronous HTTP client
+ * <p />
+ * The core class is {@link HttpClient}, which acts as a central configuration object (for example
+ * for {@link HttpClient#setIdleTimeout(long) idle timeouts}, {@link HttpClient#setMaxConnectionsPerAddress(int)
+ * max connections per domain}, etc.) and as a factory for {@link Request} objects.
+ * <p />
+ * The HTTP protocol is based on the request/response paradigm, a unit that in this implementation is called
+ * <em>exchange</em> and is represented by {@link HttpExchange}.
+ * An initial request may trigger a sequence of exchanges with one or more servers, called a <em>conversation</em>
+ * and represented by {@link HttpConversation}. A typical example of a conversation is a redirect, where
+ * upon a request for a resource URI, the server replies with a redirect (for example with the 303 status code)
+ * to another URI. This conversation is made of a first exchange made of the original request and its 303 response,
+ * and of a second exchange made of the request for the new URI and its 200 response.
+ * <p />
+ * {@link HttpClient} holds a number of {@link HttpDestination destinations}, which in turn hold a number of
+ * pooled {@link HttpConnection connections}.
+ * <p />
+ * When a request is sent, its exchange is associated to a connection, either taken from an idle queue or created
+ * anew, and when both the request and response are completed, the exchange is disassociated from the connection.
+ * Conversation may span multiple connections on different destinations, and therefore are maintained at the
+ * {@link HttpClient} level.
+ * <p />
+ * Applications may decide to send the request and wait for the response in a blocking way, using
+ * {@link Request#send()}.
+ * Alternatively, application may ask to be notified of response events asynchronously, using
+ * {@link Request#send(Response.Listener)}.
+ */
+package org.eclipse.jetty.client;
+
+import org.eclipse.jetty.client.api.Request;
+import org.eclipse.jetty.client.api.Response;

jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientAuthenticationTest.java

@@ -101,7 +101,7 @@ public class HttpClientAuthenticationTest extends AbstractHttpClientServerTest
         AuthenticationStore authenticationStore = client.getAuthenticationStore();
 
         final AtomicInteger requests = new AtomicInteger();
-        Request.Listener.Adapter requestListener = new Request.Listener.Adapter()
+        Request.Listener.Empty requestListener = new Request.Listener.Empty()
         {
             @Override
             public void onSuccess(Request request)
@@ -122,7 +122,7 @@ public class HttpClientAuthenticationTest extends AbstractHttpClientServerTest
 
         authenticationStore.addAuthentication(authentication);
 
-        requestListener = new Request.Listener.Adapter()
+        requestListener = new Request.Listener.Empty()
         {
             @Override
             public void onSuccess(Request request)
@@ -140,7 +140,7 @@ public class HttpClientAuthenticationTest extends AbstractHttpClientServerTest
         client.getRequestListeners().remove(requestListener);
         requests.set(0);
 
-        requestListener = new Request.Listener.Adapter()
+        requestListener = new Request.Listener.Empty()
         {
             @Override
             public void onSuccess(Request request)

jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientStreamTest.java

@@ -54,7 +54,7 @@ public class HttpClientStreamTest extends AbstractHttpClientServerTest
         final AtomicLong requestTime = new AtomicLong();
         ContentResponse response = client.newRequest("localhost", connector.getLocalPort())
                 .file(upload)
-                .listener(new Request.Listener.Adapter()
+                .listener(new Request.Listener.Empty()
                 {
                     @Override
                     public void onSuccess(Request request)

jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientTest.java

@@ -219,7 +219,7 @@ public class HttpClientTest extends AbstractHttpClientServerTest
         final CountDownLatch latch = new CountDownLatch(1);
         final CountDownLatch successLatch = new CountDownLatch(2);
         client.newRequest("http://localhost:" + connector.getLocalPort())
-                .listener(new org.eclipse.jetty.client.api.Request.Listener.Adapter()
+                .listener(new org.eclipse.jetty.client.api.Request.Listener.Empty()
                 {
                     @Override
                     public void onBegin(org.eclipse.jetty.client.api.Request request)
@@ -245,7 +245,7 @@ public class HttpClientTest extends AbstractHttpClientServerTest
                 });
 
         client.newRequest("http://localhost:" + connector.getLocalPort())
-                .listener(new org.eclipse.jetty.client.api.Request.Listener.Adapter()
+                .listener(new org.eclipse.jetty.client.api.Request.Listener.Empty()
                 {
                     @Override
                     public void onQueued(org.eclipse.jetty.client.api.Request request)
@@ -278,7 +278,7 @@ public class HttpClientTest extends AbstractHttpClientServerTest
 
         final CountDownLatch latch = new CountDownLatch(3);
         client.newRequest("http://localhost:" + connector.getLocalPort())
-                .listener(new org.eclipse.jetty.client.api.Request.Listener.Adapter()
+                .listener(new org.eclipse.jetty.client.api.Request.Listener.Empty()
                 {
                     @Override
                     public void onBegin(org.eclipse.jetty.client.api.Request request)
@@ -345,7 +345,7 @@ public class HttpClientTest extends AbstractHttpClientServerTest
         final AtomicLong responseTime = new AtomicLong();
         client.newRequest("localhost", connector.getLocalPort())
                 .file(file)
-                .listener(new org.eclipse.jetty.client.api.Request.Listener.Adapter()
+                .listener(new org.eclipse.jetty.client.api.Request.Listener.Empty()
                 {
                     @Override
                     public void onSuccess(org.eclipse.jetty.client.api.Request request)
@@ -435,7 +435,7 @@ public class HttpClientTest extends AbstractHttpClientServerTest
         final String host = "localhost";
         final int port = connector.getLocalPort();
         client.newRequest(host, port)
-                .listener(new org.eclipse.jetty.client.api.Request.Listener.Adapter()
+                .listener(new org.eclipse.jetty.client.api.Request.Listener.Empty()
                 {
                     @Override
                     public void onBegin(org.eclipse.jetty.client.api.Request request)

jetty-client/src/test/java/org/eclipse/jetty/client/HttpConnectionLifecycleTest.java

@@ -58,7 +58,7 @@ public class HttpConnectionLifecycleTest extends AbstractHttpClientServerTest
         final CountDownLatch headersLatch = new CountDownLatch(1);
         final CountDownLatch successLatch = new CountDownLatch(3);
         client.newRequest(host, port)
-                .listener(new Request.Listener.Adapter()
+                .listener(new Request.Listener.Empty()
                 {
                     @Override
                     public void onSuccess(Request request)
@@ -115,7 +115,7 @@ public class HttpConnectionLifecycleTest extends AbstractHttpClientServerTest
 
         final CountDownLatch headersLatch = new CountDownLatch(1);
         final CountDownLatch failureLatch = new CountDownLatch(2);
-        client.newRequest(host, port).listener(new Request.Listener.Adapter()
+        client.newRequest(host, port).listener(new Request.Listener.Empty()
         {
             @Override
             public void onBegin(Request request)
@@ -166,7 +166,7 @@ public class HttpConnectionLifecycleTest extends AbstractHttpClientServerTest
 
         final CountDownLatch successLatch = new CountDownLatch(3);
         client.newRequest(host, port)
-                .listener(new Request.Listener.Adapter()
+                .listener(new Request.Listener.Empty()
                 {
                     @Override
                     public void onBegin(Request request)
@@ -226,7 +226,7 @@ public class HttpConnectionLifecycleTest extends AbstractHttpClientServerTest
 
         final CountDownLatch failureLatch = new CountDownLatch(2);
         client.newRequest(host, port)
-                .listener(new Request.Listener.Adapter()
+                .listener(new Request.Listener.Empty()
                 {
                     @Override
                     public void onFailure(Request request, Throwable failure)

jetty-client/src/test/java/org/eclipse/jetty/client/HttpSenderTest.java

@@ -60,7 +60,7 @@ public class HttpSenderTest
         Request request = client.newRequest(URI.create("http://localhost/"));
         final CountDownLatch headersLatch = new CountDownLatch(1);
         final CountDownLatch successLatch = new CountDownLatch(1);
-        request.listener(new Request.Listener.Adapter()
+        request.listener(new Request.Listener.Empty()
         {
             @Override
             public void onHeaders(Request request)
@@ -121,7 +121,7 @@ public class HttpSenderTest
         HttpConnection connection = new HttpConnection(client, endPoint, destination);
         Request request = client.newRequest(URI.create("http://localhost/"));
         final CountDownLatch failureLatch = new CountDownLatch(2);
-        request.listener(new Request.Listener.Adapter()
+        request.listener(new Request.Listener.Empty()
         {
             @Override
             public void onFailure(Request request, Throwable x)
@@ -150,7 +150,7 @@ public class HttpSenderTest
         HttpConnection connection = new HttpConnection(client, endPoint, destination);
         Request request = client.newRequest(URI.create("http://localhost/"));
         final CountDownLatch failureLatch = new CountDownLatch(2);
-        request.listener(new Request.Listener.Adapter()
+        request.listener(new Request.Listener.Empty()
         {
             @Override
             public void onFailure(Request request, Throwable x)
@@ -188,7 +188,7 @@ public class HttpSenderTest
         request.content(new ByteBufferContentProvider(ByteBuffer.wrap(content.getBytes("UTF-8"))));
         final CountDownLatch headersLatch = new CountDownLatch(1);
         final CountDownLatch successLatch = new CountDownLatch(1);
-        request.listener(new Request.Listener.Adapter()
+        request.listener(new Request.Listener.Empty()
         {
             @Override
             public void onHeaders(Request request)
@@ -223,7 +223,7 @@ public class HttpSenderTest
         request.content(new ByteBufferContentProvider(ByteBuffer.wrap(content1.getBytes("UTF-8")), ByteBuffer.wrap(content2.getBytes("UTF-8"))));
         final CountDownLatch headersLatch = new CountDownLatch(1);
         final CountDownLatch successLatch = new CountDownLatch(1);
-        request.listener(new Request.Listener.Adapter()
+        request.listener(new Request.Listener.Empty()
         {
             @Override
             public void onHeaders(Request request)
@@ -265,7 +265,7 @@ public class HttpSenderTest
         });
         final CountDownLatch headersLatch = new CountDownLatch(1);
         final CountDownLatch successLatch = new CountDownLatch(1);
-        request.listener(new Request.Listener.Adapter()
+        request.listener(new Request.Listener.Empty()
         {
             @Override
             public void onHeaders(Request request)

jetty-client/src/test/java/org/eclipse/jetty/client/api/Usage.java

@@ -68,7 +68,7 @@ public class Usage
                 .param("a", "b")
                 .header("X-Header", "Y-value")
                 .agent("Jetty HTTP Client")
-                .decoder(null)
+//                .decoder(null)
                 .content(null)
                 .idleTimeout(5000L);
         Future<ContentResponse> responseFuture = request.send();
@@ -102,7 +102,7 @@ public class Usage
     {
         HttpClient client = new HttpClient();
         Response response = client.newRequest("localhost", 8080)
-                .listener(new Request.Listener.Adapter()
+                .listener(new Request.Listener.Empty()
                 {
                     @Override
                     public void onSuccess(Request request)