Metacat

/**

 *  '$RCSfile$'

 *    Purpose: A Class that represents a structured query, and can be 

 *             constructed from an XML serialization conforming to 

 *             pathquery.dtd. The printSQL() method can be used to print 

 *             a SQL serialization of the query.

 *  Copyright: 2000 Regents of the University of California and the

 *             National Center for Ecological Analysis and Synthesis

 *    Authors: Matt Jones

 *    Release: @release@

 *

 *   '$Author: berkley $'

 *     '$Date: 2000-10-03 15:48:41 -0700 (Tue, 03 Oct 2000) $'

 * '$Revision: 489 $'

 */

package edu.ucsb.nceas.metacat;

import java.io.*;

import java.util.Stack;

import java.util.Vector;

import java.util.Enumeration;

import org.xml.sax.Attributes;

import org.xml.sax.InputSource;

import org.xml.sax.SAXException;

import org.xml.sax.SAXParseException;

import org.xml.sax.XMLReader;

import org.xml.sax.helpers.XMLReaderFactory;

import org.xml.sax.helpers.DefaultHandler;

/**

 * A Class that represents a structured query, and can be 

 * constructed from an XML serialization conforming to @see pathquery.dtd. 

 * The printSQL() method can be used to print a SQL serialization of the query.

 */

public class QuerySpecification extends DefaultHandler {

  private boolean containsExtendedSQL=false;

  // Query data structures

  private String meta_file_id;

  private String querytitle;

  private Vector doctypeList;

  private Vector returnFieldList;

  private QueryGroup query = null;

  private Stack elementStack;

  private Stack queryStack;

  private String currentValue;

  private String currentPathexpr;

  private String parserName = null;

  /**

   * construct an instance of the QuerySpecification class 

   *

   * @param queryspec the XML representation of the query (should conform

   *                  to pathquery.dtd) as a Reader

   * @param parserName the fully qualified name of a Java Class implementing

   *                  the org.xml.sax.XMLReader interface

   */

  public QuerySpecification( Reader queryspec, String parserName ) 

         throws IOException {

    super();

    // Initialize the class variables

    doctypeList = new Vector();

    elementStack = new Stack();

    queryStack   = new Stack();

    returnFieldList = new Vector();

    this.parserName = parserName;

    // Initialize the parser and read the queryspec

    XMLReader parser = initializeParser();

    if (parser == null) {

      System.err.println("SAX parser not instantiated properly.");

    }

    try {

      parser.parse(new InputSource(queryspec));

    } catch (SAXException e) {

      System.err.println("error parsing data");

      System.err.println(e.getMessage());

    }

  }

  /**

   * construct an instance of the QuerySpecification class 

   *

   * @param queryspec the XML representation of the query (should conform

   *                  to pathquery.dtd) as a String

   * @param parserName the fully qualified name of a Java Class implementing

   *                  the org.xml.sax.Parser interface

   */

  public QuerySpecification( String queryspec, String parserName ) 

         throws IOException {

    this(new StringReader(queryspec), parserName);

  }

  /** Main routine for testing */

  static public void main(String[] args) {

     if (args.length < 1) {

       System.err.println("Wrong number of arguments!!!");

       System.err.println("USAGE: java QuerySpecification <xmlfile>");

       return;

     } else {

       String xmlfile  = args[0];

       try {

         MetaCatUtil util = new MetaCatUtil();

         FileReader xml = new FileReader(new File(xmlfile));

         QuerySpecification qspec = 

                 new QuerySpecification(xml, util.getOption("saxparser"));

         System.out.println(qspec.printSQL());

       } catch (IOException e) {

         System.err.println(e.getMessage());

       }

     }

  }

  /**

   * Returns true if the parsed query contains and extended xml query 

   * (i.e. there is at least one <returnfield> in the pathquery document)

   */

  public boolean containsExtendedSQL()

  {

    if(containsExtendedSQL)

    {

      return true;

    }

    else

    {

      return false;

    }

  }

  /**

   * Accessor method to return a vector of the extended return fields as

   * defined in the <returnfield> tag in the pathquery dtd.

   */

  public Vector getReturnFieldList()

  {

    return this.returnFieldList; 

  }

  /**

   * Set up the SAX parser for reading the XML serialized query

   */

  private XMLReader initializeParser() {

    XMLReader parser = null;

    // Set up the SAX document handlers for parsing

    try {

      // Get an instance of the parser

      parser = XMLReaderFactory.createXMLReader(parserName);

      // Set the ContentHandler to this instance

      parser.setContentHandler(this);

      // Set the error Handler to this instance

      parser.setErrorHandler(this);

    } catch (Exception e) {

       System.err.println(e.toString());

    }

    return parser;

  }

