Update README

Author: rbygrave

README.md

@@ -4,7 +4,11 @@ A light weight wrapper to the JDK 11+ Java Http Client
 
 - Adds a fluid API for request constructing URL and payload
 - Adds JSON marshalling/unmarshalling of request and response using Jackson or Gson
-- Adds request/response logging
+- Gzip encoding/decoding
+- Logging of request/response logging
+- Interception of request/response
+- Built in support for authorization via Basic Auth and Bearer Token
+
 
 
 
@@ -35,44 +39,130 @@ Create a HttpClientContext with a baseUrl, Jackson or Gson based JSON
 
 ```
 
-### Requests
+## Requests
 
 From HttpClientContext:
  - Create a request
  - Build the url via path(), matrixParam(), queryParam()
  - Optionally set headers(), cookies() etc
- - Optionally specify a request body (JSON, form, or raw BodyPublisher)
+ - Optionally specify a request body (JSON, form, or any JDK BodyPublisher)
  - Http verbs - GET(), POST(), PUT(), PATCH(), DELETE(), HEAD(), TRACE()
- - Optionally return response body as a bean, list of beans, stream of beans or various raw response types
- - Optionally use Async processing of the request
+
+ - Sync processing response body as:
+   - a bean, list of beans, stream of beans, String, Void or any JDK Response.BodyHandler
+
+ - Async processing of the request using CompleteableFuture
+   - a bean, list of beans, stream of beans, String, Void or any JDK Response.BodyHandler
+
+
+
+## Limitations:
+- NO support for POSTing multipart-form currently
+
+
+#### Example GET as String
+```java
+HttpResponse<String> hres = clientContext.request()
+  .path("hello")
+  .GET()
+  .asString();
+```
+
+
+## Overview of responses
+
+Overview of response types for sync calls.
+
+<table style="width:100%;">
+<tr><td><b>sync processing</b></td><td>&nbsp;</td></tr>
+<tr><td>asVoid</td><td>HttpResponse&lt;Void&gt;</td></tr>
+<tr><td>asString</td><td>HttpResponse&lt;String&gt;</td></tr>
+<tr><td>bean&lt;E&gt</td><td>E</td></tr>
+<tr><td>list&lt;E&gt</td><td>List&lt;E&gt;</td></tr>
+<tr><td>stream&lt;E&gt</td><td>Stream&lt;E&gt;</td></tr>
+<tr><td>withHandler(HttpResponse.BodyHandler&lt;E&gt;)</td><td>E</td></tr>
+<tr><td>&nbsp;</td><td>&nbsp;</td></tr>
+<tr><td><b>async processing</b></td><td>&nbsp;</td></tr>
+<tr><td>asVoid</td><td>CompleteableFuture&lt;Void&gt;</td></tr>
+<tr><td>asString</td><td>CompleteableFuture&lt;String&gt;</td></tr>
+<tr><td>bean&lt;E&gt</td><td>CompleteableFuture&lt;E&gt;</td></tr>
+<tr><td>list&lt;E&gt</td><td>CompleteableFuture&lt;List&lt;E&gt;&gt;</td></tr>
+<tr><td>stream&lt;E&gt</td><td>CompleteableFuture&lt;Stream&lt;E&gt;&gt;</td></tr>
+<tr><td>withHandler(HttpResponse.BodyHandler&lt;E&gt)</td><td>CompleteableFuture&lt;E&gt;</td></tr>
+</table>
+
+### JDK BodyHandlers
+
+JDK HttpClient provides a number of BodyHandlers including reactive Flow based subscribers.
+With the `withHandler()` methods we can use any of these or our own `HttpResponse.BodyHandler`
+implementation.
+
+Reference https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpResponse.BodyHandlers.html
+
+<table style="width:100%;">
+<tr><td>discarding()</td><td>Discards the response body</td></tr>
+<tr><td>ofByteArray()</td><td>byte[]</td></tr>
+<tr><td>ofString()</td><td>String, additional charset option</td></tr>
+<tr><td>ofLines()</td><td>Stream&lt;String&gt;</td></tr>
+<tr><td>ofInputStream()</td><td>InputStream</td></tr>
+
+<tr><td>ofFile(Path file)</td><td>Path with various options</td></tr>
+<tr><td>ofByteArrayConsumer(...)</td><td>&nbsp;</td></tr>
+<tr><td>fromSubscriber</td><td>various options</td></tr>
+<tr><td>fromLineSubscriber</td><td>various options</td></tr>
+</table>
 
 ## Examples
 
-GET as String
+#### GET as String
 ```java
 HttpResponse<String> hres = clientContext.request()
   .path("hello")
   .GET()
   .asString();
 ```
 
-GET as json to single bean
+#### Async GET as String
+ - All async requests use JDK httpClient.sendAsync(...) returning CompleteableFuture&lt;T&gt;
+ - throwable is a CompletionException
+ - In the example below hres is of type HttpResponse&lt;String&gt;
+
+```java
+clientContext.request()
+   .path("hello")
+   .GET()
+   .async().asString()
+   .whenComplete((hres, throwable) -> {
+
+     if (throwable != null) {
+       // CompletionException
+       ...
+     } else {
+       // HttpResponse&lt;String&gt;
+       int statusCode = hres.statusCode();
+       String body = hres.body();
+       ...
+     }
+   });
+```
+
+#### GET as json to single bean
 ```java
 Customer customer = clientContext.request()
   .path("customers").path(42)
   .GET()
   .bean(Customer.class);
 ```
 
-GET as json to a list of beans
+#### GET as json to a list of beans
 ```java
 List<Customer> list = clientContext.request()
   .path("customers")
   .GET()
   .list(Customer.class);
 ```
 
-GET as `application/x-json-stream` as a stream of beans
+#### GET as `application/x-json-stream` as a stream of beans
 ```java
 Stream<Customer> stream = clientContext.request()
   .path("customers/all")
