Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

jetty-9 - HTTP client: javadocs.

This commit is contained in:
Simone Bordet 2012-09-13 10:08:08 +02:00
parent c7c9c35fee
commit 312785eb7b
9 changed files with 248 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
jetty-client/src/main/java/org/eclipse/jetty/client/HttpRequest.java
View File

@ -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
public Request decoder(ContentDecoder decoder)
{
return this;
}
// @Override
// public Request decoder(ContentDecoder decoder)
// {
// return this;
// }
@Override
public Request followRedirects(boolean follow)

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

@ -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)
{

50
jetty-client/src/main/java/org/eclipse/jetty/client/package-info.java Normal file
View File

@ -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;

6
jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientAuthenticationTest.java
View File

@ -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)

2
jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientStreamTest.java
View File

@ -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)

10
jetty-client/src/test/java/org/eclipse/jetty/client/HttpClientTest.java
View File

@ -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)

8
jetty-client/src/test/java/org/eclipse/jetty/client/HttpConnectionLifecycleTest.java
View File

@ -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)

12
jetty-client/src/test/java/org/eclipse/jetty/client/HttpSenderTest.java
View File

@ -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)

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

@ -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)