Orbeon Search

Comments? Feedback?

This wiki does not yet support public comments (a limitation of Google Sites), so we encourage you to post your comments either:

On Twitter by responding to @orbeon.

On our community mailing list: subscribe sending an email to ops-users-subscribe@ow2.org (content of subject/body doesn't matter), you'll get a response with the email to use to send your message to the community mailing list.

Recent site activity

Processors - Pipeline

Contents

  1. 1 Introduction
  2. 2 Inputs and outputs
  3. 3 Example of use
  4. 4 Configuration
  5. 5 Optional inputs
  6. 6 Optional outputs

Introduction

The Pipeline processor provides support for sub-pipelines in XPL. It allows XPL programs to be used and manipulated like XML processors. It allows building the equivalent of functions and procedures in other programming languages.

Inputs and outputs

Type Name Purpose Mandatory
Input config Configuration following the XPL syntax Yes
Input User-defined inputs User-defined inputs accessible from the called XPL pipeline with p:param. No
Output User-defined outputs User-defined outputs accessible from the called XPL pipeline with p:param. No

Example of use

Like any XML processor, the Pipeline processor is used from within an XPL pipeline. It is important to make a distinction between the calling XPL pipeline, which is the pipeline making use of the Pipeline processor, and the called XPL pipeline, which is the sub-pipeline called by the calling pipeline. This is similar to other programming language where, for example, a function calls another function.

This is an example of using the Pipeline processor in a calling XPL pipeline to call a sub-pipeline: 

<p:processor name="oxf:pipeline">
    <!-- The config input provides the declaration of the sub-pipeline -->
    <p:input name="config" href="get-categories.xpl"/>
    <!-- The query input is an optional input that allows passing an XML document to the query input of the sub-pipeline -->
    <p:input name="query">
        <query>
            <username>jdoe</username>
            <blog-id>123456</blog-id>
        </query>
    </p:input>
    <!-- The categories output is an optional output that allows reading the categories output of the sub-pipeline -->
    <p:output name="categories" id="resulting-categories"/>
</p:processor>
NOTE: In this example the config input is contained in a separate resource file called get-categories.xpl. Because XPL configurations are usually fairly long, this is often the preferred way of referring to a pipeline. But as usual with XPL, it is also possible to inline the content of inputs (as the query input above shows), or to refer to a dynamically-generated XML document.

Configuration

The config input must follow the XPL syntax. For example the get-categories.xpl sub-pipeline in the example above can contain: 

<p:config xmlns:p="http://www.orbeon.com/oxf/pipeline" xmlns:oxf="http://www.orbeon.com/oxf/processors" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xdb="http://orbeon.org/oxf/xml/xmldb">

    <p:param type="input" name="query" schema-href="get-categories-query.rng"/>
    <p:param type="output" name="categories" schema-href="get-categories-result.rng"/>

    <p:processor name="oxf:xslt">
        <p:input name="data" href="#query"/>
        <p:input name="config">
            <xdb:query collection="/db/orbeon/blog-example/blogs" create-collection="true" xsl:version="2.0">
                xquery version "1.0";
                <categories>
                    {
                    for $i in (/blog[username = '<xsl:value-of select="/query/username"/>'
                               and blog-id = '<xsl:value-of select="/query/blog-id"/>'])[1]/categories/category
                    return
                        <category>
                            <name>{xs:string($i/name)}</name>
                            <id>{count($i/preceding-sibling::category) + 1}</id>
                        </category>
                    }
                </categories>
            </xdb:query>
        </p:input>
        <p:output name="data" id="xmldb-query"/>
    </p:processor>

    <p:processor name="oxf:xmldb-query">
        <p:input name="datasource" href="../datasource.xml"/>
        <p:input name="query" href="#xmldb-query"/>
        <p:output name="data" ref="categories"/>
    </p:processor>

</p:config>

Optional inputs

Optional inputs allow passing XML documents to sub-pipeline. The example sub-pipeline above requires a query input: 

<p:param type="input" name="query" schema-href="get-categories-query.rng"/>

The caller must therefore pass an XML document that will be received by the sub-pipeline. This is done by setting, on the Pipeline processor, an input with name query: 

<p:processor name="oxf:pipeline">
    <p:input name="query">
        ...
    </p:input>
</p:processor>
NOTE: Because the config input of the Pipeline processor is used to provide the XPL pipeline, a sub-pipeline should not expose a config input, as it won't be possible to connect that input.

Other inputs can similarly be passed to the sub-pipeline, simply by connecting inputs on the Pipeline processor that match the names of the inputs declared by the sub-processor.

Optional outputs

Optional outputs allow retrieving XML documents produced by a sub-pipeline. The example sub-pipeline above requires a categories output: 

<p:param type="output" name="categories" schema-href="get-categories-result.rng"/>

The caller, in order to read the categories output of the sub-pipeline, must set, on the Pipeline processor, an output with name categories: 

<p:processor name="oxf:pipeline">
    <p:output name="categories" id="resulting-categories"/>
</p:processor>

As usual with XPL, the id attribute provided on the output is chosen by the user. Here, we use a resulting-categories identifier.

Other outputs of the sub-pipeline can similarly be read, simply by connecting outputs on the Pipeline processor that match the names of the outputs declared by the sub-processor.