[[Jakarta_RESTful_Web_Services_Reference_Guide]]
= Jakarta RESTful Web Services Reference Guide

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

RESTEasy is the Jakarta RESTful Web Services implementation used in {appservername}. For detailed documentation see the
https://resteasy.dev/docs[RESTEasy {resteasyversion} documentation].

== Jakarta RESTful Web Services Activation

This section outlines the three options you have for deploying Jakarta RESTful Web Services
applications in WildFly {wildflyVersion}. These three methods are specified in the
Jakarta RESTful Web Services 3.1 specification in section 2.3.2.

[[subclassing-jakarta.ws.rs.core.application-and-using-applicationpath]]
=== Subclassing jakarta.ws.rs.core.Application and using @ApplicationPath

This is the easiest way and does not require any xml configuration.
Simply include a subclass of `jakarta.ws.rs.core.Application` in your
application, and annotate it with the path that you want your JAX-RS
classes to be available. For example:

[source,java,options="nowrap"]
----
@ApplicationPath("/mypath")
public class MyApplication extends Application {
}
----

This will make your Jakarta RESTful Web Services resources available under `/`
`mywebappcontext` `/mypath`.

[WARNING]

Note that that the path is `/mypath` not `/mypath/*`

[[subclassing-jakarta.ws.rs.core.application-and-using-web.xml]]
=== Subclassing jakarta.ws.rs.core.Application and using web.xml

If you do not wish to use `@ApplicationPath` but still need to subclass
`Application` you can set up the Jakarta RESTful Web Services mapping in web.xml:

[source,java,options="nowrap"]
----
public class MyApplication extends Application {
}
----

[source,xml,options="nowrap"]
----
<servlet-mapping>
   <servlet-name>com.acme.MyApplication</servlet-name>
   <url-pattern>/hello/*</url-pattern>
</servlet-mapping>
----

This will make your Jakarta RESTful Web Services resources available under `/`
`mywebappcontext` `/hello`.

[NOTE]

You can also use this approach to override an application path set with
the `@ApplicationPath` annotation.

[[using-web.xml]]
=== Using web.xml

If you don't wan't to subclass `Application` you can set the Jakarta RESTful Web Services
mapping in web.xml as follows:

[source,xml,options="nowrap"]
----
<servlet-mapping>
   <servlet-name>jakarta.ws.rs.core.Application</servlet-name>
   <url-pattern>/hello/*</url-pattern>
</servlet-mapping>
----

This will make your Jakarta RESTful Web Services resources available under `/`
`mywebappcontext` `/hello`.

[NOTE]

Note that you only have to add the mapping, not the corresponding
servlet. The server is responsible for adding the corresponding servlet
automatically.

== Using Jackson for serialization

By default, for JSON processing the Jakarta JSON Processing API is used. However, you can use Jackson instead. This can
be achieved by setting the `resteasy.preferJacksonOverJsonB` property as a system property or as a
context property in the deployment's `web.xml`. There is also a subsystem attribute, `resteasy-prefer-jackson-over-jsonb`,
which can be set to `true`. Finally, if no value is set for the context and system properties, the subsystem scans Jakarta
RESTful Web Services deployments for Jackson annotations and sets the property to true if any of those annotations are
found.

=== Custom `ObjectMapper`

In some cases you may want to or need to create a custom `ObjectMapper`. This can be achieved by creating a
`jakarta.ws.rs.ext.ContextResolver` which creates the `ObjectMapper`. The following example creates an `ObjectMapper`
which allows JSR-310 date/times.

[source,java]
----
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.ext.ContextResolver;
import jakarta.ws.rs.ext.Provider;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.json.JsonMapper;

@Provider
@Produces(MediaType.APPLICATION_JSON)
public class JacksonDatatypeJacksonProducer implements ContextResolver<ObjectMapper> {

    private final ObjectMapper json;

    public JacksonDatatypeJacksonProducer() {
        this.json = JsonMapper.builder()
                .findAndAddModules()
                .build();
    }

    @Override
    public ObjectMapper getContext(Class<?> objectType) {
        return json;
    }
}
----

As of WildFly 27 and RESTEasy 6.2 to get the Jakarta XML Binding annotations to work with Jackson for JSON serialization
you need to use a custom `ObjectMapper`. An example of this `ObjectMapper` would look like:

[source,java]
----
import jakarta.ws.rs.ext.ContextResolver;
import jakarta.ws.rs.ext.Provider;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.json.JsonMapper;
import com.fasterxml.jackson.module.jakarta.xmlbind.JakartaXmlBindAnnotationModule;

@Provider
public class JaxbJsonObjectMapperProvider implements ContextResolver<ObjectMapper> {
    private static final JsonMapper MAPPER = JsonMapper.builder()
            .addModule(new JakartaXmlBindAnnotationModule())
            .build();

    @Override
    public ObjectMapper getContext(final Class<?> type) {
        return MAPPER;
    }
}
----

== Using the Tracing Feature

The tracing feature provides more internal states of the Jakarta RESTful Web Services container. For example, it could
be able to show what filters a request is going through, or how long time a request is processed and other kinds of information.

The tracing feature can be enabled by setting the `tracing-type` attribute to `ALL` or `ON_DEMAND`. You can also control
the threshold with the `tracing-threshold` attribute. The following is an example of enabling tracing using CLI:

----
/subsystem=jaxrs:write-attribute(name=tracing-type, value=ALL)
:reload
----

You can also configure the tracing feature with the context parameters `resteasy.server.tracing.type` and
`resteasy.server.tracing.threshold` in your deployments `web.xml` file.

IMPORTANT: The tracing feature should not be used in production environments. Data can be exposed to clients via HTTP headers.

== RESTEasy Spring Framework Integration

WildFly generally includes support for Jakarta Context and Dependency Injection (CDI). The Spring Framework, however,
does not support CDI. You may need to exclude some subsystems and modules for Spring applications to work with Jakarta
RESTful Web Services.

The following is an example `jboss-deployment-structure.xml` that may be needed.

[source,xml]
----
<?xml version="1.0"?>
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2"
                            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <deployment>
        <exclusions>
            <module name="org.jboss.resteasy.resteasy-cdi"/>
        </exclusions>
    </deployment>
</jboss-deployment-structure>
----

The `org.jboss.resteasy.resteasy-cdi` module adds CDI support for the RESTEasy implementation. Excluding this
should allow Spring deployments to work.

NOTE: References in this document to Java API for RESTful Web Services (JAX-RS) refer to Jakarta RESTful Web Services unless otherwise noted.
