Configuring JAX-RS applications using JAX-RS 1.1 methods

You can configure Java™ API for RESTful Web Services (JAX-RS) applications in multiple ways depending on your needs. To take advantage of the Java Platform, Enterprise Edition (Java EE) 6 functionality, you can use the annotation scanning capabilities. By using annotation scanning, you can omit a JAX-RS javax.ws.rs.core.Application subclass or have a minimally defined javax.ws.rs.core.Application subclass.

• Configure the JAX-RS application with only one JAX-RS default application in the web.xml file.
  Use this method if you only need one JAX-RS application and all resource classes are located after a single URL pattern. You can also specify security constraints with this method, if needed.
  1. Add all of your JAX-RS resource and provider classes to the WEB-INF/classes or WEB-INF/lib directory for your web application.  
     You do not need to add a javax.ws.rs.core.Application subclass to your web application.
  2. In your web.xml file, add a servlet definition with javax.ws.rs.core.Application as the servlet name.
     You do not need to add a servlet-class.  You must add a servlet URL pattern to the web.xml file. 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_of_Web_ module}/{value_of_Web.xml_URL_pattern}/{value_of_@javax.ws.rs.Path}

• Configure the JAX-RS application using the javax.ws.rs.core.Application subclass and the web.xml file.
  Use this method if you need multiple JAX-RS applications or require only specific resources in certain JAX-RS applications with specific URL patterns. You can also specify security constraints with this method, if needed.
  1. Create a javax.ws.rs.core.Application subclass.
     In your javax.ws.rs.core.Application subclass getClasses() or getSingletons() methods, return the relevant JAX-RS resources and providers.  If you return empty sets in both the getClasses() and getSingletons() methods, all the JAX-RS resource and provider classes that are 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 your web application.
  3. Add a partial servlet definition in the web.xml file.
     The servlet name is the full name of the javax.ws.rs.core.Application subclass.  Do not define the servlet-class.  You must add a servlet URL pattern to the web.xml file.  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_of_Web_ module}/{value_of_Web.xml_URL_pattern_for_Application_subclass}/{value_of_@javax.ws.rs.Path}

• Configure the JAX-RS application without a web.xml file.
  Use this method if you do not want to use a web.xml file. When you use this method, you cannot specify security constraints. To specify security constraints, you must use a web.xml file.
  1. Create a javax.ws.rs.core.Application subclass.
     In your javax.ws.rs.core.Application subclass getClasses() or getSingletons() methods, return the relevant JAX-RS resources and providers.  If you return empty sets in both the getClasses() and getSingletons() methods, all the JAX-RS resource and provider classes that are 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 the web.xml file; 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 your web application.
     When the application is started, the resources are available at the following URL:

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