0
# Quarkus RESTEasy Classic Extension
1

2
RESTEasy Classic extension for Quarkus that provides Jakarta REST (JAX-RS) support with integration to Quarkus's reactive architecture through Vert.x HTTP. This extension enables developers to build REST endpoints with minimal configuration while maintaining fast startup times and low memory footprint optimized for cloud-native applications.
3

4
## Package Information
5

6
- **Package Name**: io.quarkus:quarkus-resteasy
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to Maven dependencies:
10

11
```xml
12
<dependency>
13
    <groupId>io.quarkus</groupId>
14
    <artifactId>quarkus-resteasy</artifactId>
15
</dependency>
16
```
17

18
## Core Imports
19

20
Standard Jakarta REST annotations and Quarkus integration classes:
21

22
```java
23
import jakarta.ws.rs.*;
24
import jakarta.ws.rs.core.*;
25
import jakarta.ws.rs.ext.*;
26
import jakarta.servlet.http.*;
27
import io.quarkus.resteasy.runtime.*;
28
import io.quarkus.resteasy.runtime.standalone.*;
29
import io.quarkus.resteasy.runtime.vertx.*;
30
import io.vertx.core.json.JsonObject;
31
import io.vertx.core.json.JsonArray;
32
import io.vertx.ext.web.RoutingContext;
33
import org.jboss.resteasy.spi.AsyncMessageBodyWriter;
34
import org.jboss.resteasy.spi.AsyncOutputStream;
35
```
36

37
## Basic Usage
38

39
Create a simple REST endpoint using Jakarta REST annotations:
40

41
```java
42
import jakarta.ws.rs.*;
43
import jakarta.ws.rs.core.MediaType;
44
import jakarta.ws.rs.core.Response;
45

46
@Path("/hello")
47
public class HelloResource {
48

49
    @GET
50
    @Produces(MediaType.TEXT_PLAIN)
51
    public String hello() {
52
        return "Hello, World!";
53
    }
54

55
    @GET
56
    @Path("/{name}")
57
    @Produces(MediaType.TEXT_PLAIN)
58
    public String helloName(@PathParam("name") String name) {
59
        return "Hello, " + name + "!";
60
    }
61

62
    @POST
63
    @Consumes(MediaType.APPLICATION_JSON)
64
    @Produces(MediaType.APPLICATION_JSON)
65
    public Response createEntity(String jsonData) {
66
        // Process JSON data
67
        return Response.status(201).entity("Created").build();
68
    }
69
}
70
```
71

72
Using Vert.x integration for JSON handling:
73

74
```java
75
import io.vertx.core.json.JsonObject;
76
import io.vertx.core.json.JsonArray;
77

78
@Path("/api")
79
public class ApiResource {
80
    
81
    @POST
82
    @Path("/data")
83
    @Consumes(MediaType.APPLICATION_JSON)
84
    @Produces(MediaType.APPLICATION_JSON)
85
    public JsonObject processData(JsonObject input) {
86
        // Direct Vert.x JsonObject usage
87
        return new JsonObject()
88
            .put("status", "processed")
89
            .put("input", input);
90
    }
91
    
92
    @GET
93
    @Path("/items")
94
    @Produces(MediaType.APPLICATION_JSON)
95
    public JsonArray getItems() {
96
        return new JsonArray()
97
            .add("item1")
98
            .add("item2")
99
            .add("item3");
100
    }
101
}
102
```
103

104
## Architecture
105

106
The extension integrates RESTEasy with Quarkus's reactive architecture:
107

108
- **Runtime Module**: Provides core JAX-RS functionality and Quarkus integration
109
- **Vert.x Integration**: Direct integration with Vert.x HTTP for reactive processing
110
- **Security Integration**: Automatic integration with Quarkus Security framework
111
- **Build-time Optimization**: Separate deployment module handles build-time processing
112

113
Key components include security filters, exception mappers, JSON message body readers/writers, and configuration interfaces that work together to provide a complete REST framework.
114

115
## Capabilities
116

117
### Configuration
118

119
Configure RESTEasy Vert.x integration settings.
120

