or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-io-quarkus--quarkus-resteasy

REST endpoint framework implementing Jakarta REST and more for Quarkus applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.quarkus/quarkus-resteasy@3.23.x

To install, run

npx @tessl/cli install tessl/maven-io-quarkus--quarkus-resteasy@3.23.0

index.mddocs/

Quarkus RESTEasy Classic Extension

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.

Package Information

  • Package Name: io.quarkus:quarkus-resteasy
  • Package Type: Maven
  • Language: Java
  • Installation: Add to Maven dependencies:
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy</artifactId>
</dependency>

Core Imports

Standard Jakarta REST annotations and Quarkus integration classes:

import jakarta.ws.rs.*;
import jakarta.ws.rs.core.*;
import jakarta.ws.rs.ext.*;
import jakarta.servlet.http.*;
import io.quarkus.resteasy.runtime.*;
import io.quarkus.resteasy.runtime.standalone.*;
import io.quarkus.resteasy.runtime.vertx.*;
import io.vertx.core.json.JsonObject;
import io.vertx.core.json.JsonArray;
import io.vertx.ext.web.RoutingContext;
import org.jboss.resteasy.spi.AsyncMessageBodyWriter;
import org.jboss.resteasy.spi.AsyncOutputStream;

Basic Usage

Create a simple REST endpoint using Jakarta REST annotations:

import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/hello")
public class HelloResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello, World!";
    }

    @GET
    @Path("/{name}")
    @Produces(MediaType.TEXT_PLAIN)
    public String helloName(@PathParam("name") String name) {
        return "Hello, " + name + "!";
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response createEntity(String jsonData) {
        // Process JSON data
        return Response.status(201).entity("Created").build();
    }
}

Using Vert.x integration for JSON handling:

import io.vertx.core.json.JsonObject;
import io.vertx.core.json.JsonArray;

@Path("/api")
public class ApiResource {
    
    @POST
    @Path("/data")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public JsonObject processData(JsonObject input) {
        // Direct Vert.x JsonObject usage
        return new JsonObject()
            .put("status", "processed")
            .put("input", input);
    }
    
    @GET
    @Path("/items")
    @Produces(MediaType.APPLICATION_JSON)
    public JsonArray getItems() {
        return new JsonArray()
            .add("item1")
            .add("item2")
            .add("item3");
    }
}

Architecture

The extension integrates RESTEasy with Quarkus's reactive architecture:

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

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

Capabilities

Configuration

Configure RESTEasy Vert.x integration settings.

@ConfigRoot(phase = ConfigPhase.BUILD_AND_RUN_TIME_FIXED)
@ConfigMapping(prefix = "quarkus.resteasy.vertx")
public interface ResteasyVertxConfig {
    @WithDefault("8191")
    int responseBufferSize();
}

Configuration properties:

  • quarkus.resteasy.vertx.response-buffer-size: Output stream response buffer size (default: 8191)

Path Template Processing

Annotation for REST path template interception and processing.

