Developing request handlers

This document explains how to implement and deploy a custom request handler.

In most cases, implementing your own request handlers is unnecessary, as both searchers and processors can access the request data directly. However, there are a few cases where custom request handlers are useful:

1. You need to implement a custom REST API.
2. Your application needs to control which parameters are used to route requests to a particular search or processing chain.

Implementing a request handler

Upon receiving a request, the request handler must consume its content, process it, and then return a response. The most convenient way to implement a request handler is by subclassing the ThreadedHttpRequestHandler.

This utility base class uses a synchronous API and a multi-threaded execution model. It also implements a lot of functionality that is needed by most request handlers:

• queries are automatically written to the access log
• a HTTP date header is added to the response (if your own code adds a date header, it will not be overwritten, though)
• logging of exceptions and queries that time out
• automatic shutdown when an Error is thrown

Example request handler implementations

The Vespa sample apps on GitHub contains a few example request handler implementations:

Deploying a request handler

To deploy a request handler in an application, use the handler element in services.xml:

<container id="default" version="1.0">
    <handler id="my.package.MyRequestHandler" bundle="the name in <artifactId> in your pom.xml">
        <binding>http://*/*</binding>
    </handler>

A request handler may be bound to zero or more URI patterns by adding a binding element for each pattern.