CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

—

Pending
Overview
Eval results
Files

client-configuration.mddocs/

Client Creation and Configuration

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

Capabilities

WebClient Creation

Factory methods for creating WebClient instances with different configuration approaches.

/**
 * Create a new web client with default configuration
 * @return a new web client instance
 */
public static WebClient create();

/**
 * Create a new web client with custom configuration
 * @param config configuration to use
 * @return a new web client instance
 */
public static WebClient create(WebClientConfig config);

/**
 * Create a new web client, customizing its configuration
 * @param consumer configuration consumer
 * @return a new web client instance
 */
public static WebClient create(Consumer<WebClientConfig.Builder> consumer);

/**
 * Create a new builder for WebClient configuration
 * @return new HTTP client builder
 */
public static WebClientConfig.Builder builder();

Usage Examples:

import io.helidon.webclient.api.WebClient;
import io.helidon.webclient.api.WebClientConfig;
import java.time.Duration;

// Default client
WebClient client = WebClient.create();

// Client with lambda configuration
WebClient client = WebClient.create(builder -> builder
    .baseUri("https://api.example.com")
    .readTimeout(Duration.ofSeconds(30))
    .followRedirects(true)
    .addHeader("User-Agent", "MyApp/1.0"));

// Client with pre-built configuration
WebClientConfig config = WebClientConfig.builder()
    .baseUri("https://api.example.com")
    .readTimeout(Duration.ofSeconds(30))
    .build();
WebClient client = WebClient.create(config);

Configuration Builder

Fluent builder interface for constructing WebClient configurations.

public interface WebClientConfig.Builder {
    // Base configuration
    WebClientConfig.Builder baseUri(String uri);
    WebClientConfig.Builder baseUri(URI uri);
    WebClientConfig.Builder baseUri(ClientUri uri);
    
    // Timeout configuration
    WebClientConfig.Builder readTimeout(Duration readTimeout);
    WebClientConfig.Builder readContinueTimeout(Duration readContinueTimeout);
    
    // Redirect configuration
    WebClientConfig.Builder followRedirects(boolean followRedirects);
    WebClientConfig.Builder maxRedirects(int maxRedirects);
    
    // Header configuration
    WebClientConfig.Builder addHeader(String name, String value);
    WebClientConfig.Builder addHeader(HeaderName name, String value);
    WebClientConfig.Builder headers(Consumer<ClientRequestHeaders> headersConsumer);
    
    // Protocol configuration
    WebClientConfig.Builder addProtocolPreference(List<String> protocolPreference);
    WebClientConfig.Builder addProtocolConfig(ProtocolConfig protocolConfig);
    
    // Connection configuration
    WebClientConfig.Builder connectionCacheSize(int connectionCacheSize);
    WebClientConfig.Builder shareConnectionCache(boolean shareConnectionCache);
    WebClientConfig.Builder keepAlive(boolean keepAlive);
    
    // Build the configuration
    WebClientConfig build();
}

Base URI Configuration

Configure the base URI that will be used for relative request URIs.

/**
 * Configure base URI for all requests
 * @param uri base URI as string
 * @return builder instance
 */
WebClientConfig.Builder baseUri(String uri);

/**
 * Configure base URI for all requests
 * @param uri base URI as java.net.URI
 * @return builder instance
 */
WebClientConfig.Builder baseUri(URI uri);

/**
 * Configure base URI for all requests
 * @param uri base URI as ClientUri
 * @return builder instance
 */
WebClientConfig.Builder baseUri(ClientUri uri);

Usage Examples:

WebClient client = WebClient.builder()
    .baseUri("https://api.example.com/v1")
    .build();

// Requests will resolve against base URI
String result = client.get("/users").requestEntity(String.class);
// Actual request: GET https://api.example.com/v1/users

Timeout Configuration

Configure read timeouts and 100-Continue timeouts for requests.

/**
 * Configure default read timeout for requests
 * @param readTimeout timeout duration
 * @return builder instance
 */
WebClientConfig.Builder readTimeout(Duration readTimeout);

/**
 * Configure timeout for reading 100-Continue responses
 * @param readContinueTimeout timeout duration
 * @return builder instance
 */
WebClientConfig.Builder readContinueTimeout(Duration readContinueTimeout);

Redirect Configuration

Configure automatic redirect following behavior.

/**
 * Configure whether to follow redirects automatically
 * @param followRedirects true to follow redirects
 * @return builder instance
 */
WebClientConfig.Builder followRedirects(boolean followRedirects);

/**
 * Configure maximum number of redirects to follow
 * @param maxRedirects maximum redirect count
 * @return builder instance
 */
WebClientConfig.Builder maxRedirects(int maxRedirects);

Default Headers Configuration

Configure headers that will be sent with all requests from this client.

/**
 * Add a header that will be sent with all requests
 * @param name header name
 * @param value header value
 * @return builder instance
 */
WebClientConfig.Builder addHeader(String name, String value);

/**
 * Add a header that will be sent with all requests
 * @param name header name (using HeaderName type for better type safety)
 * @param value header value
 * @return builder instance
 */
WebClientConfig.Builder addHeader(HeaderName name, String value);

/**
 * Configure default headers using a consumer
 * @param headersConsumer consumer to configure headers
 * @return builder instance
 */
WebClientConfig.Builder headers(Consumer<ClientRequestHeaders> headersConsumer);

