gate.creole.ontology
Interface OntologyTupleQuery

All Superinterfaces:

ClosableIterator<Vector<LiteralOrONodeID>>, Iterator<Vector<LiteralOrONodeID>>

public interface OntologyTupleQuery
extends ClosableIterator<Vector<LiteralOrONodeID>>

This represents a tuple query of the triple store for the ontology. To create a tuple query object you must use the ontology's factory method Ontology.createTupleQuery(String, gate.creole.ontology.OConstants.QueryLanguage).

NOTE: querying the ontology triple store directly should be avoided and only done in exceptional cases. Using the methods to query and access ontology entities should be preferred whenever possible!

The query object implements a closable iterator that auto-closes when all its elements are exhausted. However, you must close it if you stop retrieving elements before all elements have been exhausted (i.e. before the hasNext() method has returned false). Closing the query object is necessary to free the considerable resources allocated by it.

To use a query object properly, be sure to follow the following steps:

• Create the query object using the ontology's factory method
• Optionally set variable bindings using the setBinding method
• Evaluate the query. This is optional if you are not re-using a query object with new binding settings
• Check if there is something available using the hasNext() method
• Retrieve the next tuple using the next() or nextAsString() method, or using the nextFirst() or nextFirstAsString() method if you only need the first or only variable in a tuple.
• Close the query if hasNext() has not returned false yet and you do not need any more results from the query.
• If you want to re-use the query with different variable bindings use method setBinding() and reevaluate using the method evaluate().

  Author:

  Johann Petrak

  Method Summary

  void	close() Explicitly close the query and free its resources.
  void	evaluate() Evaluate the tuple query (again).
  boolean	hasNext() Test if more results are available.
  Vector<LiteralOrONodeID>	next() Retrieve the next tuple from the query object.
  Vector<String>	nextAsString() Retrieve the next tuple from the query object as a vector of strings.
  LiteralOrONodeID	nextFirst() Return just the first variable of a tuple.
  String	nextFirstAsString() Return just the first variable of a tuple as a String.
  void	setBinding(String varName, Literal value) Set the binding of a query variable to a new value.
  void	setBinding(String varName, ONodeID value) Set the binding of a query variable to a new value.

  Methods inherited from interface java.util.Iterator

  remove

  Method Detail

  hasNext

  boolean hasNext()

  Test if more results are available.

  Specified by:

  hasNext in interface Iterator<Vector<LiteralOrONodeID>>

  Returns:

  a boolean indicating if more results can be retrieved with one of the next methods.

  next

  Vector<LiteralOrONodeID> next()

  Retrieve the next tuple from the query object.

  Specified by:

  next in interface Iterator<Vector<LiteralOrONodeID>>

  Returns:

  a vector of LiteralOrONodeID objects that represent the next tuple of the query.

  nextAsString

  Vector<String> nextAsString()

  Retrieve the next tuple from the query object as a vector of strings.

  Returns:

  a vector of strings representing the next result tuple of the query. Each element of the vector is the result of using the original value's toString() method to convert the value into a string.

  setBinding

  void setBinding(String varName,
                  Literal value)

  Set the binding of a query variable to a new value. This can be used to re-use a query with different variable bindings without recompiling it.

  Parameters:

  varName - the name of the variable

  value - the value to assign to the variable

  setBinding

  void setBinding(String varName,
                  ONodeID value)

  Set the binding of a query variable to a new value. This can be used to re-use a query with different variable bindings without recompiling it.

  Parameters:

  varName - the name of the variable

  value - the value to assign to the variable

  evaluate

  void evaluate()

  Evaluate the tuple query (again). This method is optional but can be used to explicitly re-evaluate the query after variable bindings have been set. The method can be used explicitly to separate the query evaluation from the first retrieval of a tuple (where it is done implicitly).

  nextFirst

  LiteralOrONodeID nextFirst()

  Return just the first variable of a tuple. This is useful if the tuple only consists of one variable and can be used to avoid the creation of a vector only containing one element in that case.

  Returns:

  a LiteralOrONodeID object representing the first or only variable in a returned tuple.

  nextFirstAsString

  String nextFirstAsString()

  Return just the first variable of a tuple as a String. This is useful if the tuple only consists of one variable and can be used to avoid the creation of a vector only containing one element in that case. The original value's toString() method is used to convert the value to its String representation.

  Returns:

  a LiteralOrONodeID object representing the first or only variable in a returned tuple.

  close

  void close()

  Explicitly close the query and free its resources. This method must be used if a query is not used any longer but the hasNext() method has not returned false yet.

  Specified by:

  close in interface ClosableIterator<Vector<LiteralOrONodeID>>