@@ -81,12 +171,12 @@ Stream<Customer> stream = clientContext.request()
 ```
 
 
-POST a bean as json request body
+#### POST a bean as json request body
 ```java
-HelloDto bean = new HelloDto(12, "rob", "other");
+Hello bean = new Hello(42, "rob", "other");
 
 HttpResponse<Void> res = clientContext.request()
-  .path("hello/savebean")
+  .path("hello")
   .body(bean)
   .POST()
   .asDiscarding();
@@ -95,7 +185,11 @@ assertThat(res.statusCode()).isEqualTo(201);
 ```
 
 
-Path
+#### Path
+
+Multiple calls to `path()` append with a `/`. This is make it easier to build a path
+programmatically and also build paths that include `matrixParam()`
+
 ```java
 HttpResponse<String> res = clientContext.request()
   .path("customers")
@@ -112,27 +206,29 @@ HttpResponse<String> res = clientContext.request()
   .asString();
 ```
 
-MatrixParam
+#### MatrixParam
 ```java
 HttpResponse<String> httpRes = clientContext.request()
   .path("books")
   .matrixParam("author", "rob")
   .matrixParam("country", "nz")
   .path("foo")
   .matrixParam("extra", "banana")
-  .GET().asString();
+  .GET()
+  .asString();
 ```
 
-QueryParam
+#### QueryParam
 ```java
 List<Product> beans = clientContext.request()
   .path("products")
   .queryParam("sortBy", "name")
   .queryParam("maxCount", "100")
-  .GET().list(Product.class);
+  .GET()
+  .list(Product.class);
 ```
 
-FormParam
+#### FormParam
 ```java
 HttpResponse<Void> res = clientContext.request()
   .path("register/user")
@@ -146,10 +242,21 @@ HttpResponse<Void> res = clientContext.request()
 assertThat(res.statusCode()).isEqualTo(201);
 ```
 
-## Currently, NO support for POSTing multipart-form
+
 
 ## Async processing
 
+All async requests use JDK httpClient.sendAsync(...) returning CompleteableFuture&lt;T&gt;
+
+<table style="width:100%;">
+<tr><td>asVoid</td><td>CompleteableFuture&lt;Void&gt;</td></tr>
+<tr><td>asString</td><td>CompleteableFuture&lt;String&gt;</td></tr>
+<tr><td>bean&lt;E&gt</td><td>CompleteableFuture&lt;E&gt;</td></tr>
+<tr><td>list&lt;E&gt</td><td>CompleteableFuture&lt;List&lt;E&gt;&gt;</td></tr>
+<tr><td>stream&lt;E&gt</td><td>CompleteableFuture&lt;Stream&lt;E&gt;&gt;</td></tr>
+<tr><td>withHandler(HttpResponse.BodyHandler&lt;E&gt)</td><td>CompleteableFuture&lt;E&gt</td></tr>
+</table>
+
 ### .async().asDiscarding() - HttpResponse&lt;Void&gt;
 
 ```java
@@ -214,7 +321,7 @@ clientContext.request()
 
 ```
 
-### .async().withHandler(...) - Any response body handler
+### .async().withHandler(...) - Any `Response.BodyHandler` implementation
 
 The example below is a line subscriber processing response content line by line.
 
@@ -230,6 +337,7 @@ CompletableFuture<HttpResponse<Void>> future = clientContext.request()
      }
      @Override
      public void onNext(String item) {
+       // process the line of response content
        ...
      }
      @Override
@@ -248,10 +356,27 @@ CompletableFuture<HttpResponse<Void>> future = clientContext.request()
 
 ```
 
+## BasicAuthIntercept - Authorization Basic / Basic Auth
+
+We can use `BasicAuthIntercept` to intercept all requests adding a `Authorization: Basic ...`
+header ("Basic Auth").
+
+##### Example
+
+```java
+HttpClientContext clientContext =
+   HttpClientContext.newBuilder()
+     .withBaseUrl(baseUrl)
+     ...
+     .withRequestIntercept(new BasicAuthIntercept("myUsername", "myPassword"))  <!-- HERE
+     .build();
+```
+
 
-## Auth token
+## AuthTokenProvider - Authorization Bearer token
 
-Built in support for obtaining and setting an Authorization token.
+For Authorization using `Bearer` tokens that are obtained and expire, implement `AuthTokenProvider`
+and register that when building the HttpClientContext.
 
 ### 1. Implement AuthTokenProvider
 
@@ -280,14 +405,13 @@ Built in support for obtaining and setting an Authorization token.
 ```java
     HttpClientContext ctx = HttpClientContext.newBuilder()
       .withBaseUrl("https://foo")
-      .withBodyAdapter(new JacksonBodyAdapter(objectMapper))
-      .withRequestListener(new RequestLogger())
+      ...
       .withAuthTokenProvider(new MyAuthTokenProvider()) <!-- HERE
       .build();
 ```
 
 ### 3. Token obtained and set automatically
 
-Now all requests using the HttpClientContext will automatically get
+All requests using the HttpClientContext will automatically get
 an `Authorization` header with `Bearer` token added. The token will be
-obtained when necessary.
+obtained for initial request and then renewed when the token has expired.