diff --git a/README.md b/README.md index eed94ccf15..6685707ca7 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Follow [@AsyncHttpClient](https://twitter.com/AsyncHttpClient) on Twitter. The AsyncHttpClient (AHC) library allows Java applications to easily execute HTTP requests and asynchronously process HTTP responses. The library also supports the WebSocket Protocol. -It's built on top of [Netty](https://github.com/netty/netty). I's currently compiled on Java 8 but runs on Java 9 too. +It's built on top of [Netty](https://github.com/netty/netty). It's currently compiled on Java 8 but runs on Java 9 too. ## Installation @@ -159,7 +159,7 @@ See `AsyncCompletionHandler` implementation as an example. The below sample just capture the response status and skips processing the response body chunks. -Note that returning `ABORT` closed the underlying connection. +Note that returning `ABORT` closes the underlying connection. ```java import static org.asynchttpclient.Dsl.*; @@ -196,7 +196,7 @@ Integer statusCode = whenStatusCode.get(); #### Using Continuations -`ListenableFuture` has a `toCompletableFuture` that returns a `CompletableFuture`. +`ListenableFuture` has a `toCompletableFuture` method that returns a `CompletableFuture`. Beware that canceling this `CompletableFuture` won't properly cancel the ongoing request. There's a very good chance we'll return a `CompletionStage` instead in the next release. @@ -244,7 +244,7 @@ WebSocket websocket = c.prepareGet("ws://demos.kaazing.com/echo") ## Reactive Streams -AsyncHttpClient has build in support for reactive streams. +AsyncHttpClient has built-in support for reactive streams. You can pass a request body as a `Publisher` or a `ReactiveStreamsBodyGenerator`. @@ -289,7 +289,7 @@ Keep up to date on the library development by joining the Asynchronous HTTP Clie Of course, Pull Requests are welcome. -Here a the few rules we'd like you to respect if you do so: +Here are the few rules we'd like you to respect if you do so: * Only edit the code related to the suggested change, so DON'T automatically format the classes you've edited. * Use IntelliJ default formatting rules. diff --git a/client/src/main/java/org/asynchttpclient/AsyncCompletionHandler.java b/client/src/main/java/org/asynchttpclient/AsyncCompletionHandler.java index c7b60e0b4c..d1f30c1ac3 100644 --- a/client/src/main/java/org/asynchttpclient/AsyncCompletionHandler.java +++ b/client/src/main/java/org/asynchttpclient/AsyncCompletionHandler.java @@ -24,7 +24,7 @@ /** * An {@link AsyncHandler} augmented with an {@link #onCompleted(Response)} * convenience method which gets called when the {@link Response} processing is - * finished. This class also implement the {@link ProgressAsyncHandler} + * finished. This class also implements the {@link ProgressAsyncHandler} * callback, all doing nothing except returning * {@link org.asynchttpclient.AsyncHandler.State#CONTINUE} * diff --git a/client/src/main/java/org/asynchttpclient/AsyncHandler.java b/client/src/main/java/org/asynchttpclient/AsyncHandler.java index 090503cf14..a6fab9b369 100644 --- a/client/src/main/java/org/asynchttpclient/AsyncHandler.java +++ b/client/src/main/java/org/asynchttpclient/AsyncHandler.java @@ -37,9 +37,9 @@ * *
* Returning a {@link AsyncHandler.State#ABORT} from any of those callback methods will interrupt asynchronous response - * processing, after that only {@link #onCompleted()} is going to be called. + * processing. After that, only {@link #onCompleted()} is going to be called. *
- * AsyncHandler aren't thread safe, hence you should avoid re-using the same instance when doing concurrent requests. + * AsyncHandlers aren't thread safe. Hence, you should avoid re-using the same instance when doing concurrent requests. * As an example, the following may produce unexpected results: * 
  *   AsyncHandler ah = new AsyncHandler() {....};
@@ -49,9 +49,10 @@
  *
* It is recommended to create a new instance instead. *

- * Do NOT perform any blocking operation in there, typically trying to send another request and call get() on its future. + * Do NOT perform any blocking operations in any of these methods. A typical example would be trying to send another + * request and calling get() on its future. * There's a chance you might end up in a dead lock. - * If you really to perform blocking operation, executed it in a different dedicated thread pool. + * If you really need to perform a blocking operation, execute it in a different dedicated thread pool. * * @param Type of object returned by the {@link java.util.concurrent.Future#get} */ @@ -142,6 +143,8 @@ default void onHostnameResolutionSuccess(String name, List ad default void onHostnameResolutionFailure(String name, Throwable cause) { } + // ////////////// TCP CONNECT //////// + /** * Notify the callback when trying to open a new connection. *

@@ -152,8 +155,6 @@ default void onHostnameResolutionFailure(String name, Throwable cause) { default void onTcpConnectAttempt(InetSocketAddress remoteAddress) { } - // ////////////// TCP CONNECT //////// - /** * Notify the callback after a successful connect * @@ -174,14 +175,14 @@ default void onTcpConnectSuccess(InetSocketAddress remoteAddress, Channel connec default void onTcpConnectFailure(InetSocketAddress remoteAddress, Throwable cause) { } + // ////////////// TLS /////////////// + /** * Notify the callback before TLS handshake */ default void onTlsHandshakeAttempt() { } - // ////////////// TLS /////////////// - /** * Notify the callback after the TLS was successful */ @@ -196,14 +197,14 @@ default void onTlsHandshakeSuccess() { default void onTlsHandshakeFailure(Throwable cause) { } + // /////////// POOLING ///////////// + /** * Notify the callback when trying to fetch a connection from the pool. */ default void onConnectionPoolAttempt() { } - // /////////// POOLING ///////////// - /** * Notify the callback when a new connection was successfully fetched from the pool. * @@ -220,6 +221,8 @@ default void onConnectionPooled(Channel connection) { default void onConnectionOffer(Channel connection) { } + // //////////// SENDING ////////////// + /** * Notify the callback when a request is being written on the channel. If the original request causes multiple requests to be sent, for example, because of authorization or * retry, it will be notified multiple times. @@ -229,8 +232,6 @@ default void onConnectionOffer(Channel connection) { default void onRequestSend(NettyRequest request) { } - // //////////// SENDING ////////////// - /** * Notify the callback every time a request is being retried. */ diff --git a/client/src/main/java/org/asynchttpclient/AsyncHttpClient.java b/client/src/main/java/org/asynchttpclient/AsyncHttpClient.java index 1510de4513..2ab335f3f6 100755 --- a/client/src/main/java/org/asynchttpclient/AsyncHttpClient.java +++ b/client/src/main/java/org/asynchttpclient/AsyncHttpClient.java @@ -21,15 +21,15 @@ import java.util.function.Predicate; /** - * This class support asynchronous and synchronous HTTP request. + * This class support asynchronous and synchronous HTTP requests. *
- * To execute synchronous HTTP request, you just need to do + * To execute a synchronous HTTP request, you just need to do * 

  *    AsyncHttpClient c = new AsyncHttpClient();
  *    Future<Response> f = c.prepareGet(TARGET_URL).execute();
  *
*
- * The code above will block until the response is fully received. To execute asynchronous HTTP request, you + * The code above will block until the response is fully received. To execute an asynchronous HTTP request, you * create an {@link AsyncHandler} or its abstract implementation, {@link AsyncCompletionHandler} *
* 
@@ -48,7 +48,7 @@
  *      });
  *      Response response = f.get();
  *
- *      // We are just interested to retrieve the status code.
+ *      // We are just interested in retrieving the status code.
  *     Future<Integer> f = c.prepareGet(TARGET_URL).execute(new AsyncCompletionHandler<Integer>() {
  *
  *          @Override
@@ -63,10 +63,10 @@
  *      });
  *      Integer statusCode = f.get();
  *
- * The {@link AsyncCompletionHandler#onCompleted(Response)} will be invoked once the http response has been fully read, which include - * the http headers and the response body. Note that the entire response will be buffered in memory. + * The {@link AsyncCompletionHandler#onCompleted(Response)} method will be invoked once the http response has been fully read. + * The {@link Response} object includes the http headers and the response body. Note that the entire response will be buffered in memory. *
- * You can also have more control about the how the response is asynchronously processed by using a {@link AsyncHandler} + * You can also have more control about the how the response is asynchronously processed by using an {@link AsyncHandler} * 
  *      AsyncHttpClient c = new AsyncHttpClient();
  *      Future<String> f = c.prepareGet(TARGET_URL).execute(new AsyncHandler<String>() {
@@ -106,8 +106,8 @@
  *
  *      String bodyResponse = f.get();
  *
- * You can asynchronously process the response status,headers and body and decide when to - * stop the processing the response by returning a new {@link AsyncHandler.State#ABORT} at any moment. + * You can asynchronously process the response status, headers and body and decide when to + * stop processing the response by returning a new {@link AsyncHandler.State#ABORT} at any moment. * * This class can also be used without the need of {@link AsyncHandler}. *
@@ -125,8 +125,8 @@ * Response r = f.get(); * *
- * An instance of this class will cache every HTTP 1.1 connections and close them when the {@link DefaultAsyncHttpClientConfig#getReadTimeout()} - * expires. This object can hold many persistent connections to different host. + * An instance of this class will cache every HTTP 1.1 connection and close them when the {@link DefaultAsyncHttpClientConfig#getReadTimeout()} + * expires. This object can hold many persistent connections to different hosts. */ public interface AsyncHttpClient extends Closeable { @@ -138,7 +138,7 @@ public interface AsyncHttpClient extends Closeable { boolean isClosed(); /** - * Set default signature calculator to use for requests build by this client instance + * Set default signature calculator to use for requests built by this client instance * * @param signatureCalculator a signature calculator * @return {@link RequestBuilder} diff --git a/client/src/main/java/org/asynchttpclient/RequestBuilder.java b/client/src/main/java/org/asynchttpclient/RequestBuilder.java index ad0a141495..4b0d485ba4 100644 --- a/client/src/main/java/org/asynchttpclient/RequestBuilder.java +++ b/client/src/main/java/org/asynchttpclient/RequestBuilder.java @@ -18,7 +18,7 @@ import static org.asynchttpclient.util.HttpConstants.Methods.GET; /** - * Builder for a {@link Request}. Warning: mutable and not thread-safe! Beware that it holds a reference on the Request instance it builds, so modifying the builder will modify the + * Builder for a {@link Request}. Warning: mutable and not thread-safe! Beware that it holds a reference to the Request instance it builds, so modifying the builder will modify the * request even after it has been built. */ public class RequestBuilder extends RequestBuilderBase { diff --git a/client/src/main/java/org/asynchttpclient/Response.java b/client/src/main/java/org/asynchttpclient/Response.java index 51fa5ac30a..99f033e995 100644 --- a/client/src/main/java/org/asynchttpclient/Response.java +++ b/client/src/main/java/org/asynchttpclient/Response.java @@ -160,16 +160,16 @@ public interface Response { boolean hasResponseBody(); /** - * Get remote address client initiated request to. + * Get the remote address that the client initiated the request to. * - * @return remote address client initiated request to, may be {@code null} if asynchronous provider is unable to provide the remote address + * @return The remote address that the client initiated the request to. May be {@code null} if asynchronous provider is unable to provide the remote address */ SocketAddress getRemoteAddress(); /** - * Get local address client initiated request from. + * Get the local address that the client initiated the request from. * - * @return local address client initiated request from, may be {@code null} if asynchronous provider is unable to provide the local address + * @return The local address that the client initiated the request from. May be {@code null} if asynchronous provider is unable to provide the local address */ SocketAddress getLocalAddress(); diff --git a/client/src/main/java/org/asynchttpclient/SslEngineFactory.java b/client/src/main/java/org/asynchttpclient/SslEngineFactory.java index 1157e499f3..7fb25dd844 100644 --- a/client/src/main/java/org/asynchttpclient/SslEngineFactory.java +++ b/client/src/main/java/org/asynchttpclient/SslEngineFactory.java @@ -19,7 +19,7 @@ public interface SslEngineFactory { /** - * Creates new {@link SSLEngine}. + * Creates a new {@link SSLEngine}. * * @param config the client config * @param peerHost the peer hostname