Design Model

Home > Books > Tutorials and Training Guides > STM Language > Design Model

The STM language was designed to have a very simple structure and to provide a consistent and straightforward execution model.

Processing Sequence

An STM processor performs stm processing operations in sequence to a subject document. The STM operations are received by the STM processor as an STM document consisting of a <stm:group> root element. The stm:group document is a simple flat structure with the stm operations as first level children.

STM is a purely sequential model and does not support branching of any kind. Each STM operation is executed in turn. The operand document is modified incrementally by each instruction. Each subsequent instruction receives the processed operand document from the previous instruction. After the sequence of stm operations has completed the processed document is returned.

This can be illustrated as

		op1(d1)->d2, op2(d2)->d3, ... opN(dN)->dFinal

All instructions obey this pattern. It is important to note that certain operations radically transform the resulting document. For example, stm:regex produces a result that has a root <regex-matches> with child elements containing document fragments matching a regular expression, whilst stm:get-fragment extracts a document fragment and effectively replaces the root element with the requested fragment.

Source Data

All instructions use their enclosed document fragment or text value as source data for their operation. For example

	<stm:append xpath="/a/b">
		<x>
			<y>zebra</y>
		</x>
	</st:append>

will append the fragment

		<x>
			<y>zebra</y>
		</x>

to the operand document at xpath location /a/b.

For operations that process text values an optional select attribute on the operation can be used to specify the xpath location within the enclosed fragment from which to source the text. Omitting select will attempt to obtain the text value enclosed by the operation element.

The STM processor may also receive an optional parameter document.. Any element <stm:param xpath="/foo/bar" /> contained within an stm processing instruction will be substituted by that document fragment of the parameter document referenced by the xpath. If the xpath attribute is omitted the entire parameter document will be substituted.

One-to-Many XPath Model

STM is built around XPath references. All instructions require an attribute xpath which is the xpath reference to the target in the operand document.

A system based upon xpath is very convenient since it allows one to rapidly reference the target of an operation. However Xpath often returns multiple targets, which is very convenient but which can cause severe confusion when locating source data for an operation. This could lead to a many-to-many model where an operation would apply multiple sources to multiple targets. This can rapidly result in causality effects where operations could become ambiguous or fail outright.

In order to maintain the value of multivalued xpath targets STM enforces a one-to-many processing model. Operations always require a single unambiguous source fragment or text entity, however the target xpath may be multivalued. This gives a very clear and concise model for applying an operation to targets of the operand document.

The detailed STM Operation section contains many examples of the one-to-many patter in action. Of course nothing in this discussion prevents one-to-one operations!

This formal description of the model is necessary, though not very exciting! By following the examples in the rest of the document we think the simple consistent STM processing model will be readily illustrated.