Merge pull request #181 from avaje/feature/javadoc-improve

Improve Javadoc only

Author: rbygrave

http-client/src/main/java/io/avaje/http/client/DHttpApi.java

@@ -41,19 +41,19 @@ private <T> HttpApiProvider<T> lookup(Class<T> type) {
   }
 
   @SuppressWarnings("unchecked")
-  <T> T provideFor(Class<T> type, HttpClient clientContext) {
+  <T> T provideFor(Class<T> type, HttpClient httpClient) {
     final HttpApiProvider<T> apiProvider = lookup(type);
     if (apiProvider == null) {
       throw new IllegalArgumentException("No registered HttpApiProvider for type: " + type);
     }
-    return apiProvider.provide(clientContext);
+    return apiProvider.provide(httpClient);
   }
 
   /**
    * Return the client implementation via service loading.
    */
-  static <T> T provide(Class<T> type, HttpClient clientContext) {
-    return INSTANCE.provideFor(type, clientContext);
+  static <T> T provide(Class<T> type, HttpClient httpClient) {
+    return INSTANCE.provideFor(type, httpClient);
   }
 
   /**

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

@@ -20,7 +20,7 @@
  * <h4>Example using .join() for testing purposes</h4>
  * <pre>{@code
  *
- *    clientContext.request()
+ *    client.request()
  *       ...
  *       .POST().async()
  *       .bean(HelloDto.class)
@@ -38,7 +38,7 @@
  * In this example POST async that will return a bean converted from json response.
  * <pre>{@code
  *
- *    clientContext.request()
+ *    client.request()
  *       ...
  *       .POST().async()
  *       .bean(HelloDto.class)
@@ -80,7 +80,7 @@ public interface HttpAsyncResponse {
    *
    * <pre>{@code
    *
-   *   clientContext.request()
+   *   client.request()
    *       .path("hello/world")
    *       .GET()
    *       .async().asVoid()
@@ -115,7 +115,7 @@ public interface HttpAsyncResponse {
    *
    * <pre>{@code
    *
-   *   clientContext.request()
+   *   client.request()
    *       .path("hello/world")
    *       .GET()
    *       .async().asDiscarding()
@@ -140,7 +140,7 @@ public interface HttpAsyncResponse {
    *
    * <pre>{@code
    *
-   *   clientContext.request()
+   *   client.request()
    *       .path("hello/world")
    *       .GET()
    *       .async().asString()
@@ -191,7 +191,7 @@ public interface HttpAsyncResponse {
    * </p>
    * <pre>{@code
    *
-   *    CompletableFuture<HttpResponse<Void>> future = clientContext.request()
+   *    CompletableFuture<HttpResponse<Void>> future = client.request()
    *       .path("hello/lineStream")
    *       .GET().async()
    *       .handler(HttpResponse.BodyHandlers.fromLineSubscriber(new Flow.Subscriber<>() {
@@ -240,7 +240,7 @@ default <E> CompletableFuture<HttpResponse<E>> withHandler(HttpResponse.BodyHand
    *
    * <pre>{@code
    *
-   *    clientContext.request()
+   *    client.request()
    *       ...
    *       .POST().async()
    *       .as(HelloDto.class)
@@ -280,7 +280,7 @@ default <E> CompletableFuture<HttpResponse<E>> withHandler(HttpResponse.BodyHand
    *
    * <pre>{@code
    *
-   *    clientContext.request()
+   *    client.request()
    *       ...
    *       .POST().async()
    *       .bean(HelloDto.class)
@@ -314,7 +314,7 @@ default <E> CompletableFuture<HttpResponse<E>> withHandler(HttpResponse.BodyHand
    *
    * <pre>{@code
    *
-   *    clientContext.request()
+   *    client.request()
    *       ...
    *       .POST().async()
    *       .asList(HelloDto.class)
@@ -356,7 +356,7 @@ default <E> CompletableFuture<HttpResponse<E>> withHandler(HttpResponse.BodyHand
    *
    * <pre>{@code
    *
-   *    clientContext.request()
+   *    client.request()
    *       ...
    *       .GET().async()
    *       .list(HelloDto.class)
@@ -387,7 +387,7 @@ default <E> CompletableFuture<HttpResponse<E>> withHandler(HttpResponse.BodyHand
    *
    * <pre>{@code
    *
-   *    clientContext.request()
+   *    client.request()
    *       ...
    *       .POST().async()
    *       .asStream(HelloDto.class)

http-client/src/main/java/io/avaje/http/client/HttpCallResponse.java

@@ -32,7 +32,7 @@ public interface HttpCallResponse {
    * <pre>{@code
    *
    *   HttpCall<HttpResponse<Void>> call =
-   *     clientContext.request()
+   *     client.request()
    *       .path("hello/world")
    *       .GET()
    *       .call().asVoid();
@@ -54,7 +54,7 @@ public interface HttpCallResponse {
    * <pre>{@code
    *
    *   HttpCall<HttpResponse<Void>> call =
-   *     clientContext.request()
+   *     client.request()
    *       .path("hello/world")
    *       .GET()
    *       .call().asDiscarding();
@@ -71,7 +71,7 @@ public interface HttpCallResponse {
    * <pre>{@code
    *
    *   HttpCall<HttpResponse<String>> call =
-   *     clientContext.request()
+   *     client.request()
    *       .path("hello/world")
    *       .GET()
    *       .call().asString();
@@ -107,7 +107,7 @@ public interface HttpCallResponse {
    * Call using any given {@code HttpResponse.BodyHandler}.
    * <pre>{@code
    *
-   *    HttpCall<E> call = clientContext.request()
+   *    HttpCall<E> call = client.request()
    *       .path("hello/lineStream")
    *       .GET()
    *       .call().handler(HttpResponse.BodyHandler<E> ...);

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

@@ -19,14 +19,14 @@
  *
  * <pre>{@code
  *
- *  HelloDto dto = clientContext.request()
+ *  HelloDto dto = client.request()
  *       .path("hello").queryParam("name", "Rob").queryParam("say", "Whats up")
  *       .GET()
  *       .bean(HelloDto.class);
  *
  * }</pre>
  *
- * @see HttpClientContext
+ * @see HttpClient
  */
 public interface HttpClientRequest {
 
@@ -113,7 +113,7 @@ public interface HttpClientRequest {
    * Add the header to the request implicitly converting the value to a String. If the value is a
    * collection then it's values are appended with the same key
    *
-   * @param name The header name
+   * @param name  The header name
    * @param value The header value
    * @return The request being built
    */
@@ -130,7 +130,7 @@ public interface HttpClientRequest {
   /**
    * Add the headers to the request via Collection.
    *
-   * @param name The header name
+   * @param name  The header name
    * @param value The header values
    * @return The request being built
    */
@@ -155,7 +155,7 @@ public interface HttpClientRequest {
    * Set the URL to use replacing the base URL.
    * <pre>{code
    *
-   *  HttpResponse<String> res = clientContext.request()
+   *  HttpResponse<String> res = client.request()
    *       .url("http://127.0.0.1:8889")
    *       .path("hello")
    *       .GET()
@@ -165,7 +165,7 @@ public interface HttpClientRequest {
    *
    * @param url The url effectively replacing the base url.
    * @return The request being built
-   * @see HttpClientContext.Builder#baseUrl(String)
+   * @see HttpClient.Builder#baseUrl(String)
    */
   HttpClientRequest url(String url);
 
@@ -248,8 +248,8 @@ public interface HttpClientRequest {
   /**
    * Add a query parameter with multiple values
    *
-   * @param name The name of the query parameter
-   * @param value The values of the query parameter which can be null
+   * @param name   The name of the query parameter
+   * @param values The values of the query parameter which can be null
    * @return The request being built
    */
   default HttpClientRequest queryParam(String name, Collection<String> values) {
@@ -293,24 +293,41 @@ default HttpClientRequest queryParam(String name, Collection<String> values) {
   HttpClientRequest body(Object bean, String contentType);
 
   /**
-   * Set the body as a bean using the default content type. The default
-   * content type will often be <code>application/json; charset=utf8</code>.
+   * Set the body as a bean using the default content type.
+   * <p>
+   * The default content type will often be {@code application/json; charset=utf8}.
    */
   HttpClientRequest body(Object bean);
 
   /**
-   * Set the body as a bean with the given content type using a BodyWriter.
-   * Used for JsonbAdapter
+   * Set the body as a bean additionally specifying the type that will be
+   * used to serialise the content (e.g. JsonbAdapter).
+   * <p>
+   * Specifying the type allows the bean instance to be a type that extends
+   * a type that is known to JsonbAdapter / the body content adapter used.
+   *
+   * @param bean The body content as an instance
+   * @param type The type used by the body content adapter to write the body content
+   * @return The request being built
    */
   HttpClientRequest body(Object bean, Class<?> type);
 
   /**
-   * Set the body as a bean with the given content type using a BodyWriter.
+   * Set the body as a bean with the given content type and additionally specifying
+   * the type that will be used to serialise the content (e.g. JsonbAdapter).
+   * <p>
+   * Specifying the type allows the bean instance to be a type that extends
+   * a type that is known to JsonbAdapter / the body content adapter used.
+   *
+   * @param bean        The body content as an instance
+   * @param type        The type used by the body content adapter to write the body content
+   * @param contentType The content type of the body
+   * @return The request being built
    */
   HttpClientRequest body(Object bean, Class<?> type, String contentType);
 
   /**
-   * Set the body content as a string.
+   * Set the body content as a string using the default content type.
    *
    * @param body The body content
    * @return The request being built

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

@@ -21,7 +21,7 @@ public interface HttpClientResponse {
    * In this example POST async that will return a bean converted from json response.
    * <pre>{@code
    *
-   *    clientContext.request()
+   *    client.request()
    *       ...
    *       .POST().async()
    *       .bean(HelloDto.class)

http-client/src/main/java/io/avaje/http/client/HttpException.java

@@ -13,7 +13,7 @@
  * <pre>{@code
  *
  *   try {
- *       clientContext.request()
+ *       client.request()
  *         .path("hello/saveForm")
  *         .formParam("email", "user@foo.com")
  *         .formParam("url", "notAValidUrl")
@@ -115,7 +115,7 @@ public String bodyAsString() {
     return new String(body.content(), StandardCharsets.UTF_8);
   }
 
-  /** 
+  /**
    * Return the response body content as raw bytes, or else null if body content doesn't exist.
    */
   public byte[] bodyAsBytes() {

http-client/src/main/java/io/avaje/http/client/JacksonBodyAdapter.java

@@ -15,7 +15,7 @@
  *
  * <pre>{@code
  *
- *   HttpClientContext.builder()
+ *   HttpClient.builder()
  *       .baseUrl(baseUrl)
  *       .bodyAdapter(new JacksonBodyAdapter())
  *       .build();

http-client/src/main/java/io/avaje/http/client/JsonbBodyAdapter.java

@@ -13,7 +13,7 @@
  *
  * <pre>{@code
  *
- *   HttpClientContext.builder()
+ *   HttpClient.builder()
  *       .baseUrl(baseUrl)
  *       .bodyAdapter(new JsonbBodyAdapter())
  *       .build();

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

@@ -6,12 +6,12 @@
  *
  * <pre>{@code
  *
- *   HttpClientContext ctx = HttpClientContext.builder()
+ *   HttpClient client = HttpClient.builder()
  *       .baseUrl("http://localhost:8080")
  *       .bodyAdapter(new JacksonBodyAdapter())
  *       .build();
  *
- *  HelloDto dto = ctx.request()
+ *  HelloDto dto = client.request()
  *       .path("hello")
  *       .queryParam("say", "Whats up")
  *       .GET()