121
```java { .api }
122
@ConfigRoot(phase = ConfigPhase.BUILD_AND_RUN_TIME_FIXED)
123
@ConfigMapping(prefix = "quarkus.resteasy.vertx")
124
public interface ResteasyVertxConfig {
125
    @WithDefault("8191")
126
    int responseBufferSize();
127
}
128
```
129

130
Configuration properties:
131
- `quarkus.resteasy.vertx.response-buffer-size`: Output stream response buffer size (default: 8191)
132

133
### Path Template Processing
134

135
Annotation for REST path template interception and processing.
136

137
```java { .api }
138
@Inherited
139
@InterceptorBinding
140
@Target({ElementType.ANNOTATION_TYPE, ElementType.TYPE, ElementType.METHOD})
141
@Retention(RetentionPolicy.RUNTIME)
142
public @interface QuarkusRestPathTemplate {
143
    @Nonbinding String value() default "";
144
}
145
```
146

147
Used with interceptor for metrics and observability:
148

149
```java { .api }
150
@QuarkusRestPathTemplate
151
@Interceptor
152
@Priority(Interceptor.Priority.LIBRARY_BEFORE)
153
public class QuarkusRestPathTemplateInterceptor {
154
    // Processes path templates for monitoring integration
155
}
156
```
157

158
### Security Integration
159

160
JAX-RS permission checker for endpoint security.
161

162
```java { .api }
163
@ApplicationScoped
164
public class JaxRsPermissionChecker {
165
    public boolean shouldRunPermissionChecks();
166
    public boolean applyPermissionChecks(MethodDescription method);
167
    public MethodDescription getMethodSecuredWithAuthZPolicy(
168
        MethodDescription method, MethodDescription fallback);
169
}
170
```
171

172
Security filters for request processing:
173

174
```java { .api }
175
@Provider
176
@Priority(Priorities.AUTHENTICATION)
177
public class EagerSecurityFilter implements ContainerRequestFilter {
178
    // Performs security checks early in request processing
179
}
180

181
@Provider
182
@Priority(Priorities.AUTHENTICATION + 1)
183
public class SecurityContextFilter implements ContainerRequestFilter {
184
    // Manages security context during request processing
185
}
186
```
187

188
Security interceptor for method-level checks:
189

190
```java { .api }
191
@Interceptor
192
@Priority(Interceptor.Priority.PLATFORM_BEFORE + 1)
193
public class StandardSecurityCheckInterceptor {
194
    // Applies standard security checks to JAX-RS methods
195
}
196
```
197

198
### Exception Mapping
199

200
Built-in exception mappers for common security scenarios.
201

202
```java { .api }
203
@Provider
204
public class AuthenticationRedirectExceptionMapper 
205
    implements ExceptionMapper<AuthenticationRedirectException> {
206
    public Response toResponse(AuthenticationRedirectException exception);
207
}
208

209
@Provider
210
public class AuthenticationFailedExceptionMapper 
211
    implements ExceptionMapper<AuthenticationFailedException> {
212
    public Response toResponse(AuthenticationFailedException exception);
213
}
214

215
@Provider
216
public class AuthenticationCompletionExceptionMapper 
217
    implements ExceptionMapper<AuthenticationCompletionException> {
218
    public Response toResponse(AuthenticationCompletionException exception);
219
}
220

221
@Provider
222
public class ForbiddenExceptionMapper 
223
    implements ExceptionMapper<ForbiddenException> {
224
    public Response toResponse(ForbiddenException exception);
225
}
226

227
@Provider
228
public class UnauthorizedExceptionMapper 
229
    implements ExceptionMapper<UnauthorizedException> {
230
    public Response toResponse(UnauthorizedException exception);
231
}
232
```
233

234
### Vert.x JSON Integration
235

236
Message body readers and writers for Vert.x JSON types.
237

