0
# Request Execution
1

2
HTTP request building and execution capabilities providing comprehensive support for all standard HTTP methods, custom headers, query parameters, request entities, and both synchronous and asynchronous operations. This functionality forms the core of Jersey Client's HTTP communication capabilities.
3

4
## Capabilities
5

6
### Web Target
7

8
URI building and template resolution for constructing request endpoints with path segments, query parameters, matrix parameters, and URI template resolution.
9

10
```java { .api }
11
public class JerseyWebTarget implements WebTarget {
12
    /**
13
     * Get the resolved URI for this web target
14
     * @return resolved URI
15
     */
16
    URI getUri();
17
    
18
    /**
19
     * Get URI builder for this web target
20
     * @return URI builder instance
21
     */
22
    UriBuilder getUriBuilder();
23
    
24
    /**
25
     * Append path segment to the URI
26
     * @param path path segment to append
27
     * @return new web target with appended path
28
     */
29
    JerseyWebTarget path(String path);
30
    
31
    /**
32
     * Add matrix parameter to the URI
33
     * @param name parameter name
34
     * @param values parameter values
35
     * @return new web target with matrix parameter
36
     */
37
    JerseyWebTarget matrixParam(String name, Object... values);
38
    
39
    /**
40
     * Add query parameter to the URI
41
     * @param name parameter name
42
     * @param values parameter values
43
     * @return new web target with query parameter
44
     */
45
    JerseyWebTarget queryParam(String name, Object... values);
46
    
47
    /**
48
     * Create request builder for this web target
49
     * @return request builder instance
50
     */
51
    JerseyInvocation.Builder request();
52
    
53
    /**
54
     * Create request builder with Accept header
55
     * @param acceptedResponseTypes accepted media types
56
     * @return request builder with Accept header set
57
     */
58
    JerseyInvocation.Builder request(String... acceptedResponseTypes);
59
    
60
    /**
61
     * Create request builder with Accept header
62
     * @param acceptedResponseTypes accepted media types
63
     * @return request builder with Accept header set
64
     */
65
    JerseyInvocation.Builder request(MediaType... acceptedResponseTypes);
66
    
67
    /**
68
     * Resolve URI template parameter
69
     * @param name template parameter name
70
     * @param value parameter value
71
     * @return new web target with resolved template
72
     */
73
    JerseyWebTarget resolveTemplate(String name, Object value);
74
    
75
    /**
76
     * Resolve URI template parameter with encoding control
77
     * @param name template parameter name
78
     * @param value parameter value
79
     * @param encodeSlashInPath whether to encode slash characters
80
     * @return new web target with resolved template
81
     */
82
    JerseyWebTarget resolveTemplate(String name, Object value, boolean encodeSlashInPath);
83
    
84
    /**
85
     * Resolve URI template parameter from encoded value
86
     * @param name template parameter name
87
     * @param value pre-encoded parameter value
88
     * @return new web target with resolved template
89
     */
90
    JerseyWebTarget resolveTemplateFromEncoded(String name, Object value);
91
    
92
    /**
93
     * Resolve multiple URI template parameters
94
     * @param templateValues map of template parameter names to values
95
     * @return new web target with resolved templates
96
     */
97
    JerseyWebTarget resolveTemplates(Map<String, Object> templateValues);
98
    
99
    /**
100
     * Resolve multiple URI template parameters with encoding control
101
     * @param templateValues map of template parameter names to values
102
     * @param encodeSlashInPath whether to encode slash characters
103
     * @return new web target with resolved templates
104
     */
105
    JerseyWebTarget resolveTemplates(Map<String, Object> templateValues, boolean encodeSlashInPath);
106
    
107
    /**
108
     * Resolve multiple URI template parameters from encoded values
109
     * @param templateValues map of template parameter names to pre-encoded values
110
     * @return new web target with resolved templates
111
     */
112
    JerseyWebTarget resolveTemplatesFromEncoded(Map<String, Object> templateValues);
113
    
114
    /**
115
     * Register provider class with this web target
116
     * @param providerClass provider class to register
117
     * @return new web target with registered provider
118
     */
119
    JerseyWebTarget register(Class<?> providerClass);
120
    
121
    /**
122
     * Register provider instance with this web target
123
     * @param provider provider instance to register
124
     * @return new web target with registered provider
125
     */
126
    JerseyWebTarget register(Object provider);
127
    
128
    /**
129
     * Set configuration property for this web target
130
     * @param name property name
131
     * @param value property value
132
     * @return new web target with property set
133
     */
134
    JerseyWebTarget property(String name, Object value);
135
    
136
    /**
137
     * Get configuration for this web target
138
     * @return configuration instance
139
     */
140
    ClientConfig getConfiguration();
141
}
142
```
143

