0
# Client Building and Configuration
1

2
Core client creation and configuration capabilities for establishing HTTP client instances with appropriate security, networking, and behavioral settings. This functionality provides the foundation for all Jersey Client operations.
3

4
## Capabilities
5

6
### Client Creation
7

8
Static factory methods for creating Jersey client instances with default or custom configurations.
9

10
```java { .api }
11
/**
12
 * Create a new Jersey client instance with default configuration
13
 * @return new configured Jersey client instance
14
 */
15
static JerseyClient createClient();
16

17
/**
18
 * Create a new Jersey client instance with custom configuration
19
 * @param configuration initial configuration for the client
20
 * @return new configured Jersey client instance
21
 */
22
static JerseyClient createClient(Configuration configuration);
23
```
24

25
**Usage Examples:**
26

27
```java
28
import org.glassfish.jersey.client.JerseyClientBuilder;
29
import org.glassfish.jersey.client.ClientConfig;
30

31
// Create client with default configuration
32
Client client = JerseyClientBuilder.createClient();
33

34
// Create client with custom configuration
35
ClientConfig config = new ClientConfig();
36
config.property(ClientProperties.CONNECT_TIMEOUT, 5000);
37
config.property(ClientProperties.READ_TIMEOUT, 10000);
38
Client customClient = JerseyClientBuilder.createClient(config);
39
```
40

41
### Client Builder
42

43
Builder pattern for comprehensive client configuration including SSL, authentication, timeouts, and provider registration.
44

45
```java { .api }
46
public class JerseyClientBuilder extends ClientBuilder {
47
    /**
48
     * Create new Jersey client builder instance
49
     */
50
    public JerseyClientBuilder();
51
    
52
    /**
53
     * Build the configured client instance
54
     * @return new configured Jersey client
55
     */
56
    public JerseyClient build();
57
    
58
    /**
59
     * Set SSL context for HTTPS connections
60
     * @param sslContext SSL context for secure connections
61
     * @return builder instance for method chaining
62
     */
63
    public JerseyClientBuilder sslContext(SSLContext sslContext);
64
    
65
    /**
66
     * Set hostname verifier for SSL connections
67
     * @param hostnameVerifier verifier for hostname validation
68
     * @return builder instance for method chaining
69
     */
70
    public JerseyClientBuilder hostnameVerifier(HostnameVerifier hostnameVerifier);
71
    
72
    /**
73
     * Set key store for client certificates
74
     * @param keyStore key store containing client certificates
75
     * @param password password for key store access
76
     * @return builder instance for method chaining
77
     */
78
    public JerseyClientBuilder keyStore(KeyStore keyStore, char[] password);
79
    
80
    /**
81
     * Set trust store for server certificate validation
82
     * @param trustStore trust store for validating server certificates
83
     * @return builder instance for method chaining
84
     */
85
    public JerseyClientBuilder trustStore(KeyStore trustStore);
86
    
87
    /**
88
     * Set connection timeout
89
     * @param timeout timeout value
90
     * @param unit time unit for timeout
91
     * @return builder instance for method chaining
92
     */
93
    public ClientBuilder connectTimeout(long timeout, TimeUnit unit);
94
    
95
    /**
96
     * Set read timeout
97
     * @param timeout timeout value
98
     * @param unit time unit for timeout
99
     * @return builder instance for method chaining
100
     */
101
    public ClientBuilder readTimeout(long timeout, TimeUnit unit);
102
    
103
    /**
104
     * Set executor service for asynchronous operations
105
     * @param executorService executor service for async operations
106
     * @return builder instance for method chaining
107
     */
108
    public ClientBuilder executorService(ExecutorService executorService);
109
    
110
    /**
111
     * Set scheduled executor service for background operations
112
     * @param scheduledExecutorService scheduled executor for background tasks
113
     * @return builder instance for method chaining
114
     */
115
    public ClientBuilder scheduledExecutorService(ScheduledExecutorService scheduledExecutorService);
116
    
117
    /**
118
     * Register provider class with the client
119
     * @param componentClass provider class to register
120
     * @return builder instance for method chaining
121
     */
122
    public JerseyClientBuilder register(Class<?> componentClass);
123
    
124
    /**
125
     * Register provider instance with the client
126
     * @param component provider instance to register
127
     * @return builder instance for method chaining
128
     */
129
    public JerseyClientBuilder register(Object component);
130
    
131
    /**
132
     * Register provider class with priority
133
     * @param componentClass provider class to register
134
     * @param priority registration priority
135
     * @return builder instance for method chaining
136
     */
137
    public JerseyClientBuilder register(Class<?> componentClass, int priority);
138
    
139
    /**
140
     * Register provider class with specific contracts
141
     * @param componentClass provider class to register
142
     * @param contracts contracts the provider implements
143
     * @return builder instance for method chaining
144
     */
145
    public JerseyClientBuilder register(Class<?> componentClass, Class<?>... contracts);
146
    
147
    /**
148
     * Set configuration property
149
     * @param name property name
150
     * @param value property value
151
     * @return builder instance for method chaining
152
     */
153
    public JerseyClientBuilder property(String name, Object value);
154
    
155
    /**
156
     * Apply configuration from another configuration instance
157
     * @param config configuration to apply
158
     * @return builder instance for method chaining
159
     */
160
    public JerseyClientBuilder withConfig(Configuration config);
161
}
162
```
163