238
```java { .api }
239
@Provider
240
@Produces(MediaType.APPLICATION_JSON)
241
public class JsonObjectReader implements MessageBodyReader<JsonObject> {
242
    public boolean isReadable(Class<?> type, Type genericType,
243
                            Annotation[] annotations, MediaType mediaType);
244
    public JsonObject readFrom(Class<JsonObject> type, Type genericType,
245
                             Annotation[] annotations, MediaType mediaType,
246
                             MultivaluedMap<String, String> httpHeaders,
247
                             InputStream entityStream) throws IOException, WebApplicationException;
248
}
249

250
@Provider
251
@Consumes(MediaType.APPLICATION_JSON)
252
public class JsonObjectWriter implements AsyncMessageBodyWriter<JsonObject> {
253
    public boolean isWriteable(Class<?> type, Type genericType,
254
                             Annotation[] annotations, MediaType mediaType);
255
    public void writeTo(JsonObject jsonObject, Class<?> type, Type genericType,
256
                       Annotation[] annotations, MediaType mediaType,
257
                       MultivaluedMap<String, Object> httpHeaders,
258
                       OutputStream entityStream) throws IOException, WebApplicationException;
259
    public CompletionStage<Void> asyncWriteTo(JsonObject jsonObject, Class<?> type, Type genericType,
260
                       Annotation[] annotations, MediaType mediaType,
261
                       MultivaluedMap<String, Object> httpHeaders,
262
                       AsyncOutputStream entityStream);
263
}
264

265
@Provider
266
@Produces(MediaType.APPLICATION_JSON)
267
public class JsonArrayReader implements MessageBodyReader<JsonArray> {
268
    public boolean isReadable(Class<?> type, Type genericType,
269
                            Annotation[] annotations, MediaType mediaType);
270
    public JsonArray readFrom(Class<JsonArray> type, Type genericType,
271
                            Annotation[] annotations, MediaType mediaType,
272
                            MultivaluedMap<String, String> httpHeaders,
273
                            InputStream entityStream) throws IOException, WebApplicationException;
274
}
275

276
@Provider  
277
@Consumes(MediaType.APPLICATION_JSON)
278
public class JsonArrayWriter implements AsyncMessageBodyWriter<JsonArray> {
279
    public boolean isWriteable(Class<?> type, Type genericType,
280
                             Annotation[] annotations, MediaType mediaType);
281
    public void writeTo(JsonArray jsonArray, Class<?> type, Type genericType,
282
                       Annotation[] annotations, MediaType mediaType,
283
                       MultivaluedMap<String, Object> httpHeaders,
284
                       OutputStream entityStream) throws IOException, WebApplicationException;
285
    public CompletionStage<Void> asyncWriteTo(JsonArray jsonArray, Class<?> type, Type genericType,
286
                       Annotation[] annotations, MediaType mediaType,
287
                       MultivaluedMap<String, Object> httpHeaders,
288
                       AsyncOutputStream entityStream);
289
}
290
```
291

292
### Context Utilities
293

294
Utility for pushing context objects from virtual HTTP plugins.
295

296
```java { .api }
297
public class ContextUtil {
298
    public static void pushContext(RoutingContext routingContext);
299
}
300
```
301

302
Used by AWS Lambda, Azure Functions, and similar virtual HTTP plugins to integrate with RESTEasy context management.
303

304
### Servlet Integration
305

306
RESTEasy servlet and filter implementations for traditional servlet environments.
307

308
```java { .api }
309
public class ResteasyServlet extends HttpServlet30Dispatcher {
310
    /**
311
     * Service method for handling HTTP requests in servlet environments
312
     */
313
    public void service(String httpMethod, HttpServletRequest request, 
314
                       HttpServletResponse response) throws ServletException, IOException;
315
}
316

317
public class ResteasyFilter extends Filter30Dispatcher {
318
    /**
319
     * Filter method for intercepting requests in servlet filter chains
320
     */
321
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, 
322
                        FilterChain filterChain) throws IOException, ServletException;
323
}
324
```
325

326
### Additional Exception Mapping
327

328
Additional exception mapper for composite exception handling.
329

330
```java { .api }
331
@Provider
332
public class CompositeExceptionMapper implements ExceptionMapper<CompositeException> {
333
    public Response toResponse(CompositeException exception);
334
}
335
```
336

337
### Enhanced Security Interceptors
338

339
Complete security interceptor implementations for RBAC and authentication.
340

