Configure web.xml for JAX-RS filters

The web.xml file contains information about the structure and 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, we can configure web.xml to define filters indicating URLs on which the filter can be invoked.

We specify an IBM specific JAX-RS filter for running the JAX-RS code.

Servlet paths defined in web.xml are 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 root resource @javax.ws.rs.Path has a value of myresource, the final URL of the resource is...

The URL mapping pattern for the filter must match myresource for the root resource to be served correctly. For this example, we 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 JSP. If the web container has no matching artifact, then the web container is responsible for the error response.

  1. Edit WEB-INF/web.xml.

  2. Define the 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 the 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>

  3. Optional. If there are multiple JAX-RS application subclasses needed in the same web application, include an additional filter initialization parameter, requestProcessorAttribute, in the filter definition that we 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

  4. 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 we have the following two resources: 
    @javax.ws.rs.Path("myresource")
public class MyResource {
 }
    @javax.ws.rs.Path("myresource2")
public class MyResource2 {
 }
    We can reach the resources using the following URL:

      http://host:port/ContextRoot/myresource

      http://host:port/ContextRoot/myresource2

    If we apply the following filter mapping: 

    <filter-mapping>
        <filter-name>filter_name</filter-name>
        <url-pattern>/myresource</url-pattern>
</filter-mapping>
    we can use MyResource root resource by visiting the following URL:

      http://host:port/ContextRoot/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://host:port/ContextRoot/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 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="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_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.


Related tasks

  • Implement JAX-RS web applications
  • Configure web.xml for JAX-RS servlets