6. The Components of rm -d ms

6.1 The Configuration Files

There are two configuration files:

config
It describes the java runtime environment.

XMLDatabase
It describes your databases. If you use the test database of a mysql installation without password, you can keep the database configuration. This file also includes the absolute pathnames of the database mapping files of the legacy database interface. Since this interface will change in the near future - please ignore them.

I hope the comments above the entries describe how to bring the entries in line with your installation.

6.2 A Persistent Document

A rm -d ms application operates on one comprehensive large XML document. This document may be stored in a shred database, or it may be an XML view on an ordinary relational database. (It would be nice to plug an XML view of a relational database into a shred database, but implementing this feature hasn't been started yet).

Shred Database

The shred database can handle a small number of large documents. It uses 3 database tables for one document. By default every element and every attribute is stored in its own record, but you can configure a more efficient mapping. The create table statement can be found in de/panneleiter/db/vendor/Mysql.java

The engine modifies your xml elements: To preserve the identity of an element, the document engine adds an attribute plid to every element.

Ad Hoc Database

This interface offers a very limited service. But since you don't need to configure an XML-RMDMS mapping, it is easy to use. The idea is: you can start with an ad hoc database and when your project involves, you can switch to a full featured interface.

• This interface doesn't support nested elements.
• The element name is mapped to the table name.
• The attribute names of the alement are mapped to the column names of the table.
• The document name of a <pl:variable> or <pl:write> element must match the element name.

Legacy Database

The current release uses the xmldbms package written by Ronald Bourret. There are some features missing and the project seems to be dead. So I am going to replace it with a more comprehensive package. Can you recommend a package? Please let me know!

Xmldbms comes with a compact but complete documentation. See the readme.html of the xmldbms package.

6.3 Query Expressions

You can use two kinds of expressions: sql statements and xpath expressions. All interfaces - XSL, raw XML and the export utility - use these kinds of query expressions.

Xpath expressions on legacy databases have not been implemented yet.

The document engine translates from a subset of XPath into SQL. Some working examples

• entry/info
• entry/info[@name = "upps" and @info = "test"]
• *[@plid = 15647] - this selects an element by the primary key of the database record
• *[@plid = 15647 and @plversion != 0] - this selects the archived versions of an element

• entry[not(@name = "upps")] - 'not' is not implemented
• entry[text() = "upps"] - functions are not implemented
• entry|info - union is not implemented
• entry//info - from-descendants is not implemented
• ....

• *[@name="upps"] - may not work

• *[@id = $request/parameter/id]
• *[@name = document($doc)/name]

6.4 The Raw XML Interface

The servlet, de.pannenleiter.saxon.Engine, de.pannenleiter.xmlapache.Engine and de.pannenleiter.cocoon.XalanProcessor, handle two kinds of requests - raw XML and XSLT transformations.

Every http-request must include a pathinfo. It points to an xml file with an xml-stylesheet processing instruction.

A pi with a type attrybute application/rmdms-raw selects the raw interface: The servlet expects a http parameter 'todo' and some additional parameters. The servlet performs a database transaction and returns an xml text of the result - or the xml text of an exception. At the moment there are simple read and write transactions, you can fetch a document fragment, store a fragment or move a fragment to the archive.

There are plans to drop this interface for a full featured rpc-over-http library. So there is no documentation yet. See de/pannenleiter/client/NetInterface.java for details.

6.5 The HTML/XML Interface

If a http-request includes pathinfo, the servlet assumes that this pathinfo points to an xml file with an xml-stylesheet processing instruction. The engine processes the stylesheet and returns the result to the client. The stylesheet may start any number of database transactions.

The xmlapache servlet puts the ServletRequest object into global xsl variable $sevlet-request and the ServletResponse object into global xsl variable $sevlet-response It also servlet passes the parameters as a node set in the global xsl variable $request. Ask the engine for documentation:

 <xmp><xsl:copy-of select="$request"/></xmp>

6.6 Performance Considerations

By default, the chunk database stores every element and every attribute in its own record. There are two optimizations:

Store attributes in the element table

The element table has 2 attribute slots (the number may change). A processing instruction defines the mapping. e.g <?pl-slot element="entry" attr="name" slot="1"?>.

The only way to change the mapping is: export the document, edit the text and import it with the -recreate flag. You will loose the archive of changed elements :-(.

There is another ugly problem. The XPath to SQL translator has to know the name of the element. It cannot convert something like *[@attr=4].

Store a document fragment in a single record

The pl-pack processing instruction enumerates the packed elements. e.g <?pl-pack element="template" element="info"?>

The current implementation doesn't support selecting childs of a packed element. So you have to chain two steps. Fetch the whole element and select a child from the node set.

 <pl:variable name="template" document="forum" pattern="template[@name=$template"/>
 <xsl:apply-templates select="$template/info"/>

You can find an example in samples/forum/init.xml.

Using BindParameter

There are two reasons not to patch your values into sql statements: Some databases won't reuse their query execution plans - all applications, which use the database, will get really poor performance! The other reason: rm -d ms can't reuse the compiled xpath expressions.

If you put xsl variables into your xpath expressions, the sql compiler will use binding variables. For excample species[@plid = $id]/*:

select e2.*
  from shop e1, shop e2
 where e1.element = 'species'
   and (e1.id = ?)
   and e2.up = e1.id
   and e1.version = 0
   and e2.version = 0
 order by e2.pos

But the sql compiler still is very poor. To work around the limitations, the expressions are in fact attribute value templates. So you can say: species[@plid = {$a-node-set/*/@id}]/*, but you get:

select e2.*
  from shop e1, shop e2
 where e1.element = 'species'
   and (e1.id = 245)
   and e2.up = e1.id
   and e1.version = 0
   and e2.version = 0
 order by e2.pos

At the moment, rm -d ms offers no way to bind parameters of plain sql statements.