14. Jess and XML

Jess now supports an XML-based rule language. Rather than adopting an evolving standard like RuleML, Jess's XML rule language (JessML) was designed to be close in structure to the Jess language itself. JessML is a hybrid imperative/declarative language, just like the Jess language itself. That means you can not only write rules in it, but define and call functions as well. Anything you can do in the Jess language, you can do in JessML too.

Transformation between JessML and RuleML and other XML rule languages should be simple using XSLT.

JessML code is quite verbose. Remember, though, that it's intended to be easy for machines, not humans, to work with.

Jess comes with an XML schema for JessML; it's provided as the file JessML1_0.xsd in the lib subdirectory of the Jess distribution. The schema as written accepts all well-formed JessML code, but does not reject all invalid code; it does not include all the semantics of the JessML language (for example, the requirement that a template be defined before it is used in a pattern.) The JessML namespace URI is http://www.jessrules.com/JessML/1.0 and should be included in all JessML documents. A well-formed JessML document should therefore be of the form

<?xml version='1.0' encoding='US-ASCII'?>
<rulebase xmlns='http://www.jessrules.com/JessML/1.0'>
...
</rulebase>
        

• PLANNING::store-plan-data
• MAIN::animal
• make-pair

• <value type="SYMBOL">nil</value>
• <value type="INTEGER">1</value>
• <value type="STRING">A String</value>

<funcall>
  <name>+</name>
  <value type="VARIABLE">x</value>
  <value type="INTEGER">1</value>
</funcall>
            

<slot>
    <name>location</name>
    <value type="SYMBOL">nil</value>
</slot>
        

You can define a template in the JessML language using the template element. A template element contains a name element followed by any number of elements. The value elements of the slots are interpreted as default values.

<template>
    <name>monkey</name>
    <slot>
        <name>species</name>
        <value type="SYMBOL">rhesus</value>
    </slot>
</template>

You can also automatically define a template based on a Java class using a from-class property, like this:

<template>
  <name>MAIN::button</name>
  <properties>
    <property>
      <name>from-class</name>
      <value type="SYMBOL">java.awt.Button</value></property>
  </properties>
</template>

A rule contains a name element, a lhs element, and a rhs element. The rhs element contains a collection of funcall elements representing the rule's actions. The lhs element contains groups and patterns, which are somewhat complex, and will be discussed in the following sections. A simple rule might look like this (this rule prints "Fired!" for each "MAIN::button" fact that exists:)

<rule>
    <name>MAIN::myrule</name>
    <lhs>
        <group>
            <name>and</name>
            <pattern>
                <name>MAIN::button</name>
            </pattern>
        </group>
    </lhs>
    <rhs>
        <funcall>
            <name>printout</name>
            <value type="SYMBOL">t</value>
            <value type="STRING">Fired!</value>
            <value type="SYMBOL">crlf</value>
        </funcall>
    </rhs>
</rule>

You can use a binding element to bind a variable to the fact that matches a pattern. The text of the binding element is simply the name of the variable to use.

A test element represents a single test in a pattern. A test can either be discriminating or nondiscriminating. A discriminating test is one that sometimes matches and sometimes doesn't. A nondiscriminating test is one that always matches; generally this refers to tests that merely bind a variable to the contents of a slot. There's no difference in the syntax between these two types of test.

A test element contains a type element, an optional conjunction element, and either a value element or a funcall element. The type element's body is either "eq" or "neq", corresponding to a positive or negative test. The conjunction element's body can be either "and" or "or", and it is can used only in the second and later tests on a slot. Finally, the value element represents the test itself. If it's a constant, the contents of the slot will be compared to it for equality or inequality, according to the contents of the type element. If the value is a variable, and if that variable has not been bound to a slot, the variable is bound to the current slot. Otherwise, the variable is compared to the contents of the slot. Finally, if there is a funcall element, the function is evaluated and the test passes if the result is true (for an "eq" test) or false (for a "neq" test.)

The save-facts-xml function writes an XML-formatted file containing only Jess facts. The load-facts function knows how to read those files; the facts contained in the file will be immediately asserted. Any deftemplates needed must have been previously defined or an error will occur. You can create this kind of file yourself, as well. Such a file should be a complete, well-formed XML file containing an XML declaration and a fact-list root element. Inside the document should be nothing but fact elements, each representing a single Jess fact.

You can translate a file of Jess language code into XML using Jess's jess.xml.XMLPrinter class; this is a good way to learn how Jess and JessML correspond. You can use this tool from the command line like this:

java -classpath jess.jar jess.xml.XMLPrinter myfile.clp > myfile.xml
            

The file "myfile.xml" will be a complete translation of all the code in "myfile.clp", including templates, rules, deffunctions, and top-level function calls.

The XMLPrinter class and its companion jess.xml.XMLVisitor can also be used to translate Jess code into XML programatically. You could use XMLPrinter to translate a file of Java code like this:

import jess.xml.XMLPrinter;
import jess.JessException;
import java.io.*;
public class ExXMLPrinter {
    public static void main(String[] args) throws JessException, IOException {
        FileReader fr = new FileReader(args[0]);
        XMLPrinter printer = new XMLPrinter(new PrintWriter(System.out, true));
        try {
            printer.printFrontMatter();
            printer.translateToXML(fr);
            printer.printBackMatter();
        } finally {
            printer.close();
        }
    }
}

To translate individual constructs and other Jess objects that you've already read into Jess, you can use the XMLVisitor class. To write a single Jess object as XML, you create an XMLVisitor instance, passing the object as the constructor argument; any of the library classes that implement jess.Visitable will do. Then you can just call jess.xml.XMLVisitor.toString() on this instance to get the XML version.

import jess.xml.*;
import jess.*;
import java.io.*;
public class ExXMLVisitor {
    public static void main(String[] argv) throws JessException {        
        Rete engine = new Rete();
        engine.eval("(defrule hello => )");
        XMLVisitor visitor = new XMLVisitor(engine.findDefrule("hello"));
        System.out.println(visitor);
    }
}

Jess comes with an XML Schema which you can use to validate the XML you write; it's the file JessML1_0.xsd in the lib subdirectory. Jess won't actually validate your code against this schema, as the standard JDK XML parser is a non-validating parser. To validate your code you'll need a validating parser like Apache Xerces.

In general, anywhere you can use a file full of Jess language code, you can also use a JessML file. For example, the file you provide as a command-line argument to jess.Main can be a JessML file.

The standard batch function can read JessML code as well as Jess language code. It decides what kind of file it is looking at by looking for the "<?xml" characters that should begin a well-formed XML file. require, which uses batch internally, will work with JessML as well.

You can get a little bit more control of the process by using the classes JessSAXParser or JessSAXHandler directly. JessSAXParser will parse a JessML document from an InputSource, installing the results into a Rete object you provide. JessSAXHandler is a SAX event handler that you can use with your own parser.