7. Builtin Extention Elements

7.1 Database interface

The de.pannenleiter.saxon.* package implements 4 extention elements:

<pl:transaction db="" readonly="" isolation="" autocommit="">

This element wraps a database transaction.

Attributes

• db (Expression) - the databasename, looked up in XMLDatabase.properties
• autocommit (String) - can be "yes" or "no", default "no"
• readonly (String) - can be "yes" or "no", default "no"
• isolation (String) - can be "TRANSACTION_READ_UNCOMMITTED", "TRANSACTION_READ_COMMITTED", "TRANSACTION_REPEATABLE_READ" or "TRANSACTION_SERIALIZABLE" default "TRANSACTION_READ_COMMITTED". If an isolation level is not supported, the engine uses a lesser one.

---

<pl:transaction db="$db">
 <xsl:apply-templates/>
</pl:transaction>

---

<pl:variable name="" document="" sql-table="" select="" fetch-childs="" fetch-attributes="" plid="" plversion="" plchilds="">

This is an extended xsl variable. It fetches a node set from the database. You can pass the node-set to a <xsl:apply-templates>.

• name (String) - the name of the variable
• document (Expression) - the document name.
  • If you use a chumk database, this is the table name.
  • If you use the ad-hoc database interface, the document name must match the element name.
  • If you use a legacy database this is the key of the mapping in XMLDatabase.properties.
• sql-table (Expression) - If select includes a sql statement, this is the real name of the selected table. Omit this attribute, if you use xpath expressions.
• select This is a sql statement or an xpath expression. If you put a query expression into the body of pl:variable, you have to omit this attribute.
• fetch-childs (Expression) - A list of element names. If you add this attribute, the query engine will only fetch the childs of the listed elements. Fetch-childs will be replaced by a lazy query algorithm.
• Fetch-attributes (Expression) - A list of attribute names. If you add this attribute, the query engine will only fetch the attributes of the listed elements. fetch-attributes will be replaced by a lazy query algorithm.
• plid (yes/no) - Add the plid attribute to the fetched elements. Default is yes. The plid is the primary key of the database record. You need this id to update the database, but to copy an element you have to strip it.
• plversion (yes/no) - Add the plversion attribute to the fetched elements. Default is no. Archived elements have a number greater then zero. The plversion of active elements is zero.
• plchilds (yes/no) - Add the plchilds attribute to the fetched elements. Default is no. This tells you, how the childs of this element are stored in the database. Leaf: the element has no childs, inner: the childs are stored in their own records, packed: the childs are packed in the content column.

The first example fetches a list of articles from a database and renders a table of them. The second fetches a list of sales orders from a legacy database and renders the items.

---

<pl:variable name="articles" document="$document" select="*[@plid = $category]/article"/>
<table>
 <xsl:apply-templates select="$articles" mode="show-articles"/>
</table>

<pl:variable name="orders" document="'basket-all'" sql-table="'orders'">
 select * from orders order by session
  where session = <xsl:value-of select="$session"/>
</pl:variable>
<xsl:apply-templates select="$order/sales-order/item" mode="show-basket"/>

---

<pl:write name="" document="" select="" owner="" position="">

This is also an xsl variable. It stores a document fragment in a database. An element with a plid updates the old element, elements without id are inserted. After performing the database operation, the variable contains the id of the outermost written element.

• name (String) - the name of the variable
• document (Expression) - the document name.
  • If you use a chumk database, this is the table name.
  • If you use the ad-hoc database interface, the document name must match the element name.
  • If you use a legacy database this is the key of the mapping in XMLDatabase.properties.
• select This is an ordinary xpath expression. It selects a document fragment and stores it in the database. If you put a fragment into the body of pl:write, you have to omit this attribute.
• owner (Expression) - if you store a new element, you have to give the plid of the owner. It is ignored, if you update an element.
• position (Expression) - if you store a new element, you can give a position number. If you omit it, the engine will append the new element to the existing childs. It is ignored, if you update an element.

The first example creates a new document fragment from a template, witch it fetches from the database. The second updates a fragment.

---

<pl:variable  name="template" document="$document" select="*[@plid = $species]/*" plid="no"/>
<pl:write name="new-id" select="$template" document="$document" owner="$category"/>

<pl:variable name="article" document="$document" select="*[@plid = $edit]"/>
<xsl:variable name="entry">
 <xsl:apply-templates select="$article" mode="copy-replace-config"/>
</xsl:variable>
<pl:write name="id" select="$entry" document="$document" owner="$edit"/>

---

By default the ad-hoc interface will insert a new record into the database. You can control the action of an ad-hoc database by wrapping your element with a <pl-hint> element. The surrogate="session" tells the interface to create a new surrogate key (You will find it in the content of the pl:write variable). The pair todo="update" primary="session" tells the interface to update the corresponding record.

