OntologyTupleQuery.java
001 /*
002  *  Copyright (c) 1995-2012, 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 17530 2014-03-04 15:57:43Z markagreenwood $
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, gate.creole.ontology.OConstants.QueryLanguage)}.
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   @Override
061   public boolean hasNext();
062   /**
063    * Retrieve the next tuple from the query object.
064    @return a vector of LiteralOrONodeID objects that represent the next
065    * tuple of the query.
066    */
067   @Override
068   public Vector<LiteralOrONodeID> next();
069   /**
070    * Retrieve the next tuple from the query object as a vector of strings.
071    *
072    @return a vector of strings representing the next result tuple of the query.
073    * Each element of the vector is the result of using the original value's
074    * toString() method to convert the value into a string.
075    */
076   public Vector<String> nextAsString();
077   /**
078    * Set the binding of a query variable to a new value. This can be used
079    * to re-use a query with different variable bindings without recompiling
080    * it.
081    *
082    @param varName the name of the variable
083    @param value the value to assign to the variable
084    */
085   public void setBinding(String varName, Literal value);
086   /**
087    * Set the binding of a query variable to a new value. This can be used
088    * to re-use a query with different variable bindings without recompiling
089    * it.
090    *
091    @param varName the name of the variable
092    @param value the value to assign to the variable
093    */
094   public void setBinding(String varName, ONodeID value);
095   /**
096    * Evaluate the tuple query (again). This method is optional but can
097    * be used to explicitly re-evaluate the query after variable bindings
098    * have been set. The method can be used explicitly to separate the
099    * query evaluation from the first retrieval of a tuple (where it is
100    * done implicitly).
101    */
102   public void evaluate();
103   /**
104    * Return just the first variable of a tuple. This is useful if the
105    * tuple only consists of one variable and can be used to avoid the
106    * creation of a vector only containing one element in that case.
107    *
108    @return a LiteralOrONodeID object representing the first or only variable
109    * in a returned tuple.
110    */
111   public LiteralOrONodeID nextFirst();
112   /**
113    * Return just the first variable of a tuple as a String. This is useful if the
114    * tuple only consists of one variable and can be used to avoid the
115    * creation of a vector only containing one element in that case.
116    * The original value's toString() method is used to convert the value
117    * to its String representation.
118    *
119    @return a LiteralOrONodeID object representing the first or only variable
120    * in a returned tuple.
121    */
122   public String nextFirstAsString();
123   /**
124    * Explicitly close the query and free its resources. This method must be
125    * used if a query is not used any longer but the hasNext() method has
126    * not returned false yet. 
127    */
128   @Override
129   public void close();
130 }