JBoss.orgCommunity Documentation

Chapter 2. Installation/Configuration

2.1. javax.ws.rs.core.Application
2.2. RESTEasyLogging

RESTeasy is deployed as a WAR archive and thus depends on a Servlet container. When you download RESTeasy and unzip it you will see that it contains an exploded WAR. Make a deep copy of the WAR archive for your particular application. Place your JAX-RS annotated class resources and providers within one or more jars within /WEB-INF/lib or your raw class files within /WEB-INF/classes. RESTeasy is configured by default to scan jars and classes within these directories for JAX-RS annotated classes and deploy and register them within the system.

RESTeasy is implemented as a ServletContextListener and a Servlet and deployed within a WAR file. If you open up the WEB-INF/web.xml in your RESTeasy download you will see this:

    
<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 is responsible for initializing some basic components of RESTeasy as well as scanning for annotation classes you have in your WAR file. It receives configuration options from <context-param> elements. Here's a list of what options are available

This config variable must be set if your 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>

Table 2.1. 

Option Name Default Value Description
resteasy.servlet.mapping.prefix no default If the url-pattern for the Resteasy servlet-mapping is not /*
resteasy.scan.providers false Scan for @Provider classes and register them
resteasy.scan.resources false Scan for JAX-RS resource classes
resteasy.scan false Scan for both @Provider and JAX-RS resource classes (@Path, @GET, @POST etc..) and register them
resteasy.providers no default A comma delimited list of fully qualified @Provider class names you want to register
resteasy.use.builtin.providers true Whether or not to register default, built-in @Provider classes. (Only available in 1.0-beta-5 and later)
resteasy.resources no default A comma delimited list of fully qualified JAX-RS resource class names you want to register
resteasy.jndi.resources no default A comma delimited list of JNDI names which reference objects you want to register as JAX-RS resources
javax.ws.rs.core.Application no default Fully qualified name of Application class to bootstrap in a spec portable way


The ResteasyBootstrap listener configures an instance of an ResteasyProviderFactory and Registry. You can obtain instances of a ResteasyProviderFactory and Registry from the ServletContext attributes org.jboss.resteasy.spi.ResteasyProviderFactory and org.jboss.resteasy.spi.Registry.

javax.ws.rs.core.Application is a standard JAX-RS class that you may implement to provide information on your deployment. It is simply a class the lists all JAX-RS root resources and providers.

/**
 * Defines the components of a JAX-RS application and supplies additional
 * metadata. A JAX-RS application or implementation supplies a concrete
 * subclass of this abstract class.
 */
public abstract class Application
{
   private static final Set<Object> emptySet = Collections.emptySet();

   /**
    * Get a set of root resource and provider classes. The default lifecycle
    * for resource class instances is per-request. The default lifecycle for
    * providers is singleton.
    * <p/>
    * <p>Implementations should warn about and ignore classes that do not
    * conform to the requirements of root resource or provider classes.
    * Implementations should warn about and ignore classes for which
    * {@link #getSingletons()} returns an instance. Implementations MUST
    * NOT modify the returned set.</p>
    *
    * @return a set of root resource and provider classes. Returning null
    *         is equivalent to returning an empty set.
    */
   public abstract Set<Class<?>> getClasses();

   /**
    * Get a set of root resource and provider instances. Fields and properties
    * of returned instances are injected with their declared dependencies
    * (see {@link Context}) by the runtime prior to use.
    * <p/>
    * <p>Implementations should warn about and ignore classes that do not
    * conform to the requirements of root resource or provider classes.
    * Implementations should flag an error if the returned set includes
    * more than one instance of the same class. Implementations MUST
    * NOT modify the returned set.</p>
    * <p/>
    * <p>The default implementation returns an empty set.</p>
    *
    * @return a set of root resource and provider instances. Returning null
    *         is equivalent to returning an empty set.
    */
   public Set<Object> getSingletons()
   {
      return emptySet;
   }

}

To use Application you must set a servlet context-param, javax.ws.rs.core.Application with a fully qualified class that implements Application. For example:


   <context-param>
      <param-name>javax.ws.rs.core.Application</param-name>
      <param-value>com.mycom.MyApplicationConfig</param-value>
   </context-param>



If you have this set, you should probably turn off automatic scanning as this will probably result in duplicate classes being registered.

RESTEasy logs various events using slf4j.

The slf4j API is intended to serve as a simple facade for various logging APIs allowing to plug in the desired implementation at deployment time. By default, RESTEasy is configured to use Apache log4j, but you may opt to choose any logging provider supported by slf4j.

The logging categories are still a work in progress, but the initial set should make it easier to trouleshoot issues. Currently, the framework has defined the following log categories:


If you're developing RESTEasy code, the LoggerCategories class provide easy access to category names and provides easy access to the various loggers.