144
**Usage Examples:**
145

146
```java
147
import jakarta.ws.rs.client.WebTarget;
148
import jakarta.ws.rs.core.MediaType;
149

150
// Basic URI building
151
WebTarget target = client.target("https://api.example.com");
152
WebTarget usersTarget = target.path("users").path("{id}");
153

154
// Query and matrix parameters
155
WebTarget searchTarget = target.path("search")
156
    .queryParam("q", "jersey client")
157
    .queryParam("limit", 10)
158
    .matrixParam("version", "v1");
159

160
// URI template resolution
161
WebTarget userTarget = usersTarget.resolveTemplate("id", 123);
162
// Results in: https://api.example.com/users/123
163

164
// Multiple template resolution
165
Map<String, Object> templates = new HashMap<>();
166
templates.put("userId", 123);
167
templates.put("resourceId", 456);
168
WebTarget resourceTarget = target.path("users/{userId}/resources/{resourceId}")
169
    .resolveTemplates(templates);
170
```
171

172
### Request Building
173

174
Request builder for configuring HTTP requests with headers, cookies, caching directives, and content negotiation settings.
175

176
```java { .api }
177
public static class JerseyInvocation.Builder implements Invocation.Builder {
178
    /**
179
     * Set Accept header for content negotiation
180
     * @param mediaTypes accepted media types
181
     * @return this builder instance
182
     */
183
    Builder accept(String... mediaTypes);
184
    
185
    /**
186
     * Set Accept header for content negotiation
187
     * @param mediaTypes accepted media types
188
     * @return this builder instance
189
     */
190
    Builder accept(MediaType... mediaTypes);
191
    
192
    /**
193
     * Set Accept-Encoding header
194
     * @param encodings accepted encodings
195
     * @return this builder instance
196
     */
197
    Invocation.Builder acceptEncoding(String... encodings);
198
    
199
    /**
200
     * Set Accept-Language header
201
     * @param locales accepted locales
202
     * @return this builder instance
203
     */
204
    Builder acceptLanguage(Locale... locales);
205
    
206
    /**
207
     * Set Accept-Language header
208
     * @param locales accepted language tags
209
     * @return this builder instance
210
     */
211
    Builder acceptLanguage(String... locales);
212
    
213
    /**
214
     * Add cookie to the request
215
     * @param cookie cookie to add
216
     * @return this builder instance
217
     */
218
    Builder cookie(Cookie cookie);
219
    
220
    /**
221
     * Add cookie to the request
222
     * @param name cookie name
223
     * @param value cookie value
224
     * @return this builder instance
225
     */
226
    Builder cookie(String name, String value);
227
    
228
    /**
229
     * Set Cache-Control header
230
     * @param cacheControl cache control directives
231
     * @return this builder instance
232
     */
233
    Builder cacheControl(CacheControl cacheControl);
234
    
235
    /**
236
     * Add custom header to the request
237
     * @param name header name
238
     * @param value header value
239
     * @return this builder instance
240
     */
241
    Builder header(String name, Object value);
242
    
243
    /**
244
     * Set multiple headers from map
245
     * @param headers map of header names to values
246
     * @return this builder instance
247
     */
248
    Builder headers(MultivaluedMap<String, Object> headers);
249
    
250
    /**
251
     * Set configuration property for this request
252
     * @param name property name
253
     * @param value property value
254
     * @return this builder instance
255
     */
256
    Builder property(String name, Object value);
257
}
258
```
259

260
### Synchronous Request Execution
261

262
Synchronous HTTP request execution methods for all standard HTTP methods with support for typed responses and request entities.
263