  /**

   * callback method used by the SAX Parser when the start tag of an 

   * element is detected. Used in this context to parse and store

   * the query information in class variables.

   */

  public void startElement (String uri, String localName, 

                            String qName, Attributes atts) 

         throws SAXException {

    BasicNode currentNode = new BasicNode(localName);

    // add attributes to BasicNode here

    if (atts != null) {

      int len = atts.getLength();

      for (int i = 0; i < len; i++) {

        currentNode.setAttribute(atts.getLocalName(i), atts.getValue(i));

      }

    }

    elementStack.push(currentNode); 

    if (currentNode.getTagName().equals("querygroup")) {

      QueryGroup currentGroup = new QueryGroup(

                                currentNode.getAttribute("operator"));

      if (query == null) {

        query = currentGroup;

      } else {

        QueryGroup parentGroup = (QueryGroup)queryStack.peek();

        parentGroup.addChild(currentGroup);

      }

      queryStack.push(currentGroup);

    }

  }

  /**

   * callback method used by the SAX Parser when the end tag of an 

   * element is detected. Used in this context to parse and store

   * the query information in class variables.

   */

  public void endElement (String uri, String localName,

                          String qName) throws SAXException {

    BasicNode leaving = (BasicNode)elementStack.pop(); 

    if (leaving.getTagName().equals("queryterm")) {

      boolean isCaseSensitive = (new Boolean(

              leaving.getAttribute("casesensitive"))).booleanValue();

      QueryTerm currentTerm = null;

      if (currentPathexpr == null) {

        currentTerm = new QueryTerm(isCaseSensitive,

                      leaving.getAttribute("searchmode"),currentValue);

      } else {

        currentTerm = new QueryTerm(isCaseSensitive,

                      leaving.getAttribute("searchmode"),currentValue,

                      currentPathexpr);

      }

      QueryGroup currentGroup = (QueryGroup)queryStack.peek();

      currentGroup.addChild(currentTerm);

      currentValue = null;

      currentPathexpr = null;

    } else if (leaving.getTagName().equals("querygroup")) {

      QueryGroup leavingGroup = (QueryGroup)queryStack.pop();

    }

  }

  /**

   * callback method used by the SAX Parser when the text sequences of an 

   * xml stream are detected. Used in this context to parse and store

   * the query information in class variables.

   */

  public void characters(char ch[], int start, int length) {

    String inputString = new String(ch, start, length);

    BasicNode currentNode = (BasicNode)elementStack.peek(); 

    String currentTag = currentNode.getTagName();

    if (currentTag.equals("meta_file_id")) {

      meta_file_id = inputString;

    } else if (currentTag.equals("querytitle")) {

      querytitle = inputString;

    } else if (currentTag.equals("value")) {

      currentValue = inputString;

    } else if (currentTag.equals("pathexpr")) {

      currentPathexpr = inputString;

    } else if (currentTag.equals("returndoctype")) {

      doctypeList.add(inputString);

    } else if (currentTag.equals("returnfield")) {

      returnFieldList.add(inputString);

      containsExtendedSQL = true;

    }

  }

  /**

   * create a SQL serialization of the query that this instance represents

   */

  public String printSQL() {

    StringBuffer self = new StringBuffer();

    self.append("SELECT docid,docname,doctype,doctitle,");

    self.append("date_created, date_updated ");

    self.append("FROM xml_documents WHERE docid IN (");

    // This determines the documents that meet the query conditions

    self.append(query.printSQL());

    self.append(") ");

    // Add SQL to filter for doctypes requested in the query

    if (!doctypeList.isEmpty()) {

      boolean firstdoctype = true;

      self.append(" AND ("); 

      Enumeration en = doctypeList.elements();

      while (en.hasMoreElements()) {

        String currentDoctype = (String)en.nextElement();

        if (firstdoctype) {

           firstdoctype = false;

           self.append(" doctype = '" + currentDoctype + "'"); 

        } else {

          self.append(" OR doctype = '" + currentDoctype + "'"); 

        }

      }

      self.append(") ");

    }

    return self.toString();

  }

  /**

   * This method prints sql based upon the <returnfield> tag in the

   * pathquery document.  This allows for customization of the 

   * returned fields

   * @param doclist the list of document ids to search by

   */

  public String printExtendedSQL(String doclist)

