OPS User Guide

XML Databases

1. Introduction

XML databases allow you to easily store, index and query XML documents. They are especially useful when dealing with document-centric applications, where the structure cannot be mapped naturally to a relational database.

OPS integrates with Tamino XML Server databases, as well as XML:DB databases such as eXist.

2. Tamino XML Server 4.1

Software AG's Tamino provides a complete XML storage solution. OPS allows you to easily store, query, update, and delete documents in Tamino. The following sections describe the four OPS processors for Tamino.

2.1. Configuration

All Tamino processors have a common config input, describing the database connection and collection.

The configuration of the Tamino processors can be done in two ways: either system-wide via the OPS Properties, or locally for a specific instance of the processor through the config input. The local configuration takes precedence if available.

Note

The collection configuration elements cannot be specified system-wide.

2.1.1. config Input

The config input document specifies the URL of the Tamino server, the credentials to use when connecting and the collection to access. The following table describes the configuration elements.

Name Description
url Tamino database URL.
username Username to authenticate with the server
password Password to authenticate with the server
collection XML Collection to use

This RelaxNG schema describes the expected document.

  <element name="config" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">  <interleave>  <optional>  <element name="url">  <data type="anyURI"/>  </element>  </optional>  <optional>  <element name="username">  <data type="string"/>  </element>  </optional>  <optional>  <element name="password">  <data type="string"/>  </element>  </optional>  <element name="collection">  <data type="string"/>  </element>  </interleave>  </element>

2.1.2. System-Wide Configuration

The Tamino processors can be configured in the OPS properties file, allowing all instances to share the same configuration. The following processor properties are allowed:

Name Type Description
url anyURI Tamino Server URL.
username string Username to authenticate with the server.
password string Password to authenticate with the server.

These properties are set as follows:

  <property as="xs:anyURI" processor-name="oxf:tamino-query" name="url" value="http://localhost/tamino/welcome_4_1_4"/>  <property as="xs:string" processor-name="oxf:tamino-query" name="username" value="..."/>  <property as="xs:string" processor-name="oxf:tamino-query" name="password" value="..."/>

The following global properties are allowed:

Name Type Description
oxf.tamino.isolation-degree string Isolation degree. Possible values are: uncommittedDocument, committedCommand, stableCursor, stableDocument, serializable. See the Tamino documentation for more details on the isolation degree.
oxf.tamino.lock-mode string Lock mode. Possible values are unprotected, shared, protected. See the Tamino documentation for more details on the lock mode.

These properties as set as follows:

  <property as="xs:string" name="oxf.tamino.isolation-degree" value="..."/>  <property as="xs:string" name="oxf.tamino.lock-mode" value="..."/>

2.2. Queries

The oxf:tamino-query processor processes queries either using Tamino's X-Query or W3C XQuery.

2.2.1. data Input

The data input contains only the root element and the query. The root element is either query for an X-Query query, or xquery for an XQuery query.

2.2.2. data Output

The processor sends the result of the query in the data output. The root element is always result.

2.2.3. X-Query Example

  <p:processor name="oxf:tamino-query" xmlns:p="http://www.orbeon.com/oxf/pipeline">  <p:input name="config">  <config>  <url>http://localhost/tamino/welcome_4_1_4</url>  <username>tamino</username>  <password>password</password>  <collection>encyclopedia</collection>  </config>  </p:input>  <p:input name="data">  <query>/jazzMusician[@ID="ParkerCharlie"]  </query>  </p:input>  <p:output name="data" id="result"/>  </p:processor>

2.2.4. XQuery Example

  <p:processor name="oxf:tamino-query" xmlns:p="http://www.orbeon.com/oxf/pipeline">  <p:input name="config">  <config>  <url>http://localhost/tamino/welcome_4_1_4</url>  <username>tamino</username>  <password>password</password>  <collection>encyclopedia</collection>  </config>  </p:input>  <p:input name="data">  <xquery>for $m in input()/jazzMusician, $c in input()/collaboration, $a in input()/album where $m/@ID= $c/jazzMusician and $c/result = $a/productNo return  <musician>{$m/name}<album>{$a/title}</album>  </musician>  </xquery>  </p:input>  <p:output name="data" id="result"/>  </p:processor>

2.3. Insertions

The oxf:tamino-insert processor allows you to insert a document in Tamino.

Note
You need to make sure that the document conforms to one of the registered schemas in the current collection. If Tamino can't validate the document, an exception is thrown.

2.3.1. data Input

The data input contains the document to insert.

2.3.2. Example

  <p:processor name="oxf:tamino-insert" xmlns:p="http://www.orbeon.com/oxf/pipeline">  <p:input name="config">  <config>  <url>http://localhost/tamino/welcome_4_1_4</url>  <username>tamino</username>  <password>password</password>  <collection>encyclopedia</collection>  </config>  </p:input>  <p:input name="data">  <jazzMusician ID="DavisMiles" type="instrumentalist">  <name>  <first>Miles</first>  <last>Davis</last>  </name>  <birthDate>1926-05-26</birthDate>  <instrument>trumpet</instrument>  </jazzMusician>  </p:input>  </p:processor>

2.4. Deletions

The oxf:tamino-delete processor allows you to remove documents from Tamino.

2.4.1. data Input

The data input contains the X-Query to select the document(s) to be removed.

2.4.2. Example

  <p:processor name="oxf:tamino-delete" xmlns:p="http://www.orbeon.com/oxf/pipeline">  <p:input name="config">  <config>  <url>http://localhost/tamino/welcome_4_1_4</url>  <username>tamino</username>  <password>password</password>  <collection>encyclopedia</collection>  </config>  </p:input>  <p:input name="data">  <query>/jazzMusician[@ID="DavisMiles"]  </query>  </p:input>  </p:processor>

2.5. Updates

The oxf:tamino-update processor allows you to update parts of documents directly inside Tamino. An extension of XQuery is used for that purpose. Refer to the Tamino documentation for more information.

2.5.1. data Input

The data input contains the XQuery expression to update one or multiple nodes.

2.5.2. Example

  <p:processor name="oxf:tamino-update" xmlns:p="http://www.orbeon.com/oxf/pipeline">  <p:input name="config">  <config>  <url>http://localhost/tamino/welcome_4_1_4</url>  <username>tamino</username>  <password>password</password>  <collection>encyclopedia</collection>  </config>  </p:input>  <p:input name="data">  <query>update replace input()/jazzMusician[@ID="ParkerCharlie"]/instrument with<instrument>piano</instrument>  </query>  </p:input>  </p:processor>

2.6. Transactions

OPS initiates a transaction for every HTTP request, and commits the transaction when the pipeline is executed normally. If an exception occurs in the pipeline, the transaction in rolled back.

3. XML:DB Databases (eXist)

Note
This documentation has not yet been written.