Pipeline Processor
1. 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.
2. 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 |
3. 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"><p:input name="config" href="get-categories.xpl"/><p:input name="query"><query><username>jdoe</username><blog-id>123456</blog-id></query></p:input><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.
4. 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:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:oxf="http://www.orbeon.com/oxf/processors" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xu="http://www.xmldb.org/xupdate" 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>
5. 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.
6. 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.