[Mulgara-svn] r381 - branches/nw-interface/src/jar/itql/java/org/mulgara/itql

[pag at mulgara.org]

Author: pag
Date: 2007-08-27 16:13:48 -0500 (Mon, 27 Aug 2007)
New Revision: 381

Added:
   branches/nw-interface/src/jar/itql/java/org/mulgara/itql/SableCCInterpreter.java
Log:
Base class for Itql interpreting classes.  This extends the interface Interpreter, which has now moved to the lang package.

Added: branches/nw-interface/src/jar/itql/java/org/mulgara/itql/SableCCInterpreter.java
===================================================================
--- branches/nw-interface/src/jar/itql/java/org/mulgara/itql/SableCCInterpreter.java	2007-08-27 21:12:45 UTC (rev 380)
+++ branches/nw-interface/src/jar/itql/java/org/mulgara/itql/SableCCInterpreter.java	2007-08-27 21:13:48 UTC (rev 381)
@@ -0,0 +1,85 @@
+/**
+ * The contents of this file are subject to the Open Software License
+ * Version 3.0 (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ * http://www.opensource.org/licenses/osl-3.0.txt
+ *
+ * Software distributed under the License is distributed on an "AS IS"
+ * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ * the License for the specific language governing rights and limitations
+ * under the License.
+ */
+package org.mulgara.itql;
+
+import java.net.URI;
+import java.net.URISyntaxException;
+
+import org.mulgara.itql.node.PLiteral;
+import org.mulgara.itql.node.TResource;
+import org.mulgara.itql.node.Token;
+import org.mulgara.parser.Interpreter;
+import org.mulgara.query.Query;
+import org.mulgara.query.QueryException;
+import org.mulgara.query.Variable;
+import org.mulgara.query.rdf.LiteralImpl;
+
+/**
+ * Interpreter methods specific to sableCC structures.
+ * 
+ * @created Aug 24, 2007
+ * @author Paul Gearon
+ * @copyright &copy; 2007 <a href="mailto:pgearon at users.sourceforge.net">Paul Gearon</a>
+ * @licence <a href="{@docRoot}/../../LICENCE.txt">Open Software License v3.0</a>
+ */
+public interface SableCCInterpreter extends Interpreter {
+
+  /**
+   * Construct a {@link LiteralImpl} from a {@link PLiteral}.
+   *
+   * @param p  the instance to convert
+   */
+  public LiteralImpl toLiteralImpl(PLiteral p);
+
+  /**
+   * Returns an anonymous variable unique for this interpreter.
+   * Note: We really should introduce a new subclass of Variable
+   * that is explicitly anonymous, but for now this will do.
+   */
+  public Variable nextAnonVariable();
+
+  /**
+   * Executes a query and returns its results.
+   *
+   * @param rawQuery a select query, represented as either a {@link
+   *      org.mulgara.itql.node.ASelectCommand} or a {@link
+   *      org.mulgara.itql.node.ASelectSetOfTriples}
+   * @return the answer to the query
+   * @throws QueryException if the query cannot be executed
+   * @throws URISyntaxException if the <code>query</code> contains a resource
+   *      whose text violates <a href="http://www.isi.edu/in-notes/rfc2396.txt">
+   *      RFC\uFFFD2396</a>
+   */
+  public Query buildQuery(org.mulgara.itql.node.Node rawQuery) throws QueryException,
+      URISyntaxException;
+
+  /**
+   * Convert SableCC-generated {@link TResource} tokens into {@link URI}s.
+   *
+   * Resolution will treat the token as an XML
+   * <a href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">qualified
+   * names</a> if the {@link #aliasMap} <code>aliasMap</code> contains a key
+   * for the URI scheme part that can be treated as an XML namespace prefix.
+   * For example, <kbd>dc:title</kbd> is treated as a qname and mapped to the
+   * to the URI <kbd>http://purl.org/dc/elements/1.1/title</kbd>, assuming the
+   * {@link #aliasMap} had an entry mapping <code>"dc"</code> to the Dublin
+   * Core namespace.
+   *
+   * @param token  the token to be converted, which should actually be a
+   *   {@link TResource}
+   * @throws Error if the <var>token</var> text isn't syntactically
+   *   a {@link URI}; this shouldn't ever occur, assuming the <var>token</var>
+   *   is a {@link TResource}
+   */
+  URI toURI(Token token);
+
+}