164
**Usage Examples:**
165

166
```java
167
import javax.net.ssl.SSLContext;
168
import javax.net.ssl.HostnameVerifier;
169
import java.util.concurrent.TimeUnit;
170

171
// Configure client with SSL and timeouts
172
Client client = new JerseyClientBuilder()
173
    .sslContext(customSslContext)
174
    .hostnameVerifier(customHostnameVerifier)
175
    .connectTimeout(5, TimeUnit.SECONDS)
176
    .readTimeout(30, TimeUnit.SECONDS)
177
    .build();
178

179
// Configure client with authentication feature
180
Client authClient = new JerseyClientBuilder()
181
    .register(HttpAuthenticationFeature.basic("username", "password"))
182
    .property(ClientProperties.FOLLOW_REDIRECTS, true)
183
    .build();
184
```
185

186
### Client Configuration
187

188
Configuration management for Jersey client instances including property management and provider registration.
189

190
```java { .api }
191
public class ClientConfig implements Configurable<ClientConfig> {
192
    /**
193
     * Create new client configuration
194
     */
195
    public ClientConfig();
196
    
197
    /**
198
     * Create client configuration with provider classes
199
     * @param providerClasses provider classes to register
200
     */
201
    public ClientConfig(Class<?>... providerClasses);
202
    
203
    /**
204
     * Create client configuration with provider instances
205
     * @param providers provider instances to register
206
     */
207
    public ClientConfig(Object... providers);
208
    
209
    /**
210
     * Load configuration from another configuration instance
211
     * @param config configuration to load from
212
     * @return this configuration instance
213
     */
214
    public ClientConfig loadFrom(Configuration config);
215
    
216
    /**
217
     * Register provider class
218
     * @param providerClass provider class to register
219
     * @return this configuration instance
220
     */
221
    public ClientConfig register(Class<?> providerClass);
222
    
223
    /**
224
     * Register provider instance
225
     * @param provider provider instance to register
226
     * @return this configuration instance
227
     */
228
    public ClientConfig register(Object provider);
229
    
230
    /**
231
     * Set configuration property
232
     * @param name property name
233
     * @param value property value
234
     * @return this configuration instance
235
     */
236
    public ClientConfig property(String name, Object value);
237
    
238
    /**
239
     * Get configuration property value
240
     * @param name property name
241
     * @return property value or null if not set
242
     */
243
    public Object getProperty(String name);
244
    
245
    /**
246
     * Get all configuration properties
247
     * @return map of all properties
248
     */
249
    public Map<String, Object> getProperties();
250
    
251
    /**
252
     * Set connector provider for HTTP transport
253
     * @param connectorProvider connector provider implementation
254
     * @return this configuration instance
255
     */
256
    public ClientConfig connectorProvider(ConnectorProvider connectorProvider);
257
    
258
    /**
259
     * Get current connector provider
260
     * @return connector provider or null if not set
261
     */
262
    public ConnectorProvider getConnectorProvider();
263
    
264
    /**
265
     * Set executor service for asynchronous operations
266
     * @param executorService executor service for async operations
267
     * @return this configuration instance
268
     */
269
    public ClientConfig executorService(ExecutorService executorService);
270
    
271
    /**
272
     * Get executor service for asynchronous operations
273
     * @return executor service or null if not set
274
     */
275
    public ExecutorService getExecutorService();
276
    
277
    /**
278
     * Get runtime type (always CLIENT for client configurations)
279
     * @return RuntimeType.CLIENT
280
     */
281
    public RuntimeType getRuntimeType();
282
}
283
```
284

