• [+] expand all

services.xml - container
edit page

This is the reference for container cluster configuration: 

container [version, id]
    http
        server [id, port]
        filtering
    rest-api
        components [bundle]
            package
    servlet [id, class, bundle]
        path
        servlet-config
    handler [id, class, bundle]
        binding
        clientbinding
        component
    client [id, class, bundle]
        binding
        clientbinding
        component
    server [id, class, bundle]
    components
    component
    search
        include [dir]
        binding
        searcher
        federation
        provider
        chain
        renderer
    document-processing
        include [dir]
        documentprocessor
        chain
    processing
        include [dir]
        binding
        processor
        chain
        renderer
    document-api
        abortondocumenterror
        retryenabled
        route
        maxpendingdocs
        maxpendingbytes
        retrydelay
        timeout
        tracelevel
        mbusport
    document [type, class, bundle]
    accesslog [type, fileNamePattern, symlinkName, rotationInterval, rotationScheme]
    config
    nodes [jvmargs, allocated-memory]
        node [hostalias]
Note: container is equivalent to jdisc - use container, as jdisc will be discontinued.

Contained in services, zero or more container elements. The root element of a container cluster definition. Most elements takes optional config elements. Attributes:

NameRequiredValueDefaultDescription
version required number 1.0 in this version of Vespa
id required string logical name of this cluster
Example: 
<container id="default" version="1.0">
  <search>
    <chain id="default">
      <searcher id="com.mydomain.search.SimpleSearcher"/>
    </chain>
  </search>
  <nodes>
    <node hostalias="node1"/>
  </nodes>
</container>
Each container cluster has a default http server port, unless it contains a http element. Hence, when running more than one container cluster on the same node, it is necessary to manually assign a port to the http server to all but one cluster. Otherwise, the application will not deploy. Assigning a port is done by adding a server element with an explicit port number: 
<container id="cluster2" version="1.0">
  <http>
    <server id="myServer" port="8081" />
  </http>
  ...
</container>

rest-api

Add a Jersey web application with resources and providers to the container cluster. Multiple web applications can be created by adding multiple rest-api elements with unique paths. Bundles containing Jersey components are added by giving the symbolic name (and optional version) in components sub-elements. From each given bundle, all classes with root annotations will be included in the corresponding web application. Note: No extra dependencies in pom.xml - the relevant artifacts are already pulled in via container. The bundle plugin ensures that the Jersey resources are available. Attributes:

NameRequiredValueDefaultDescription
path required string The path to bind the rest-api.
Notes:
  • Components can be injected directly into Jersey resources
  • Injecting Config without wrapping it in a Component will not work
  • While Jersey creates a new resource instance for each request, the Components is the same object until the application is restarted or redeployed
  • Injected components can be a subclass of the parameter class required by the resource constructor

components

Add a bundle to scan for Jersey components. Attributes:

NameRequiredValueDefaultDescription
bundle required string The bundle to include Jersey components from. Format: 'symbolicName:version'

package

Scan for components only in the given packages. If no package elements are given, all packages will be scanned. Example: 

<rest-api path="my-app">
  <components bundle="my-bundle">
    <package>com.mydomain.foo</package>
    <package>com.mydomain.bar</package>
  </components>
  <components bundle="other-bundle:2.0.0" />
</rest-api>

servlet

Add a Servlet, one per servlet element. Minimum one path child element is required. Attributes:

NameRequiredValueDefaultDescription
id required string A unique id
class required string The class to load as a Servlet
bundle required string The bundle that the Servlet resides in

path

The path the Servlet will bind to.

servlet-config

An alternative to regular config to support legacy ServletConfig. It is a simple map of string keys to string values that will be available as ServletConfig inside the Servlet. Example: 

<servlet id="my-servlet" class="com.mydomain.MyServlet" bundle="servlet-example">
  <path>my-path</path>
  <servlet-config>
    <myKey>myValue</myKey>
  </servlet-config>
