Generate the project sources using the Helidon SE Maven archetype. The result is a simple project that can be used for the examples in this guide.

mvn -U archetype:generate -DinteractiveMode=false \
    -DarchetypeGroupId=io.helidon.archetypes \
    -DarchetypeArtifactId=helidon-quickstart-se \
    -DarchetypeVersion=3.2.16 \
    -DgroupId=io.helidon.examples \
    -DartifactId=helidon-quickstart-se \
    -Dpackage=io.helidon.examples.quickstart.se

You should now have a directory called helidon-quickstart-se.

cd helidon-quickstart-se

The Helidon quickstart is a greeting application supporting several HTTP requests such as GET and PUT. Using it will be time saving and allow us to focus on the WebClient features and how to use it.

In the pom.xml, remove the test scope under the WebClient dependency as it will be used not only in the tests.

<dependency>
    <groupId>io.helidon.webclient</groupId>
    <artifactId>helidon-webclient</artifactId>
    <scope>test</scope> <!--  Remove this line -->
</dependency>

In io.helidon.examples.quickstart.se package, create a new class named ClientExample. This class will use the WebClient to send request to the greeting application.

package io.helidon.examples.quickstart.se;

public class ClientExample {

    public static void main(String[] args) {

    }
}

Add the following code to create a WebClient instance. The builder approach allows you to create the WebClient with specific settings and improves the readability and simplicity of the code.

import io.helidon.media.jsonp.JsonpSupport;
import io.helidon.webclient.WebClient;

WebClient webClient = WebClient.builder()
                .baseUri("http://localhost:8080")   
                .addMediaSupport(JsonpSupport.create())     
                .build();

• The base URI of the outbound requests.
• Register a support for Jsonp.

By default, the Helidon quickstart application runs on localhost:8080. If you changed the host name or port number make sure to modify the base URI as well. Once built, the WebClient can be used to send a GET request to the greeting application.

webClient.get()     
    .path("/greet")     
    .request(String.class)  
    .peek(System.out::println)  
    .await();   

• Create a HTTP GET request.
• Target endpoint path.
• Execute the request and return Single with response entity handled as a String.
• Print the response in the console.
• Wait for server response because of reactive approach.

The path method joins /greet to the WebClient base URI. The target URI for this request becomes http://localhost:8080/greet where the response should be a greeting message. Received response entity will be automatically handled as a String. If no specific type is put into the method request(), WebClientResponse is returned by default. This WebClientResponse object contains response code, headers and non-handled entity.

mvn package

This command will create helidon-quickstart-se.jar in the target folder.

java -cp target/helidon-quickstart-se.jar io.helidon.examples.quickstart.se.Main

Open a new command prompt or terminal and run the ClientExample class you just created.

java -cp target/helidon-quickstart-se.jar io.helidon.examples.quickstart.se.ClientExample

{"message":"Hello World!"}

When the ClientExample finishes its execution, you can stop the Main class by pressing ctrl+c.

In practice, String is not the most useful return type, since it usually needs some more handling. In this case it could be more interesting to return an object such as JsonObject. In the previous step JSON support was added to the WebClient so that it could be used instead of String.

import javax.json.JsonObject;

webClient.get()
    .path("/greet/David")
    .request(JsonObject.class)  
    .peek(System.out::println)
    .await();

• Request a JsonObject as return value.

In the URI, the String following greet is a path parameter which allows the application to greet someone.

{"message":"Hello David!"}

This time, a JsonObject is printed out in the console. It is possible to change the greeting itself by using a PUT request to /greet/greeting endpoint from the base URI.

import javax.json.Json;

JsonObject entity = Json.createObjectBuilder() 
    .add("greeting", "Bonjour")
    .build();
webClient.put()     
    .path("/greet/greeting")
    .submit(entity)     
    .thenCompose(response -> webClient.get()    
        .path("/greet/David")
        .request(JsonObject.class))
    .thenAccept(System.out::println)
    .await();

• Create a JsonObject with key greeting and value bonjour.
• Create a PUT request.
• Submit the JsonObject created earlier.
• Once done, make a GET call to verify the modification was processed to the greeting.

