Configure JAX-RS applications using JAX-RS 1.1 methods

With Java EE 6 functionality we can use the annotation scanning capabilities. By using annotation scanning, we can omit a JAX-RS javax.ws.rs.core.Application subclass or have a minimally defined javax.ws.rs.core.Application subclass.

The JAX-RS 1.1 specification supports several new ways to configure a JAX-RS application. Use the built-in annotation scanning to help automatically configure the application. We can optionally add javax.ws.rs.core.Application subclasses to the application and then add the URL patterns required using either the javax.ws.rs.ApplicationPath annotation or a web.xml servlet definition. When using the IBM JAX-RS implementation, we do not have to specify the servlet class implementation because it is automatically added to the configuration of the web module by the time the JAX-RS application is started.

Use a Java Servlet 3.0 web.xml file. This allows us to specify security constraints.

• Configure the JAX-RS application with only one JAX-RS default application in web.xml.

  Use this method if we only need one JAX-RS application and all resource classes are located after a single URL pattern.

  1. Add all of the JAX-RS resource and provider classes to the WEB-INF/classes or WEB-INF/lib directory for the web application. You do not need to add a javax.ws.rs.core.Application subclass to the web application.

  2. In web.xml, add a servlet definition with javax.ws.rs.core.Application as the servlet name. You do not need to add a servlet-class. We must add a servlet URL pattern to web.xml. The application server runtime environment adds the specific IBM JAX-RS implementation to the configuration of the web module by the time the JAX-RS application is started; for example:

     <?xml version="1.0" encoding="UTF-8"?>
     <web-app xmlns="http://java.sun.com/xml/ns/j2ee"           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
              http://java.sun.com/xml/ns/j2ee/web-app_3_0.xsd"
              version="3.0">
       <servlet>
       <servlet-name>javax.ws.rs.core.Application</servlet-name>
      </servlet>
      <servlet-mapping>
       <servlet-name>javax.ws.rs.core.Application</servlet-name>
       <url-pattern>/rest/*</url-pattern>
      </servlet-mapping>
     </web-app>
     

     The JAX-RS resources are now available at a URL such as:

     http://{hostname}:{port}/{context_root}/{Web.xml_URL_pattern}/{value_of_@javax.ws.rs.Path}

• Configure the JAX-RS application using the javax.ws.rs.core.Application subclass and web.xml.

  Use this method for multiple JAX-RS applications, for specific resources in certain JAX-RS applications with specific URL patterns.

  1. Create a javax.ws.rs.core.Application subclass.

     In the javax.ws.rs.core.Application subclass methods...

     • getClasses()
     • getSingletons()

     ...return the relevant JAX-RS resources and providers. If we return empty sets in both the getClasses() and getSingletons() methods, all the JAX-RS resource and provider classes found in the application are added to the JAX-RS application subclass; for example:

     package com.example;
      public class MyApplication extends javax.ws.rs.core.Application  {
     }

     This example uses the default implementations of javax.ws.rs.core.Application subclass getClasses() and getSingletons() methods that return empty sets. Therefore, all relevant JAX-RS classes are assumed to be returned by the javax.ws.rs.core.Application subclass.

  2. Add the javax.ws.rs.core.Application subclass to the web application.

  3. Add a partial servlet definition in web.xml.

     The servlet name is the full name of the javax.ws.rs.core.Application subclass. Do not define the servlet-class. We must add a servlet URL pattern to web.xml. The application server runtime environment adds the specific IBM JAX-RS implementation to the configuration of the web module by the time the JAX-RS application is started; for example:

     <?xml version="1.0" encoding="UTF-8"?>
      <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
              http://java.sun.com/xml/ns/j2ee/web-app_3_0.xsd"
              version="3.0">
      <servlet>
          <servlet-name>com.example.MyApplication</servlet-name>
      </servlet>
       <servlet-mapping>
          <servlet-name>com.example.MyApplication</servlet-name>
          <url-pattern>/rest/*</url-pattern>
      </servlet-mapping>
      </web-app>
     

     The JAX-RS resources are now available at a URL such as:

     http://{hostname}:{port}/{context_root}/{Web.xml_URL_pattern_App_subclass}/{value_of_@javax.ws.rs.Path}

• Configure the JAX-RS application without a web.xml file.

  Use this method if we do not want to use a web.xml file. When you use this method, we cannot specify security constraints. To specify security constraints, use a web.xml file.

  1. Create a javax.ws.rs.core.Application subclass.

     In the javax.ws.rs.core.Application subclass getClasses() or getSingletons() methods, return the relevant JAX-RS resources and providers. If we return empty sets in both the getClasses() and getSingletons() methods, all the JAX-RS resource and provider classes found in the application are added to the JAX-RS application subclass; for example:

     package com.example;
      public class MyApplication extends javax.ws.rs.core.Application {
      }

     This example uses the default implementations of javax.ws.rs.core.Application subclass getClasses() and getSingletons() methods that return empty sets. Therefore, all relevant JAX-RS classes are assumed to be returned by the javax.ws.rs.core.Application subclass.

  2. Add a javax.ws.rs.ApplicationPath annotation to the javax.ws.rs.core.Application subclass. The ApplicationPath annotation is supported with the JAX-RS 1.1 specification. The value of the ApplicationPath annotation is used as the servlet URL pattern which is equivalent to the servlet URL pattern in web.xml; for example:

     package com.example;
      @javax.ws.rs.ApplicationPath("rest")
     public class MyApplication extends javax.ws.rs.core.Application {
      }

  3. Add the javax.ws.rs.core.Application subclass to the web application.

     When the application is started, the resources are available at the following URL:

     http://{hostname}:{port}/{context_rootmodule}/{value_of_@javax.ws.rs.ApplicationPath}}/{value_of_@javax.ws.rs.Path}

Results

You have configured the JAX-RS application using JAX-RS 1.1 supported methods by taking advantage of annotation scanning to help automatically configure the application.

Related tasks

Configure web.xml for JAX-RS servlets

Configure web.xml for JAX-RS filters