  {  

    StringBuffer self = new StringBuffer();

    self.append("select xml_nodes.docid, xml_index.path, xml_nodes.nodedata ");

    self.append("from xml_index, xml_nodes where xml_index.nodeid=");

    self.append("xml_nodes.parentnodeid and (xml_index.path like '");

    boolean firstfield = true;

    //put the returnfields into the query

    //the for loop allows for multiple fields

    for(int i=0; i<returnFieldList.size(); i++)

    {

      if(firstfield)

      {

        firstfield = false;

        self.append((String)returnFieldList.elementAt(i));

        self.append("' ");

      }

      else

      {

        self.append("or xml_index.path like '");

        self.append((String)returnFieldList.elementAt(i));

        self.append("' ");

      }

    }

    self.append(") AND xml_nodes.docid in (");

    //self.append(query.printSQL());

    self.append(doclist);

    self.append(")");

    self.append(" AND xml_nodes.nodetype = 'TEXT'");

    //System.out.println(self.toString());

    return self.toString();

  }

  public static String printRelationSQL(String docid)

  {

    StringBuffer self = new StringBuffer();

    self.append("select subject, relationship, object, subdoctype, ");

    self.append("objdoctype from xml_relation ");

    self.append("where subject like '").append(docid).append("'");

    return self.toString();

  }

  /**

   * Prints sql that returns all relations in the database.

   */

  public static String printPackageSQL()

  {

    StringBuffer self = new StringBuffer();

    self.append("select z.nodedata, x.nodedata, y.nodedata from ");

    self.append("(select nodeid, parentnodeid from xml_index where path like ");

    self.append("'package/relation/subject') s, (select nodeid, parentnodeid ");

    self.append("from xml_index where path like ");

    self.append("'package/relation/relationship') rel, ");

    self.append("(select nodeid, parentnodeid from xml_index where path like ");

    self.append("'package/relation/object') o, ");

    self.append("xml_nodes x, xml_nodes y, xml_nodes z ");

    self.append("where s.parentnodeid = rel.parentnodeid ");

    self.append("and rel.parentnodeid = o.parentnodeid ");

    self.append("and x.parentnodeid in rel.nodeid ");

    self.append("and y.parentnodeid in o.nodeid ");

    self.append("and z.parentnodeid in s.nodeid ");

    //self.append("and z.nodedata like '%");

    //self.append(docid);

    //self.append("%'");

    return self.toString();

  }

  /**

   * Prints sql that returns all relations in the database that were input

   * under a specific docid

   * @param docid the docid to search for.

   */

  public static String printPackageSQL(String docid)

  {

    StringBuffer self = new StringBuffer();

    self.append("select z.nodedata, x.nodedata, y.nodedata from ");

    self.append("(select nodeid, parentnodeid from xml_index where path like ");

    self.append("'package/relation/subject') s, (select nodeid, parentnodeid ");

    self.append("from xml_index where path like ");

    self.append("'package/relation/relationship') rel, ");

    self.append("(select nodeid, parentnodeid from xml_index where path like ");

    self.append("'package/relation/object') o, ");

    self.append("xml_nodes x, xml_nodes y, xml_nodes z ");

    self.append("where s.parentnodeid = rel.parentnodeid ");

    self.append("and rel.parentnodeid = o.parentnodeid ");

    self.append("and x.parentnodeid in rel.nodeid ");

    self.append("and y.parentnodeid in o.nodeid ");

    self.append("and z.parentnodeid in s.nodeid ");

    self.append("and z.docid like '").append(docid).append("'");

    return self.toString();

  }

  /**

   * Returns all of the relations that has a certain docid in the subject

   * or the object.

   * 

   * @param docid the docid to search for

   */

  public static String printPackageSQL(String subDocidURL, String objDocidURL)

  {

    StringBuffer self = new StringBuffer();

    self.append("select z.nodedata, x.nodedata, y.nodedata from ");

    self.append("(select nodeid, parentnodeid from xml_index where path like ");

    self.append("'package/relation/subject') s, (select nodeid, parentnodeid ");

    self.append("from xml_index where path like ");

    self.append("'package/relation/relationship') rel, ");

    self.append("(select nodeid, parentnodeid from xml_index where path like ");

    self.append("'package/relation/object') o, ");

    self.append("xml_nodes x, xml_nodes y, xml_nodes z ");

    self.append("where s.parentnodeid = rel.parentnodeid ");

    self.append("and rel.parentnodeid = o.parentnodeid ");

    self.append("and x.parentnodeid in rel.nodeid ");

    self.append("and y.parentnodeid in o.nodeid ");

    self.append("and z.parentnodeid in s.nodeid ");

    self.append("and (z.nodedata like '");

    self.append(subDocidURL);

    self.append("' or y.nodedata like '");

    self.append(objDocidURL);

    self.append("')");

    return self.toString();

  }

