Writing Rules in Java

Rules can be written in Java, loaded by the system at startup, and applied by specification in a rule. A rule class extends XDRuleClass, and can make use of any of its services. Each public method in the rule class that meets the rule signature can be applied by name as a rule. The rule methods can make use of service methods in the parental XDRuleClass.

Rules apply to the input document, which is represented as a tree of XDNodes. An XDNode is a self-contained representation of the element with its attributes, value, and relationships to other nodes. XDNode objects support a complete set of access methods to both obtain these values and to walk the tree. When the rule method is called, it is passed a reference to the node for which it was called, along with the rule parameters. Your rule method can walk the tree to locate related nodes and to evaluate them as appropriate.

In addition to writing rules, you can replace the existing search rules with your own search methods. The default search method supplied by iWay Software searches either a rule-supplied list carried in an attribute, or a delimited text file. You might replace this, for example, with a search method that tests lists in a relational data base or other storage media.

In this example, a node is checked to determine whether its value is included in the attribute’s collection. If not, it is an error.

On entry to the rule, parameters are passed:

Parameter

Description

attributes

HashMap of rule attributes. The rule method can check for any attributes that it desires. A HashMap is a fast implementation of a Hashtable that does not serialize.

node

Node identified by the tag attribute in the rule. The rule method is called once for each node that matches the tag specification.

value

Data value of the addressed node. This differs from the node.getValue() return if the tag contained a subfield address (for example, tag=x:2).

import java.util.*;
import com.ibi.edaqm.*;
public class XDMyRules extends XDRuleClass
{
    public XDMyRules()
    {
    }
    public void specialRule(XDNode node, String value, HashMap attributes)
                throws XDException
    {
        trace(XD.TRACE_DEBUG, "specialRule called with parms: " +
              node.getFullName() + ", " + attributes.toString());
        String testValue = (String)attributes.get("value");
        if (value.equals(testValue))
        {
          node.setAssociatedVector(new XDEDIError(4,0,error,"explanation"));
          throw new XDException(XDException.RULE,
          XDException.RULE_VIOLATION,
          "node value "+value+" is not 'Value'");
        }
    }
}

Rule violations should throw an XDException describing the violation.

The parental class provides a group of services to assist in preparing rules:

Method

Description

boolean isYYYYMMDD(String date)

Validates that a date is formatted correctly.

boolean isInList(String list, String value)

Value must be in the list.

void trace(int level, String msg)

Text of the message is written to the system trace file. The level should be XD.TRACE_DEBUG, XD.TRACE_ERROR, or XD.TRACE_ALL.

Rules can also use all methods in XDNode to address the values in the passed node and the tree in general. Details of XDNode, XDException, and other available engine programming services can be found elsewhere in iWay Software documentation.

Rule violations must be returned as XDExceptions of class XDException.RULE. Two causes are available, XDException.RULE_SYNTAX if the rule is in error, and XD.RULE_VIOLATION if the data violates the rule. Syntax errors cause the document to be aborted, as it is presumed that rules should have been debugged. Violations should be posted to the node by the rule, and the engine continues to process the document. Violations are traced by the engine, and affect the later acknowledgement generation.

The error itself is posted to the node using the standard XDNode service setAssociatedVector(Object o) which records an object with the node. The special EDIError object contains the following elements:

Element

Description

class

Class of the error. Should be 4 for a syntax error, resulting in an AK4.

errorcode

Code to be returned in the ack AKx (997).

explanation

String explaining the error, for tracing use.

reserved

Must be 0.

To test an XML file for rules, the root of the rules file needs to match the root tag of the XML file. For instance if the XML file is as below:

<Customer>
<CustomerName>John Smith</CustomerName>
<bdate>11/77/2007</bdate>
</Customer>

The rules file might look like this:

<Customer>
   <using radix=",">
      <!-- End User Header Record Validation -->
<!--  Your rule goes here -->
      <rule tag="bdate" method="isDate" schema="Customer"/>
<!-end of rule(s) -->
   </using>
</Customer>

The rule needs to be created under Registry->Components->Rules.