264
```java { .api }
265
public static class JerseyInvocation.Builder implements Invocation.Builder {
266
    /**
267
     * Execute GET request
268
     * @return HTTP response
269
     */
270
    Response get();
271
    
272
    /**
273
     * Execute GET request with typed response
274
     * @param responseType expected response type
275
     * @return typed response entity
276
     */
277
    <T> T get(Class<T> responseType);
278
    
279
    /**
280
     * Execute GET request with generic typed response
281
     * @param responseType expected generic response type
282
     * @return typed response entity
283
     */
284
    <T> T get(GenericType<T> responseType);
285
    
286
    /**
287
     * Execute POST request with entity
288
     * @param entity request entity
289
     * @return HTTP response
290
     */
291
    Response post(Entity<?> entity);
292
    
293
    /**
294
     * Execute POST request with entity and typed response
295
     * @param entity request entity
296
     * @param responseType expected response type
297
     * @return typed response entity
298
     */
299
    <T> T post(Entity<?> entity, Class<T> responseType);
300
    
301
    /**
302
     * Execute POST request with entity and generic typed response
303
     * @param entity request entity
304
     * @param responseType expected generic response type
305
     * @return typed response entity
306
     */
307
    <T> T post(Entity<?> entity, GenericType<T> responseType);
308
    
309
    /**
310
     * Execute PUT request with entity
311
     * @param entity request entity
312
     * @return HTTP response
313
     */
314
    Response put(Entity<?> entity);
315
    
316
    /**
317
     * Execute PUT request with entity and typed response
318
     * @param entity request entity
319
     * @param responseType expected response type
320
     * @return typed response entity
321
     */
322
    <T> T put(Entity<?> entity, Class<T> responseType);
323
    
324
    /**
325
     * Execute PUT request with entity and generic typed response
326
     * @param entity request entity
327
     * @param responseType expected generic response type
328
     * @return typed response entity
329
     */
330
    <T> T put(Entity<?> entity, GenericType<T> responseType);
331
    
332
    /**
333
     * Execute DELETE request
334
     * @return HTTP response
335
     */
336
    Response delete();
337
    
338
    /**
339
     * Execute DELETE request with typed response
340
     * @param responseType expected response type
341
     * @return typed response entity
342
     */
343
    <T> T delete(Class<T> responseType);
344
    
345
    /**
346
     * Execute DELETE request with generic typed response
347
     * @param responseType expected generic response type
348
     * @return typed response entity
349
     */
350
    <T> T delete(GenericType<T> responseType);
351
    
352
    /**
353
     * Execute HEAD request
354
     * @return HTTP response
355
     */
356
    Response head();
357
    
358
    /**
359
     * Execute OPTIONS request
360
     * @return HTTP response
361
     */
362
    Response options();
363
    
364
    /**
365
     * Execute OPTIONS request with typed response
366
     * @param responseType expected response type
367
     * @return typed response entity
368
     */
369
    <T> T options(Class<T> responseType);
370
    
371
    /**
372
     * Execute OPTIONS request with generic typed response
373
     * @param responseType expected generic response type
374
     * @return typed response entity
375
     */
376
    <T> T options(GenericType<T> responseType);
377
    
378
    /**
379
     * Execute TRACE request
380
     * @return HTTP response
381
     */
382
    Response trace();
383
    
384
    /**
385
     * Execute TRACE request with typed response
386
     * @param responseType expected response type
387
     * @return typed response entity
388
     */
389
    <T> T trace(Class<T> responseType);
390
    
391
    /**
392
     * Execute TRACE request with generic typed response
393
     * @param responseType expected generic response type
394
     * @return typed response entity
395
     */
396
    <T> T trace(GenericType<T> responseType);
397
    
398
    /**
399
     * Execute custom HTTP method request
400
     * @param name HTTP method name
401
     * @return HTTP response
402
     */
403
    Response method(String name);
404
    
405
    /**
406
     * Execute custom HTTP method request with typed response
407
     * @param name HTTP method name
408
     * @param responseType expected response type
409
     * @return typed response entity
410
     */
411
    <T> T method(String name, Class<T> responseType);
412
    
413
    /**
414
     * Execute custom HTTP method request with generic typed response
415
     * @param name HTTP method name
416
     * @param responseType expected generic response type
417
     * @return typed response entity
418
     */
419
    <T> T method(String name, GenericType<T> responseType);
420
    
421
    /**
422
     * Execute custom HTTP method request with entity
423
     * @param name HTTP method name
424
     * @param entity request entity
425
     * @return HTTP response
426
     */
427
    Response method(String name, Entity<?> entity);
428
    
429
    /**
430
     * Execute custom HTTP method request with entity and typed response
431
     * @param name HTTP method name
432
     * @param entity request entity
433
     * @param responseType expected response type
434
     * @return typed response entity
435
     */
436
    <T> T method(String name, Entity<?> entity, Class<T> responseType);
437
    
438
    /**
439
     * Execute custom HTTP method request with entity and generic typed response
440
     * @param name HTTP method name
441
     * @param entity request entity
442
     * @param responseType expected generic response type
443
     * @return typed response entity
444
     */
445
    <T> T method(String name, Entity<?> entity, GenericType<T> responseType);
446
}
447
```
448

