Implement user handlers for JAX-RS applications

We can develop user handlers to customize the behavior of a handler chain and to add unique functionality to the handler. By implementing user handlers on the server-side of Java API for RESTful Web Services (JAX-RS) applications, we can enhance request and response processing.

We can add custom server-side user handlers to the request, response, and error handler chains. If additional processing such as logging every client request is required, then adding user handlers is one way of implementing the logging functionality.

In general, a handler receives a MessageContext instance for accessing and manipulating the current request information and a HandlerChain instance for advancing the chain. To pass control from one handler to another in the handler chain, it is the responsibility of the handler to invoke the doChain() method on the HandlerChain instance. Because a handler can call the doChain() method multiple times, you must consider the possibility that the handler might get invoked more than once for the same request. All handler-related interfaces reside in the org.apache.wink.server.handlers package.

Handlers use the MessageContext interface to access and manipulate the current request information. This interface enables handlers to maintain the state of a message by setting attributes on the message context. We can also use this interface to pass information to other handlers on the chain.

The request handler chain is responsible for processing a request according to the JAX-RS specification by accepting the request, searching for the resource method to invoke, deserializing the request entity, and ultimately invoking the resource method. A request handler is a class that implements the org.apache.wink.server.handlers.RequestHandler interface.

The response handler chain is responsible for handling the object returned from invoking a resource method or a sub-resource method according to the JAX-RS specification. It is responsible for determining the response status code, selecting the response media type, and for serializing the response entity. A Response handler is a class that implements the org.apache.wink.server.handlers.ResponseHandler interface.

A user handler class must implement the org.apache.wink.server.handlers.RequestHandler or org.apache.wink.server.handlers.ResponseHandler interface. Create a class that extends the org.apache.wink.server.handlers.HandlersFactory interface to return the request or response handler. Finally, specify the location of the property file, that has the HandlersFactory class name, as an initialization parameter in the web.xml file to ensure that the properties file is read by the servlet or filter.

1. Create a Java class that implements a handler interface for the request handler. In the following example, a request handler is created. This specific request handler prints out the path of every request to the RESTful service.

   package com.example;
    public class MyRequestHandler implements org.apache.wink.server.handlers.RequestHandler {
       public void init(java.util.Properties props) {
            /* This class is initialized with runtime properties. */
       }
        public void handleRequest(MessageContext context, HandlersChain chain) {
           UriInfo info = context.getUriInfo();
           System.out.println("The path relative to the base URI is : " + info.getPath());
           chain.doChain(context);
       }
   }

   To continue the handler chain, call the chain.doChain(context) method. Use the org.apache.wink.server.handlers.AbstractHandler interface to extend the handler chain. See the Javadoc information for all available methods on the context.

2. Create the handler factory implementation. The handler factory must have a public constructor that takes no arguments.

   public class MyHandlersFactory extends org.apache.wink.server.handlers.HandlersFactory {
       public MyHandlersFactory() {
           /* This constructor must exist because it is the only one called.*/
       }
   }

3. In the handler factory class, override the appropriate method to return the user handlers and to add the user handlers to the appropriate handler chain. In this example, because created a request handler, the getRequestHandlers() method is overridden.

   package com.example;
    public class MyHandlersFactory extends org.apache.wink.server.handlers.HandlersFactory {
       public MyHandlersFactory() {
           /* This constructor must exist because it is the only one called.*/
       }
        public List<? extends org.apache.wink.server.handlers.RequestHandler> getRequestHandlers() {
           return Arrays.asList(com.example.MyRequestHandler);
       }
   }

4. Create a simple text file containing properties to initialize at run time. In the following example, the properties file contains the following statement to specify the custom handler factory.
   wink.handlersFactoryClass=com.example.MyHandlersFactory

5. In the web.xml file, add the propertiesLocation initialization parameter to the servlet or filter definition that specifies the properties file. By specifying the location of the property file, containing the HandlersFactory class name, as an initialization parameter in the web.xml file, you ensure that the properties file is read by the JAX-RS servlet or filter.

   <servlet>
       <servlet-name>RestServlet</servlet-name>
       <servlet-class>com.ibm.websphere.rest.server.IBMRestServlet<servlet-class>
       <init-param>
           <param-name>javax.ws.rs.Application</param-name>
           <param-value>com.example.MyJAXRSApplicationSubclass</param-value>
       </init-param>
       <init-param>
           <param-name>propertiesLocation</param-name>
           <param-value>myproperties.properties</param-value>
       </init-param>
   </servlet>

Results

You have added a user handler to the handler chain on the server-side of the JAX-RS application so that these custom handlers get invoked on every request or response process.

Related tasks

Use handlers to enhance request and response processing