  public static String printGetDocByDoctypeSQL(String docid)

  {

    StringBuffer self = new StringBuffer();

    self.append("SELECT docid,docname,doctype,doctitle,");

    self.append("date_created, date_updated ");

    self.append("FROM xml_documents WHERE docid IN (");

    self.append(docid).append(")");

    return self.toString();

  }

  /**

   * create a String description of the query that this instance represents.

   * This should become a way to get the XML serialization of the query.

   */

  public String toString() {

    return "meta_file_id=" + meta_file_id + "\n" + 

           "querytitle=" + querytitle + "\n" + query;

  }

  /** a utility class that represents a group of terms in a query */

  private class QueryGroup {

    private String operator = null;  // indicates how query terms are combined

    private Vector children = null;  // the list of query terms and groups

    /** 

     * construct a new QueryGroup 

     *

     * @param operator the boolean conector used to connect query terms 

     *                    in this query group

     */

    public QueryGroup(String operator) {

      this.operator = operator;

      children = new Vector();

    }

    /** 

     * Add a child QueryGroup to this QueryGroup

     *

     * @param qgroup the query group to be added to the list of terms

     */

    public void addChild(QueryGroup qgroup) {

      children.add((Object)qgroup); 

    }

    /**

     * Add a child QueryTerm to this QueryGroup

     *

     * @param qterm the query term to be added to the list of terms

     */

    public void addChild(QueryTerm qterm) {

      children.add((Object)qterm); 

    }

    /**

     * Retrieve an Enumeration of query terms for this QueryGroup

     */

    public Enumeration getChildren() {

      return children.elements();

    }

    /**

     * create a SQL serialization of the query that this instance represents

     */

    public String printSQL() {

      StringBuffer self = new StringBuffer();

      boolean first = true;

      self.append("(");

      Enumeration en= getChildren();

      while (en.hasMoreElements()) {

        Object qobject = en.nextElement();

        if (first) {

          first = false;

        } else {

          self.append(" " + operator + " ");

        }

        if (qobject instanceof QueryGroup) {

          QueryGroup qg = (QueryGroup)qobject;

          self.append(qg.printSQL());

        } else if (qobject instanceof QueryTerm) {

          QueryTerm qt = (QueryTerm)qobject;

          self.append(qt.printSQL());

        } else {

          System.err.println("qobject wrong type: fatal error");

        }

      }

      self.append(") \n");

      return self.toString();

    }

    /**

     * create a String description of the query that this instance represents.

     * This should become a way to get the XML serialization of the query.

     */

    public String toString() {

      StringBuffer self = new StringBuffer();

      self.append("  (Query group operator=" + operator + "\n");

      Enumeration en= getChildren();

      while (en.hasMoreElements()) {

        Object qobject = en.nextElement();

        self.append(qobject);

      }

      self.append("  )\n");

      return self.toString();

    }

  }

  /** a utility class that represents a single term in a query */

  private class QueryTerm {

    private boolean casesensitive = false;

    private String searchmode = null;

    private String value = null;

    private String pathexpr = null;

    /**

     * Construct a new instance of a query term for a free text search

     * (using the value only)

     *

     * @param casesensitive flag indicating whether case is used to match

     * @param searchmode determines what kind of substring match is performed

     *        (one of starts-with|ends-with|contains|matches-exactly)

     * @param value the text value to match

     */

    public QueryTerm(boolean casesensitive, String searchmode, 

                     String value) {

      this.casesensitive = casesensitive;

      this.searchmode = searchmode;

      this.value = value;

    }

    /**

     * Construct a new instance of a query term for a structured search

     * (matching the value only for those nodes in the pathexpr)

     *

     * @param casesensitive flag indicating whether case is used to match

     * @param searchmode determines what kind of substring match is performed

     *        (one of starts-with|ends-with|contains|matches-exactly)

     * @param value the text value to match

     * @param pathexpr the hierarchical path to the nodes to be searched

     */

    public QueryTerm(boolean casesensitive, String searchmode, 

                     String value, String pathexpr) {

      this(casesensitive, searchmode, value);

      this.pathexpr = pathexpr;

    }

    /** determine if the QueryTerm is case sensitive */

    public boolean isCaseSensitive() {

      return casesensitive;

    }

    /** get the searchmode parameter */

    public String getSearchMode() {

      return searchmode;

    }

    /** get the Value parameter */

    public String getValue() {

      return value;

    }

    /** get the path expression parameter */

    public String getPathExpression() {

      return pathexpr;

    }

    /**

     * create a SQL serialization of the query that this instance represents

     */

