#5 - Add HttpClientRequest.url(String url) - ability to replace the base url

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/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);

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);
 
@@ -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/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;

client/src/test/java/io/avaje/http/client/HelloControllerTest.java

@@ -28,6 +28,18 @@ void get_helloMessage() {
     assertThat(hres.statusCode()).isEqualTo(200);
   }
 
+  @Test
+  void get_helloMessage_via_url() {
+
+    final HttpResponse<String> hres = clientContext.request()
+      .url("http://127.0.0.1:8887")
+      .path("hello").path("message")
+      .get().asString();
+
+    assertThat(hres.body()).contains("hello world");
+    assertThat(hres.statusCode()).isEqualTo(200);
+  }
+
   @Test
   void get_hello_returningListOfBeans() {
 

client/src/test/java/io/avaje/http/client/UrlBuilderTest.java

@@ -6,6 +6,12 @@
 
 class UrlBuilderTest {
 
+  @Test
+  void url() {
+    String url = new UrlBuilder("https://foo").url("http://bar").path("bazz").build();
+    assertThat(url).isEqualTo("http://bar/bazz");
+  }
+
   @Test
   void path() {
     assertThat(new UrlBuilder("https://foo").path("bar").build()).isEqualTo("https://foo/bar");