0
# Request Processing
1

2
Core request processing functionality including the main application handler, container request/response objects, lifecycle management, and exception handling. This system handles the complete request flow from HTTP input to JAX-RS resource method execution and response generation.
3

4
## Capabilities
5

6
### ApplicationHandler
7

8
Central request processing engine that handles the complete request lifecycle from routing to response generation. Manages the entire Jersey server runtime environment.
9

10
```java { .api }
11
/**
12
 * Jersey server-side application handler. 
13
 * Provides functionality to process HTTP requests in a JAX-RS application.
14
 */
15
public final class ApplicationHandler {
16
    
17
    /**
18
     * Create a new Jersey application handler based on an Application.
19
     * @param application JAX-RS application instance
20
     */
21
    public ApplicationHandler(Application application);
22
    
23
    /**
24
     * Create a new Jersey application handler based on an Application class.
25
     * @param applicationClass JAX-RS application class
26
     */
27
    public ApplicationHandler(Class<? extends Application> applicationClass);
28
    
29
    /**
30
     * Process a container request and return the response asynchronously.
31
     * @param requestContext Container request to process
32
     * @return Future containing the container response
33
     */
34
    public Future<ContainerResponse> apply(ContainerRequest requestContext);
35
    
36
    /**
37
     * Process a container request with entity stream and return response asynchronously.
38
     * @param requestContext Container request to process
39
     * @param entityStream Output stream for writing response entity
40
     * @return Future containing the container response
41
     */
42
    public Future<ContainerResponse> apply(ContainerRequest requestContext, OutputStream entityStream);
43
    
44
    /**
45
     * Get the application configuration.
46
     * @return Current application configuration
47
     */
48
    public Configuration getConfiguration();
49
    
50
    /**
51
     * Get the injection manager instance.
52
     * @return Injection manager for dependency injection
53
     */
54
    public InjectionManager getInjectionManager();
55
    
56
    /**
57
     * Get the resource model for the application.
58
     * @return Resource model containing all registered resources
59
     */
60
    public ResourceModel getResourceModel();
61
}
62
```
63

64
**Usage Examples:**
65

66
```java
67
import org.glassfish.jersey.server.ApplicationHandler;
68
import org.glassfish.jersey.server.ResourceConfig;
69
import org.glassfish.jersey.server.ContainerRequest;
70
import java.net.URI;
71
import java.util.concurrent.Future;
72

73
// Create application handler from ResourceConfig
74
ResourceConfig config = new ResourceConfig()
75
    .packages("com.example.resources");
76
ApplicationHandler handler = new ApplicationHandler(config);
77

78
// Create application handler from Application class
79
ApplicationHandler handler2 = new ApplicationHandler(MyApplication.class);
80

81
// Process a request
82
URI baseUri = URI.create("http://localhost:8080/api/");
83
URI requestUri = URI.create("http://localhost:8080/api/users/123");
84
ContainerRequest request = new ContainerRequest(
85
    baseUri, requestUri, "GET", null, new MapPropertiesDelegate()
86
);
87

88
// Process asynchronously
89
Future<ContainerResponse> responseFuture = handler.apply(request);
90
ContainerResponse response = responseFuture.get();
91

92
// Access configuration and resource model
93
Configuration config = handler.getConfiguration();
94
ResourceModel model = handler.getResourceModel();
95
```
96

97
### ContainerRequest
98

99
Server-side request representation providing access to all request information including headers, parameters, entity, security context, and URI information.
100

101
```java { .api }
102
/**
103
 * Jersey container request implementation providing server-side HTTP request representation.
104
 * Extends InboundMessageContext and implements ContainerRequestContext.
105
 */
106
public class ContainerRequest extends InboundMessageContext implements ContainerRequestContext {
107
    
108
    /**
109
     * Create a new container request.
110
     * @param baseUri Application base URI
111
     * @param requestUri Full request URI  
112
     * @param httpMethod HTTP method (GET, POST, etc.)
113
     * @param securityContext Security context for the request
114
     * @param propertiesDelegate Properties delegate for request properties
115
     */
116
    public ContainerRequest(URI baseUri, URI requestUri, String httpMethod,
117
                          SecurityContext securityContext, PropertiesDelegate propertiesDelegate);
118
    
119
    // URI Information
120
    /**
121
     * Get the base URI of the application.
122
     * @return Base URI
123
     */
124
    public URI getBaseUri();
125
    
126
    /**
127
     * Get the full request URI.
128
     * @return Request URI
129
     */
130
    public URI getRequestUri();
131
    
132
    /**
133
     * Get the absolute request URI builder.
134
     * @return UriBuilder for the absolute request URI
135
     */
136
    public UriBuilder getAbsolutePathBuilder();
137
    
138
    // HTTP Method and Headers
139
    /**
140
     * Get the HTTP method of the request.
141
     * @return HTTP method string
142
     */
143
    public String getMethod();
144
    
145
    /**
146
     * Set the HTTP method of the request.
147
     * @param method HTTP method to set
148
     */
149
    public void setMethod(String method);
150
    
151
    /**
152
     * Get request headers.
153
     * @return MultivaluedMap of request headers
154
     */
155
    public MultivaluedMap<String, String> getHeaders();
156
    
157
    // Security Context
158
    /**
159
     * Get the security context for the request.
160
     * @return Security context
161
     */
162
    public SecurityContext getSecurityContext();
163
    
164
    /**
165
     * Set the security context for the request.
166
     * @param context Security context to set
167
     */
168
    public void setSecurityContext(SecurityContext context);
169
    
170
    // Request Entity
171
    /**
172
     * Check if the request has an entity.
173
     * @return true if request has entity, false otherwise
174
     */
175
    public boolean hasEntity();
176
    
177
    /**
178
     * Get the request entity input stream.
179
     * @return InputStream for reading request entity
180
     */
181
    public InputStream getEntityStream();
182
    
183
    /**
184
     * Set the request entity input stream.
185
     * @param input InputStream containing request entity
186
     */
187
    public void setEntityStream(InputStream input);
188
}
189
```
190

