de.fuberlin.wiwiss.ng4j.triql
Class TriQLQuery

java.lang.Object
  de.fuberlin.wiwiss.ng4j.triql.TriQLQuery

public class TriQLQuery
extends Object

A TriQL query. The data source can be a NamedGraphSet, or any RDF document given in the query's FROM clause.

A query is executed by creating a new TriQLQuery instance and calling its getResults() method. The static exec(String) and exec(NamedGraphSet, String) methods combine both steps into a single call.

TriQL query results are iterators over a list of maps. The map's keys are the names of the result variables. The map's values are the corresponding result values.

The class provides methods for assembling a query programmatically. This is an alternative to creating the query from a String. For example, one can add prefix bindings using the setPrefix(String, String) method, instead of the ususal USING ... FOR clauses.

Author:

Richard Cyganiak (richard@cyganiak.de)

Constructor Summary

TriQLQuery()
Constructor for assembling a TriQL query programmatically.

TriQLQuery(NamedGraphSet dataSource, String queryString)
Creates a new query instance whose data source is a NamedGraphSet.

TriQLQuery(String queryString)
Creates a new query instance whose data source is an URL given in the query's FROM clause, or is passed later to the setSource(de.fuberlin.wiwiss.ng4j.NamedGraphSet) or setSourceURL(java.lang.String) method.

Method Summary

void	addBoundVar(String name) TODO: Is this necessary? We can find them all by going throug the patterns.
void	addConstraint(Constraint constraint) Programmatically adds a constraint to the query.
void	addGraphPattern(GraphPattern graphPattern) Programmatically adds a graph pattern to the query.
void	addResultVar(String name) Programmatically adds a result variable.
static Iterator	exec(NamedGraphSet dataSource, String queryString) Convenience method for quick query execution.
static Iterator	exec(String queryString) Convenience method for quick query execution.
URL	getBaseURL()
List	getBoundVars()
List	getConstraints()
List	getGraphPatterns()
Map	getPreboundVariableValues() Gets all pre-bound variables.
PrefixMapping	getPrefixMapping()
Iterator	getResults() Executes the query and delivers results as an iterator over maps.
List	getResultsAsList() Executes the query and delivers results as a list of maps.
List	getResultVars()
NamedGraphSet	getSource()
String	getSourceURL()
void	prebindVariableValue(String variable, Node value) Fixes the value of a variable before executing the query.
void	setBaseURL(URL baseURL) If the FROM URI of the query is relative, it will be evaluated relative to this base URI.
void	setPrefix(String prefix, String expansion) Programmatically adds a prefix mapping.
void	setSource(NamedGraphSet source) Programmatically sets the NamedGraphSet on which the query will run.
void	setSourceURL(String sourceURL) Programmatically sets the source URL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TriQLQuery

public TriQLQuery(NamedGraphSet dataSource,
                  String queryString)

Creates a new query instance whose data source is a NamedGraphSet.

Parameters:

dataSource - The NamedGraphSet on which to execute the query

queryString - The TriQL query

TriQLQuery

public TriQLQuery(String queryString)

Creates a new query instance whose data source is an URL given in the query's FROM clause, or is passed later to the setSource(de.fuberlin.wiwiss.ng4j.NamedGraphSet) or setSourceURL(java.lang.String) method.

Parameters:

queryString - The TriQL query

TriQLQuery

public TriQLQuery()

Constructor for assembling a TriQL query programmatically. All components of the query (bound variables, source URL or NamedGraphSet, GraphPatterns, Constraints, and namespace prefixes) must be passed to the instance using the methods of the class.

Method Detail

exec

public static Iterator exec(NamedGraphSet dataSource,
                            String queryString)

Convenience method for quick query execution. A NamedGraphSet is the data source.

Iterator results = TriQLQuery.exec(mySet, "SELECT ?x, ?y FROM ...")

is equivalent to

TriQLQuery query = new TriQLQuery(mySet, "SELECT ?x, ?y FROM ...");
 Iterator results = query.getResults();

Parameters:

dataSource - The datasource

queryString - The TriQL query to be executed

Returns:

An iterator over the results

See Also:

getResults()

exec

public static Iterator exec(String queryString)

Convenience method for quick query execution. The data source is an URL which must be given in the query's FROM clause.

Iterator results = TriQLQuery.exec("SELECT ?x, ?y FROM ...")

is equivalent to

TriQLQuery query = new TriQLQuery("SELECT ?x, ?y FROM ...");
 Iterator results = query.getResults();

Parameters:

queryString - The TriQL query to be executed

Returns:

An iterator over the results

See Also:

getResults()

getResults

public Iterator getResults()

Executes the query and delivers results as an iterator over maps. The keys of each map are the variable names. The values are the result Nodes.

Returns:

An iterator over the query results

getResultsAsList

public List getResultsAsList()

Executes the query and delivers results as a list of maps. The keys of each map are the variable names. The values are the result Nodes.

Returns:

A list of the query results

setBaseURL

public void setBaseURL(URL baseURL)

If the FROM URI of the query is relative, it will be evaluated relative to this base URI.

Parameters:

baseURL -

getBaseURL

public URL getBaseURL()

setSource

public void setSource(NamedGraphSet source)

Programmatically sets the NamedGraphSet on which the query will run.

Parameters:

source -

getSource

public NamedGraphSet getSource()

setSourceURL

public void setSourceURL(String sourceURL)

Programmatically sets the source URL. On query execution, the URL will be fetched and the query will run on the RDF data found there.

Parameters:

sourceURL -

getSourceURL

public String getSourceURL()

addResultVar

public void addResultVar(String name)

Programmatically adds a result variable. Calling addResultVar("foo") is equivalent to having "?foo" in the SELECT clause.

Parameters:

name -

getResultVars

public List getResultVars()

addBoundVar

public void addBoundVar(String name)

TODO: Is this necessary? We can find them all by going throug the patterns.

Parameters:

name -

getBoundVars

public List getBoundVars()

addGraphPattern

public void addGraphPattern(GraphPattern graphPattern)

Programmatically adds a graph pattern to the query. This is equivalent to having the pattern in the WHERE clause.

Parameters:

graphPattern -

getGraphPatterns

public List getGraphPatterns()

addConstraint

public void addConstraint(Constraint constraint)

Programmatically adds a constraint to the query. This is equivalent to having the constraint in the AND clause.

Parameters:

constraint -

getConstraints

public List getConstraints()

setPrefix

public void setPrefix(String prefix,
                      String expansion)

Programmatically adds a prefix mapping. This is equivalent to the USING ... FOR clause.

Parameters:

prefix - The namespace prefix to be added

expansion - The full namespace URI

getPrefixMapping

public PrefixMapping getPrefixMapping()

prebindVariableValue

public void prebindVariableValue(String variable,
                                 Node value)

Fixes the value of a variable before executing the query. Equivalent to adding "AND ?variable = <value>".

Parameters:

variable - A variable name

value - The value required for that variable

See Also:

getPreboundVariableValues()

getPreboundVariableValues

public Map getPreboundVariableValues()

Gets all pre-bound variables. It's a map from variable names to their pre-bound values.

Returns:

A map from strings to Nodes

See Also:

prebindVariableValue(java.lang.String, com.hp.hpl.jena.graph.Node)