expand all
collapse all

Developer Guide

Application packages can contain Java components to be run in container clusters. The most common component types are:

Searchers, which can modify or build the query, modify the result, implement workflows issuing multiple queries etc.
Document processors that can modify incoming write operations.
Handlers that can implement custom web service APIs.
Renderers that are used to define custom result formats.

Components are constructed by dependency injection and are reloaded safely on deployment without restarts. See the container documentation for more details.

See the sample applications in getting started, to find examples of applications containing Java components. Also see troubleshooting.

Developing Components

The development cycle consists of creating the component, deploying the application package to Vespa, writing tests, and iterating. These steps refer to files in album-recommendation-java:

Build

Build	All the Vespa sample applications use the bundle plugin to build the components.
Configure	A key Vespa feature is code and configuration consistency, deployed using an application package. This ensures that code and configuration is in sync, and loaded atomically when deployed. This is done by generating config classes from config definition files. In Vespa and application code, configuration is therefore accessed through generated config classes. The Maven target `generate-sources` (invoked by `mvn install`) uses metal-names.def to generate `target/generated-sources/vespa-configgen-plugin/com/mydomain/example/MetalNamesConfig.java`. After generating config classes, they will resolve in tools like IntelliJ IDEA.
Tests	Examples unit tests are found in MetalSearcherTest.java. `testAddedOrTerm1` and `testAddedOrTerm2` illustrates two ways of doing the same test: The first setting up the minimal search chain for YQL programmatically The second uses `com.yahoo.application.Application`, which sets up the application package and simplifies testing Read more in unit testing.

All the Vespa sample applications use the bundle plugin to build the components.

Configure

A key Vespa feature is code and configuration consistency, deployed using an application package. This ensures that code and configuration is in sync, and loaded atomically when deployed. This is done by generating config classes from config definition files. In Vespa and application code, configuration is therefore accessed through generated config classes.

The Maven target generate-sources (invoked by mvn install) uses metal-names.def to generate target/generated-sources/vespa-configgen-plugin/com/mydomain/example/MetalNamesConfig.java.

After generating config classes, they will resolve in tools like IntelliJ IDEA.

Tests

Examples unit tests are found in MetalSearcherTest.java. testAddedOrTerm1 and testAddedOrTerm2 illustrates two ways of doing the same test:

The first setting up the minimal search chain for YQL programmatically
The second uses com.yahoo.application.Application, which sets up the application package and simplifies testing

Debugging Components

Important: The debugging procedure only works for endpoints with an open debug port - most managed services don't do this for security reasons.

To debug a Searcher / Document Processor / Component running in the container, set up a remote debugging configuration in the IDEA - IntelliJ example:

Run -> Edit Configurations...
Click + to add a new configuration.
Select the "Remote JVM Debug" option in the left-most pane.
Set hostname to the host running the container, change the port if needed.

Set the container's jvm options to the value in "Command line arguments for remote JVM":

<container id="default" version="1.0">
    <nodes>
        <jvm options="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" />

Re-deploy the application, then restart Vespa on the node that runs the container. Make sure the port is published if using a Docker container, e.g.:

$ docker run --detach --name vespa --hostname vespa-container \
  --publish 127.0.0.1:8080:8080 --publish 127.0.0.1:19071:19071 --publish 127.0.0.1:5005:5005 \
  vespaengine/vespa

Start debugging! Check vespa.log for errors.

Vespa videos: Find Debugging a Vespa Searcher in the vespaengine youtube channel!