Merge pull request #7 from avaje/feature/requestListener

 API - Refactor rename ResponseListener to RequestListener

Author: rbygrave

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

@@ -1,7 +1,13 @@
 package io.avaje.http.client;
 
+/**
+ * Read content as a java type.
+ */
 public interface BodyReader<T> {
 
+  /**
+   * Read the content returning it as a java type.
+   */
   T read(BodyContent content);
 
 }

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

@@ -15,14 +15,14 @@ class DHttpClientContext implements HttpClientContext {
   private final String baseUrl;
   private final Duration requestTimeout;
   private final BodyAdapter bodyAdapter;
-  private final ResponseListener responseListener;
+  private final RequestListener requestListener;
 
-  DHttpClientContext(HttpClient httpClient, String baseUrl, Duration requestTimeout, BodyAdapter bodyAdapter, ResponseListener responseListener) {
+  DHttpClientContext(HttpClient httpClient, String baseUrl, Duration requestTimeout, BodyAdapter bodyAdapter, RequestListener requestListener) {
     this.httpClient = httpClient;
     this.baseUrl = baseUrl;
     this.requestTimeout = requestTimeout;
     this.bodyAdapter = bodyAdapter;
-    this.responseListener = responseListener;
+    this.requestListener = requestListener;
   }
 
   @Override
@@ -128,14 +128,14 @@ <T> List<T> readList(Class<T> cls, BodyContent content) {
 
 
   void afterResponse(DHttpClientRequest request) {
-    if (responseListener != null) {
-      responseListener.response(request.listenerEvent());
+    if (requestListener != null) {
+      requestListener.response(request.listenerEvent());
     }
   }
 
   void afterResponseHandler(DHttpClientRequest request) {
-    if (responseListener != null) {
-      responseListener.response(request.listenerEvent());
+    if (requestListener != null) {
+      requestListener.response(request.listenerEvent());
     }
   }
 }

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

@@ -18,7 +18,7 @@ class DHttpClientContextBuilder implements HttpClientContext.Builder {
 
   private BodyAdapter bodyAdapter;
 
-  private ResponseListener responseListener;
+  private RequestListener requestListener;
 
   private CookieHandler cookieHandler = new CookieManager();
 
@@ -55,8 +55,8 @@ public HttpClientContext.Builder withBodyAdapter(BodyAdapter adapter) {
   }
 
   @Override
-  public HttpClientContext.Builder withResponseListener(ResponseListener responseListener) {
-    this.responseListener = responseListener;
+  public HttpClientContext.Builder withRequestListener(RequestListener requestListener) {
+    this.requestListener = requestListener;
     return this;
   }
 
@@ -89,7 +89,7 @@ public HttpClientContext build() {
     if (client == null) {
       client = defaultClient();
     }
-    return new DHttpClientContext(client, baseUrl, requestTimeout, bodyAdapter, responseListener);
+    return new DHttpClientContext(client, baseUrl, requestTimeout, bodyAdapter, requestListener);
   }
 
   private HttpClient defaultClient() {

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

@@ -75,6 +75,12 @@ public HttpClientRequest gzip(boolean gzip) {
     return this;
   }
 
+  @Override
+  public HttpClientRequest url(String baseUrl) {
+    url.url(baseUrl);
+    return this;
+  }
+
   @Override
   public HttpClientRequest path(String path) {
     url.path(path);
@@ -348,11 +354,11 @@ protected HttpRequest.Builder newRequest(String method, String url, HttpRequest.
       .method(method, body);
   }
 
-  ResponseListener.Event listenerEvent() {
+  RequestListener.Event listenerEvent() {
     return new ListenerEvent();
   }
 
-  private class ListenerEvent implements ResponseListener.Event {
+  private class ListenerEvent implements RequestListener.Event {
 
     @Override
     public long responseTimeNanos() {

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

@@ -8,11 +8,40 @@
 
 /**
  * The HTTP client context that we use to build and process requests.
+ *
+ * <pre>{@code
+ *
+ *   HttpClientContext ctx = HttpClientContext.newBuilder()
+ *       .withBaseUrl("http://localhost:8080")
+ *       .withBodyAdapter(new JacksonBodyAdapter(new ObjectMapper()))
+ *       .build();
+ *
+ *  HelloDto dto = ctx.request()
+ *       .path("hello")
+ *       .queryParam("name", "Rob")
+ *       .queryParam("say", "Ki ora")
+ *       .get()
+ *       .bean(HelloDto.class);
+ *
+ * }</pre>
  */
 public interface HttpClientContext {
 
   /**
    * Return the builder to config and build the client context.
+   *
+   * <pre>{@code
+   *
+   *   HttpClientContext ctx = HttpClientContext.newBuilder()
+   *       .withBaseUrl("http://localhost:8080")
+   *       .withBodyAdapter(new JacksonBodyAdapter(new ObjectMapper()))
+   *       .build();
+   *
+   *  HttpResponse<String> res = ctx.request()
+   *       .path("hello")
+   *       .get().asString();
+   *
+   * }</pre>
    */
   static HttpClientContext.Builder newBuilder() {
     return new DHttpClientContextBuilder();
@@ -31,6 +60,9 @@ static HttpClientContext.Builder newBuilder() {
 
   /**
    * Return the body adapter used by the client context.
+   * <p>
+   * This is the body adapter used to convert request and response
+   * bodies to java types. For example using Jackson with JSON payloads.
    */
   BodyAdapter converters();
 
@@ -70,9 +102,24 @@ static HttpClientContext.Builder newBuilder() {
    */
   byte[] decodeContent(String encoding, byte[] content);
 
-
   /**
    * Builds the HttpClientContext.
+   *
+   * <pre>{@code
+   *
+   *   HttpClientContext ctx = HttpClientContext.newBuilder()
+   *       .withBaseUrl("http://localhost:8080")
+   *       .withBodyAdapter(new JacksonBodyAdapter(new ObjectMapper()))
+   *       .build();
+   *
+   *  HelloDto dto = ctx.request()
+   *       .path("hello")
+   *       .queryParam("name", "Rob")
+   *       .queryParam("say", "Ki ora")
+   *       .get()
+   *       .bean(HelloDto.class);
+   *
+   * }</pre>
    */
   interface Builder {
 
@@ -85,6 +132,8 @@ interface Builder {
 
     /**
      * Set the base URL to use for requests created from the context.
+     * <p>
+     * Note that the base url can be replaced via {@link HttpClientRequest#url(String)}.
      */
     Builder withBaseUrl(String baseUrl);
 
@@ -102,11 +151,11 @@ interface Builder {
     Builder withBodyAdapter(BodyAdapter adapter);
 
     /**
-     * Add a response listener. Note that {@link RequestLogger} is an
+     * Add a request listener. Note that {@link RequestLogger} is an
      * implementation for debug logging request/response headers and
      * content.
      */
-    Builder withResponseListener(ResponseListener requestListener);
+    Builder withRequestListener(RequestListener requestListener);
 
     /**
      * Specify a cookie handler to use on the HttpClient. This would override the default cookie handler.
@@ -139,6 +188,21 @@ interface Builder {
 
     /**
      * Build and return the context.
+     *
+     * <pre>{@code
+     *
+     *   HttpClientContext ctx = HttpClientContext.newBuilder()
+     *       .withBaseUrl("http://localhost:8080")
+     *       .withBodyAdapter(new JacksonBodyAdapter(new ObjectMapper()))
+     *       .build();
+     *
+     *  HelloDto dto = ctx.request()
+     *       .path("hello")
+     *       .queryParam("say", "Ki ora")
+     *       .get()
+     *       .bean(HelloDto.class);
+     *
+     * }</pre>
      */
     HttpClientContext build();
   }

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

@@ -13,6 +13,16 @@
  * Largely wraps the standard JDK HttpRequest with additional
  * support for converting beans to body content and converting
  * beans from response content.
+ *
+ * <pre>{@code
+ *
+ *  HelloDto dto = clientContext.request()
+ *       .path("hello").queryParam("name", "Rob").queryParam("say", "Ki ora")
+ *       .get().bean(HelloDto.class);
+ *
+ * }</pre>
+ *
+ * @see HttpClientContext
  */
 public interface HttpClientRequest {
 
@@ -42,6 +52,23 @@ public interface HttpClientRequest {
    */
   HttpClientRequest gzip(boolean gzip);
 
+  /**
+   * Set the URL to use replacing the base URL.
+   * <pre>{code
+   *
+   *  HttpResponse<String> res = clientContext.request()
+   *       .url("http://127.0.0.1:8887")
+   *       .path("hello")
+   *       .get().asString();
+   *
+   * }</pre>
+   *
+   * @param url The url effectively replacing the base url.
+   * @return The request being built
+   * @see HttpClientContext.Builder#withBaseUrl(String)
+   */
+  HttpClientRequest url(String url);
+
   /**
    * Add a path segment to the URL.
    *

client/src/main/java/io/avaje/http/client/ResponseListener.java renamed to client/src/main/java/io/avaje/http/client/RequestListener.java

@@ -7,10 +7,10 @@
 /**
  * Listen to responses.
  * <p>
- * {@link RequestLogger} is an implementation for debug logging the
- * requests and responses.
+ * {@link RequestLogger} is an implementation for debug logging
+ * the requests and responses.
  */
-public interface ResponseListener {
+public interface RequestListener {
 
   /**
    * Handle the response.

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

@@ -13,7 +13,7 @@
 /**
  * Logs request and response details for debug logging purposes.
  */
-public class RequestLogger implements ResponseListener {
+public class RequestLogger implements RequestListener {
 
   private static final Logger log = LoggerFactory.getLogger(RequestLogger.class);
 

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

@@ -3,21 +3,46 @@
 import java.net.URLEncoder;
 import java.nio.charset.StandardCharsets;
 
+/**
+ * Build a URL typically using a base url and adding path and query parameters.
+ */
 public class UrlBuilder {
 
   private final StringBuilder buffer = new StringBuilder(100);
 
   private boolean hasParams;
 
+  /**
+   * Create with a base url.
+   */
   public UrlBuilder(String base) {
     buffer.append(base);
   }
 
+  /**
+   * Set the url. This effectively replaces a base url.
+   */
+  public UrlBuilder url(String url) {
+    buffer.delete(0, buffer.length());
+    buffer.append(url);
+    return this;
+  }
+
+  /**
+   * Add a path segment to the url.
+   * <p>
+   * This includes appending a "/" prefix with the path.
+   */
   public UrlBuilder path(String path) {
     buffer.append("/").append(path);
     return this;
   }
 
+  /**
+   * Append a query parameter.
+   * <p>
+   * The name and value parameters are url encoded.
+   */
   public UrlBuilder queryParam(String name, String value) {
     if (value != null) {
       buffer.append(hasParams ? '&' : '?');
@@ -27,20 +52,30 @@ public UrlBuilder queryParam(String name, String value) {
     return this;
   }
 
+  /**
+   * Append a matrix parameter.
+   * <p>
+   * The name and value parameters are url encoded.
+   */
   public UrlBuilder matrixParam(String name, String value) {
     if (value != null) {
       buffer.append(';').append(enc(name)).append("=").append(enc(value));
     }
     return this;
   }
 
+  /**
+   * URL encode the value.
+   */
   public static String enc(String val) {
     return URLEncoder.encode(val, StandardCharsets.UTF_8);
   }
 
+  /**
+   * Return the full URL.
+   */
   public String build() {
     return buffer.toString();
   }
 
-
 }

client/src/main/java/io/avaje/http/client/package-info.java

@@ -0,0 +1,22 @@
+/**
+ * Provides a HTTP client with support for adapting body content
+ * (like JSON) to java types.
+ * <p>
+ * Uses the Java http client
+ *
+ * <pre>{@code
+ *
+ *   HttpClientContext ctx = HttpClientContext.newBuilder()
+ *       .withBaseUrl("http://localhost:8080")
+ *       .withBodyAdapter(new JacksonBodyAdapter(new ObjectMapper()))
+ *       .build();
+ *
+ *  HelloDto dto = ctx.request()
+ *       .path("hello")
+ *       .queryParam("say", "Ki ora")
+ *       .get()
+ *       .bean(HelloDto.class);
+ *
+ * }</pre>
+ */
+package io.avaje.http.client;