or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-configuration.mdconnection-management.mdindex.mdprotocol-clients.mdrequests-responses.mdservice-integration.md
tile.json

tessl/maven-io-helidon-webclient--helidon-webclient

Helidon WebClient is a comprehensive HTTP client library for Java microservices supporting HTTP/1.1, HTTP/2, and protocol negotiation with virtual thread support.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.helidon.webclient/helidon-webclient@4.2.x

To install, run

npx @tessl/cli install tessl/maven-io-helidon-webclient--helidon-webclient@4.2.0

index.mddocs/

Helidon WebClient

Helidon WebClient is a comprehensive HTTP client library designed for Java microservices, providing flexible HTTP communication with support for multiple HTTP protocol versions (HTTP/1.1, HTTP/2), automatic version negotiation through ALPN, DNS resolution customization, proxy support, and built-in observability features. Built on Java 21 Virtual Threads, it delivers high throughput while supporting both blocking and reactive programming models.

Package Information

  • Package Name: helidon-webclient
  • Package Type: maven
  • Language: Java
  • Installation: Add to your Maven dependencies:
<dependency>
    <groupId>io.helidon.webclient</groupId>
    <artifactId>helidon-webclient</artifactId>
    <version>4.2.2</version>
</dependency>

Core Imports

import io.helidon.webclient.api.WebClient;
import io.helidon.webclient.api.HttpClient;
import io.helidon.webclient.api.HttpClientRequest;
import io.helidon.webclient.api.HttpClientResponse;
import io.helidon.webclient.api.WebClientConfig;
import io.helidon.webclient.api.ClientUri;
import io.helidon.webclient.api.Proxy;
import io.helidon.webclient.api.WebClientCookieManager;
import io.helidon.http.MediaType;
import java.time.Duration;
import java.util.function.Consumer;

Basic Usage

import io.helidon.webclient.api.WebClient;

// Create default client
WebClient client = WebClient.create();

// Simple GET request
String response = client.get("https://api.example.com/data")
    .requestEntity(String.class);

// POST request with JSON entity
MyResponse result = client.post("https://api.example.com/submit")
    .contentType(MediaType.APPLICATION_JSON)
    .submit(requestData, MyResponse.class)
    .entity();

// Configure client with custom settings
WebClient configuredClient = WebClient.builder()
    .baseUri("https://api.example.com")
    .addHeader("Authorization", "Bearer token")
    .readTimeout(Duration.ofSeconds(30))
    .followRedirects(true)
    .build();

Architecture

Helidon WebClient is designed around several key architectural components:

  • Multi-Protocol Support: Automatically selects HTTP/1.1 or HTTP/2 based on server capabilities and configuration
  • Protocol Negotiation: Uses ALPN (Application-Layer Protocol Negotiation) for TLS connections and HTTP upgrade mechanisms for plaintext
  • Virtual Thread Integration: Built on Java 21 Virtual Threads for high-throughput, non-blocking operations
  • Service Chain Architecture: Extensible interceptor pattern for adding cross-cutting concerns like authentication, logging, and metrics
  • Connection Management: Intelligent connection pooling and caching with configurable strategies
  • DNS Resolution: Pluggable DNS resolution with multiple strategies (default, first-available, round-robin)

Capabilities

Client Creation and Configuration

Core functionality for creating and configuring WebClient instances with various settings including base URIs, default headers, timeouts, and protocol preferences.

public interface WebClient extends HttpClient<HttpClientRequest> {
    static WebClient create();
    static WebClient create(WebClientConfig config);
    static WebClient create(Consumer<WebClientConfig.Builder> consumer);
    static WebClientConfig.Builder builder();
}

Client Creation and Configuration

HTTP Requests and Responses

Fluent API for building and executing HTTP requests with support for all HTTP methods, headers, query parameters, request bodies, and typed response handling.

