0
# Client Creation and Configuration
1

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

4
## Capabilities
5

6
### WebClient Creation
7

8
Factory methods for creating WebClient instances with different configuration approaches.
9

10
```java { .api }
11
/**
12
 * Create a new web client with default configuration
13
 * @return a new web client instance
14
 */
15
public static WebClient create();
16

17
/**
18
 * Create a new web client with custom configuration
19
 * @param config configuration to use
20
 * @return a new web client instance
21
 */
22
public static WebClient create(WebClientConfig config);
23

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

31
/**
32
 * Create a new builder for WebClient configuration
33
 * @return new HTTP client builder
34
 */
35
public static WebClientConfig.Builder builder();
36
```
37

38
**Usage Examples:**
39

40
```java
41
import io.helidon.webclient.api.WebClient;
42
import io.helidon.webclient.api.WebClientConfig;
43
import java.time.Duration;
44

45
// Default client
46
WebClient client = WebClient.create();
47

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

55
// Client with pre-built configuration
56
WebClientConfig config = WebClientConfig.builder()
57
    .baseUri("https://api.example.com")
58
    .readTimeout(Duration.ofSeconds(30))
59
    .build();
60
WebClient client = WebClient.create(config);
61
```
62

63
### Configuration Builder
64

65
Fluent builder interface for constructing WebClient configurations.
66

67
```java { .api }
68
public interface WebClientConfig.Builder {
69
    // Base configuration
70
    WebClientConfig.Builder baseUri(String uri);
71
    WebClientConfig.Builder baseUri(URI uri);
72
    WebClientConfig.Builder baseUri(ClientUri uri);
73
    
74
    // Timeout configuration
75
    WebClientConfig.Builder readTimeout(Duration readTimeout);
76
    WebClientConfig.Builder readContinueTimeout(Duration readContinueTimeout);
77
    
78
    // Redirect configuration
79
    WebClientConfig.Builder followRedirects(boolean followRedirects);
80
    WebClientConfig.Builder maxRedirects(int maxRedirects);
81
    
82
    // Header configuration
83
    WebClientConfig.Builder addHeader(String name, String value);
84
    WebClientConfig.Builder addHeader(HeaderName name, String value);
85
    WebClientConfig.Builder headers(Consumer<ClientRequestHeaders> headersConsumer);
86
    
87
    // Protocol configuration
88
    WebClientConfig.Builder addProtocolPreference(List<String> protocolPreference);
89
    WebClientConfig.Builder addProtocolConfig(ProtocolConfig protocolConfig);
90
    
91
    // Connection configuration
92
    WebClientConfig.Builder connectionCacheSize(int connectionCacheSize);
93
    WebClientConfig.Builder shareConnectionCache(boolean shareConnectionCache);
94
    WebClientConfig.Builder keepAlive(boolean keepAlive);
95
    
96
    // Build the configuration
97
    WebClientConfig build();
98
}
99
```
100

101
### Base URI Configuration
102

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

105
```java { .api }
106
/**
107
 * Configure base URI for all requests
108
 * @param uri base URI as string
109
 * @return builder instance
110
 */
111
WebClientConfig.Builder baseUri(String uri);
112

113
/**
114
 * Configure base URI for all requests
115
 * @param uri base URI as java.net.URI
116
 * @return builder instance
117
 */
118
WebClientConfig.Builder baseUri(URI uri);
119

120
/**
121
 * Configure base URI for all requests
122
 * @param uri base URI as ClientUri
123
 * @return builder instance
124
 */
125
WebClientConfig.Builder baseUri(ClientUri uri);
126
```
127

128
**Usage Examples:**
129

130
```java
131
WebClient client = WebClient.builder()
132
    .baseUri("https://api.example.com/v1")
133
    .build();
134

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

140
### Timeout Configuration
141

142
Configure read timeouts and 100-Continue timeouts for requests.
143

144
```java { .api }
145
/**
146
 * Configure default read timeout for requests
147
 * @param readTimeout timeout duration
148
 * @return builder instance
149
 */