---

<pl:write name="new-session" document="'orders'">
 <pl-hint surrogate="session">
  <orders/>
 </pl-hint>
</pl:write>

<pl:write name="confirmed" document="'orders'">
 <pl-hint todo="update" primary="session">
  <orders session="{$session}" name="{$request/parameter/address}" email="{$request/parameter/email}"/>
 </pl-hint>
</pl:write>

---

This one inserts a customer record into a legacy database.

---

<pl:write name="confirmed" document="'basket-cust'">
 <customer session="{$session}">
  <name><xsl:value-of select="$request/parameter/address"/></name>
  <email><xsl:value-of select="$request/parameter/email"/></email>
 </customer>
</pl:write>

---

<pl:remove name="" document="" id="">

Yet another xsl variable. It moves a document fragment to the archive. The variable contains the new version number.

• name (String) - the name of the variable
• document (Expression) - the document name.
  • If you use a chumk database, this is the table name.
  • If you use the ad-hoc database interface, the document name must match the element name.
  • If you use a legacy database this is the key of the mapping in XMLDatabase.properties.
• id (Expression) - the plid of the root element of the document fragment.

7.2 Trace Hooks

These elements and functions are the foundation of the debugger. They consist of two parts. Other components of rm -d ms collect trace informations. This ones allow regular rm -d ms applications to access the informations.

Please have a look into the plxml and xsl files of the workbench for further documentation.

<trace:set name="" value="">

Switches a tracepoint on (value="yes") of off (value="no")

public static String get(String name)

Is a tracepoint active? Returns "yes" or "no".

public static Value list(Context context)

Returns a nodeset, the list of collected traces.

public static Value show(Context context, String idStr)

Returns a nodeset, the trace of a request.

7.3 Regular expression matcher

The regular expression extention is a thin wrapper for the OROMatcher library. It does pearl like pattern matching on strings.

Today it is binary only, copyright by Original Reusable Objects Inc, but they prommised to contribute the sourcecode to the apache project. You will find furter informations at http://www.roinc.com.

The de.pannenleiter.saxon.Regex resp. de.pannenleiter.xmlapache.Regex contains 4 static methods:

public static boolean matches(String input, String pattern)

Returns true if pattern matches a substring of input.

public static String substring(String input, String pattern)

Returns the first substring of input whitch is matched by pattern - null if it doesn't match.

public static NodeSetValue allsubstrings(Context context, String input, String pattern)

Returns a nodeset of all substrings of input, matched by pattern.

public static NodeSetValue split(Context context, String input, String pattern)

Returns a nodeset of the substrings of input that are seperated by the matches of patterb

public static String substitute(String input, String pattern, String substitution)

Returns a copy of input with all matches replaces by substitution.
Uses () and $ - e.g. regex:substitute('123456123456123456', '4(.)6', 'x$1y').

7.4 Embedded Cocoon Processor

De.pannenleiter.cocoon.CocoonElement contains an ugly hack to call the cocoon reactor recursively from a stylesheet. You will find an example in samples/test/cocoon/embedded.xsl.

<cocoon:variable name="" url="">

This element is an xsl variable. If calls the engine and keeps the result - a nodeset.

• name (String) - the name of the variable
• url (Expression) - the url of file, processed by cocoon. Has to be a file url. Other kinds of urls are not implemented yet.

The body of this element may contain parameters, whitch are passed to the engine. Each one has a parameter tag. The name if the child tag will become the name of the parameter.

The following example comes from samples/test/cocoon/embedded.xsl. The embedded page will be processed by the dcp processor. It gets the original parameters of the http request plus two additional parameters.

---

<cocoon:variable name="dcp" url="'embedded-dcp.xml'">
 <parameter><hallo>This is a Test</hallo></parameter>
 <parameter><two>This one is also a test</two></parameter>
 <xsl:copy-of select="$request/parameter"/>
</cocoon:variable>
<xsl:apply-templates select="$dcp" mode="dcp"/>

---

7.5 Utilities

You will find some functions in the de.pannenleiter.saxon.Regex and de.pannenleiter.xmlapache.Regex classes.

public static Value nodeset(Context context, Value value)

Converts a result tree fragment to a nodset. Saxon has a builtin one, but a common one for saxon and xalan is more handy.

public static String prettyprintXML(Context context, Value value, boolean indent, boolean stripId)

This is a DOM serializer. It takes xml and returns a string representation. Indent is not implemented yet. If stripId is true, the database attributes (plid, plversion, plchilds) will be omitted.

public static Value parseXML(Context context, String value, boolean stripId)

Takes the string representation and returns a dom, or whatever the xslt processor uses internally. If stripId is true, the database attributes (plid, plversion, plchilds) will be omitted.

public static Value checkXML(Context context, String value)

This method parses the string and returns an error message - or an empty string if the string is ok.