</servlet>

handler

The handler element holds the configuration of a handler. If any binding tag, binding or clientBinding is present, the handler is a JDisc request handler, and will be bound to the pertinent JDisc interfaces using the given bindings.

  • binding For JDisc request handlers, add this server binding to this handler.
  • clientBinding For JDisc request handlers, add this client binding to this handler.
  • component for injecting another component. Must be a declaration of a new component, not a reference.
Attributes:
NameRequiredValueDefaultDescription
id required string The component ID
class optional string The class of the handler, defaults to id
bundle optional string The bundle to load the handler from, defaults to class or id (if no class is given)
Example: 
<container id="default" version="1.0">
  <handler id="com.yahoo.search.handler.LegacyBridge">
    <binding>http://*/*</binding>
  </handler>
  <handler bundle="myHandlers" id="com.mydomain.vespatest.RedirectingHandler"/>
  <handler bundle="myHandlers" id="com.mydomain.vespatest.ExampleHandler"/>
  <nodes>
    <node hostalias="node1"/>
  </nodes>
</container>

binding

The URI to map a Handler to. Multiple elements are allowed. See example above.

clientbinding

ToDo

client

The client element holds the configuration of a JDisc client provider. It has one mandatory attribute, id and must be bound to some URI pattern to be available for use. Same subelements as handler. Attributes:

NameRequiredValueDefaultDescription
id required string The component ID
class optional string The class of the handler, defaults to id
bundle optional string The bundle to load the handler from, defaults to class or id (if no class is given)
Example: 
<client id="com.mydomain.vespatest.DemoClient">
  <config name="vespatest.response">
    <response>DemoClient says: Hello, world!
    </response>
  </config>
  <binding>http://remotehost/*</binding>
  <binding>http://another-remotehost/*</binding>
  <serverBinding>http://*:8080/DemoClient</serverBinding>
</client>

server

The server element holds the configuration of a JDisc server provider. Attributes:

NameRequiredValueDefaultDescription
id required string The component ID
class optional string The class of the server, defaults to id
bundle optional string The bundle to load the server from, defaults to class or id (if no class is given)
Example: 
<server id="com.mydomain.vespatest.DemoServer">
  <config name="vespatest.demo-server">
    <response>Hello, world!
    </response>
    <port>16889</port>
  </config>
</server>

components

Contains component elements. Can be used in conjunction with include for modular config of components.

component

The component element holds the configuration of a generic component. Must be a declaration of a new component, not a reference.

Nested component child elements can be added for injecting specific component instances. This is useful if there is more than one declared component of the same Java class. Refer to Injecting components for details and examples.

Attributes:
NameRequiredValueDefaultDescription
id required string The component ID
class optional string The class of the component, defaults to id
bundle optional string The bundle to load the component from, defaults to class or id (if no class is given)
Example: 
<component id="com.mydomain.demo.DemoComponent" bundle="demo" />

document-api

Use to enable Document API operations to a container cluster. Children elements:

NameRequiredValueDefaultDescription
binding optional string http://*/ The URI to map the document-api handlers to. Multiple bindings are valid. Must end with a '/'. Note that each document-api handler will get its individual binding by adding a suffix, e.g. the feed handler will add 'feed/', the remove handler will add 'remove/' and so on. Example: 
<document-api>
  <binding>http://*/document-api/</binding>
  <binding>https://*/document-api/</binding>
