XITE® User’s Manual[1]
© Sphere Software Corporation,
2002
Contents............................................................................................................................... 1
Introduction........................................................................................................................... 2
XITE® Tuple Space............................................................................................................. 2
Rules..................................................................................................................................... 4
Basic Pattern Matching.......................................................................................................... 4
Actions................................................................................................................................. 5
XITE Functions..................................................................................................................... 5
addnode............................................................................................................................ 6
addattr.............................................................................................................................. 6
xbatch............................................................................................................................... 6
xnamespace...................................................................................................................... 6
xpath................................................................................................................................. 6
xprop................................................................................................................................ 7
XITE® Java API.................................................................................................................. 7
JESS..................................................................................................................................... 7
Features of the Commercial XITEâ Toolkit........................................................................... 7
Appendix A: JESS User Manual............................................................................................ 8
XITE(tm) transforms XML input (javax.xml.transform.Source) into XML output (javax.xml.transform.Result). By transform, we mean that XML tags, attributes, and text content can be changed, added, or deleted. While XSLT is useful for simple XML transformations[2], complex transformations can be expressed more easily with XITE® using simple, high-level, transform rules. These rules express conditions and actions over a "tuple space" of XML content.
XITELite® is an evaluation version of the XITE® toolkit. XITELite® is a fully-functional, non-expiring version of XITE® with feature and performance limitations. The full XITE® toolkit is an industrial-strength, TrAX-compliant API. The full XITE® product’s features include:
* SAXSource input, SAXResult output
* DOMSource input, DOMResult output
* Multiple input sources, multiple output results
* Synchronous and asychronous transform modes
* High-performance transforms using SAX pipelines
More information is available about XITE® at http://www.sphere.com/ where you can download more examples of using XITE® in servlets, filters, and in Java Server Pages (JSPs).
XITE(tm) and XITELite(tm) use XPath expressions to characterize selections of XML nodes, nodesets, and attributes. Selected elements of XML content are deserialized into a “tuple space” upon which transform rules can operate. The user can specify any number of (xpath path) declarations anywhere within a rule specification.
For example, the declaration:
(xpath “*”)
would deserialize ALL the XML elements of the input into the tuple space. XITE® current supports matching only tag elements in (xpath path) declarations. Attempts to use XPath expressions that match onlt text or attribute elements within XML content will result in errors.
For each XML element in the input matching a given XPath expression specified with an (xpath path) declaration, the matching XML content is deserialized into a tuplespace according the following method:
1. A tag element <X> is deserialized as the tuple:
(node prefix
X nodeid)
where prefix is the current tag stack and nodeid is the unique, internal node identifier for the occurance of X within the XML content. The tag X and nodeid are then pushed on the current tag stack and then the attributes and content of <X> is processed. When the content of tag X is finished processing, the tag X and nodeid are popped off the tag stack.
2. An attribute element A=string is deseralized as the tuple:
(attr prefix
A nodeid string)
where prefix is the current tag stack, nodeid is the unique, internal node identifier for the occurance of the attribute A within the XML content, and string is the attribute string value with quotations.
3. A text element (i.e., the text within <X>text</X>) is deserialized as the tuple:
(node prefix
#text nodeid “text”)
where prefix is the current tag stack, nodeid is the unique, internal node identifier for the occurance of the attribute A within the XML content, and text is the text content string value with quotations. The constant #text signifies that this is a text node and can be used in the rule condition patterns.
To illustrate the deserialization method by way of example, suppose we are given the XML content as input:
<?xml
version="1.0" encoding="UTF-8"?>
<message
status="Request"><request>hello</request></message>
This input would be deserialized into the XITE® tuple space as:
(node message N1)
(attr message N1 status N2 “Request”)
(node message N1 request N4)
(node message N1 request N4 #text N5
“hello”)
This represents the complete deserialization of the XML content into the tuple space. Note that end tags are not mapped into the tuple space as they would be redundant. It should be noted that ALL whitespace is also deserialized into the tuple space. The full version of the XITE® toolkit has options for control whitespace deserialization/serialization.
XITE® includes a version of the Java Expert System Shell (JESS) expert system rules engine from Sandia National Laboratories. XITELite® contains a crippled version of JESS for evaluation purposes.
XITE® uses JESS declarative rules to specify transforms on XML content in the tuple space. Each rule consists of a set of conditions and a set of actions. The conditions appear on the left-hand side of a rule (LHS) while the actions appear on the right-hand side (RHS) of a rule. The conditions and actions in a rule are separated by a “=>” symbol.
A rule may have zero or more conditions on its left-hand side that specify patterns on tuples in the tuple space. Each pattern may match one or more tuples. A rule will fire, i.e., execute the actions on its right-hand side when ALL conditions match on the LHS of the rule. Each condition may bind zero or more variables during the pattern matching process. Variables begin with a “?” character within a condition. For example, the condition
(node message N1 request N4 #text N5 ?msg)
will match the tuple:
(node message
N1 request N4 #text N5 “hello”)
and bind the variable ?msg to the value “hello” on the ENTIRE LHS of a rule. Other conditions may also specify the variable ?msg which must satisfy all conditions within which it is used.
A rule will fire for ALL combinations on tuples matching its conditions. This means that a rule may fire more than once if the condition pattern is ambiguous enough to warrant matching the same tuples in a different combination.
Variable binding gives XITE® tremendous power and flexibility to transform XML content. Pattern matching can transform all or parts of XML content tuples using XITE®. Consider the conditions on the rule:
(defrule helloworld
(node message ?m request ?r #text ? "hello")
(attr message ?m status ? "Request")
=>
(addnode message ?m response N0)
(addnode message ?m response N0 #text N0 "world")
(addattr message ?m status N0 "Request With Reply")
)
The two conditions on the LHS of the rule (labeled “helloworld” in this case) will match two specific XML content tuples in the tuple space given in the last section. The variable ?m will bind to the value “N1” while the ?r variable will bind to the value “N4” as specified in the last section for the tuples:
(node message
N1 request N4 #text N5 “hello”)
(attr message
N1 status N2 “Request”)
respectively. The single “?” character in the second condition shows a use of an anonymous variable. The “?” variable matches with the value “N2” but has no name. This means it matches but does not bind with any named variable thus implementing a “don’t care” match.
Variable bindings can also be wildcarded or have test conditions attached to them. The condition:
(node $?prefix request ?r #text ? "hello")
contains a variable that begins with a “$” character. This means that the variable can match and bind with zero or more terms within any qualified tuple. This condition will match both of the following XML content tuples:
(node message
N1 request N4 #text N5 “hello”)
(node request
N4 #text N5 “hello”)
where $?prefix = “message N1” in the first tuple and $?prefix = “” in the case of the second tuple.
A rule will fire and execute the actions on its RHS if and only if ALL conditions on the LHS match and all variables bind to unique values. Actions are different than patterns. Actions are JESS functions that resemble program instructions. All JESS functions are available to the XITE® programming including two new functions described below: addnode and addattr. The full version of XITE® includes functions for deleting and changing tag and attribiute content.
Since XITEâ uses JESS, all JESS functions are available to be used in actions on the RHS of rules. XITEâ adds some additional functions to make it easier to express rule-based XML transformations.
Usage: (addnode multi-expression)
The addnode function is used to add XML node to the output during a rule-based transformation with XITE®. The tuple path is the new attribute’s tuple content (see the rule above for an example). To add a text node, one MUST add the parent node as well (see the above example).
Usage: (addattr multi-expression)
The addattr function will add an attribute declaration to an existing XML tuple for an XML tag node. The tuple path is the new node’s tuple content (see the rule above for an example). The tag node must eventually exist for the attribute to be visible on output. One interesting side effect of the addattr function is that you can change the value of an existing attribute by adding a new attribute with the same name. The new attribute value will override the existing value because attribute names must be unique within XML tags.
Usage: (xbatch filename)
The xbatch function takes a file name as its argument to include other rules files. This differs from the JESS batch function in that the xbatch function finds the included rule file from the same relative directory from which the XITEâ object was created (see the Xite Java API).
Usage: (xnamespace prefix urn)
The xnamespace function is used to declare any namespace used in xpath function calls. The namespaces MUST be declared separately using xnamespace or an error will result during the deserialization process.
Usage: (xpath string [option])
The xpath function is used to specify which tag nodes and their attributes are deserialized into the XITE tuple space. The string argument specifies the Xpath expression according to the XSLT 1.1 W3C 1999 standard. The option argument is optional and can be perm to specify that the deserialized XML tuples persist across (reset) calls or Xite.reset( ) invocations.
Usage: (xprop PROPERTYNAME) or (xprop PROPERTYNAME value)
The xprop function associates a value with a property name so that properties and values can be passed between Java and XITEâ rules using the Xite.setProperty and Xite.getProperty Java API methods. Property and value pairs that are associated using the xprop function also persist across (reset) and Xite.reset( ) invocations.
XITE® is primarily designed as a TrAX complaint API for Java programmers. We have included the Javadoc API for XITELite® with this distribution in the doc subdirectory.
XITE® and XITELiteâ include a version of the Java Expert System Shell (JESS) expert system rules engine from Sandia National Laboratories. THERE IS NO NEED TO DOWNLOAD JESS FROM THE SANDIA WEB SITE. XITELite® contains a crippled version of JESS for evaluation purposes. The JESS manual is attached as an appendix to this manual. JESS is the programming language used within XITE® to specify transform rules.
XITELite® is a fully functional, non-expiring evaluation version of XITE(tm) with limited functionality. The full version of XITE(tm) implements additional features such as:
· A high performance, SAX-based XML serializer/deserializer
· A fully TrAX-compliant transform interface.
· The ability to delete or change XML elements
· Support for JESS modules and all JESS 6.0 functions
· XITE API methods for output-only transforms (Xite.write() methods)
· Dynamic generation of XSLT
More information about purchasing and licensing the XITEâ toolkit is available at http://www.sphere.com/
(see following pages for content)