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
@Providerclasses 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
@Providerand JAX-RS resource classes (@Path,@GET,@POST, etc.) and registers them. -
resteasy.providers - A comma-delimited list of fully-qualified
@Providerclass names you want to register. -
resteasy.use.builtin.providers - Determines whether default, built-in
@Providerclasses 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.
