Add javadoc examples of using .join() with .async()

In test code we frequently will use .join() to wait for the async callback to execute before proceeding with asserts etc

Author: rbygrave

client/src/main/java/io/avaje/http/client/HttpAsyncResponse.java

@@ -8,6 +8,55 @@
 
 /**
  * Async processing of the request with responses as CompletableFuture.
+ *
+ * <h4>Testing and .join()</h4>
+ * <p>
+ * Note that when testing with async requests we frequently use {@code .join()}
+ * on the {@code CompletableFuture} such that the main thread waits for the async
+ * processing to complete. After that various asserts can run knowing that the
+ * async callback code has been executed.
+ *
+ * <h4>Example using .join() for testing purposes</h4>
+ * <pre>{@code
+ *
+ *    clientContext.request()
+ *       ...
+ *       .POST().async()
+ *       .bean(HelloDto.class)
+ *       .whenComplete((helloDto, throwable) -> {
+ *         ...
+ *       }).join(); // wait for async processing to complete
+ *
+ *       // can assert now ...
+ *       assertThat(...)
+ *
+ * }</pre>
+ *
+ * <h4>Example async().bean()</h4>
+ * <p>
+ * In this example POST async that will return a bean converted from json response.
+ * <pre>{@code
+ *
+ *    clientContext.request()
+ *       ...
+ *       .POST().async()
+ *       .bean(HelloDto.class)
+ *       .whenComplete((helloDto, throwable) -> {
+ *
+ *         if (throwable != null) {
+ *           HttpException httpException = (HttpException) throwable.getCause();
+ *           int statusCode = httpException.statusCode();
+ *
+ *           // maybe convert json error response body to a bean (using Jackson/Gson)
+ *           MyErrorBean errorResponse = httpException.bean(MyErrorBean.class);
+ *           ..
+ *
+ *         } else {
+ *           // process helloDto
+ *           ...
+ *         }
+ *       });
+ * }</pre>
  */
 public interface HttpAsyncResponse {
 

client/src/main/java/io/avaje/http/client/HttpClientResponse.java

@@ -14,6 +14,32 @@ public interface HttpClientResponse {
 
   /**
    * Send the request async using CompletableFuture.
+   *
+   * <h4>Example async().bean()</h4>
+   * <p>
+   * In this example POST async that will return a bean converted from json response.
+   * <pre>{@code
+   *
+   *    clientContext.request()
+   *       ...
+   *       .POST().async()
+   *       .bean(HelloDto.class)
+   *       .whenComplete((helloDto, throwable) -> {
+   *
+   *         if (throwable != null) {
+   *           HttpException httpException = (HttpException) throwable.getCause();
+   *           int statusCode = httpException.statusCode();
+   *
+   *           // maybe convert json error response body to a bean (using Jackson/Gson)
+   *           MyErrorBean errorResponse = httpException.bean(MyErrorBean.class);
+   *           ..
+   *
+   *         } else {
+   *           // process helloDto
+   *           ...
+   *         }
+   *       });
+   * }</pre>
    */
   HttpAsyncResponse async();