285
### Client Properties
286

287
Configuration property keys and utility methods for Jersey client configuration.
288

289
```java { .api }
290
public final class ClientProperties {
291
    // Connection and timeout properties
292
    public static final String FOLLOW_REDIRECTS = "jersey.config.client.followRedirects";
293
    public static final String READ_TIMEOUT = "jersey.config.client.readTimeout";
294
    public static final String CONNECT_TIMEOUT = "jersey.config.client.connectTimeout";
295
    
296
    // Chunked encoding properties
297
    public static final String CHUNKED_ENCODING_SIZE = "jersey.config.client.chunkedEncodingSize";
298
    public static final int DEFAULT_CHUNK_SIZE = 4096;
299
    
300
    // Thread pool properties
301
    public static final String ASYNC_THREADPOOL_SIZE = "jersey.config.client.async.threadPoolSize";
302
    public static final String BACKGROUND_SCHEDULER_THREADPOOL_SIZE = "jersey.config.client.backgroundSchedulerThreadPoolSize";
303
    
304
    // Content encoding properties
305
    public static final String USE_ENCODING = "jersey.config.client.useEncoding";
306
    
307
    // Error handling properties
308
    public static final String IGNORE_EXCEPTION_RESPONSE = "jersey.config.client.ignoreExceptionResponse";
309
    
310
    // Feature control properties
311
    public static final String FEATURE_AUTO_DISCOVERY_DISABLE = "jersey.config.disableAutoDiscovery";
312
    public static final String JSON_BINDING_FEATURE_DISABLE = "jersey.config.jsonBinding.disable";
313
    public static final String JSON_PROCESSING_FEATURE_DISABLE = "jersey.config.jsonProcessing.disable";
314
    public static final String MOXY_JSON_FEATURE_DISABLE = "jersey.config.client.disableMoxyJson";
315
    
316
    // HTTP properties
317
    public static final String SUPPRESS_HTTP_COMPLIANCE_VALIDATION = "jersey.config.client.suppressHttpComplianceValidation";
318
    public static final String EXPECT_100_CONTINUE = "jersey.config.client.httpUrlConnector.expect100Continue";
319
    public static final String EXPECT_100_CONTINUE_THRESHOLD_SIZE = "jersey.config.client.httpUrlConnector.expect100ContinueThreshold";
320
    public static final Long DEFAULT_EXPECT_100_CONTINUE_THRESHOLD_SIZE = 1024L;
321
    
322
    // Proxy properties
323
    public static final String PROXY_URI = "jersey.config.client.proxy.uri";
324
    public static final String PROXY_USERNAME = "jersey.config.client.proxy.username";
325
    public static final String PROXY_PASSWORD = "jersey.config.client.proxy.password";
326
    
327
    // Request processing properties
328
    public static final String REQUEST_ENTITY_PROCESSING = "jersey.config.client.request.entity.processing";
329
    public static final String OUTBOUND_CONTENT_LENGTH_BUFFER = "jersey.config.client.outbound.contentLength.buffer";
330
    
331
    // Query parameter style
332
    public static final String QUERY_PARAM_STYLE = "jersey.config.client.uri.query.param.style";
333
    
334
    // SSL properties
335
    public static final String SNI_HOST_NAME = "jersey.config.client.tls.sni.hostname";
336
    public static final String SSL_CONTEXT_SUPPLIER = "jersey.config.client.tls.sslContext.supplier";
337
    
338
    /**
339
     * Get typed property value with default
340
     * @param properties property map
341
     * @param key property key
342
     * @param defaultValue default value if property not found
343
     * @return property value or default
344
     */
345
    public static <T> T getValue(Map<String, ?> properties, String key, T defaultValue);
346
    
347
    /**
348
     * Get typed property value with type conversion
349
     * @param properties property map
350
     * @param key property key
351
     * @param defaultValue default value if property not found
352
     * @param type target type for conversion
353
     * @return converted property value or default
354
     */
355
    public static <T> T getValue(Map<String, ?> properties, String key, T defaultValue, Class<T> type);
356
}
357
```
358

