Merge remote-tracking branch 'upstream/master'

Author: Oleksandr Kylymnychenko

README.md

@@ -10,15 +10,15 @@ Async Http Client library purpose is to allow Java applications to easily execut
 <dependency>
   <groupId>com.ning</groupId>
   <artifactId>async-http-client</artifactId>
-  <version>1.7.16</version>
+  <version>1.8.13</version>
 </dependency>
 ```
 
 You can also download the artifact
 
 [Maven Search](http://search.maven.org)
 
-Then in your code you can simply do ([Javadoc](http://sonatype.github.com/async-http-client/apidocs/index.html))
+Then in your code you can simply do [Javadoc](http://asynchttpclient.github.io/async-http-client/apidocs/reference/packages.html)
 
 ```java
 import com.ning.http.client.*;
@@ -133,14 +133,18 @@ Future<String> f = c.prepareGet("http://www.ning.com/").execute(new AsyncHandler
 String bodyResponse = f.get();
 ```
 
-Finally, you can also configure the AsyncHttpClient via it's AsyncHttpClientConfig object:
+## Configuration
+
+Finally, you can also configure the AsyncHttpClient via its AsyncHttpClientConfig object:
 
 ```java
 AsyncHttpClientConfig cf = new AsyncHttpClientConfig.Builder()
     S.setProxyServer(new ProxyServer("127.0.0.1", 38080)).build();
 AsyncHttpClient c = new AsyncHttpClient(cf);
 ```
 
+## WebSocket
+
 Async Http Client also support WebSocket by simply doing:
 
 ```java
@@ -154,7 +158,7 @@ WebSocket websocket = c.prepareGet(getTargetUrl())
 
           @Override
           public void onOpen(WebSocket websocket) {
-              websocket.sendTextMessage("...").sendBinaryMessage("...");
+              websocket.sendTextMessage("...").sendMessage("...");
           }
 
           @Override
@@ -175,10 +179,29 @@ AsyncHttpClientConfig config = new AsyncHttpClientConfig.Builder().build();
 AsyncHttpClient client = new AsyncHttpClient(new GrizzlyAsyncHttpProvider(config), config);
 ```
 
+## User Group
+
 Keep up to date on the library development by joining the Asynchronous HTTP Client discussion group
 
 [Google Group](http://groups.google.com/group/asynchttpclient)
 
 or follow us on [Twitter](http://twitter.com/jfarcand)
 
 [![githalytics.com alpha](https://cruel-carlota.pagodabox.com/6433679063b2351599c6ca44a08246a2 "githalytics.com")](http://githalytics.com/AsyncHttpClient/async-http-client)
+
+## Contributing
+
+Of course, Pull Requests are welcome.
+
+Here a 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.
+* Respect the formatting rules:
+  * Ident with 4 spaces
+  * Use a 140 chars line max length
+  * Don't use * imports
+  * Stick to the org, com, javax, java imports order
+* Your PR can contain multiple commits when submitting, but once it's been reviewed, we'll ask you to squash them into a single one
+* Regarding licensing:
+  * You must be the original author of the code you suggest.
+  * If not, you have to prove that the original code was published under Apache License 2 and properly mention original copyrights.

api/pom.xml

@@ -31,10 +31,15 @@
     </build>
 
     <dependencies>
+        <dependency>
+            <groupId>com.typesafe</groupId>
+            <artifactId>config</artifactId>
+            <version>1.2.1</version>
+        </dependency>
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-api</artifactId>
-            <version>1.7.5</version>
+            <version>1.7.6</version>
         </dependency>
     </dependencies>
 

api/src/main/java/org/asynchttpclient/AsyncCompletionHandler.java

@@ -105,7 +105,7 @@ public STATE onContentWriteCompleted() {
     /**
      * Invoked when the I/O operation associated with the {@link Request} body as been progressed.
      *
-     * @param amount  The amount of bytes to transfer.
+     * @param amount  The amount of bytes to transfer
      * @param current The amount of bytes transferred
      * @param total   The total number of bytes transferred
      * @return a {@link org.asynchttpclient.AsyncHandler.STATE} telling to CONTINUE or ABORT the current processing.

api/src/main/java/org/asynchttpclient/AsyncCompletionHandlerBase.java

@@ -36,7 +36,7 @@ public Response onCompleted(Response response) throws Exception {
     /**
      * {@inheritDoc}
      */
-    /* @Override */
+    @Override
     public void onThrowable(Throwable t) {
         log.debug(t.getMessage(), t);
     }

api/src/main/java/org/asynchttpclient/AsyncHandler.java

@@ -70,6 +70,7 @@ public static enum STATE {
 
     /**
      * Invoked as soon as some response body part are received. Could be invoked many times.
+     * Beware that, depending on the provider (Netty) this can be notified with empty body parts.
      *
      * @param bodyPart response's body part.
      * @return a {@link STATE} telling to CONTINUE or ABORT the current processing.

api/src/main/java/org/asynchttpclient/AsyncHandlerExtensions.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2010-2012 Sonatype, Inc. All rights reserved.
+ *
+ * This program is licensed to you under the Apache License Version 2.0,
+ * and you may not use this file except in compliance with the Apache License Version 2.0.
+ * You may obtain a copy of the Apache License Version 2.0 at http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the Apache License Version 2.0 is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
+ */
+package org.asynchttpclient;
+
+/**
+ * This interface hosts new low level callback methods on {@link AsyncHandler}.
+ * For now, those methods are in a dedicated interface in order not to break the existing API,
+ * but could be merged into one of the existing ones in AHC 2.
+ * 
+ * More additional hooks might come, such as:
+ * <ul>
+ *   <li>onConnectionClosed()</li>
+ *   <li>onBytesSent(long numberOfBytes)</li>
+ *   <li>onBytesReceived(long numberOfBytes)</li>
+ * </ul>
+ */
+public interface AsyncHandlerExtensions {
+
+    /**
+     * Notify the callback when trying to open a new connection.
+     */
+    void onOpenConnection();
+
+    /**
+     * Notify the callback when a new connection was successfully opened.
+     */
+    void onConnectionOpen();
+
+    /**
+     * Notify the callback when trying to fetch a connection from the pool.
+     */
+    void onPoolConnection();
+
+    /**
+     * Notify the callback when a new connection was successfully fetched from the pool.
+     */
+    void onConnectionPooled();
+
+    /**
+     * Notify the callback when a request is being written on the wire.
+     * If the original request causes multiple requests to be sent, for example, because of authorization or retry,
+     * it will be notified multiple times.
+     */
+    void onSendRequest();
+
+    /**
+     * Notify the callback every time a request is being retried.
+     */
+    void onRetry();
+}