449
**Usage Examples:**
450

451
```java
452
import jakarta.ws.rs.core.Response;
453
import jakarta.ws.rs.core.MediaType;
454
import jakarta.ws.rs.client.Entity;
455

456
// Simple GET request
457
Response response = target.path("users").request().get();
458
if (response.getStatus() == 200) {
459
    String json = response.readEntity(String.class);
460
}
461

462
// GET with typed response
463
User user = target.path("users/123")
464
    .request(MediaType.APPLICATION_JSON)
465
    .get(User.class);
466

467
// POST with entity
468
User newUser = new User("John", "john@example.com");
469
Response postResponse = target.path("users")
470
    .request()
471
    .post(Entity.json(newUser));
472

473
// PUT with entity and typed response
474
User updatedUser = target.path("users/123")
475
    .request()
476
    .put(Entity.json(updateData), User.class);
477

478
// Custom headers and content negotiation
479
List<Product> products = target.path("products")
480
    .queryParam("category", "electronics")
481
    .request(MediaType.APPLICATION_JSON)
482
    .header("X-API-Key", "your-api-key")
483
    .accept(MediaType.APPLICATION_JSON)
484
    .get(new GenericType<List<Product>>() {});
485
```
486

487
### Asynchronous Request Execution
488

489
Asynchronous HTTP request execution using Future-based and callback-based approaches for non-blocking operations.
490

491
```java { .api }
492
public class JerseyInvocation implements Invocation {
493
    /**
494
     * Submit request for asynchronous execution
495
     * @return Future representing the response
496
     */
497
    Future<Response> submit();
498
    
499
    /**
500
     * Submit request for asynchronous execution with typed response
501
     * @param responseType expected response type
502
     * @return Future representing the typed response
503
     */
504
    <T> Future<T> submit(Class<T> responseType);
505
    
506
    /**
507
     * Submit request for asynchronous execution with generic typed response
508
     * @param responseType expected generic response type
509
     * @return Future representing the typed response
510
     */
511
    <T> Future<T> submit(GenericType<T> responseType);
512
    
513
    /**
514
     * Submit request for asynchronous execution with callback
515
     * @param callback invocation callback for handling response/errors
516
     * @return Future representing the response
517
     */
518
    <T> Future<T> submit(InvocationCallback<T> callback);
519
    
520
    /**
521
     * Submit request for asynchronous execution with callback and generic type
522
     * @param responseType expected generic response type
523
     * @param callback invocation callback for handling response/errors
524
     * @return Future representing the typed response
525
     */
526
    <T> Future<T> submit(GenericType<T> responseType, InvocationCallback<T> callback);
527
}
528

529
// Async invoker for request builder
530
public static class JerseyInvocation.Builder implements Invocation.Builder {
531
    /**
532
     * Get asynchronous invoker for this request
533
     * @return async invoker instance
534
     */
535
    jakarta.ws.rs.client.AsyncInvoker async();
536
}
537
```
538

539
**Usage Examples:**
540

541
```java
542
import jakarta.ws.rs.client.InvocationCallback;
543
import java.util.concurrent.Future;
544

545
// Future-based async execution
546
Future<Response> futureResponse = target.path("users")
547
    .request()
548
    .buildGet()
549
    .submit();
550

551
// Process when ready
552
Response response = futureResponse.get(); // blocks until complete
553

554
// Callback-based async execution
555
target.path("users/123")
556
    .request()
557
    .async()
558
    .get(new InvocationCallback<User>() {
559
        @Override
560
        public void completed(User user) {
561
            System.out.println("Received user: " + user.getName());
562
        }
563
        
564
        @Override
565
        public void failed(Throwable throwable) {
566
            System.err.println("Request failed: " + throwable.getMessage());
567
        }
568
    });
569

570
// Async POST with callback
571
target.path("users")
572
    .request()
573
    .async()
574
    .post(Entity.json(newUser), new InvocationCallback<Response>() {
575
        @Override
576
        public void completed(Response response) {
577
            if (response.getStatus() == 201) {
578
                System.out.println("User created successfully");
579
            }
580
        }
581
        
582
        @Override
583
        public void failed(Throwable throwable) {
584
            System.err.println("Failed to create user: " + throwable.getMessage());
585
        }
586
    });
587
```
588

589
### Reactive Request Execution
590

591
Reactive HTTP request execution using CompletionStage for composable asynchronous operations.
592