359
**Usage Examples:**
360

361
```java
362
import org.glassfish.jersey.client.ClientProperties;
363

364
// Configure client with properties
365
ClientConfig config = new ClientConfig();
366
config.property(ClientProperties.CONNECT_TIMEOUT, 5000);
367
config.property(ClientProperties.READ_TIMEOUT, 30000);
368
config.property(ClientProperties.FOLLOW_REDIRECTS, true);
369
config.property(ClientProperties.CHUNKED_ENCODING_SIZE, 8192);
370

371
// Set proxy configuration
372
config.property(ClientProperties.PROXY_URI, "http://proxy.company.com:8080");
373
config.property(ClientProperties.PROXY_USERNAME, "proxyuser");
374
config.property(ClientProperties.PROXY_PASSWORD, "proxypass");
375

376
// Control request entity processing
377
config.property(ClientProperties.REQUEST_ENTITY_PROCESSING, RequestEntityProcessing.CHUNKED);
378

379
Client client = JerseyClientBuilder.createClient(config);
380
```
381

382
### SSL Configuration
383

384
SSL context building for secure HTTPS connections with support for custom key stores, trust stores, and SSL contexts.
385

386
```java { .api }
387
public class SslContextClientBuilder {
388
    /**
389
     * Create new SSL context builder
390
     */
391
    public SslContextClientBuilder();
392
    
393
    /**
394
     * Set custom SSL context
395
     * @param sslContext SSL context to use
396
     * @return this builder instance
397
     */
398
    public SslContextClientBuilder sslContext(SSLContext sslContext);
399
    
400
    /**
401
     * Set key store for client certificates
402
     * @param keyStore key store containing client certificates
403
     * @param password password for key store access
404
     * @return this builder instance
405
     */
406
    public SslContextClientBuilder keyStore(KeyStore keyStore, char[] password);
407
    
408
    /**
409
     * Set trust store for server certificate validation
410
     * @param trustStore trust store for validating server certificates
411
     * @return this builder instance
412
     */
413
    public SslContextClientBuilder trustStore(KeyStore trustStore);
414
    
415
    /**
416
     * Build SSL context from configuration
417
     * @return configured SSL context
418
     */
419
    public SSLContext get();
420
}
421
```
422

423
**Usage Examples:**
424

425
```java
426
import javax.net.ssl.SSLContext;
427
import java.security.KeyStore;
428

429
// Build SSL context with custom trust store
430
KeyStore trustStore = loadTrustStore();
431
SslContextClientBuilder sslBuilder = new SslContextClientBuilder()
432
    .trustStore(trustStore);
433

434
SSLContext sslContext = sslBuilder.get();
435

436
// Use with client builder
437
Client client = new JerseyClientBuilder()
438
    .sslContext(sslContext)
439
    .build();
440
```