- * Typically the token will be valid for a period and then expire. */ public interface AuthToken { /** - * Return the Authorization bearer token. + * The Authorization bearer token. */ String token(); /** - * Return true if the token has expired or is no longer valid. + * Whether the token has expired or no longer valid. */ boolean isExpired(); /** - * Return the duration until expiry. + * Duration until expiration. */ Duration expiration(); /** - * Create an return a AuthToken with the given token and time it is valid until. + * Create an AuthToken with the given token and when it expires. */ static AuthToken of(String token, Instant validUntil) { return new Basic(token, validUntil); diff --git a/http-client/src/main/java/io/avaje/http/client/AuthTokenProvider.java b/http-client/src/main/java/io/avaje/http/client/AuthTokenProvider.java index 9dcc5118..778d2f19 100644 --- a/http-client/src/main/java/io/avaje/http/client/AuthTokenProvider.java +++ b/http-client/src/main/java/io/avaje/http/client/AuthTokenProvider.java @@ -1,7 +1,7 @@ package io.avaje.http.client; /** - * Use to obtain an Authorization bearer token that is expected to be used. + * Use to obtain an Authorization bearer token used for authenticated requests. * *
{@code
*
@@ -33,7 +33,7 @@ public interface AuthTokenProvider {
/**
* Obtain a new Authorization token.
*
- * @param tokenRequest A new request to obtain an Authorisation token
+ * @param tokenRequest A new request to obtain an Authorization token
*/
AuthToken obtainToken(HttpClientRequest tokenRequest);
diff --git a/http-client/src/main/java/io/avaje/http/client/BodyAdapter.java b/http-client/src/main/java/io/avaje/http/client/BodyAdapter.java
index ef6ee6de..8764eff1 100644
--- a/http-client/src/main/java/io/avaje/http/client/BodyAdapter.java
+++ b/http-client/src/main/java/io/avaje/http/client/BodyAdapter.java
@@ -3,22 +3,18 @@
import java.lang.reflect.Type;
import java.util.List;
-/**
- * Adaptor between beans and content of a request or response.
- *
- * Typically converts between beans as JSON content.
- */
+/** Adapter between beans and content of a request or response. */
public interface BodyAdapter {
/**
- * Return a BodyWriter to write beans of this type as request content.
+ * BodyWriter to write beans of this type as request content.
*
* @param type The type of the bean this writer is for
*/
BodyWriter beanWriter(Class type);
/**
- * Return a BodyWriter to write beans of this type as request content.
+ * BodyWriter to write beans of this type as request content.
*
* @param type The type of the bean this writer is for
*/
@@ -27,32 +23,32 @@ default BodyWriter beanWriter(Type type) {
}
/**
- * Return a BodyReader to read response content and convert to a bean.
+ * BodyReader to read response content and convert to a bean.
*
- * @param type The bean type to convert the content to.
+ * @param type type to convert the content to.
*/
BodyReader beanReader(Class type);
/**
- * Return a BodyReader to read response content and convert to a bean.
+ * BodyReader to read response content and convert to a bean.
*
- * @param type The bean type to convert the content to.
+ * @param type type to convert the content to.
*/
default BodyReader beanReader(Type type) {
throw new UnsupportedOperationException("java.lang.reflect.Type is not supported for this adapter");
}
/**
- * Return a BodyReader to read response content and convert to a list of beans.
+ * BodyReader to read response content and convert to a list of beans.
*
- * @param type The bean type to convert the content to.
+ * @param type type to convert the content to.
*/
BodyReader> listReader(Class type);
/**
- * Return a BodyReader to read response content and convert to a list of beans.
+ * BodyReader to read response content and convert to a list of beans.
*
- * @param type The bean type to convert the content to.
+ * @param type type to convert the content to.
*/
default BodyReader> listReader(Type type) {
throw new UnsupportedOperationException("java.lang.reflect.Type is not supported for this adapter");
diff --git a/http-client/src/main/java/io/avaje/http/client/BodyContent.java b/http-client/src/main/java/io/avaje/http/client/BodyContent.java
index 6e6f0e42..08f5f297 100644
--- a/http-client/src/main/java/io/avaje/http/client/BodyContent.java
+++ b/http-client/src/main/java/io/avaje/http/client/BodyContent.java
@@ -1,7 +1,7 @@
package io.avaje.http.client;
/**
- * Content of request or response body used for adapting to beans.
+ * Content of request or response body.
*
* This is not used for streaming content.
*/
diff --git a/http-client/src/main/java/io/avaje/http/client/HttpAsyncResponse.java b/http-client/src/main/java/io/avaje/http/client/HttpAsyncResponse.java
index f56b4481..1f5126b3 100644
--- a/http-client/src/main/java/io/avaje/http/client/HttpAsyncResponse.java
+++ b/http-client/src/main/java/io/avaje/http/client/HttpAsyncResponse.java
@@ -62,44 +62,38 @@
public interface HttpAsyncResponse {
/**
- * Process the response with check for 200 range status code
- * returning as {@literal HttpResponse}.
- *
- * Unlike {@link #asDiscarding()} this request will read any response
- * content as bytes with the view that the response content can be
- * an error message that could be read via for example
- * {@link HttpException#bean(Class)}.
- *
- * Will throw an HttpException if the status code is in the
- * error range allowing the caller to access the error message
- * body via for example {@link HttpException#bean(Class)}
- *
- * This is intended to be used for POST, PUT, DELETE requests
- * where the caller is only interested in the response body
- * when an error occurs (status code not in 200 range).
- *
- *
{@code
- *
- * client.request()
- * .path("hello/world")
- * .GET()
- * .async().asVoid()
- * .whenComplete((hres, throwable) -> {
- *
- * if (throwable != null) {
+ * Process the response with check for 200 range status code returning as {@literal
+ * HttpResponse}.
*
- * // if throwable.getCause() is a HttpException for status code >= 300
- * HttpException httpException = (HttpException) throwable.getCause();
- * int status = httpException.statusCode();
+ * Unlike {@link #asDiscarding()}, this request will read any response content as bytes with
+ * the view that the response content can be an error message that could be read via for example
+ * {@link HttpException#bean(Class)}.
*
- * // convert json error response body to a bean
- * ErrorResponse errorResponse = httpException.bean(ErrorResponse.class);
- * ...
- * } else {
- * int statusCode = hres.statusCode();
- * ...
- * }
- * });
+ * @throws HttpException if the status code is in the error range allowing the caller to access
+ * the error message body via for example {@link HttpException#bean(Class)}
+ *
This is intended to be used for POST, PUT, DELETE requests where the caller is only
+ * interested in the response body when an error occurs (status code not in 200 range).
+ *
{@code
+ * client.request()
+ * .path("hello/world")
+ * .GET()
+ * .async().asVoid()
+ * .whenComplete((hres, throwable) -> {
+ *
+ * if (throwable != null) {
+ *
+ * // if throwable.getCause() is a HttpException for status code >= 300
+ * HttpException httpException = (HttpException) throwable.getCause();
+ * int status = httpException.statusCode();
+ *
+ * // convert json error response body to a bean
+ * ErrorResponse errorResponse = httpException.bean(ErrorResponse.class);
+ * ...
+ * } else {
+ * int statusCode = hres.statusCode();
+ * ...
+ * }
+ * });
*
* }
*/
diff --git a/http-client/src/main/java/module-info.java b/http-client/src/main/java/module-info.java
index f8445cd8..07527a06 100644
--- a/http-client/src/main/java/module-info.java
+++ b/http-client/src/main/java/module-info.java
@@ -1,3 +1,24 @@
+/**
+ * Provides a HTTP client backed by java's built in {@link java.net.http.HttpClient} with support for adapting body content
+ * (like JSON) to java types.
+ *
+ * Uses the Java http client
+ *
+ *
{@code
+ *
+ * HttpClient client = HttpClient.builder()
+ * .baseUrl("http://localhost:8080")
+ * .bodyAdapter(new JacksonBodyAdapter())
+ * .build();
+ *
+ * HelloDto dto = client.request()
+ * .path("hello")
+ * .queryParam("say", "Whats up")
+ * .GET()
+ * .bean(HelloDto.class);
+ *
+ * }
+ */
module io.avaje.http.client {
uses io.avaje.http.client.HttpClient.GeneratedComponent;