Skip to content

Update README to use HttpClient (from HttpClientContext) #141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 18, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 31 additions & 33 deletions http-client/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,7 @@
[![Maven Central](https://img.shields.io/maven-central/v/io.avaje/avaje-http-client.svg?label=Maven%20Central)](https://mvnrepository.com/artifact/io.avaje/avaje-http-client)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/avaje/avaje-http-client/blob/master/LICENSE)

# avaje-http-client

Documentation at [avaje.io/http-client](https://avaje.io/http-client/)
# [Avaje-HTTP-Client](https://avaje.io/http-client/)

A lightweight wrapper to the [JDK 11+ Java Http Client](http://openjdk.java.net/groups/net/httpclient/intro.html)

Expand All @@ -28,14 +26,14 @@ A lightweight wrapper to the [JDK 11+ Java Http Client](http://openjdk.java.net/
</dependency>
```

### Create HttpClientContext
### Create HttpClient

Create a HttpClientContext with a baseUrl, Jackson or Gson based JSON
Create a HttpClient with a baseUrl, Jackson or Gson based JSON
body adapter, logger.

```java
public HttpClientContext client() {
return HttpClientContext.builder()
public HttpClient client() {
return HttpClient.builder()
.baseUrl(baseUrl)
.bodyAdapter(new JsonbBodyAdapter())
//.bodyAdapter(new JacksonBodyAdapter(new ObjectMapper()))
Expand All @@ -47,7 +45,7 @@ Create a HttpClientContext with a baseUrl, Jackson or Gson based JSON

## Requests

From HttpClientContext:
From HttpClient:
- Create a request
- Build the url via path(), matrixParam(), queryParam()
- Optionally set headers(), cookies() etc
Expand Down Expand Up @@ -78,15 +76,15 @@ From HttpClientContext:

#### Example GET as String
```java
HttpResponse<String> hres = clientContext.request()
HttpResponse<String> hres = client.request()
.path("hello")
.GET()
.asString();
```

#### Example GET as JSON marshalling into a java class/dto
```java
CustomerDto customer = clientContext.request()
CustomerDto customer = client.request()
.path("customers").path(42)
.GET()
.bean(CustomerDto.class);
Expand All @@ -98,7 +96,7 @@ CustomerDto customer = clientContext.request()
- In the example below hres is of type HttpResponse&lt;String&gt;

```java
clientContext.request()
client.request()
.path("hello")
.GET()
.async().asString() // CompletableFuture<HttpResponse<String>>
Expand Down Expand Up @@ -173,7 +171,7 @@ When sending body content we can use:

#### GET as String
```java
HttpResponse<String> hres = clientContext.request()
HttpResponse<String> hres = client.request()
.path("hello")
.GET()
.asString();
Expand All @@ -185,7 +183,7 @@ HttpResponse<String> hres = clientContext.request()
- In the example below hres is of type HttpResponse&lt;String&gt;

```java
clientContext.request()
client.request()
.path("hello")
.GET()
.async().asString()
Expand All @@ -205,23 +203,23 @@ clientContext.request()

#### GET as json to single bean
```java
Customer customer = clientContext.request()
Customer customer = client.request()
.path("customers").path(42)
.GET()
.bean(Customer.class);
```

#### GET as json to a list of beans
```java
List<Customer> list = clientContext.request()
List<Customer> list = client.request()
.path("customers")
.GET()
.list(Customer.class);
```

#### GET as `application/x-json-stream` as a stream of beans
```java
Stream<Customer> stream = clientContext.request()
Stream<Customer> stream = client.request()
.path("customers/all")
.GET()
.stream(Customer.class);
Expand All @@ -232,7 +230,7 @@ Stream<Customer> stream = clientContext.request()
```java
Hello bean = new Hello(42, "rob", "other");

HttpResponse<Void> res = clientContext.request()
HttpResponse<Void> res = client.request()
.path("hello")
.body(bean)
.POST()
Expand All @@ -248,7 +246,7 @@ Multiple calls to `path()` append with a `/`. This is make it easier to build a
programmatically and also build paths that include `matrixParam()`

```java
HttpResponse<String> res = clientContext.request()
HttpResponse<String> res = client.request()
.path("customers")
.path("42")
.path("contacts")
Expand All @@ -257,15 +255,15 @@ HttpResponse<String> res = clientContext.request()

// is the same as ...

HttpResponse<String> res = clientContext.request()
HttpResponse<String> res = client.request()
.path("customers/42/contacts")
.GET()
.asString();
```

#### MatrixParam
```java
HttpResponse<String> httpRes = clientContext.request()
HttpResponse<String> httpRes = client.request()
.path("books")
.matrixParam("author", "rob")
.matrixParam("country", "nz")
Expand All @@ -277,7 +275,7 @@ HttpResponse<String> httpRes = clientContext.request()

#### QueryParam
```java
List<Product> beans = clientContext.request()
List<Product> beans = client.request()
.path("products")
.queryParam("sortBy", "name")
.queryParam("maxCount", "100")
Expand All @@ -287,7 +285,7 @@ List<Product> beans = clientContext.request()

#### FormParam
```java
HttpResponse<Void> res = clientContext.request()
HttpResponse<Void> res = client.request()
.path("register/user")
.formParam("name", "Bazz")
.formParam("email", "user@foo.com")
Expand Down Expand Up @@ -355,7 +353,7 @@ The `bean()`, `list()` and `stream()` responses throw a `HttpException` if the s

```java

clientContext.request()
client.request()
.path("hello/world")
.GET()
.async().asDiscarding()
Expand All @@ -374,7 +372,7 @@ clientContext.request()
### .async().asString() - HttpResponse&lt;String&gt;

```java
clientContext.request()
client.request()
.path("hello/world")
.GET()
.async().asString()
Expand All @@ -393,7 +391,7 @@ clientContext.request()
### .async().bean(HelloDto.class)

```java
clientContext.request()
client.request()
...
.POST().async()
.bean(HelloDto.class)
Expand All @@ -420,7 +418,7 @@ clientContext.request()
The example below is a line subscriber processing response content line by line.

```java
CompletableFuture<HttpResponse<Void>> future = clientContext.request()
CompletableFuture<HttpResponse<Void>> future = client.request()
.path("hello/lineStream")
.GET().async()
.handler(HttpResponse.BodyHandlers.fromLineSubscriber(new Flow.Subscriber<>() {
Expand Down Expand Up @@ -460,7 +458,7 @@ choose `async()` to execute the request asynchronously.

```java
HttpCall<List<Customer>> call =
clientContext.request()
client.request()
.path("customers")
.GET()
.call().list(Customer.class);
Expand All @@ -484,8 +482,8 @@ header ("Basic Auth").
##### Example

```java
HttpClientContext clientContext =
HttpClientContext.builder()
HttpClient client =
HttpClient.builder()
.baseUrl(baseUrl)
...
.requestIntercept(new BasicAuthIntercept("myUsername", "myPassword")) <!-- HERE
Expand All @@ -496,7 +494,7 @@ HttpClientContext clientContext =
## AuthTokenProvider - Authorization Bearer token

For Authorization using `Bearer` tokens that are obtained and expire, implement `AuthTokenProvider`
and register that when building the HttpClientContext.
and register that when building the HttpClient.

### 1. Implement AuthTokenProvider

Expand All @@ -520,10 +518,10 @@ and register that when building the HttpClientContext.
}
```

### 2. Register with HttpClientContext
### 2. Register with HttpClient

```java
HttpClientContext ctx = HttpClientContext.builder()
HttpClient client = HttpClient.builder()
.baseUrl("https://foo")
...
.authTokenProvider(new MyAuthTokenProvider()) <!-- HERE
Expand All @@ -532,7 +530,7 @@ and register that when building the HttpClientContext.

### 3. Token obtained and set automatically

All requests using the HttpClientContext will automatically get
All requests using the HttpClient will automatically get
an `Authorization` header with `Bearer` token added. The token will be
obtained for initial request and then renewed when the token has expired.

Expand Down