    public String printSQL() {

      StringBuffer self = new StringBuffer();

      // Uppercase the search string if case match is not important

      String casevalue = null;

      String nodedataterm = null;

      if (casesensitive) {

        nodedataterm = "nodedata";

        casevalue = value;

      } else {

        nodedataterm = "UPPER(nodedata)";

        casevalue = value.toUpperCase();

      }

      // Add appropriate wildcards to search string

      String searchvalue = null;

      if (searchmode.equals("starts-with")) {

        searchvalue = casevalue + "%";

      } else if (searchmode.equals("ends-with")) {

        searchvalue = "%" + casevalue;

      } else if (searchmode.equals("contains")) {

        searchvalue = "%" + casevalue + "%";

      } else {

        searchvalue = casevalue;

      }

      self.append("SELECT DISTINCT docid FROM xml_nodes WHERE \n");

      if (pathexpr != null) {

        self.append(nodedataterm + " LIKE " + "'" + searchvalue + "' ");

        self.append("AND parentnodeid IN ");

        self.append("(SELECT nodeid FROM xml_index WHERE path LIKE " + 

                    "'" +  pathexpr + "') " );

      } else {

        self.append(nodedataterm + " LIKE " + "'" + searchvalue + "' ");

      }

      return self.toString();

    }

    /**

     * create a String description of the query that this instance represents.

     * This should become a way to get the XML serialization of the query.

     */

    public String toString() {

      StringBuffer self = new StringBuffer();

      self.append("    Query Term iscasesensitive=" + casesensitive + "\n");

      self.append("               searchmode=" + searchmode + "\n");

      self.append("               value=" + value + "\n");

      if (pathexpr != null) {

        self.append("               pathexpr=" + pathexpr + "\n");

      }

      return self.toString();

    }

  }

}

/**

 * '$Log$

 * 'Revision 1.16  2000/09/26 22:06:52  berkley

 * 'Added backtrack functionality.  Backtracking works by passing a returndoc parameter.  There can be more than one.  If a document that is hit by a query is not of type returndoc then it searches the database for a related file of type returndoc.  If one is found it is displayed, if no relation is found, the original is displayed.

 * '

 * 'Support was also added for an index of relations.  the table xml_relation handles the all of the relation indexing.

 * '

 * 'Revision 1.15  2000/09/15 19:52:12  berkley

 * 'Added functionality for package specifications.  metacatservlet now contains a new action called getrelateddocument that handles retrieving related documents using the metacatURL specification (metacatURL.java).  DBQuery contains new code in runQuery that embeds relation tags in the returned hashtable describing the documents related to each docid.  querySpecification contains a new method which prints the sql that does the relation query.

 * '

 * 'Revision 1.14  2000/08/31 21:20:39  berkley

 * 'changed xslf for new returnfield scheme.  the returnfields are now returned as <param name="<returnfield>"> tags.

 * 'hThe sql for the returnfield query was redone to fix a previous problem with slow queries

 * '

 * 'Revision 1.13  2000/08/23 22:55:38  berkley

 * 'changed the field names to be case-sensitive in the returnfields

 * '

 * 'Revision 1.12  2000/08/23 17:29:05  berkley

 * 'added support for the returnfield parameter

 * '-QuerySpecification now sets a flag (containsExtendedSQL) when there are returnfield items in the pathquery document.

 * 'the accessor method containsExtendedSQL() can be called by other classes to check for extended return parameters

 * '-getReturnFields returns a Vector of the names of each specified return field.

 * '-printExtendedSQL returns a string of the extra SQL statements required for the query.

 * '

 * '-a calling class should first check containsExtendedSQL to make sure that there are extra fields being returned, then call printExtendedSQL to

 * 'insert the extra SQL into the query.  (Note that this is how DBQuery implements this.)

 * '

 * 'Revision 1.11  2000/08/14 20:53:34  jones

 * 'Added "release" keyword to all metacat source files so that the release

 * 'number will be evident in software distributions.

 * '

 * 'Revision 1.10  2000/06/26 10:35:05  jones

 * 'Merged in substantial changes to DBWriter and associated classes and to

 * 'the MetaCatServlet in order to accomodate the new UPDATE and DELETE

 * 'functions.  The command line tools and the parameters for the

 * 'servlet have changed substantially.

 * '

 * 'Revision 1.9.2.3  2000/06/25 23:38:17  jones

 * 'Added RCSfile keyword

 * '

 * 'Revision 1.9.2.2  2000/06/25 23:34:18  jones

 * 'Changed documentation formatting, added log entries at bottom of source files

 * ''

 */