You are encouraged to use REST APIs instead of these processors whenever possible, either directly
from XForms (typically using XForms'
<xforms:submission>
, which supports REST since XForms 1.1) or with the XForms Submission processor, which exposes
<xforms:submission>
to XML pipelines. The eXist XML database, for example, exposes a
REST API.
XML Databases
- 1. Introduction
- 2. eXist
- 2.1. API
- 2.1.1. The REST API from XPL
- 2.1.2. The XML:DB API
- 2.2. How-To
- 2.1. API
- 3. Tamino XML Server 4.1
- 3.1. Configuration
- 3.1.1. config Input
- 3.1.2. System-Wide Configuration
- 3.2. Queries
- 3.2.1. data Input
- 3.2.2. data Output
- 3.2.3. X-Query Example
- 3.2.4. XQuery Example
- 3.3. Insertions
- 3.3.1. data Input
- 3.3.2. Example
- 3.4. Deletions
- 3.4.1. data Input
- 3.4.2. Example
- 3.5. Updates
- 3.5.1. data Input
- 3.5.2. Example
- 3.6. Transactions
- 3.1. Configuration
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.
Orbeon Forms provides processors to integrate with Tamino XML Server databases as well as databases that support the XML:DB API, such as eXist.
2. eXist
2.1. API
The eXist database can be accessed through the XML:DB API or through a REST Web API:
- The REST API is a web API to access the database through HTTP with the methods GET, POST, PUT, and DELETE. You can call the eXist REST API directly from XForms. You can also call the eXist REST API from XPL using the XForms Submission processor.
- The XML:DB API is a Java API, which you can call from XPL using the XML:DB processors provided by Orbeon Forms.
2.1.1. The REST API from XPL
The example below uses XForms Submission processor to call to the eXist REST API from XPL:
2.1.2. The XML:DB API
XML:DB is a Java API for XML databases, just like JDBC is a Java API for relational databases. The XML:DB processor interface with the XML:DB API and so may be used with any XML databases that implements XML:DB, including eXist.
There are 4 different XML:DB processors, for querying, updating, deleting, and inserting data in
the database. All 4 processors take 2 inputs: datasource
and query
.
The datasource
input points to a description of the database. For instance, to
connect to an embedded eXist, use:
To connect to eXist deployed as a servlet, use:
The 4 examples below show how to use the XML:DB query, update, delete, and insert processors.
2.2. How-To
2.2.1. Create a Named File with the XML:DB Processor
When using the insert processor, you cannot specify the name of the "file" that gets created in
eXist. The XML:DB API does not provide a facility to specify the name of the resource that gets
created in the database. So when using XML:DB, you need to call the
oxf:xmldb-query
processor and the xmldb:store()
extension function in
your query. If the collection where you want to add the document does not exist yet, you will
also need to use the xmldb-create-collection()
function.
Calling the oxf:xmldb-query
processor as in the code below will create a
collection myCollection
and a file in that collection called
myFile.xml
. The file will just have a root element <root/>
.
2.2.2. Create a Named File with the REST API
With the REST API, to create a "file" /db/myCollection/myFile.xml
, you PUT the
XML data for you file to the URL /db/myCollection/myFile.xml
. You can do this
with an XForms submission, directly from XForms, or by calling the XForms submission processor, as in the example below:
2.2.3. Execute Queries from The Command Line
It is sometimes convenient to run queries from the command line. The method below uses the eXist REST API, the same that is used if you access eXist directly from XForms.
- You first need to install curl. If you are running UNIX, curl might already be installed, and if it isn't, look for the curl package for your UNIX distribution. On Windows, you can download an executable with no dependencies of any library (no need for cygwin).
-
Create an XML file that contains your query, for instance:
<exist:query max="0" xmlns:exist="http://exist.sourceforge.net/NS/exist"><exist:text>declare namespace SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"; count(/*)</exist:text></exist:query>
-
Assuming the context for your application is
/ops
, the file that contains your query isquery.xml
, the web server is running on port 8080, and you want to run the query on the collectionyourCollection
, execute the command line:curl http://localhost:8080/ops/exist/rest/db/yourCollection -H "Content-Type: application/xml" --data-binary @query.xml
For more on curl, see the curl man page.
3. Tamino XML Server 4.1
Software AG's Tamino provides a complete XML storage solution. Orbeon Forms allows you to easily store, query, update, and delete documents in Tamino. The following sections describe the four Orbeon Forms processors for Tamino.
3.1. Configuration
All Tamino processors have a common config
input, describing the
database connection, collection and how it is handled.
The configuration of the Tamino processors can be done in two ways: either system-wide via the Properties, or locally for a specific instance of the processor
through the config
input. The local configuration takes precedence if available.
The collection
configuration elements cannot be specified
system-wide.
3.1.1. config Input
The config
input document specifies the URL of the Tamino
server, the credentials to use when connecting, the collection to
access, isolation degree and locking modes. 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 |
isolation-degree
|
Type of isolation degree used (optional). One of
uncommittedDocument
|
lock-mode
|
Type of locking mode used (optional). One of
protected
|
lock-wait
|
'yes' if the query should wait for locked records to become free. (optional) |
This RelaxNG schema describes the expected document.
3.1.2. System-Wide Configuration
The Tamino processors can be configured in the 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:
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.
|
oxf.tamino.lock-wait |
string |
Lock Wait Mode. If 'yes' then the query will wait for locked records to become free before returning the results. |
These properties as set as follows:
3.2. Queries
The oxf:tamino-query
processor processes queries either using
Tamino's X-Query or W3C XQuery.
3.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.
3.2.2. data Output
The processor sends the result of the query in the data
output.
The root element is always result
.
3.2.3. X-Query Example
3.2.4. XQuery Example
3.3. Insertions
The oxf:tamino-insert
processor allows you to insert a document in
Tamino.
3.3.1. data Input
The
data
input contains the document to insert.
3.3.2. Example
3.4. Deletions
The oxf:tamino-delete
processor allows you to remove documents
from Tamino.
3.4.1. data Input
The data
input contains the X-Query to select the document(s)
to be removed.
3.4.2. Example
3.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.
3.5.1. data Input
The data
input contains the XQuery expression to update one or
multiple nodes.
3.5.2. Example
3.6. Transactions
Orbeon Forms 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.