</document-api>
With these configured bindings, the feed handler will be available at http://*/document-api/feed/ and https://*/document-api/feed/. For other handlers, just replace 'feed/' with the appropriate suffix, e.g. 'get/', 'remove/' etc.
abortondocumenterror optional true/false true Controls whether or not to abort the entire feed if a document-related error occurs, ie. if a document contains an unknown field. Setting this field to true will abort the feed on such errors, while setting it to false will cause Vespa to simply skip to the next document in the feed. Note that malformed XML in the input will abort the feed regardless of this setting.
maxpendingbytes optional number The maximum number of pending bytes. If <maxpendingdocs> is 0 and this is set to 0, this defaults to 100MB. If <maxpendingdocs> is more than 0, and this is set to 0, the send window is only limited by number of messages sent, not the memory footprint.
maxpendingdocs optional number The maximum number of pending documents the client can have. By default, the client will dynamically adjust the window size based on the latency of the performed operations. If the parameter is set, dynamic window sizing will be turned off in favor of the configured value.
mbusport optional number Set the MessageBus port
retrydelay optional double 1.0 Delay in seconds between retries
retryenabled optional true/false Enable or disable retrying documents that have failed.
route optional string default Set the route to feed documents to
timeout optional double 180.0 Set the timeout value in seconds for an operation
tracelevel optional 0-9 0 Configure the level of which to trace messages sent. The higher the level, the more detailed descriptions.
Example: 
<document-api>
  <binding>http://*/document-api/</binding>
  <binding>https://*/document-api/</binding>
  <abortondocumenterror>false</abortondocumenterror>
  <maxpendingbytes>1048576</maxpendingdocs>
  <maxpendingdocs>1000</maxpendingdocs>
  <mbusport>1234</mbusport>
  <retrydelay>5.5</retrydelay>
  <retryenabled>false</retryenabled>
  <route>default</route>
  <timeout>250.5</timeout>
  <tracelevel>3</tracelevel>
<document-api>

document

Concrete document type bindings for the container. Example: 

<container id="default" version="1.0">
  <document class="com.mydomain.concretedocs.Vehicle" bundle="concretedocs" type="vehicle"/>
  <document class="com.mydomain.concretedocs.Vehicle" bundle="concretedocs" type="ship"/>
  <document class="com.mydomain.concretedocs2.Disease" bundle="concretedocs2" type="disease"/>
  <search/>
  <document-processing>
    <chain id="default">
      <documentprocessor bundle="concretedocs" id="concretedocs.ConcreteDocDocProc"/>
    </chain>
  </document-processing>
  <nodes>
    <node hostalias="node1"/>
  </nodes>
</container>

accesslog

Configures properties of the accesslog. Setting the type to vespa gives a classic Apache CLF-like format. For a more detailed and more easily parsable format, type json will give output in (line-based) JSON format. Access logging can be disabled by setting the type to disabled. Attributes:

NameRequiredValueDefaultDescription
type optional string vespa The accesslog type: vespa, json or disabled
fileNamePattern string File name pattern
symlinkName string Symlink name
rotationInterval string Rotation interval
rotationScheme string Valid values are date or sequence
Example: 
<accesslog fileNamePattern='$VESPA_HOME/logs/vespa/qrs/QueryAccessLog.a.%Y%m%d%H%M%S' symlinkName='QueryAccessLog.a' rotationInterval='0 1 ...' type='vespa' />

include

Allows including XML snippets contained in external files. All files from all listed directories will be included. All files must have the same outer tag as they were referred from, i.e. search, document-processing or processing. The path must be relative to the application package root, and must never point outside of the package. Attributes:

NameRequiredValueDefaultDescription
dir required string The directory to include files from. File inclusion order is undefined.
Example: 
<include dir="included_configs/search" />

nodes

The nodes element specifies the nodes that comprise this container cluster by adding node children. Attributes:

NameRequiredValueDefaultDescription
jvmargs optional string JVM arguments for nodes in this cluster
allocated-memory optional percentage Memory to allocate to each JVM instance as a percentage of available memory. Must be an integer percentage followed by %

node

Attributes:

NameRequiredValueDefaultDescription
hostalias required string logical hostname - mapped to hostnames in hosts.xml
Example: 
<nodes jvmargs="-XX:+PrintGCDetails -XX:+PrintGCTimeStamps" allocated-memory="50%">
  <node hostalias="searchnode1" />
</nodes>