Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
261 lines (235 sloc) 9.85 KB
---
# Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
title: "Chained Components"
---
<p >
<a href="jdisc/processing.html">Processors</a>,
<a href="searcher-development.html">searcher plug-ins</a> and
<a href="docproc-development.html">document processors</a>
are chained components.
They are executed serially, with each providing some service or transform,
and other optionally depending on these.
In other words, a chain is a set of components with dependencies.
</p><p>
Javadoc: <a href="http://javadoc.io/page/com.yahoo.vespa/chain/latest/com/yahoo/component/chain/Chain.html">
com.yahoo.component.chain.Chain</a>
</p><p>
A chained component has three basic differences from a component in general:
<ul>
<li>The named services it <em>provides</em> to other components in the chain.</li>
<li>The list of services or checkpoints which the component itself
should be <em>before</em> in a chain, in other words, its dependants.</li>
<li>The list of services or checkpoints which the component itself
should be <em>after</em> in a chain, in other words, its dependencies.</li>
</ul>
What a component should be placed before, what it should be placed
after and what itself provides, may be either defined using Java
annotations directly on the component class, or it may be added
specifically to the component declarations
in <a href="reference/services-container.html">services.xml</a>.
In general, the implementation should have as many of the necessary
annotations as practical, leaving the application specific
configuration clean and simple to work with.
</p>
<h2 id="ordering-components">Ordering Components</h2>
<p>
The execution order of the components in a chain is not defined by the
order of the components in the configuration. Instead the order is
defined by adding the <em>ordering constraints</em> to the components:
<ul>
<li>Any component may declare that it <code>@Provides</code> some
named functionality (the names are just labels that have no meaning
to the container).</li>
<li>Any component may declare that it must be placed
<code>@Before</code> some named functionality,</li>
<li>or that it must be placed <code>@After</code> some
functionality.</li>
</ul>
The container will pick any ordering of a chain consistent with the
constraints of the components in the chain.
</p><p>
Dependencies can be added in two ways. Dependencies which are due to
the code should be added as annotations in the code:
<pre>
import com.yahoo.processing.*;
<strong>@Provides("SourceSelection")
@Before("Federation")
@After("IntentModel")</strong>
public class SimpleProcessor extends Processor {
@Override
public Response process(Request request, Execution execution) {
//TODO: Implement this
}
}
</pre>
Multiple functionality names may be specified by using the
syntax <code>@Provides/Before/After({"A",
"B"})</code>.
</p><p>
Annotations which do not belong in the code may be added in the
<a href="reference/services-container.html">configuration</a>:
<pre>
&lt;container version="1.0"&gt;
&lt;processing&gt;
&lt;processor id="processor1" class="com.yahoo.test.Processor1" /&gt;
&lt;chain id="default"&gt;
&lt;processor idref="processor1"/&gt;
&lt;processor id="processor2" class="com.yahoo.test.Processor2"&gt;
<strong>&lt;after&gt;com.yahoo.test.Processor1&lt;/after&gt;</strong>
&lt;/processor&gt;
&lt;/chain&gt;
&lt;/processing&gt;
&lt;nodes&gt;
&lt;node hostalias="node1" /&gt;
&lt;/nodes&gt;
&lt;/container&gt;
</pre>
For convenience, components always <code>Provides</code> their own
fully qualified class name (the package and simple class name
concatenated, e.g.
<code>com.yahoo.example.SimpleProcessor</code>) and their
simple name (that is, only the class name, like
<code>SimpleProcessor</code> in our searcher case), so it is always
possible to declare that one must execute before or after some
particular component. This goes for both general processors, searchers
and document processors.
</p><p>
Finally, note that ordering constraints are just that; in particular
they are not used to determine if a given search chain, or set of
search chains, is &ldquo;complete&rdquo;.
</p>
<h2 id="chain-inheritance">Chain Inheritance</h2>
<p>
As implied by examples above, chains may inherit other chains
in <em>services.xml</em>.
<pre>
&lt;container version="1.0"&gt;
&lt;processing&gt;
&lt;chain id="foo"&gt;
&lt;processor id="com.yahoo.example.ConnexityProcessor"/&gt;
&lt;processor id="com.yahoo.example.IteratingProcessor"/&gt;
&lt;processor id="com.yahoo.example.SignificanceProcessor" /&gt;
&lt;/chain&gt;
&lt;chain id="bar" inherits="foo" excludes="com.yahoo.example.IteratingProcessor"&gt;
&lt;processor id="com.yahoo.example.ReverseProcessor" /&gt;
&lt;/chain&gt;
&lt;/processing&gt;
&lt;nodes&gt;
&lt;node hostalias="node1" /&gt;
&lt;/nodes&gt;
&lt;/container&gt;
</pre>
A chain will include all components from the chains named in the
optional <code>inherits</code> attribute, exclude from that set all
components named in the also optional
<code>excludes</code> attribute and add all the components listed
inside the defining tag. Both <code>inherits</code> and
<code>excludes</code> are space delimited lists of reference
names.
</p><p>
For search chains, there are two built-in search chains which are especially
useful to inherit from, <code>native</code> and <code>vespa</code>.
<code>native</code> is a basic search chain, containing the
basic functionality most systems will need anyway,
<code>vespa</code> inherits from <code>native</code> and adds a
few extra searchers which most installations containing Vespa backends will need.
<pre>
&lt;container version="1.0"&gt;
&lt;search&gt;
&lt;chain id="default" inherits="vespa" excludes="com.yahoo.prelude.querytransform.StemmingSearcher com.yahoo.prelude.querytransform.NormalizingSearcher"&gt;
&lt;searcher id="com.yahoo.example.ConnexitySearcher" /&gt;
&lt;searcher id="com.yahoo.example.SignificanceSearcher" /&gt;
&lt;searcher id="com.yahoo.example.ReverseSearcher" /&gt;
&lt;/chain&gt;
&lt;/search&gt;
&lt;nodes&gt;
&lt;node hostalias="node1" /&gt;
&lt;/nodes&gt;
&lt;/container&gt;
</pre>
<h2 id="unit-tests">Unit Tests</h2>
<p>
A component should be unit tested in a chain containing the components it depends on.
It is not necessary to run the dependency handling framework to achieve that,
as the <code>com.yahoo.component.chain.Chain</code> class has several
constructors which are easy to use while testing.
<pre>
Chain&lt;Searcher&gt; c = new Chain(new UselessSearcher("first"),
new UselessSearcher("second"),
new UselessSearcher("third"));
Execution e = new Execution(c, Execution.Context.createContextStub(null));
Result r = e.search(new Query());
</pre>
The above is a rather useless test, but it illustrates how the basic
workflow can be simulated. The constructor will create a chain with
supplied searchers in the given order (it will not analyze any annotations).
</p>
<h2 id="passing-information-between-components">Passing Information Between Components</h2>
<p>
When different searchers or document processors depend on shared classes or field names,
it is good practice to define the name only in a single place.
An <a href="searcher-development.html#passing-information-between-searchers">
example</a> in the searcher development introduction illustrates an easy way to do that.
</p>
<h2 id="invoking-a-specific-search-chain">Invoking a Specific Search Chain</h2>
<p>
The search chain to use can be selected in the request, by adding the request parameter:
<pre>
searchChain=myChain
</pre>
If no chain is selected in the query, the chain called
<code>default</code> will be used. If no chain called
<code>default</code> has been configured, the chain called
<code>native</code> will be used. The <em>native</em> chain is
always present and contains a basic set of searchers needed in most applications.
Custom chains will usually inherit the native chain to include those searchers.
</p><p>
The search chain can also be set in a <a href="query-profiles.html">query profile</a>.
</p>
<h2 id="configuration-examples">Configuration Examples</h2>
<p>
Annotations which do not belong in the code may be added in the configuration,
here a simple example with
<a href="reference/services-search.html#chain">search chains</a>:
<pre>
&lt;container version="1.0"&gt;
&lt;search&gt;
&lt;chain id="default" inherits="vespa"&gt;
&lt;searcher id="simpleSearcher"/&gt;
&lt;/chain&gt;
&lt;searcher id="simpleSearcher" class="com.yahoo.search.example.SimpleSearcher"&gt;
<strong>&lt;before&gt;Cache&lt;/before&gt;
&lt;after&gt;Statistics&lt;/after&gt;
&lt;after&gt;Logging&lt;/after&gt;
&lt;provides&gt;SimpleTest&lt;/provides&gt;</strong>
&lt;/searcher&gt;
&lt;/search&gt;
&lt;nodes&gt;
&lt;node hostalias="node1" /&gt;
&lt;/nodes&gt;
&lt;/container&gt;
</pre>
And for <a href="reference/services-docproc.html">document processor chains</a>, it becomes:
<pre>
&lt;container version="1.0"&gt;
&lt;document-processing&gt;
&lt;chain id="default"&gt;
&lt;documentprocessor id="ReplaceInFieldDocumentProcessor"&gt;
<strong>&lt;after&gt;TextMetrics&lt;/after&gt;</strong>
&lt;/chain&gt;
&lt;/document-processing&gt;
&lt;nodes&gt;
&lt;node hostalias="node1"/&gt;
&lt;/nodes&gt;
&lt;/container&gt;
</pre>
For searcher plugins the class
<a href="http://javadoc.io/page/com.yahoo.vespa/container-search/latest/com/yahoo/search/searchchain/PhaseNames.html">
<code>com.yahoo.search.searchchain.PhaseNames</code></a>
defines a set of checkpoints third party searchers may use to help
order themselves when extending the Vespa search chains.
</p><p>
Note that ordering constraints are just that; in particular
they are not used to determine if a given search chain, or set of
search chains, is &ldquo;complete&rdquo;.
</p>