According to the quickstart documentation, a JSON object can be sent to the application to change the greeting following this structure: {"greeting" : "value"}. The first three lines of code create the JsonObject with the required content. This time, we use the PUT request and submit methods to push the new greeting. One way to check the greeting modification is to execute GET request again and display obtained response. The thenCompose method will execute a GET request after the PUT request is executed.

{"message":"Bonjour David!"}

There is a specific dependency to use WebClient metrics in your application.

<dependency>
    <groupId>io.helidon.webclient</groupId>
    <artifactId>helidon-webclient-metrics</artifactId>
</dependency>

It is possible to register metrics on WebClient directly into the code. The following example shows a general method that can be used with any metric.

import io.helidon.common.http.Http;
import io.helidon.metrics.RegistryFactory;
import io.helidon.webclient.metrics.WebClientMetrics;
import io.helidon.webclient.spi.WebClientService;
import org.eclipse.microprofile.metrics.MetricRegistry;
import org.eclipse.microprofile.metrics|.Counter;
                                       |.Meter;
                                       |.Timer;
                                       |.ConcurrentGauge;

public static void main(String[] args) {

    MetricRegistry metricFactory = RegistryFactory.getInstance()
            .getRegistry(MetricRegistry.Type.APPLICATION);

    String metricName = "metric.GET.localhost";             

    Counter counter = metricFactory|.counter(metricName);   
                                   |.meter(metricName)
                                   |.timer(metricName)
                                   |.concurrentGauge(metricName)

    WebClientService clientServiceMetric = WebClientMetrics|.counter()
                                                           |.meter()
                                                           |.timer()
                                                           |.gaugeInProgress()

                    .methods(Http.Method.GET)           // OPTIONAL
                    .success(true)                      // OPTIONAL
                    .errors(true)                       // OPTIONAL
                    .description("Metric Description")  // OPTIONAL
                    .nameFormat("counter.%1$s.%2$s")
                    .build();                           

• Choose the metric name.
• Create a metric from metricFactory.
• Build a WebClient Service for counting the GET requests.

The metric name can indicate what is measured. In this example, the metric target GET requests on the localhost. In order to pass this information to the webclient, the nameFormat method extracts it from the metric name. Otherwise, the metric name can also have nothing in common with its job. In this case, the methods with OPTIONAL comment are not required to be used. The methods will target the chosen HTTP request type. While success and error will respectively measure if a request is successful or failed. The description will add a metric description.

WebClient webClient = WebClient.builder()
                .baseUri("http://localhost:8080")
                .addMediaSupport(JsonpSupport.create())
                .addService(clientServiceMetric)           
                .build();

• Register the metric service to the webclient.

Simply use the addService method to add the metric to the WebClient on which the metrics will be measured.

System.out.println(metricName + ": " + counter.getCount());

To quickly check metrics are set up correctly, print the counter at the end of the main method. In this guide, the WebClient uses GET and PUT requests, so metrics can be applied on.

Using the configuration file can reduce the code complexity and make the metrics simpler to use. There is no need to modify the source code but only the configuration file to measure other values. The application.yaml file is the default configuration file for Helidon. It can be used to set up metrics settings.

client:
  services:
    config:
      metrics:
        - type: METER
          name-format: "client.meter.overall"
        - type: TIMER
          # meter per method
          name-format: "client.meter.%1$s"
        - methods: ["GET"]
          type: COUNTER
          errors: false
          name-format: "client.counter.%1$s.success"
          description: "Counter of successful GET requests"
        - methods: ["PUT", "POST", "DELETE"]
          type: COUNTER
          success: false
          name-format: "wc.counter.%1$s.error"
          description: "Counter of failed PUT, POST and DELETE requests"
        - methods: ["GET"]
          type: GAUGE_IN_PROGRESS
          name-format: "client.inprogress.%2$s"
          description: "In progress requests to host"

The metrics are located under client.services.config.metrics. The metric setting can start either by its type or methods. The configuration file uses the same keywords as the programmatic way. type defines the kind of metric.

Config config = Config.create();       

WebClient webClient = WebClient.builder()
                .baseUri("http://localhost:8080")
                .config(config.get("client"))       
                .addMediaSupport(JsonpSupport.create())
                .build();

• Create a Helidon Config instance from default file application.yaml.
• Configure the WebClient with the client section from application.yaml.

As demonstrated, using the configuration file reduces the amount of code needed in the source code. For more information about metrics, see the Helidon Metrics Guide.