public interface HttpClient<REQ extends ClientRequest<REQ>> {
    REQ method(Method method);
    default REQ get(String uri);
    default REQ post(String uri);
    default REQ put(String uri);
    default REQ delete(String uri);
}

public interface ClientRequest<T> {
    T uri(String uri);
    T header(HeaderName name, String... values);
    T queryParam(String name, String... values);
    T contentType(MediaType contentType);
    HttpClientResponse request();
    HttpClientResponse submit(Object entity);
    <E> E requestEntity(Class<E> type);
}

HTTP Requests and Responses

Protocol-Specific Clients

Access to protocol-specific functionality including HTTP/1.1 features like protocol upgrades, HTTP/2 specific capabilities, and non-HTTP protocols like WebSocket and gRPC.

public interface WebClient {
    <T, C extends ProtocolConfig> T client(Protocol<T, C> protocol);
    <T, C extends ProtocolConfig> T client(Protocol<T, C> protocol, C protocolConfig);
}

Protocol-Specific Clients

Connection Management

Advanced connection handling including custom connections, connection caching, proxy support, TLS configuration, and DNS resolution strategies.

public interface ClientConnection extends ReleasableResource {
    DataReader reader();
    DataWriter writer();
    String channelId();
    HelidonSocket helidonSocket();
    void readTimeout(Duration readTimeout);
}

public interface DnsAddressLookup {
    List<InetAddress> listAddresses(String hostname);
    static DnsAddressLookup defaultLookup();
    static DnsAddressLookup roundRobin();
}

Connection Management

Service Integration

Client-side interceptors and middleware for adding cross-cutting concerns like authentication, logging, metrics, tracing, and custom request/response processing.

@FunctionalInterface
public interface WebClientService extends NamedService {
    WebClientServiceResponse handle(Chain chain, WebClientServiceRequest clientRequest);
    
    interface Chain {
        WebClientServiceResponse proceed(WebClientServiceRequest clientRequest);
    }
}

Service Integration

Types

public interface WebClientConfig extends HttpClientConfig {
    List<ProtocolConfig> protocolConfigs();
    List<String> protocolPreference();
}

public interface HttpClientConfig {
    Optional<ClientUri> baseUri();
    Duration readTimeout();
    boolean followRedirects();
    int maxRedirects();
    Optional<Proxy> proxy();
    SocketOptions socketOptions();
    DnsResolver dnsResolver();
    ExecutorService executor();
    List<WebClientService> services();
    Optional<WebClientCookieManager> cookieManager();
}

public class ClientUri implements UriInfo {
    static ClientUri create();
    static ClientUri create(URI baseUri);
    ClientUri scheme(String scheme);
    ClientUri host(String host);
    ClientUri port(int port);
    ClientUri path(String path);
    ClientUri queryParam(String name, String... values);
    URI toUri();
}

public class Proxy {
    static Builder builder();
    static Proxy noProxy();
    static Proxy create();
    ProxyType type();
    String host();
    int port();
    
    enum ProxyType { NONE, SYSTEM, HTTP }
}

public interface HttpClientResponse extends ClientResponseBase, AutoCloseable {
    ReadableEntity entity();
    default InputStream inputStream();
    default <T> T as(Class<T> type);
}

public interface ClientResponseBase {
    Status status();
    ClientResponseHeaders headers();
    Optional<MediaType> contentType();
    long contentLength();
}

public class WebClientCookieManager extends CookieManager {
    static WebClientCookieManager create(WebClientCookieManagerConfig config);
    static WebClientCookieManager create(Consumer<WebClientCookieManagerConfig.Builder> configConsumer);
    static WebClientCookieManagerConfig.Builder builder();
    
    void request(ClientUri uri, ClientRequestHeaders requestHeaders);
    void response(ClientUri uri, ClientResponseHeaders headers);
}

public interface WebClientCookieManagerConfig {
    boolean automaticStoreEnabled();
    CookiePolicy cookiePolicy();
    Map<String, String> defaultCookies();
    Optional<CookieStore> cookieStore();
}