341
```java { .api }
342
public abstract class StandardSecurityCheckInterceptor {
343
    
344
    @Interceptor
345
    @RolesAllowed("")
346
    @Priority(Interceptor.Priority.LIBRARY_BEFORE)
347
    public static class RolesAllowedInterceptor {
348
        @AroundInvoke
349
        public Object intercept(InvocationContext invocationContext) throws Exception;
350
    }
351
    
352
    @Interceptor
353
    @PermissionsAllowed("")
354
    @Priority(Interceptor.Priority.LIBRARY_BEFORE)
355
    public static class PermissionsAllowedInterceptor {
356
        @AroundInvoke
357
        public Object intercept(InvocationContext invocationContext) throws Exception;
358
    }
359
    
360
    @Interceptor
361
    @PermitAll
362
    @Priority(Interceptor.Priority.LIBRARY_BEFORE)
363
    public static class PermitAllInterceptor {
364
        @AroundInvoke
365
        public Object intercept(InvocationContext invocationContext) throws Exception;
366
    }
367
    
368
    @Interceptor
369
    @Authenticated
370
    @Priority(Interceptor.Priority.LIBRARY_BEFORE)
371
    public static class AuthenticatedInterceptor {
372
        @AroundInvoke
373
        public Object intercept(InvocationContext invocationContext) throws Exception;
374
    }
375
}
376
```
377

378
### Standalone Runtime Components
379

380
Core components for standalone (non-servlet) RESTEasy deployment.
381

382
```java { .api }
383
@Recorder
384
public class ResteasyStandaloneRecorder {
385
    public RuntimeValue<Deployment> staticInit(ResteasyDeployment dep, String path);
386
    public void start(ShutdownContext shutdown, boolean isVirtual);
387
    public Handler<RoutingContext> vertxRequestHandler(RuntimeValue<Deployment> deployment, 
388
                                                      String rootPath);
389
    public Handler<FailureRoutingContext> vertxFailureHandler(RuntimeValue<Deployment> deployment, 
390
                                                             String rootPath);
391
    public Handler<RoutingContext> defaultAuthFailureHandler();
392
}
393

394
public class VertxRequestHandler implements Handler<RoutingContext> {
395
    public void handle(RoutingContext request);
396
}
397

398
public class VertxHttpRequest extends BaseHttpRequest {
399
    // HTTP request abstraction for Vert.x integration
400
}
401

402
public class VertxHttpResponse implements HttpResponse {
403
    // HTTP response implementation for Vert.x integration
404
}
405
```
406

407
### Vert.x Streaming and Buffer Management
408

409
Utilities for efficient streaming and buffer management in Vert.x integration.
410

411
```java { .api }
412
public interface BufferAllocator {
413
    ByteBuf allocateBuffer();
414
    ByteBuf allocateBuffer(boolean direct);
415
    ByteBuf allocateBuffer(int bufferSize);
416
    ByteBuf allocateBuffer(boolean direct, int bufferSize);
417
    int getBufferSize();
418
}
419

420
public interface VertxOutput {
421
    void write(ByteBuf data, boolean last) throws IOException;
422
    CompletableFuture<Void> writeNonBlocking(ByteBuf data, boolean last);
423
}
424

425
public class VertxBlockingOutput implements VertxOutput {
426
    public void write(ByteBuf data, boolean last) throws IOException;
427
    public CompletableFuture<Void> writeNonBlocking(ByteBuf data, boolean last);
428
}
429

430
public class VertxOutputStream extends AsyncOutputStream {
431
    // Standard OutputStream methods plus async variants for Vert.x integration
432
}
433
```
434

435
### Utility Classes
436

437
Additional utility classes for RESTEasy integration.
438

439
```java { .api }
440
public class NonJaxRsClassMappings {
441
    public String getBasePath();
442
    public void setBasePath(String basePath);
443
    public Map<String, String> getMethodNameToPath();
444
    public void setMethodNameToPath(Map<String, String> methodNameToPath);
445
}
446

447
public class VertxUtil {
448
    public static UriInfo extractUriInfo(HttpServerRequest req, String contextPath);
449
    public static HttpHeaders extractHttpHeaders(HttpServerRequest request);
450
    public static List<MediaType> extractAccepts(MultivaluedMap<String, String> requestHeaders);
451
    public static List<Locale> extractLanguages(MultivaluedMap<String, String> requestHeaders);
452
    public static MultivaluedMap<String, String> extractRequestHeaders(HttpServerRequest request);
453
}
454

455
public class RequestDispatcher {
456
    public SynchronousDispatcher getDispatcher();
457
    public String getDomain();
458
    public ResteasyProviderFactory getProviderFactory();
459
    public void service(Context context, HttpServerRequest req, HttpServerResponse resp, 
460
                       HttpRequest vertxReq, HttpResponse vertxResp, boolean handleNotFound, 
461
                       Throwable throwable);
462
}
463
```
464