150
WebClientConfig.Builder readTimeout(Duration readTimeout);
151

152
/**
153
 * Configure timeout for reading 100-Continue responses
154
 * @param readContinueTimeout timeout duration
155
 * @return builder instance
156
 */
157
WebClientConfig.Builder readContinueTimeout(Duration readContinueTimeout);
158
```
159

160
### Redirect Configuration
161

162
Configure automatic redirect following behavior.
163

164
```java { .api }
165
/**
166
 * Configure whether to follow redirects automatically
167
 * @param followRedirects true to follow redirects
168
 * @return builder instance
169
 */
170
WebClientConfig.Builder followRedirects(boolean followRedirects);
171

172
/**
173
 * Configure maximum number of redirects to follow
174
 * @param maxRedirects maximum redirect count
175
 * @return builder instance
176
 */
177
WebClientConfig.Builder maxRedirects(int maxRedirects);
178
```
179

180
### Default Headers Configuration
181

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

184
```java { .api }
185
/**
186
 * Add a header that will be sent with all requests
187
 * @param name header name
188
 * @param value header value
189
 * @return builder instance
190
 */
191
WebClientConfig.Builder addHeader(String name, String value);
192

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

201
/**
202
 * Configure default headers using a consumer
203
 * @param headersConsumer consumer to configure headers
204
 * @return builder instance
205
 */
206
WebClientConfig.Builder headers(Consumer<ClientRequestHeaders> headersConsumer);
207
```
208

209
**Usage Examples:**
210

211
```java
212
WebClient client = WebClient.builder()
213
    .addHeader("Authorization", "Bearer " + token)
214
    .addHeader("Accept", "application/json")
215
    .addHeader("User-Agent", "MyApp/1.0")
216
    .headers(headers -> {
217
        headers.add("X-API-Version", "v1");
218
        headers.add("X-Client-ID", clientId);
219
    })
220
    .build();
221
```
222

223
### Protocol Configuration
224

225
Configure HTTP protocol preferences and protocol-specific settings.
226

227
```java { .api }
228
/**
229
 * Configure HTTP protocol preference order for ALPN negotiation
230
 * @param protocolPreference list of protocol identifiers in preference order
231
 * @return builder instance
232
 */
233
WebClientConfig.Builder addProtocolPreference(List<String> protocolPreference);
234

235
/**
236
 * Add protocol-specific configuration
237
 * @param protocolConfig configuration for specific protocol
238
 * @return builder instance
239
 */
240
WebClientConfig.Builder addProtocolConfig(ProtocolConfig protocolConfig);
241
```
242

243
**Usage Examples:**
244

245
```java
246
import io.helidon.webclient.http2.Http2ClientProtocolConfig;
247

248
WebClient client = WebClient.builder()
249
    // Prefer HTTP/2, fall back to HTTP/1.1
250
    .addProtocolPreference(List.of("h2", "http/1.1"))
251
    // Configure HTTP/2 specific settings
252
    .addProtocolConfig(Http2ClientProtocolConfig.builder()
253
        .maxFrameSize(32768)
254
        .build())
255
    .build();
256
```
257

258
### Connection Configuration
259

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

262
```java { .api }
263
/**
264
 * Configure maximum number of cached connections
265
 * @param connectionCacheSize maximum cached connections
266
 * @return builder instance
267
 */
268
WebClientConfig.Builder connectionCacheSize(int connectionCacheSize);
269

270
/**
271
 * Configure whether to share connection cache across WebClient instances
272
 * @param shareConnectionCache true to share cache
273
 * @return builder instance
274
 */
275
WebClientConfig.Builder shareConnectionCache(boolean shareConnectionCache);
276

277
/**
278
 * Configure TCP keep-alive for connections
279
 * @param keepAlive true to enable keep-alive
280
 * @return builder instance
281
 */
