Writing Rule Search Routines in Java

Short lists can be searched by built-in rule engine code. Longer lists, in which the values in the list are obtained not from the attribute directly, but instead from an external source, requires a rule list searcher tailored to the source. Lists might be obtained from a:

• Simple file.
• Database with values loaded at startup.
• Database with an access at each search request.

Each list might need its own search logic, tailored to the source and format of the list itself. To accommodate this, the rule engine allows list-specific search routines to be developed and added to the system. These routines are loaded at system initialization, and terminated at system closedown. Each must offer a search method that determines whether the passed value is valid.

Search routines must extend the XDRuleList class, which is part of the edaqm package: com.ibi.edaqm.XDRuleClass. The routine must offer three methods in the manner common to all XD extensions:

• init(String[] args) is called once at system initialization.
• term() is called once at system termination. It is not guaranteed to be called.
• search(String value) is called when the rule is executed.

The Rule List search code is identified in the <preload> section of the <system> area of the dictionary. The Preloads console page manages this section.

The following preload

<preload>
   <name file="RuleFileList(c:\ziplist.txt)"
         comment="validates zip codes">ziplist
   </name>
</preload>

specifies that a rule can be written, such as:

<rule tag="xxx" code="@ziplist" method="checklist"/>

The ziplist routine might load a list from a text file.

A simplified example procedure to load a file containing codes is shown below:

import com.ibi.edaqm.*;
import java.util.*;
import java.io.*;
/**
 * A rule list handler is a routine called to enable users search lists during
 * execution or the checkList rule. checkList() is a generally available rule to
 * test whether the contents of a document field are valid. The rule list handler is
 * invoked when the code= attribute indicates the name of a coder routine rather
 * than a simple list.
 * For example, <I>code="@list1"</I> will cause the search routine of the list1
 * class to be invoked.
 * The file read by this procedure consists of tokens separated by a new line, white
 * space or commas.
 */
public class XDRuleListFile extends XDRuleList
{
     String[] list;
     ArrayList al = new ArrayList(127);
     public XDRuleListFile()
     {
     }
     /**
      * The init method is called when a rule is loaded. It can perform any
      * necessary initialization, and can store any persistent information in the
      * object store.
      *
      * @param parms Array of parameter string passed within the start command
      * init-name(parms).
      */
     public void init(String[] parms) throws XDException
     {
         if (parms == null)
         {
             throw new XDException(XD.XDException.RULE, XDException.RULE_SYNTAX,
                    "no parms sent to " + name);
         }
         try
         {
             File f = new File(parms[0]);
             FileInputStream fs = new FileInputStream(f);
             long len = f.length();
             byte[] b = new byte[(int)len];
             fs.read(b);
             fs.close();
             String data = new String(b);
             StringTokenizer st = new StringTokenizer(data, ", " +XD.NEWLINE);

             while (st.hasMoreTokens())
             {
                 String part = st.nextToken();
                 al.add(part);
             }
         }
         catch (FileNotFoundException e)
         {
             throw new XDException(XDException.RULE, XDException.RULE_SYNTAX,
                    "list file "+parms[0] + " not found");
         }
         catch (IOException eio)
         {
             throw new XDException(XDException.RULE, XDException.RULE_SYNTAX, eio.toString());
         }
     }
     /**
      * The term() method is called when the worker is terminated. It is NOT
      * guaranteed to be called, and applications should not rely upon this
      * method to update databases or perform other critical operations.
      */
     public void term()
     {
     }
        /**
         * Search the given value to determine whether it is in the list. 
         * 
         * @param value String to test against the list
         * @return true if found, false otherwise
         */
        public boolean search(String value)
        {
            return al.contains(value);
        }
}