593
```java { .api }
594
public static class JerseyInvocation.Builder implements Invocation.Builder {
595
    /**
596
     * Get reactive invoker using CompletionStage
597
     * @return CompletionStage-based reactive invoker
598
     */
599
    CompletionStageRxInvoker rx();
600
    
601
    /**
602
     * Get reactive invoker for specific RxInvoker type
603
     * @param clazz RxInvoker implementation class
604
     * @return typed reactive invoker
605
     */
606
    <T extends RxInvoker> T rx(Class<T> clazz);
607
}
608

609
public class JerseyCompletionStageRxInvoker implements CompletionStageRxInvoker {
610
    // Reactive methods returning CompletionStage for all HTTP methods
611
    // Implementation details are package-private, accessed via rx() method
612
}
613
```
614

615
**Usage Examples:**
616

617
```java
618
import java.util.concurrent.CompletionStage;
619

620
// Reactive GET request
621
CompletionStage<Response> completionStage = target.path("users")
622
    .request()
623
    .rx()
624
    .get();
625

626
// Chain reactive operations
627
completionStage
628
    .thenApply(response -> response.readEntity(String.class))
629
    .thenAccept(json -> System.out.println("Response: " + json))
630
    .exceptionally(throwable -> {
631
        System.err.println("Request failed: " + throwable.getMessage());
632
        return null;
633
    });
634

635
// Reactive POST with typed response
636
target.path("users")
637
    .request()
638
    .rx()
639
    .post(Entity.json(newUser), User.class)
640
    .thenCompose(user -> {
641
        // Chain another request
642
        return target.path("users/" + user.getId() + "/profile")
643
            .request()
644
            .rx()
645
            .get(UserProfile.class);
646
    })
647
    .thenAccept(profile -> System.out.println("User profile: " + profile));
648
```
649

650
### Invocation Building
651

652
Low-level invocation building for creating reusable request templates that can be executed multiple times.
653

654
```java { .api }
655
public static class JerseyInvocation.Builder implements Invocation.Builder {
656
    /**
657
     * Build invocation for custom HTTP method
658
     * @param method HTTP method name
659
     * @return invocation instance
660
     */
661
    JerseyInvocation build(String method);
662
    
663
    /**
664
     * Build invocation for custom HTTP method with entity
665
     * @param method HTTP method name
666
     * @param entity request entity
667
     * @return invocation instance
668
     */
669
    JerseyInvocation build(String method, Entity<?> entity);
670
    
671
    /**
672
     * Build GET invocation
673
     * @return GET invocation instance
674
     */
675
    JerseyInvocation buildGet();
676
    
677
    /**
678
     * Build DELETE invocation
679
     * @return DELETE invocation instance
680
     */
681
    JerseyInvocation buildDelete();
682
    
683
    /**
684
     * Build POST invocation with entity
685
     * @param entity request entity
686
     * @return POST invocation instance
687
     */
688
    JerseyInvocation buildPost(Entity<?> entity);
689
    
690
    /**
691
     * Build PUT invocation with entity
692
     * @param entity request entity
693
     * @return PUT invocation instance
694
     */
695
    JerseyInvocation buildPut(Entity<?> entity);
696
}
697

698
public class JerseyInvocation implements Invocation {
699
    /**
700
     * Execute the invocation synchronously
701
     * @return HTTP response
702
     */
703
    Response invoke();
704
    
705
    /**
706
     * Execute the invocation synchronously with typed response
707
     * @param responseType expected response type
708
     * @return typed response entity
709
     */
710
    <T> T invoke(Class<T> responseType);
711
    
712
    /**
713
     * Execute the invocation synchronously with generic typed response
714
     * @param responseType expected generic response type
715
     * @return typed response entity
716
     */
717
    <T> T invoke(GenericType<T> responseType);
718
}
719
```
720

721
**Usage Examples:**
722

723
```java
724
// Build reusable invocations
725
Invocation getUserInvocation = target.path("users/{id}")
726
    .resolveTemplate("id", 123)
727
    .request(MediaType.APPLICATION_JSON)
728
    .buildGet();
729

730
// Execute multiple times
731
Response response1 = getUserInvocation.invoke();
732
Response response2 = getUserInvocation.invoke(); // Can reuse
733

734
// Build POST invocation template
735
Invocation createUserInvocation = target.path("users")
736
    .request()
737
    .buildPost(Entity.json(newUser));
738

739
// Execute and get typed response
740
User createdUser = createUserInvocation.invoke(User.class);
741
```