Merge pull request #2 from saasquatch/dev

Dev

README.md

@@ -4,11 +4,71 @@
 [![Build Status](https://travis-ci.org/saasquatch/apache-client5-reactive.svg?branch=master)](https://travis-ci.org/saasquatch/apache-client5-reactive)
 [![](https://jitpack.io/v/saasquatch/apache-client5-reactive.svg)](https://jitpack.io/#saasquatch/apache-client5-reactive)
 
-Thin wrapper around Apache HttpComponents HttpAsyncClient 5.x to expose Reactive Streams interfaces.
+Thin wrapper around [Apache HttpComponents](https://hc.apache.org/) HttpAsyncClient 5.x to expose [Reactive Streams](https://www.reactive-streams.org) interfaces.
 
 ## Sample usage
 
-For examples, see package [`com.saasquatch.client5reactive.examples`](https://github.com/saasquatch/apache-client5-reactive/tree/master/src/test/java/com/saasquatch/client5reactive/examples).
+```java
+import static java.nio.charset.StandardCharsets.UTF_8;
+import java.nio.ByteBuffer;
+import org.apache.hc.client5.http.async.methods.SimpleHttpRequests;
+import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient;
+import org.apache.hc.client5.http.impl.async.HttpAsyncClients;
+import com.saasquatch.client5reactive.HttpReactiveClient;
+import com.saasquatch.client5reactive.HttpReactiveClients;
+import io.reactivex.rxjava3.core.Single;
+
+public class Example {
+
+  public static void main(String[] args) throws Exception {
+    // Create a CloseableHttpAsyncClient first
+    try (CloseableHttpAsyncClient asyncClient = HttpAsyncClients.createDefault()) {
+      /*
+       * HttpReactiveClient does not support lifecycle management, so the underlying
+       * CloseableHttpAsyncClient needs to be started and closed.
+       */
+      asyncClient.start();
+      // HttpReactiveClient is just a thin wrapper
+      final HttpReactiveClient reactiveClient = HttpReactiveClients.create(asyncClient);
+      // Execute a simple in-memory request
+      Single
+          .fromPublisher(reactiveClient.execute(SimpleHttpRequests.get("https://www.example.com")))
+          .doOnSuccess(response -> {
+            // Get the response status and body in memory
+            System.out.println(response.getCode());
+            System.out.println(response.getBodyText());
+          })
+          .blockingSubscribe();
+      System.out.println("----------");
+      // Execute a streaming request
+      // In this case, the request is a simple in-memory request without a request body
+      Single
+          .fromPublisher(
+              reactiveClient.streamingExecute(SimpleHttpRequests.get("https://www.example.com")))
+          .flatMapPublisher(message -> {
+            // Get the status before subscribing to the streaming body
+            System.out.println(message.getHead().getCode());
+            return message.getBody();
+          })
+          // Collect the streaming body chunks into a List
+          .toList()
+          .map(byteBuffers -> {
+            // Concatenate the body chunks and decode with UTF-8
+            final int totalLength = byteBuffers.stream().mapToInt(ByteBuffer::remaining).sum();
+            final ByteBuffer combined = ByteBuffer.allocate(totalLength);
+            byteBuffers.forEach(combined::put);
+            combined.flip();
+            return UTF_8.decode(combined).toString();
+          })
+          .doOnSuccess(System.out::println)
+          .blockingSubscribe();
+    }
+  }
+
+}
+```
+
+The source code is in package [`com.saasquatch.client5reactive.examples`](https://github.com/saasquatch/apache-client5-reactive/tree/master/src/test/java/com/saasquatch/client5reactive/examples).
 
 ## Adding it to your project
 

src/test/java/com/saasquatch/client5reactive/examples/Example.java

@@ -11,26 +11,40 @@
 
 public class Example {
 
-  private static final String EXAMPLE_URL = "https://www.example.com";
-
   public static void main(String[] args) throws Exception {
+    // Create a CloseableHttpAsyncClient first
     try (CloseableHttpAsyncClient asyncClient = HttpAsyncClients.createDefault()) {
+      /*
+       * HttpReactiveClient does not support lifecycle management, so the underlying
+       * CloseableHttpAsyncClient needs to be started and closed.
+       */
       asyncClient.start();
+      // HttpReactiveClient is just a thin wrapper
       final HttpReactiveClient reactiveClient = HttpReactiveClients.create(asyncClient);
-      Single.fromPublisher(reactiveClient.execute(SimpleHttpRequests.get(EXAMPLE_URL)))
+      // Execute a simple in-memory request
+      Single
+          .fromPublisher(reactiveClient.execute(SimpleHttpRequests.get("https://www.example.com")))
           .doOnSuccess(response -> {
+            // Get the response status and body in memory
             System.out.println(response.getCode());
             System.out.println(response.getBodyText());
           })
           .blockingSubscribe();
       System.out.println("----------");
-      Single.fromPublisher(reactiveClient.streamingExecute(SimpleHttpRequests.get(EXAMPLE_URL)))
+      // Execute a streaming request
+      // In this case, the request is a simple in-memory request without a request body
+      Single
+          .fromPublisher(
+              reactiveClient.streamingExecute(SimpleHttpRequests.get("https://www.example.com")))
           .flatMapPublisher(message -> {
+            // Get the status before subscribing to the streaming body
             System.out.println(message.getHead().getCode());
             return message.getBody();
           })
+          // Collect the streaming body chunks into a List
           .toList()
           .map(byteBuffers -> {
+            // Concatenate the body chunks and decode with UTF-8
             final int totalLength = byteBuffers.stream().mapToInt(ByteBuffer::remaining).sum();
             final ByteBuffer combined = ByteBuffer.allocate(totalLength);
             byteBuffers.forEach(combined::put);