services.xml - processing

This document explains the syntax and semantics of the processing subelement of the container part of services.xml. processing is for configuring a pure request-response processing application, with no particular dependency to search or query handling. The processing block is used to configure processors:

processing
  binding
  processor [id, class, bundle, provides, before, after]
    provides
    before
    after
  renderer [id, class, bundle]
  chain [id, inherits, excludes]
    processor [idref, id, class, bundle, provides, before, after]
      provides
      before
      after
    inherits
      chain
      exclude
    phase [id, before, after]
      before
      after
Example:
<processing>
  <processor id="processor1" class="com.yahoo.test.Processor1" />
  <chain id="default">
    <processor idref="processor1"/>
    <processor id="processor2" class="com.yahoo.test.Processor2"/>
  </chain>
  <renderer id="renderer1" class="com.yahoo.test.Renderer1" />
</processing>

binding

The URI to map the ProcessingHandler to. The default binding is http://*/processing/*. Multiple elements are allowed. Example:

<binding>http://*/processing/*</binding>

processor

The definition of a single processor, for referencing when defining chains. If a single processor is to be used in several different chains, it is in general cleaner to define it directly under processing and then refer to it with idref, than defining it inline separately for each chain. 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)
before optional string Space separated list of phases and/or processors which should succeed this processor
after optional string Space separated list of phases and/or processors which should precede this processor
Example:
<processor id="processor2" class="com.yahoo.test.Processor2"/>

renderer

The definition of a renderer, for use by a Handler. 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:
<renderer id="renderer1" class="com.yahoo.test.Renderer1" />

processor (in chain)

Reference to or inline definition of a processor in a chain. If inlining, same as processor - if referring to, use idref attribute:

NameRequiredValueDefaultDescription
idref string Reference to the definition of this processor.
Example:
<chain id="default">
  <processor idref="processor2" />
</chain>

provides

A name provided by a processor for phases and other processors to use as dependencies. Example:

<provides>IntentAnalysis</provides>

chain

An element for defining a chain of processors / searchers / document processors (i.e. components). A chain is a set ordered by dependencies. Dependencies are expressed through phases, which may depend upon other phases, or components. For an incoming request from the network, the chain named default will be invoked. Refer to Chained components for a guide. Requires one of id or idref - attributes:

NameRequiredValueDefaultDescription
idref string A reference to a defined chain. Mutually exclusive with id. If idref is used, no other attributes apply.
id required string The chain ID. Required unless idref is used
inherits optional string A space separated list of chains this chain should include the contents of - see inherits
excludes optional string A space separated list of processors (contained in an inherited chain) this chain should not include. The exclusion is done before any consolidation of component references when inheriting chains. See exclude
class optional string
name
documentprocessors

inherits

Inherit from one or more parent chain(s). Equivalent to inherits attribute. Example:

<chain id="demo">
  <inherits>
    <chain>idOfSomeInheritedChain</chain>
  </inherits>
  <processor id="processor2" class="com.yahoo.test.Processor2"/>
</chain>
When a search chain inherits from another search chain, it subsumes the phases and the searcher references (both implicitly and explicitly defined) from the parent chain.

If two or more inherited component references have the same name, a new component specification matching those will be used instead. If that is not possible, an error will be signaled (i.e. if the version specifications can not be consolidated or if they require component definitions from different chains).

The component references determines which instances are used in the resulting chain instance.

A component reference is a component specification that says: there shall be exactly one component in this chain with the given name, and this component must must match the version specification.

A component reference overrides any inherited component references with the same name (i.e. the inherited ones are ignored).

If several components matches a given component reference, the newest (as determined by the version) is used.

exclude

Exclude components from inherited chains. Example:

<chain id="demo">
  <inherits>
    <chain>idOfSomeInheritedChain</chain>
    <exclude>idOfUnwantedProcessor</exclude>
    <exclude>idOfYetAnotherUnwantedProcessor</exclude>
  </inherits>
  <processor id="processor2" class="com.yahoo.test.Processor2"/>
</chain>

phase

Defines a phase, which is a named checkpoint to help order components inside a chain. Components and other phases may depend on a phase to be able to make assumptions about the order of components. Refer to the Chained components guide. Attributes:

NameRequiredValueDefaultDescription
id required string The ID, or name, which other phases and processors may depend upon as a successor or predecessor.
before optional string Space separated list of phases and/or processors which should succeed this phase
after optional string Space separated list of phases and/or processors which should precede this phase
Optional sub-elements:
  • before: same as the attribute
  • after: same as the attribute
These are hence equivalent:
<phase id="name">
  <before>phaseName1</before>
  <after>phaseName2</after>
</phase>
  
<phase id="name" before="phaseName1" after="phaseName2" />
Example:
<chain id="demo">
  <phase id="CheckpointName">
    <before>IntentAnalysis</before>
    <after>OtherAnalysis</after>
  </phase>
  <processor id="processor2" class="com.yahoo.test.Processor2"/>
</chain>

before

The name of a phase or component which should succeed this phase or component. Several before elements can be used to define several components or phases which always should succeed this component or phase in a chain. In other words, the phase or component defined is placed before name in the element.

after

The name of a phase or component which should precede this phase or component. Several after elements can be used to define several component or phases which always should precede this component or phase in a chain. In other words, the phase or component defined is placed after the name in the element.