465
### Security Context Implementation
466

467
Security context implementation for RESTEasy integration.
468

469
```java { .api }
470
public class QuarkusResteasySecurityContext implements SecurityContext {
471
    public Principal getUserPrincipal();
472
    public boolean isUserInRole(String role);
473
    public boolean isSecure();
474
    public String getAuthenticationScheme();
475
}
476
```
477

478
### Configuration Bridge
479

480
Bridge between MicroProfile Config and RESTEasy configuration.
481

482
```java { .api }
483
public class ResteasyConfigurationMPConfig implements ResteasyConfiguration {
484
    public String getParameter(String name);
485
    public Enumeration<String> getParameterNames();
486
    public String getInitParameter(String name);
487
    public Enumeration<String> getInitParameterNames();
488
}
489
```
490

491
### Core Interface Definitions
492

493
Essential interfaces used throughout the extension.
494

495
```java { .api }
496
public interface AsyncMessageBodyWriter<T> extends MessageBodyWriter<T> {
497
    CompletionStage<Void> asyncWriteTo(T t, Class<?> type, Type genericType,
498
                                      Annotation[] annotations, MediaType mediaType,
499
                                      MultivaluedMap<String, Object> httpHeaders,
500
                                      AsyncOutputStream entityStream);
501
}
502
```
503

504
## Extension Configuration
505

506
The extension provides these Quarkus capabilities:
507
- `io.quarkus.rest`: General REST capability
508
- `io.quarkus.resteasy`: RESTEasy-specific capability
509

510
Configuration prefix: `quarkus.resteasy.*`
511

512
Extension metadata:
513
- Short name: "jax-rs"  
514
- Categories: ["web"]
515
- Keywords: ["resteasy", "jaxrs", "web", "rest", "jakarta-rest"]
516
- Status: "stable"
517
- Supported languages: Java, Kotlin, Scala
518

519
## Dependencies
520

521
Core dependencies provided by the extension:
522
- Jakarta REST (JAX-RS) API
523
- RESTEasy implementation  
524
- Quarkus Vert.x HTTP integration
525
- Jakarta Servlet API (provided scope)
526
- Quarkus Security integration (when security extensions are present)
527

528
## Extension Points
529

530
The extension supports standard JAX-RS extension mechanisms:
531
- Custom `ExceptionMapper` implementations
532
- Custom `ContainerRequestFilter` and `ContainerResponseFilter` implementations  
533
- Custom `MessageBodyReader` and `MessageBodyWriter` implementations
534
- Security integrations through Quarkus Security framework
535
- Custom interceptors using `@Interceptor` and `@InterceptorBinding`
536

537
## Usage Patterns
538

539
### Standard JAX-RS Resource Development
540
Create standard Jakarta REST resources using familiar annotations:
541
- `@Path` - Define resource paths
542
- `@GET`, `@POST`, `@PUT`, `@DELETE` - HTTP methods  
543
- `@Produces`, `@Consumes` - Media types
544
- `@PathParam`, `@QueryParam`, `@FormParam` - Parameter binding
545

546
### Security Integration
547
Leverage Quarkus Security for declarative security:
548
- `@RolesAllowed`, `@PermitAll`, `@DenyAll` - Role-based access control
549
- `@Authenticated` - Require authentication
550
- HTTP security policies via `quarkus.http.auth.*` configuration
551

552
### Reactive Integration
553
Use Vert.x types directly in JAX-RS methods for reactive processing:
554
- `JsonObject` and `JsonArray` for JSON handling
555
- Integration with Quarkus's reactive ecosystem
556
- Support for reactive types through additional reactive extensions
557

558
This extension serves as the foundation for building REST APIs in Quarkus applications, providing seamless integration between RESTEasy and Quarkus's reactive, cloud-native architecture.