@Inherited
@InterceptorBinding
@Target({ElementType.ANNOTATION_TYPE, ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface QuarkusRestPathTemplate {
    @Nonbinding String value() default "";
}

Used with interceptor for metrics and observability:

@QuarkusRestPathTemplate
@Interceptor
@Priority(Interceptor.Priority.LIBRARY_BEFORE)
public class QuarkusRestPathTemplateInterceptor {
    // Processes path templates for monitoring integration
}

Security Integration

JAX-RS permission checker for endpoint security.

@ApplicationScoped
public class JaxRsPermissionChecker {
    public boolean shouldRunPermissionChecks();
    public boolean applyPermissionChecks(MethodDescription method);
    public MethodDescription getMethodSecuredWithAuthZPolicy(
        MethodDescription method, MethodDescription fallback);
}

Security filters for request processing:

@Provider
@Priority(Priorities.AUTHENTICATION)
public class EagerSecurityFilter implements ContainerRequestFilter {
    // Performs security checks early in request processing
}

@Provider
@Priority(Priorities.AUTHENTICATION + 1)
public class SecurityContextFilter implements ContainerRequestFilter {
    // Manages security context during request processing
}

Security interceptor for method-level checks:

@Interceptor
@Priority(Interceptor.Priority.PLATFORM_BEFORE + 1)
public class StandardSecurityCheckInterceptor {
    // Applies standard security checks to JAX-RS methods
}

Exception Mapping

Built-in exception mappers for common security scenarios.

@Provider
public class AuthenticationRedirectExceptionMapper 
    implements ExceptionMapper<AuthenticationRedirectException> {
    public Response toResponse(AuthenticationRedirectException exception);
}

@Provider
public class AuthenticationFailedExceptionMapper 
    implements ExceptionMapper<AuthenticationFailedException> {
    public Response toResponse(AuthenticationFailedException exception);
}

@Provider
public class AuthenticationCompletionExceptionMapper 
    implements ExceptionMapper<AuthenticationCompletionException> {
    public Response toResponse(AuthenticationCompletionException exception);
}

@Provider
public class ForbiddenExceptionMapper 
    implements ExceptionMapper<ForbiddenException> {
    public Response toResponse(ForbiddenException exception);
}

@Provider
public class UnauthorizedExceptionMapper 
    implements ExceptionMapper<UnauthorizedException> {
    public Response toResponse(UnauthorizedException exception);
}

Vert.x JSON Integration

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

@Provider
@Produces(MediaType.APPLICATION_JSON)
public class JsonObjectReader implements MessageBodyReader<JsonObject> {
    public boolean isReadable(Class<?> type, Type genericType,
                            Annotation[] annotations, MediaType mediaType);
    public JsonObject readFrom(Class<JsonObject> type, Type genericType,
                             Annotation[] annotations, MediaType mediaType,
                             MultivaluedMap<String, String> httpHeaders,
                             InputStream entityStream) throws IOException, WebApplicationException;
}

@Provider
@Consumes(MediaType.APPLICATION_JSON)
public class JsonObjectWriter implements AsyncMessageBodyWriter<JsonObject> {
    public boolean isWriteable(Class<?> type, Type genericType,
                             Annotation[] annotations, MediaType mediaType);
    public void writeTo(JsonObject jsonObject, Class<?> type, Type genericType,
                       Annotation[] annotations, MediaType mediaType,
                       MultivaluedMap<String, Object> httpHeaders,
                       OutputStream entityStream) throws IOException, WebApplicationException;
    public CompletionStage<Void> asyncWriteTo(JsonObject jsonObject, Class<?> type, Type genericType,
                       Annotation[] annotations, MediaType mediaType,
                       MultivaluedMap<String, Object> httpHeaders,
                       AsyncOutputStream entityStream);
}

@Provider
@Produces(MediaType.APPLICATION_JSON)
public class JsonArrayReader implements MessageBodyReader<JsonArray> {
    public boolean isReadable(Class<?> type, Type genericType,
                            Annotation[] annotations, MediaType mediaType);
    public JsonArray readFrom(Class<JsonArray> type, Type genericType,
                            Annotation[] annotations, MediaType mediaType,
                            MultivaluedMap<String, String> httpHeaders,
                            InputStream entityStream) throws IOException, WebApplicationException;
}

@Provider  
@Consumes(MediaType.APPLICATION_JSON)
public class JsonArrayWriter implements AsyncMessageBodyWriter<JsonArray> {
    public boolean isWriteable(Class<?> type, Type genericType,
                             Annotation[] annotations, MediaType mediaType);
    public void writeTo(JsonArray jsonArray, Class<?> type, Type genericType,
                       Annotation[] annotations, MediaType mediaType,
                       MultivaluedMap<String, Object> httpHeaders,
                       OutputStream entityStream) throws IOException, WebApplicationException;
    public CompletionStage<Void> asyncWriteTo(JsonArray jsonArray, Class<?> type, Type genericType,
                       Annotation[] annotations, MediaType mediaType,
                       MultivaluedMap<String, Object> httpHeaders,
                       AsyncOutputStream entityStream);
}

Context Utilities

Utility for pushing context objects from virtual HTTP plugins.

public class ContextUtil {
    public static void pushContext(RoutingContext routingContext);
}

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

Servlet Integration

RESTEasy servlet and filter implementations for traditional servlet environments.

public class ResteasyServlet extends HttpServlet30Dispatcher {
    /**
     * Service method for handling HTTP requests in servlet environments
     */
    public void service(String httpMethod, HttpServletRequest request, 
                       HttpServletResponse response) throws ServletException, IOException;
}

public class ResteasyFilter extends Filter30Dispatcher {
    /**
     * Filter method for intercepting requests in servlet filter chains
     */
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, 
                        FilterChain filterChain) throws IOException, ServletException;
}

Additional Exception Mapping

Additional exception mapper for composite exception handling.

@Provider
public class CompositeExceptionMapper implements ExceptionMapper<CompositeException> {
    public Response toResponse(CompositeException exception);
}

Enhanced Security Interceptors

Complete security interceptor implementations for RBAC and authentication.

public abstract class StandardSecurityCheckInterceptor {
    
    @Interceptor
    @RolesAllowed("")
    @Priority(Interceptor.Priority.LIBRARY_BEFORE)
    public static class RolesAllowedInterceptor {
        @AroundInvoke
        public Object intercept(InvocationContext invocationContext) throws Exception;
    }
    
    @Interceptor
    @PermissionsAllowed("")
    @Priority(Interceptor.Priority.LIBRARY_BEFORE)
    public static class PermissionsAllowedInterceptor {
        @AroundInvoke
        public Object intercept(InvocationContext invocationContext) throws Exception;
    }
    
    @Interceptor
    @PermitAll
    @Priority(Interceptor.Priority.LIBRARY_BEFORE)
    public static class PermitAllInterceptor {
        @AroundInvoke
        public Object intercept(InvocationContext invocationContext) throws Exception;
    }
    
    @Interceptor
    @Authenticated
    @Priority(Interceptor.Priority.LIBRARY_BEFORE)
    public static class AuthenticatedInterceptor {
        @AroundInvoke
        public Object intercept(InvocationContext invocationContext) throws Exception;
    }
}

Standalone Runtime Components

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

@Recorder
public class ResteasyStandaloneRecorder {
    public RuntimeValue<Deployment> staticInit(ResteasyDeployment dep, String path);
    public void start(ShutdownContext shutdown, boolean isVirtual);
    public Handler<RoutingContext> vertxRequestHandler(RuntimeValue<Deployment> deployment, 
                                                      String rootPath);
    public Handler<FailureRoutingContext> vertxFailureHandler(RuntimeValue<Deployment> deployment, 
                                                             String rootPath);
    public Handler<RoutingContext> defaultAuthFailureHandler();
}

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

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

public class VertxHttpResponse implements HttpResponse {
    // HTTP response implementation for Vert.x integration
}

Vert.x Streaming and Buffer Management

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

public interface BufferAllocator {
    ByteBuf allocateBuffer();
    ByteBuf allocateBuffer(boolean direct);
    ByteBuf allocateBuffer(int bufferSize);
    ByteBuf allocateBuffer(boolean direct, int bufferSize);
    int getBufferSize();
}

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

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

public class VertxOutputStream extends AsyncOutputStream {
    // Standard OutputStream methods plus async variants for Vert.x integration
}

Utility Classes

Additional utility classes for RESTEasy integration.

public class NonJaxRsClassMappings {
    public String getBasePath();
    public void setBasePath(String basePath);
    public Map<String, String> getMethodNameToPath();
    public void setMethodNameToPath(Map<String, String> methodNameToPath);
}

public class VertxUtil {
    public static UriInfo extractUriInfo(HttpServerRequest req, String contextPath);
    public static HttpHeaders extractHttpHeaders(HttpServerRequest request);
    public static List<MediaType> extractAccepts(MultivaluedMap<String, String> requestHeaders);
    public static List<Locale> extractLanguages(MultivaluedMap<String, String> requestHeaders);
    public static MultivaluedMap<String, String> extractRequestHeaders(HttpServerRequest request);
}

public class RequestDispatcher {
    public SynchronousDispatcher getDispatcher();
    public String getDomain();
    public ResteasyProviderFactory getProviderFactory();
    public void service(Context context, HttpServerRequest req, HttpServerResponse resp, 
                       HttpRequest vertxReq, HttpResponse vertxResp, boolean handleNotFound, 
                       Throwable throwable);
}

Security Context Implementation

Security context implementation for RESTEasy integration.

public class QuarkusResteasySecurityContext implements SecurityContext {
    public Principal getUserPrincipal();
    public boolean isUserInRole(String role);
    public boolean isSecure();
    public String getAuthenticationScheme();
}

Configuration Bridge

Bridge between MicroProfile Config and RESTEasy configuration.

public class ResteasyConfigurationMPConfig implements ResteasyConfiguration {
    public String getParameter(String name);
    public Enumeration<String> getParameterNames();
    public String getInitParameter(String name);
    public Enumeration<String> getInitParameterNames();
}

Core Interface Definitions

Essential interfaces used throughout the extension.

public interface AsyncMessageBodyWriter<T> extends MessageBodyWriter<T> {
    CompletionStage<Void> asyncWriteTo(T t, Class<?> type, Type genericType,
                                      Annotation[] annotations, MediaType mediaType,
                                      MultivaluedMap<String, Object> httpHeaders,
                                      AsyncOutputStream entityStream);
}

Extension Configuration

The extension provides these Quarkus capabilities:

  • io.quarkus.rest: General REST capability
  • io.quarkus.resteasy: RESTEasy-specific capability

Configuration prefix: quarkus.resteasy.*

Extension metadata:

  • Short name: "jax-rs"
  • Categories: ["web"]
  • Keywords: ["resteasy", "jaxrs", "web", "rest", "jakarta-rest"]
  • Status: "stable"
  • Supported languages: Java, Kotlin, Scala

Dependencies

Core dependencies provided by the extension:

  • Jakarta REST (JAX-RS) API
  • RESTEasy implementation
  • Quarkus Vert.x HTTP integration
  • Jakarta Servlet API (provided scope)
  • Quarkus Security integration (when security extensions are present)

Extension Points

The extension supports standard JAX-RS extension mechanisms:

  • Custom ExceptionMapper implementations
  • Custom ContainerRequestFilter and ContainerResponseFilter implementations
  • Custom MessageBodyReader and MessageBodyWriter implementations
  • Security integrations through Quarkus Security framework
  • Custom interceptors using @Interceptor and @InterceptorBinding

Usage Patterns

Standard JAX-RS Resource Development

Create standard Jakarta REST resources using familiar annotations:

  • @Path - Define resource paths
  • @GET, @POST, @PUT, @DELETE - HTTP methods
  • @Produces, @Consumes - Media types
  • @PathParam, @QueryParam, @FormParam - Parameter binding

Security Integration

Leverage Quarkus Security for declarative security:

  • @RolesAllowed, @PermitAll, @DenyAll - Role-based access control
  • @Authenticated - Require authentication
  • HTTP security policies via quarkus.http.auth.* configuration

Reactive Integration

Use Vert.x types directly in JAX-RS methods for reactive processing:

  • JsonObject and JsonArray for JSON handling
  • Integration with Quarkus's reactive ecosystem
  • Support for reactive types through additional reactive extensions

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.