282
WebClientConfig.Builder keepAlive(boolean keepAlive);
283
```
284

285
### Proxy Configuration
286

287
Configure proxy settings for the client.
288

289
```java { .api }
290
/**
291
 * Configure proxy for requests
292
 * @param proxy proxy configuration
293
 * @return builder instance
294
 */
295
WebClientConfig.Builder proxy(Proxy proxy);
296
```
297

298
**Usage Examples:**
299

300
```java
301
import io.helidon.webclient.api.Proxy;
302

303
// HTTP proxy
304
WebClient client = WebClient.builder()
305
    .proxy(Proxy.builder()
306
        .type(Proxy.ProxyType.HTTP)
307
        .host("proxy.example.com")
308
        .port(8080)
309
        .username("user")
310
        .password("pass".toCharArray())
311
        .build())
312
    .build();
313

314
// System proxy (uses system properties)
315
WebClient client = WebClient.builder()
316
    .proxy(Proxy.create())
317
    .build();
318

319
// No proxy
320
WebClient client = WebClient.builder()
321
    .proxy(Proxy.noProxy())
322
    .build();
323
```
324

325
### Executor Configuration
326

327
Configure the executor service used for asynchronous operations.
328

329
```java { .api }
330
/**
331
 * Configure executor service for async operations
332
 * @param executor custom executor service
333
 * @return builder instance
334
 */
335
WebClientConfig.Builder executor(ExecutorService executor);
336
```
337

338
### Service Configuration
339

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

342
```java { .api }
343
/**
344
 * Add a client service to the service chain
345
 * @param service client service implementation
346
 * @return builder instance
347
 */
348
WebClientConfig.Builder addService(WebClientService service);
349

350
/**
351
 * Configure all client services
352
 * @param services list of client services
353
 * @return builder instance
354
 */
355
WebClientConfig.Builder services(List<WebClientService> services);
356
```
357

358
**Usage Examples:**
359

360
```java
361
import io.helidon.webclient.spi.WebClientService;
362

363
WebClient client = WebClient.builder()
364
    .addService(new LoggingService())
365
    .addService(new AuthenticationService())
366
    .addService(new MetricsService())
367
    .build();
368
```
369

370
### Cookie Management
371

372
Configure cookie handling for the client.
373

374
```java { .api }
375
/**
376
 * Configure cookie manager for automatic cookie handling
377
 * @param cookieManager cookie manager instance
378
 * @return builder instance
379
 */
380
WebClientConfig.Builder cookieManager(WebClientCookieManager cookieManager);
381
```
382

383
**Usage Examples:**
384

385
```java
386
import io.helidon.webclient.api.WebClientCookieManager;
387

388
WebClient client = WebClient.builder()
389
    .cookieManager(WebClientCookieManager.create())
390
    .build();
391
```
392

393
## Types
394

395
```java { .api }
396
public interface WebClientConfig extends HttpClientConfig {
397
    List<ProtocolConfig> protocolConfigs();
398
    List<String> protocolPreference();
399
}
400

401
public interface HttpClientConfig {
402
    Optional<ClientUri> baseUri();
403
    Optional<UriQuery> baseQuery();
404
    Optional<UriFragment> baseFragment();
405
    Duration readTimeout();
406
    boolean followRedirects();
407
    int maxRedirects();
408
    Optional<Proxy> proxy();
409
    SocketOptions socketOptions();
410
    DnsResolver dnsResolver();
411
    DnsAddressLookup dnsAddressLookup();
412
    Set<Header> headers();
413
    ClientRequestHeaders defaultRequestHeaders();
414
    ExecutorService executor();
415
    List<WebClientService> services();
416
    int connectionCacheSize();
417
    boolean shareConnectionCache();
418
    boolean keepAlive();
419
    Optional<WebClientCookieManager> cookieManager();
420
    Duration readContinueTimeout();
421
    boolean sendExpectContinue();
422
    int maxInMemoryEntity();
423
    int writeBufferSize();
424
    MediaContext mediaContext();
425
    List<MediaSupport> mediaSupports();
426
    ContentEncodingContext contentEncoding();
427
}
428
```