Helidon WebClient

The new Helidon WebClient for Helidon SE 2.0 allows you to perform any HTTP requests to the target endpoint (via GET, PUT, etc.), and handle the provided response in a reactive way. The WebClient’s reactive approach means that you are no longer blocked while waiting for the data.

The experimental version of the Helidon WebClient is included in the 2.0.0 release. You can download it from Maven Central Repository, or by including the following dependency in your project’s pom.xml.

<dependency>
    <groupId>io.helidon.webclient</groupId>
    <artifactId>helidon-webclient</artifactId>
    <version>2.0.0</version>
</dependency>

Note: WebClient is still experimental and not intended for production use. APIs and features are not yet fully tested and are subject to change.

Features Overview

The Helidon 2.0 WebClient includes the following features:

• Reactive approach
  Every executed request and response is handled in a reactive way. You will no longer have to wait for the server response. When the response is received, the client requests only the amount of data it can handle at that time. Therefore, the memory is not overflowed.
• Simple, builder-like setup and execution
  Every client and request is created by a builder pattern, so it improves readability and code maintenance.
• Following redirects
  The WebClient is able to follow the redirect chain and perform requests on the correct endpoint for you. You no longer have to point your client to the correct/final endpoint.
• Tracing, metrics and security propagation
  When you configure the Helidon WebServer to use tracing, metrics and security, the settings are automatically propagated to the WebClient and used during request/response.

The Helidon WebClient is designed with simplicity in mind. The example below demonstrates a simple GET request to ‘target’ endpoint:

WebClient client = WebClient.builder()
        .baseUri("http://localhost")
        .build();

Single<String> response = webClient.get()
        .path("/endpoint")
        .request(String.class);

In this next example you can see that JsonObject is now being used as the return type. Since JsonObject processing is not present in the WebClient by default, it needs to be registered to the client builder using the corresponding add method as shown below:

WebClient client = WebClient.builder()
        .baseUri("http://localhost")
        //Register only JSON-P reader
        .addReader(JsonpSupport.reader())
        //Register only JSON-P writer
        .addWriter(JsonpSupport.writer())
        //Register both JSON-P reader and writer
        .addMediaSupport(JsonpSupport.create())
        .build();

You can now make requests to the endpoint using various methods such as GET or PUT.

JsonObject entity = //some JsonObject entity
WebClient client = WebClient.builder()
        .baseUri("http://localhost")
        .addMediaSupport(JsonpSupport.create())
        .build();

Single<JsonObject> responseGet = webClient.get()
        .path("/endpoint")
        .request(JsonObject.class);
Single<WebClientResponse> responsePut = webClient.put()
        .path("/endpoint")
        .submit(entity);

The Helidon WebClient is also highly configurable. While the default configuration is suitable for most common use cases, you can also configure it to handle your specific requirements as shown in the examples below:

Config config = Config.create();
WebClient client = WebClient.builder()
        .baseUri("http://localhost")
        .config(config.get("client"))
        .build();

Or, using Helidon configuration such as yaml file:

client:
  connect-timeout-millis: 2000
  read-timeout-millis: 2000
  follow-redirects: true
  max-redirects: 5
  headers:
    - name: "Accept"
        value: ["application/json","text/plain"]
  services:
    exclude: ["some.webclient.service.Provider"]
    config:
      metrics:
        - methods: ["PUT", "POST", "DELETE"]
          type: COUNTER
          name-format: "client.counter.%1$s.%2$s"

This is a simplified configuration for the example. You can find a full version of the config here.

Samples

A sample project that shows you how to use the WebClient can be found in the Helidon repository. These samples will give you a better understanding of how to use WebClient.

Summary

Helidon WebClient is still an experimental feature. Before making it final we need your feedback. Please try it and let us know how we can improve it by leaving a comment to this article, as an issue in our issues tracker or in our official Slack channel.