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
            excludes
        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 multiple chains, it is cleaner to define it directly under processing and then refer to it with idref, than defining it inline separately for each chain.

Example:

<processor id="processor2" class="com.yahoo.test.Processor2"/>

renderer

The definition of a renderer, for use by a Handler.

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:

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.

Searcher, Document processing and Processing chains can be modified at runtime without restarts. Modification includes adding/removing processors in chains and changing names of chains and processors. Make the change and deploy. Some changes require a container restart, refer to reconfiguring document processing.

inherits

Inherit from one or more parent chain(s). Example:

<chain id="demo" inherits="idOfSomeInheritedChain idOfYetAnotherChain">
    <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 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.

excludes

Exclude components from inherited chains. Example:

<chain id="demo" inherits="idOfSomeInheritedChain" excludes="idOfUnwantedProcessor idOfYetAnotherUnwantedProcessor">
    <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.

Optional sub-elements:

• before: same as the attribute
• after: same as the attribute

These are 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. Multiple before elements can be used to define multiple 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. Multiple after elements can be used to define multiple 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.