191
**Usage Examples:**
192

193
```java
194
import org.glassfish.jersey.server.ContainerRequest;
195
import jakarta.ws.rs.core.SecurityContext;
196
import jakarta.ws.rs.core.UriBuilder;
197
import java.io.InputStream;
198
import java.net.URI;
199

200
// Create container request
201
URI baseUri = URI.create("http://localhost:8080/api/");
202
URI requestUri = URI.create("http://localhost:8080/api/users/123?active=true");
203
SecurityContext securityContext = createSecurityContext();
204
PropertiesDelegate propertiesDelegate = new MapPropertiesDelegate();
205

206
ContainerRequest request = new ContainerRequest(
207
    baseUri, requestUri, "GET", securityContext, propertiesDelegate
208
);
209

210
// Access request information
211
String method = request.getMethod(); // "GET"
212
URI base = request.getBaseUri(); // http://localhost:8080/api/
213
URI full = request.getRequestUri(); // http://localhost:8080/api/users/123?active=true
214

215
// Access headers
216
MultivaluedMap<String, String> headers = request.getHeaders();
217
String contentType = headers.getFirst("Content-Type");
218
String userAgent = headers.getFirst("User-Agent");
219

220
// Access security context
221
SecurityContext security = request.getSecurityContext();
222
Principal principal = security.getUserPrincipal();
223
boolean isSecure = security.isSecure();
224

225
// Handle request entity
226
if (request.hasEntity()) {
227
    InputStream entityStream = request.getEntityStream();
228
    // Process entity data
229
}
230

231
// Modify request
232
request.setMethod("POST");
233
request.setSecurityContext(newSecurityContext);
234
```
235

236
### ContainerResponse
237

238
Server-side response representation providing control over response status, headers, and entity for HTTP responses.
239

240
```java { .api }
241
/**
242
 * Jersey container response implementation providing server-side HTTP response representation.
243
 * Implements ContainerResponseContext interface.
244
 */
245
public class ContainerResponse implements ContainerResponseContext {
246
    
247
    /**
248
     * Create a new container response.
249
     * @param requestContext Associated request context
250
     * @param response JAX-RS Response object
251
     */
252
    public ContainerResponse(ContainerRequest requestContext, Response response);
253
    
254
    // Status Information
255
    /**
256
     * Get the response status code.
257
     * @return HTTP status code
258
     */
259
    public int getStatus();
260
    
261
    /**
262
     * Set the response status code.
263
     * @param code HTTP status code to set
264
     */
265
    public void setStatus(int code);
266
    
267
    /**
268
     * Get the response status info.
269
     * @return Response.StatusType containing status information
270
     */
271
    public Response.StatusType getStatusInfo();
272
    
273
    /**
274
     * Set the response status info.
275
     * @param statusInfo Status information to set
276
     */
277
    public void setStatusInfo(Response.StatusType statusInfo);
278
    
279
    // Headers
280
    /**
281
     * Get response headers.
282
     * @return MultivaluedMap of response headers
283
     */
284
    public MultivaluedMap<String, Object> getHeaders();
285
    
286
    /**
287
     * Get response string headers.
288
     * @return MultivaluedMap of response headers as strings
289
     */
290
    public MultivaluedMap<String, String> getStringHeaders();
291
    
292
    /**
293
     * Get header value as string.
294
     * @param name Header name
295
     * @return Header value as string
296
     */
297
    public String getHeaderString(String name);
298
    
299
    // Entity
300
    /**
301
     * Check if response has an entity.
302
     * @return true if response has entity, false otherwise
303
     */
304
    public boolean hasEntity();
305
    
306
    /**
307
     * Get the response entity.
308
     * @return Response entity object
309
     */
310
    public Object getEntity();
311
    
312
    /**
313
     * Set the response entity.
314
     * @param entity Entity to set
315
     */
316
    public void setEntity(Object entity);
317
    
318
    /**
319
     * Get the response entity output stream.
320
     * @return OutputStream for writing response entity
321
     */
322
    public OutputStream getEntityStream();
323
    
324
    /**
325
     * Set the response entity output stream.
326
     * @param outputStream OutputStream to set
327
     */
328
    public void setEntityStream(OutputStream outputStream);
329
    
330
    // Associated Request
331
    /**
332
     * Get the associated container request.
333
     * @return ContainerRequest that generated this response
334
     */
335
    public ContainerRequest getRequestContext();
336
}
337
```
338

