001 /*
002 * Copyright (c) 1995-2010, The University of Sheffield. See the file
003 * COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
004 *
005 * This file is part of GATE (see http://gate.ac.uk/), and is free
006 * software, licenced under the GNU Library General Public License,
007 * Version 2, June 1991 (in the distribution as file licence.html,
008 * and also available at http://gate.ac.uk/gate/licence.html).
009 *
010 * Johann Petrak 2009-08-13
011 *
012 * $Id: OntologyTupleQuery.java 12006 2009-12-01 17:24:28Z thomas_heitz $
013 */
014 package gate.creole.ontology;
015
016 import gate.util.ClosableIterator;
017 import java.util.Vector;
018
019 /**
020 * This represents a tuple query of the triple store for the ontology.
021 * To create a tuple query object you must use the ontology's factory
022 * method {@link Ontology.createTupleQuery(String query, QueryLanguage lang)}.
023 * <p>
024 * NOTE: querying the ontology triple store directly should be avoided and
025 * only done in exceptional cases. Using the methods to query and access ontology
026 * entities should be preferred whenever possible!
027 * <p>
028 * The query object implements a closable iterator that auto-closes when all
029 * its elements are exhausted. However, you must close it if you stop retrieving
030 * elements before all elements have been exhausted (i.e. before the
031 * hasNext() method has returned false). Closing the query object is necessary
032 * to free the considerable resources allocated by it.
033 * <p>
034 * To use a query object properly, be sure to follow the following steps:
035 * <ul>
036 * <li>Create the query object using the ontology's factory method
037 * <li>Optionally set variable bindings using the setBinding method
038 * <li>Evaluate the query. This is optional if you are not re-using a query
039 * object with new binding settings
040 * <li>Check if there is something available using the hasNext() method
041 * <li>Retrieve the next tuple using the next() or nextAsString() method, or
042 * using the nextFirst() or nextFirstAsString() method if you only need the
043 * first or only variable in a tuple.
044 * <li>Close the query if hasNext() has not returned false yet and you do not
045 * need any more results from the query.
046 * <li>If you want to re-use the query with different variable bindings
047 * use method setBinding() and reevaluate using the method evaluate().
048 * </uk>
049 *
050 * @author Johann Petrak
051 */
052 public interface OntologyTupleQuery
053 extends ClosableIterator<Vector<LiteralOrONodeID>>
054 {
055 /**
056 * Test if more results are available.
057 * @return a boolean indicating if more results can be retrieved with one
058 * of the next methods.
059 */
060 public boolean hasNext();
061 /**
062 * Retrieve the next tuple from the query object.
063 * @return a vector of LiteralOrONodeID objects that represent the next
064 * tuple of the query.
065 */
066 public Vector<LiteralOrONodeID> next();
067 /**
068 * Retrieve the next tuple from the query object as a vector of strings.
069 *
070 * @return a vector of strings representing the next result tuple of the query.
071 * Each element of the vector is the result of using the original value's
072 * toString() method to convert the value into a string.
073 */
074 public Vector<String> nextAsString();
075 /**
076 * Set the binding of a query variable to a new value. This can be used
077 * to re-use a query with different variable bindings without recompiling
078 * it.
079 *
080 * @param varName the name of the variable
081 * @param value the value to assign to the variable
082 */
083 public void setBinding(String varName, Literal value);
084 /**
085 * Set the binding of a query variable to a new value. This can be used
086 * to re-use a query with different variable bindings without recompiling
087 * it.
088 *
089 * @param varName the name of the variable
090 * @param value the value to assign to the variable
091 */
092 public void setBinding(String varName, ONodeID value);
093 /**
094 * Evaluate the tuple query (again). This method is optional but can
095 * be used to explicitly re-evaluate the query after variable bindings
096 * have been set. The method can be used explicitly to separate the
097 * query evaluation from the first retrieval of a tuple (where it is
098 * done implicitly).
099 */
100 public void evaluate();
101 /**
102 * Return just the first variable of a tuple. This is useful if the
103 * tuple only consists of one variable and can be used to avoid the
104 * creation of a vector only containing one element in that case.
105 *
106 * @return a LiteralOrONodeID object representing the first or only variable
107 * in a returned tuple.
108 */
109 public LiteralOrONodeID nextFirst();
110 /**
111 * Return just the first variable of a tuple as a String. This is useful if the
112 * tuple only consists of one variable and can be used to avoid the
113 * creation of a vector only containing one element in that case.
114 * The original value's toString() method is used to convert the value
115 * to its String representation.
116 *
117 * @return a LiteralOrONodeID object representing the first or only variable
118 * in a returned tuple.
119 */
120 public String nextFirstAsString();
121 /**
122 * Explicitly close the query and free its resources. This method must be
123 * used if a query is not used any longer but the hasNext() method has
124 * not returned false yet.
125 */
126 public void close();
127 }
|