Container Component Reference

A component is any Java class whose lifetime is controlled by the container, see the Developer Guide for an introduction. Components are specified and configured in services.xml and can have other components, and config (represented by generated "Config" classes) injected at construction time, and in turn be injected into other components.

Whenever a component or a resource your component depends on is changed by a redeployment, your component is reconstructed. Once all changed components are reconstructed, new requests are atomically switched to use the new set and the old ones are destructed.

If you have multiple constructors in your component, annotate the one to use for injection by @Inject.

Identifiable components must implement, and components that need to destruct resources at removal must subclass and implement deconstruct().

Component Types

Vespa defined various component types (superclasses) for common tasks:

Request handlers

Request handlers lets applications implement arbitrary HTTP API's.

A request handler accepts a request and returns a response. In the most general case they are asynchronous. can be subclasses to use synchronous request prcoessing.


The processing framework can be used to create general composable synchronous request-response systems. Searchers and search chains are an instantiation (through subclasses) of this general framework for a specific domain. Processors are invoked synchronously and the response is a tree of arbitrary data elements. Custom output formats can be defined by adding renderers.


Renderers convert a Response (or query Result) into a serialized form sent over the network. Renderers are subclasses of


Searchers processes Queries and their Results. Since they are synchronous, they can issue multiple queries serially or in parallel to e.g implement federation or decorate queries with information fetched from a content cluster. Searchers are composed into search chains defined in services.xml. A query request selects a particular search chain which implements the logic of that query.

Document processors

Document processors processes incoming document operations. Similar to Searchers and Processors they can be composed in chains, but document processors are asynchronous.


A binding matches a request URI to the correct filter chain or request handler, and route outgoing requests to the correct client. For instance, the binding http://*/* would match any HTTP request, while http://*/processing would only match that specific path. If several bindings match, the most specific one is chosen.

Server binding A server binding is a rule for matching incoming requests to the correct request handler, basically the JDisc building block for implementing RESTful APIs
Client binding A client binding is a pattern which is used to match requests originating inside the container, e.g. when doing federation, to a client provider. That is, it is a rule which determines what code should handle a given outgoing request

A filter is a lightweight request checker. It may set some specific request property, or it may do security checking and simply block requests missing some mandatory property or header.


Clients, or client providers, are implementations of clients for different protocols, or special rules for given protocols. When a JDisc application acts as a client, e.g. fetches a web page from another host, it is a client provider that handles the transaction. Bindings are used, as with request handlers and filters, to choose the correct client, matching protocol, server, etc, and then hands off the request to the client provider. There is no problem in using arbitrary other types of clients for external services in processors and request handlers.

Clickable illustration:

DFD for JDisc container binding client binding client custom request handler processing processing request processing response processor processor processor JDisc request and response JDisc request and response JDisc request and response binding binding binding filter filter filter filter filter filter filter filter filter binding binding binding server server server

Component configurations

This illustrates a typical component configuration set up by the Vespa container:

The network layer associates a Request with a response handler and routes it to the correct type of request handler (typically based on URI binding patterns).

If an application needs lightweight request-response processing using decomposition by a series of chained logical units, the processing framework is the correct family of components to use. The request will be routed from ProcessingHandler through one or more chains of Processor instances. The exact format of the output is customizable using a Renderer.

If doing queries, SearchHandler will create a Query object, route that to the pertinent chain of Searcher instances, and associate the returned Result with the correct Renderer instance for optional customization of the output format.

The DocumentProcessingHandler is usually invoked from messagebus, and used for feeding documents into an index or storage. The incoming data is used to build a Document object, and this is then feed through a chain of DocumentProcessor instances.

If building an application with custom HTTP APIs, for instance arbitrary REST APIs, the easiest way is building a custom RequestHandler. This gets the Request, which is basically a set of key-value pairs, and returns a stream of arbitrary data back to the network.

Injectable Components

These components are available from Vespa to applications in various contexts.

Always available
ConfigInstance Configuration is injected into components as ConfigInstance components - see configuring components.
MetricReceiver Use to emit metrics from a component. Find an example in the metrics guide.
Statistics Use to keep values that are logged periodically. Support for min/max/avg/sum and histograms, see statistics.
Linguistics Inject a Linguistics component like SimpleLinguistics or provide a custom implementation - see linguistics.
AthenzIdentityProvider Provides the application's Athenz-identity and gives access to identity/role certificate and tokens.

A client for ZooKeeper. For use in container clusters that have ZooKeeper enabled. See using ZooKeeper.

Executor Default threadpool for processing requests in threaded request handler
VipStatus Use this to gain control overe the service status (up/down) to be emitted from this container.
Metric Jdisc core interface for metrics. Required by all sub-classes of ThreadedRequestHandler.
Available in containers having search
ExecutionFactory To execute new queries from code. Example code.
Available in containers having document-api or document-processing
DocumentAccess To use the Document API.
Available in the Vespa Cloud
SecretStore Secret store interface - use to get secrets and list secret versions.
SystemInfo Provides information about the environment the component is running in.