Chapter 2. Installation/Configuration

2.1. Using RESTEasy in your Application

RESTEasy is deployed as a WAR archive, so it must be deployed inside a Servlet container.
You can obtain the resteasy-jaxrs-war from the enterprise code source. The file is located in the /resteasy folder of the source code archive. Download the archive from the Red Hat Customer Support Portal.
Place your JAX-RS annotated class resources and providers in one or more JARs within /WEB-INF/lib. Alternatively, place your raw class files within /WEB-INF/classes. By default, RESTEasy is configured to scan JARs and classes within these directories for JAX-RS annotated classes, and to deploy and register them within the system.
RESTEasy is implemented as a ServletContextListener and a Servlet, and deployed within a WAR file. The WEB-INF/web.xml file contains the following:
<web-app>
    <display-name>Archetype Created Web Application</display-name>
    <!--Set this if you want Resteasy to scan for JAX-RS classes
    <context-param>
        <param-name>resteasy.scan</param-name>
        <param-value>true</param-value>
    </context-param>
    -->

    <!-- set this if you map the Resteasy servlet to something other than /*
    <context-param>
       <param-name>resteasy.servlet.mapping.prefix</param-name>
       <param-value>/resteasy</param-value>
    </context-param>
    -->
    <!-- to turn on security
    <context-param>
        <param-name>resteasy.role.based.security</param-name>
        <param-value>true</param-value>
    </context-param>
    -->

    <listener>
        <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
    </listener>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>
The ResteasyBootstrap listener initializes some of RESTEasy's basic components and scans for annotation classes that exist in your WAR file. It also receives configuration options from <context-param> elements.
These configuration options must be set if the <servlet-mapping> for the RESTEasy Servlet has a URL pattern other than /*. For example, if the URL pattern is:
<servlet-mapping>
  <servlet-name>Resteasy</servlet-name>
  <url-pattern>/restful-services/*</url-pattern>
</servlet-mapping>
Then the value of resteasy-servlet.mapping.prefix must be:
<context-param>
  <param-name>resteasy.servlet.mapping.prefix</param-name>
  <param-value>/restful-services</param-value>
</context-param>
The available <param-name> values are outlined below with the <param-value> defaults (or expected patterns) listed for reference.

Available <context-param> Parameter Names

resteasy.servlet.mapping.prefix
Defines the URL pattern for the RESTEasy servlet-mapping, if not /*.
resteasy.scan.providers
Scans for @Provider classes and registers them. The default value is false.
resteasy.scan.resources
Scans for JAX-RS resource classes. The default value is false.
resteasy.scan
Scans for both @Provider and JAX-RS resource classes (@Path, @GET, @POST, etc.) and registers them.
resteasy.providers
A comma-delimited list of fully-qualified @Provider class names you want to register.
resteasy.use.builtin.providers
Determines whether default, built-in @Provider classes are registered. The default value is true.
resteasy.resources
Comma-delimited list of fully-qualified JAX-RS resource class names you want to register.
resteasy.jndi.resources
A comma-delimited list of JNDI names referencing the objects that you want to register as JAX-RS resources.
javax.ws.rs.core.Application
Fully-qualified name of the Application class to bootstrap in a spec-portable way.
The ResteasyBootstrap listener configures an instance of the ResteasyProviderFactory and Registry. You can obtain ResteasyProviderFactory and Registry instances from the ServletContext attributes org.jboss.resteasy.spi.ResteasyProviderFactory and org.jboss.resteasy.spi.Registry.