Disabling the JAX-RS runtime environment

Sometimes you must disable the Java™ API for RESTful Web Services (JAX-RS) runtime environment. When you disable the JAX-RS runtime environment, JAX-RS features are not available, including base JAX-RS runtime capabilities, Enterprise JavaBeans (EJB) runtime integration, Java Contexts and Dependency Injection (JCDI) runtime integration, and Servlet 3.0 web container integration.

Avoid trouble: If you are disabling JAX-RS runtime environment to prevent class conflicts with application classes, then it is preferable to switch to a different JAX-RS implementation to avoid these conflicts. For more information, see Coexistence of JAX-RS 2.0 with JAX-RS 1.1.

About this task

By disabling the JAX-RS runtime environment, any JAX-RS related processing of the application, including processing of classes with scanned JAX-RS annotations, EJB metadata, and JCDI bean enablement, is no longer performed. The JAX-RS runtime environment is not used to process requests and responses to and from the web container.

Best practice: Disabling the JAX-RS runtime environment does not disable Servlet 3.0 based annotation scanning for JAX-RS annotations such as javax.ws.rs.Path. To disable annotation scanning, set the metadata-complete attribute. If annotation scanning is disabled, it is disabled for all other components outside of JAX-RS.

The explicit plug points to the IBM® JAX-RS runtime environment are the com.ibm.websphere.jaxrs.server.IBMRestServlet servlet class and the com.ibm.websphere.jaxrs.server.IBMRestFilter filter class. If you specify these classes as your servlet-class or servlet-filter in the web module web.xml file, the IBM JAX-RS runtime environment processes requests to that servlet.

To disable the JAX-RS runtime environment from doing so, replace those classes with any other servlet or filter class that can handle expected requests to the servlet, or remove the servlet entirely from the web.xml file.

Avoid trouble: Replacing the IBMRestServlet class with another might modify existing behavior in the application. Removing the servlet entirely results in requests not being processed.

Even if not explicitly using the com.ibm.websphere.jaxrs.server.IBMRestServlet or com.ibm.websphere.jaxrs.server.IBMRestFilter classes, the JAX-RS integration runtime environment might still process the application. For example, if the web.xml file of a web module is Servlet 3.0 based, and appropriate conditions are met according to the JSR-311 specification, the JAX-RS integration runtime environment processes scanned classes with JAX-RS annotations and might inject a servlet that can handle requests to the JAX-RS resources in the application.

To disable this function, and other functions such as EJB and JCDI integration, set the com.ibm.websphere.jaxrs.server.DisableIBMJAXRS20Engine custom Java virtual machine (JVM) property on the application server with a value of true.

Procedure

Remove references to IBMRestServlet and IBMRestFilter from the web.xml file.

The following example illustrates a sample web.xml file from an application that uses the IBM JAX-RS runtime environment.

<?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>MyRestApplication1</servlet-name>
        <servlet-class>com.ibm.websphere.jaxrs.server.IBMRestServlet</servlet-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.ibm.websphere.jaxrs.example.Application1</param-value>
        </init-param>
        <init-param>
            <param-name>requestProcessorAttribute</param-name>
            <param-value>MyRestApplication1RequestProcessorAttribute</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet>
        <servlet-name>MyNonJAXRSApplication</servlet-name>
        <servlet-class>com.ibm.websphere.example.NonJAXRSServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <filter>
        <filter-name>MyRestApplication2</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.websphere.jaxrs.example.Application2</param-value>
        </init-param>
        <init-param>
            <param-name>requestProcessorAttribute</param-name>
            <param-value>MyRestApplication2RequestProcessorAttribute</param-value>
        </init-param>
    </filter>
    <servlet-mapping>
        <servlet-name>MyRestApplication1</servlet-name>
        <url-pattern>/jaxrsapp1/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>MyNonJAXRSApplication</servlet-name>
        <url-pattern>/nonjaxrsapp/*</url-pattern>
    </servlet-mapping>
    <filter-mapping>
        <filter-name>MyRestApplication2</servlet-name>
        <url-pattern>/jaxrsapp2/*</url-pattern>
    </filter-mapping>
<web-app>

The following example illustrates how the web.xml file looks after you remove the references to the IBMRestServlet and IBMRestFilter classes.

<?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>MyNonJAXRSApplication</servlet-name>
        <servlet-class>com.ibm.websphere.example.NonJAXRSServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>MyNonJAXRSApplication</servlet-name>
        <url-pattern>/nonjaxrsapp/*</url-pattern>
    </servlet-mapping>
</web-app>

Set the com.ibm.websphere.jaxrs.server.DisableIBMJAXRS20Engine custom JVM property on the application server with a value of true.
Restart the application server for the custom JVM property to take effect.

Results

You disabled the JAX-RS runtime environment from processing your application.