Configuring the web.xml file for JAX-RS filters

The web.xml file contains information about the structure and external dependencies of web components in the module and describes how the components are used at run time. To enable the web container to run Java™ API for RESTful Web Services (JAX-RS) applications, you can configure the web.xml file to define filters that indicate the possible URLs on which the filter can be invoked.

About this task

You can configure the web.xml file for your web application to enable the JAX-RS application code. You can specify an IBM® specific JAX-RS filter to use to run your JAX-RS code. The web.xml file provides configuration and deployment information for the web components that comprise a web application. Read about configuring the web.xml file for JAX-RS to learn more about this deployment descriptor file.

When using servlets, any servlet path defined in the web.xml is appended to the base URL. Filters do not append a path to the resource base URL. Instead, filter URL mappings indicate the possible URLs on which the filter can be invoked. For instance, if a root resource has a @javax.ws.rs.Path value of myresource, the final URL of the resource is http://<your_hostname>:<your Web_container_port>/<context_root_of_Web_application>/myresource. The URL mapping pattern for the filter must match myresource for the root resource to be served correctly. For this example, you can use /* or /myresource for the URL pattern. When there are multiple resources in the application, the URL pattern for the filter must match all of the resources. The /* pattern is a common value for the filter.

If the incoming request URL does not match any JAX-RS resources in the JAX-RS application, the request is passed to the rest of the filter chain. Depending on the application, you might want to use the filter behavior so that requests are served by the JAX-RS application, or if there is no JAX-RS resource available, the request can proceed to an underlying web container artifact, such as a JavaServer Pages (JSP). If the web container has no matching artifact, then the web container is responsible for the error response.

Procedure

Open the WEB-INF/web.xml file.

Define your filter in the WEB-INF/web.xml file.

Add the following filter definition to the WEB-INF/web.xml file. Replace the unique_filter_name with your unique filter name. Also replace the Java_class_name variable with the full Java package and class name of the JAX-RS application Java subclass.

<filter>
         <filter-name>unique_filter_name</filter-name>
         <filter-class>com.ibm.websphere.jaxrs.server.IBMRestFilter</filter-class>
         <init-param>
                 <param-name>javax.ws.rs.Application</param-name>
                 <param-value>Java_class_name</param-value>
         </init-param>
 </filter>

(optional) If there are multiple JAX-RS application subclasses needed in the same web application, you must include an additional filter initialization parameter, requestProcessorAttribute, in the filter definition that you add to the WEB-INF/web.xml file.

In the following filter, replace the unique_filter_name with your unique filter name; replace the Java_class_name variable with the full Java package and the class name of the JAX-RS application Java subclass; replace the unique_identifier variable with a unique identifier.

<filter>
   <filter-name>unique_filter_name_a</filter-name>
   <filter-class>com.ibm.websphere.jaxrs.server.IBMRestFilter</filter-class>
   <init-param>
       <param-name>javax.ws.rs.Application</param-name>
       <param-value>Java_class_name_a</param-value>
   </init-param>
   
   <init-param>
       <param-name>requestProcessorAttribute</param-name>
       <param-value>unique_identifier_a</param-value>
   </init-param>
</filter>

<filter>
   <filter-name>unique_filter_name_b</filter-name>
   <filter-class>com.ibm.websphere.jaxrs.server.IBMRestFilter</filter-class>
   <init-param>
       <param-name>javax.ws.rs.Application</param-name>
       <param-value>Java_class_name_b</param-value>
   </init-param>
        
   <init-param>
       <param-name>requestProcessorAttribute</param-name>
       <param-value>unique_identifier_b</param-value>
   </init-param>
</filter

Add filter mappings in the WEB-INF/web.xml file for each filter definition.
The URL pattern specified in the filter mapping defines to the container the valid URL patterns for invoking the IBMRestFilter filter. If an incoming request URL is compatible with the URL pattern, the IBMRestFilter is invoked. If the request URL does not match, the filter is not invoked. The request URLs always start at the context root for the filter. See the following example filter mappings:
```
<filter-mapping>
    <filter-name>filter_name</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
```
For example, suppose you have the following two resources:
```
@javax.ws.rs.Path("myresource")
public class MyResource {

}
```
```
@javax.ws.rs.Path("myresource2")
public class MyResource2 {

}
```
You can reach the resources using the following URL:
```
http://<your_hostname>:<your Web_container_port>/<context_root_of_Web_application>/myresource
```
```
http://<your_hostname>:<your Web_container_port>/<context_root_of_Web_application>/myresource2
```
If you apply the following filter mapping:
```
<filter-mapping>
        <filter-name>filter_name</filter-name>
        <url-pattern>/myresource</url-pattern>
</filter-mapping>   
```
you can use MyResource root resource by visiting the following URL:
```
http://<your_hostname>:<your Web_container_port>/<context_root_of_Web_application>/myresource
```
This URL invokes the IBMRestFilter filter and the URL can find the resource. Because the /myresource path matches with the URL pattern in the filter-mapping, the IBMRestFilter does get invoked and there is a root resource that has a matching @Path value.
However, suppose you visit the following URL:
```
http://<your_hostname>:<your Web_container_port>/<context_root_of_Web_application>/myresource2
```
the IBMRestFilter filter is not invoked because the URL pattern /myresource does not match /myresource2.

Results

After editing the WEB-INF/web.xml file to apply filters, the web application is configured for the JAX-RS application.

Example

The following example illustrates a WEB-INF/web.xml file that is configured to apply filters to a JAX-RS application. This example defines the RestApplication1 filter. If an incoming request URL matches a resource in the RestApplication1 filter, the response is generated from RestApplication1 filter. If the incoming request URL does not match a resource in the RestApplication1 filter but matches a resource in OtherRestApplicationFilter, then the response is generated from the OtherRestApplicationFilter filter. If the incoming URL does not match either filter, then the request can be served from another web container artifact, such as a JSP.

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_9" version="2.4" 
xmlns=http://java.sun.com/xml/ns/j2ee 
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

     <filter>
        <filter-name>RestApplication1</filter-name>
        <filter-class>com.ibm.websphere.jaxrs.server.IBMRestFilter</filter-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.ibm.rest.sample.app1.MyApplication</param-value>
        </init-param>
        <init-param>
            <param-name>requestProcessorAttribute</param-name>
            <param-value>restApplication1ProcessorID</param-value>
        </init-param>
    </filter>
     <filter>
        <filter-name>OtherRestApplicationServlet</filter-name>
        <filter-class>com.ibm.websphere.jaxrs.server.IBMRestFilter</filter-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.ibm.rest.other.sample.OtherApplication</param-value>
        </init-param>
        <init-param>
            <param-name>requestProcessorAttribute</param-name>
            <param-value>otherRestApplicationID </param-value>
        </init-param>
    </filter>

    <filter-mapping>
        <filter-name>RestApplication1</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    <filter-mapping>
        <filter-name>OtherRestApplicationServlet</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
</web-app>

What to do next

Assemble the web application.