339
**Usage Examples:**
340

341
```java
342
import org.glassfish.jersey.server.ContainerResponse;
343
import org.glassfish.jersey.server.ContainerRequest;
344
import jakarta.ws.rs.core.Response;
345
import jakarta.ws.rs.core.MediaType;
346
import java.io.OutputStream;
347

348
// Create response from request and JAX-RS Response
349
ContainerRequest request = createContainerRequest();
350
Response jaxrsResponse = Response.ok("Hello World")
351
    .type(MediaType.TEXT_PLAIN)
352
    .header("Custom-Header", "custom-value")
353
    .build();
354

355
ContainerResponse response = new ContainerResponse(request, jaxrsResponse);
356

357
// Access response information
358
int status = response.getStatus(); // 200
359
Response.StatusType statusInfo = response.getStatusInfo(); // OK
360

361
// Access headers
362
MultivaluedMap<String, Object> headers = response.getHeaders();
363
String contentType = response.getHeaderString("Content-Type"); // "text/plain"
364
String customHeader = response.getHeaderString("Custom-Header"); // "custom-value"
365

366
// Access entity
367
if (response.hasEntity()) {
368
    Object entity = response.getEntity(); // "Hello World"
369
}
370

371
// Modify response
372
response.setStatus(201);
373
response.setStatusInfo(Response.Status.CREATED);
374
response.getHeaders().add("Location", "/api/users/123");
375

376
// Set new entity
377
response.setEntity("Updated response content");
378

379
// Access entity stream for direct writing
380
OutputStream entityStream = response.getEntityStream();
381
entityStream.write("Direct response content".getBytes());
382
```
383

384
### Exception Handling
385

386
Container-level exception handling for Jersey server processing errors.
387

388
```java { .api }
389
/**
390
 * Container exception representing errors in container-level processing.
391
 * Extends ProcessingException for Jersey-specific error handling.
392
 */
393
public class ContainerException extends ProcessingException {
394
    
395
    /**
396
     * Create a new container exception.
397
     * @param message Exception message
398
     */
399
    public ContainerException(String message);
400
    
401
    /**
402
     * Create a new container exception with cause.
403
     * @param message Exception message
404
     * @param cause Underlying cause
405
     */
406
    public ContainerException(String message, Throwable cause);
407
    
408
    /**
409
     * Create a new container exception with cause.
410
     * @param cause Underlying cause
411
     */
412
    public ContainerException(Throwable cause);
413
}
414
```
415

416
**Usage Examples:**
417

418
```java
419
import org.glassfish.jersey.server.ContainerException;
420

421
// Handle container exceptions in processing
422
try {
423
    Future<ContainerResponse> responseFuture = handler.apply(request);
424
    ContainerResponse response = responseFuture.get();
425
} catch (ExecutionException e) {
426
    if (e.getCause() instanceof ContainerException) {
427
        ContainerException containerEx = (ContainerException) e.getCause();
428
        logger.error("Container processing error: " + containerEx.getMessage(), containerEx);
429
    }
430
}
431

432
// Throw container exceptions in custom components
433
public class CustomContainerProvider implements ContainerProvider {
434
    @Override
435
    public <T> T createContainer(Class<T> type, Application application) {
436
        try {
437
            // Container creation logic
438
            return createContainerInstance(type, application);
439
        } catch (Exception e) {
440
            throw new ContainerException("Failed to create container", e);
441
        }
442
    }
443
}
444
```
445

446
### Extended Context Interfaces
447

448
Extended interfaces providing additional functionality beyond standard JAX-RS contexts.
449

450
```java { .api }
451
/**
452
 * Extended resource context providing additional resource-related functionality.
453
 */
454
public interface ExtendedResourceContext extends ResourceContext {
455
    /**
456
     * Get resource instance with specific type.
457
     * @param resourceClass Resource class type
458
     * @return Resource instance
459
     */
460
    <T> T getResource(Class<T> resourceClass);
461
    
462
    /**
463
     * Initialize resource instance.
464
     * @param resource Resource instance to initialize
465
     * @return Initialized resource instance
466
     */
467
    <T> T initResource(T resource);
468
}
469

470
/**
471
 * Extended URI info providing additional URI-related functionality.
472
 */
473
public interface ExtendedUriInfo extends UriInfo {
474
    /**
475
     * Get throwable mapped to response.
476
     * @return Mapped throwable or null
477
     */
478
    Throwable getMappedThrowable();
479
    
480
    /**
481
     * Get all template parameter values.
482
     * @return MultivaluedMap of all template parameters
483
     */
484
    MultivaluedMap<String, String> getPathParameters();
485
    
486
    /**
487
     * Get matched resource method.
488
     * @return ResourceMethod that matched the request
489
     */
490
    ResourceMethod getMatchedResourceMethod();
491
}
492
```