Usage Examples:

WebClient client = WebClient.builder()
    .addHeader("Authorization", "Bearer " + token)
    .addHeader("Accept", "application/json")
    .addHeader("User-Agent", "MyApp/1.0")
    .headers(headers -> {
        headers.add("X-API-Version", "v1");
        headers.add("X-Client-ID", clientId);
    })
    .build();

Protocol Configuration

Configure HTTP protocol preferences and protocol-specific settings.

/**
 * Configure HTTP protocol preference order for ALPN negotiation
 * @param protocolPreference list of protocol identifiers in preference order
 * @return builder instance
 */
WebClientConfig.Builder addProtocolPreference(List<String> protocolPreference);

/**
 * Add protocol-specific configuration
 * @param protocolConfig configuration for specific protocol
 * @return builder instance
 */
WebClientConfig.Builder addProtocolConfig(ProtocolConfig protocolConfig);

Usage Examples:

import io.helidon.webclient.http2.Http2ClientProtocolConfig;

WebClient client = WebClient.builder()
    // Prefer HTTP/2, fall back to HTTP/1.1
    .addProtocolPreference(List.of("h2", "http/1.1"))
    // Configure HTTP/2 specific settings
    .addProtocolConfig(Http2ClientProtocolConfig.builder()
        .maxFrameSize(32768)
        .build())
    .build();

Connection Configuration

Configure connection pooling, caching, and keep-alive behavior.

/**
 * Configure maximum number of cached connections
 * @param connectionCacheSize maximum cached connections
 * @return builder instance
 */
WebClientConfig.Builder connectionCacheSize(int connectionCacheSize);

/**
 * Configure whether to share connection cache across WebClient instances
 * @param shareConnectionCache true to share cache
 * @return builder instance
 */
WebClientConfig.Builder shareConnectionCache(boolean shareConnectionCache);

/**
 * Configure TCP keep-alive for connections
 * @param keepAlive true to enable keep-alive
 * @return builder instance
 */
WebClientConfig.Builder keepAlive(boolean keepAlive);

Proxy Configuration

Configure proxy settings for the client.

/**
 * Configure proxy for requests
 * @param proxy proxy configuration
 * @return builder instance
 */
WebClientConfig.Builder proxy(Proxy proxy);

Usage Examples:

import io.helidon.webclient.api.Proxy;

// HTTP proxy
WebClient client = WebClient.builder()
    .proxy(Proxy.builder()
        .type(Proxy.ProxyType.HTTP)
        .host("proxy.example.com")
        .port(8080)
        .username("user")
        .password("pass".toCharArray())
        .build())
    .build();

// System proxy (uses system properties)
WebClient client = WebClient.builder()
    .proxy(Proxy.create())
    .build();

// No proxy
WebClient client = WebClient.builder()
    .proxy(Proxy.noProxy())
    .build();

Executor Configuration

Configure the executor service used for asynchronous operations.

/**
 * Configure executor service for async operations
 * @param executor custom executor service
 * @return builder instance
 */
WebClientConfig.Builder executor(ExecutorService executor);

Service Configuration

Configure client services (interceptors) that will process all requests and responses.

/**
 * Add a client service to the service chain
 * @param service client service implementation
 * @return builder instance
 */
WebClientConfig.Builder addService(WebClientService service);

/**
 * Configure all client services
 * @param services list of client services
 * @return builder instance
 */
WebClientConfig.Builder services(List<WebClientService> services);

Usage Examples:

import io.helidon.webclient.spi.WebClientService;

WebClient client = WebClient.builder()
    .addService(new LoggingService())
    .addService(new AuthenticationService())
    .addService(new MetricsService())
    .build();

Cookie Management

Configure cookie handling for the client.

/**
 * Configure cookie manager for automatic cookie handling
 * @param cookieManager cookie manager instance
 * @return builder instance
 */
WebClientConfig.Builder cookieManager(WebClientCookieManager cookieManager);

Usage Examples:

import io.helidon.webclient.api.WebClientCookieManager;

WebClient client = WebClient.builder()
    .cookieManager(WebClientCookieManager.create())
    .build();

Types

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

public interface HttpClientConfig {
    Optional<ClientUri> baseUri();
    Optional<UriQuery> baseQuery();
    Optional<UriFragment> baseFragment();
    Duration readTimeout();
    boolean followRedirects();
    int maxRedirects();
    Optional<Proxy> proxy();
    SocketOptions socketOptions();
    DnsResolver dnsResolver();
    DnsAddressLookup dnsAddressLookup();
    Set<Header> headers();
    ClientRequestHeaders defaultRequestHeaders();
    ExecutorService executor();
    List<WebClientService> services();
    int connectionCacheSize();
    boolean shareConnectionCache();
    boolean keepAlive();
    Optional<WebClientCookieManager> cookieManager();
    Duration readContinueTimeout();
    boolean sendExpectContinue();
    int maxInMemoryEntity();
    int writeBufferSize();
    MediaContext mediaContext();
    List<MediaSupport> mediaSupports();
    ContentEncodingContext contentEncoding();
}

Install with Tessl CLI

npx tessl i tessl/maven-io-helidon-webclient--helidon-webclient

docs

client-configuration.md

connection-management.md

index.md

protocol-clients.md

requests-responses.md

service-integration.md

tile.json