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
JAR
s within /WEB-INF/lib
. Alternatively, place your raw class files within /WEB-INF/classes
. By default, RESTEasy is configured to scan JAR
s 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 isfalse
. -
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 istrue
. -
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
.