com.franz.agbase
Class SPARQLQuery

java.lang.Object
  extended by SPARQLQueryInternals
      extended by com.franz.agbase.SPARQLQuery
All Implemented Interfaces:
SPARQLQueryConstants

public class SPARQLQuery
extends SPARQLQueryInternals
implements SPARQLQueryConstants

This class collects the parameters and results of a SPARQL query.

The typical sequence of steps is to

The choice of action method is determined by the kind of query and by the desired datatype of the result.

This document is not intended to be a SPARQL tutorial or reference. Please refer to other documents for the definition of SPARQL syntax and semantics and for the precise behavior of the SPARQL engine.


Nested Class Summary
 
Nested classes/interfaces inherited from interface com.franz.agbase.SPARQLQueryConstants
SPARQLQueryConstants.ENGINE, SPARQLQueryConstants.PLANNER
 
Constructor Summary
SPARQLQuery()
          Create a new empty SPARQL query with default arguments.
 
Method Summary
 boolean ask()
          Run a SPARQL query that returns a boolean result.
 boolean ask(AllegroGraph ag)
          Run a SPARQL query that returns a boolean result.
 boolean ask(AllegroGraph ag, java.lang.String query)
          Run a SPARQL query that returns a boolean result.
 boolean ask(java.lang.String query)
          Run a SPARQL query that returns a boolean result.
 TriplesIterator construct()
          Run a SPARQL query that retrieves a set of statements.
 TriplesIterator construct(AllegroGraph ag)
          Run a SPARQL query that retrieves a set of statements.
 TriplesIterator construct(AllegroGraph ag, java.lang.String query)
          Run a SPARQL query that retrieves a set of statements.
 TriplesIterator construct(java.lang.String query)
          Run a SPARQL query that retrieves a set of statements.
 long count()
          Run a SPARQL query that retrieves a set (or row) of variable bindings.
 long count(AllegroGraph ag)
          Run a SPARQL query that retrieves a set (or row) of variable bindings.
 long count(AllegroGraph ag, java.lang.String query)
          Run a SPARQL query that retrieves a set (or row) of variable bindings.
 long count(java.lang.String query)
          Run a SPARQL query that retrieves a set (or row) of variable bindings.
 TriplesIterator describe()
          Run a SPARQL query that retrieves a set of statements.
 TriplesIterator describe(AllegroGraph ag)
          Run a SPARQL query that retrieves a set of statements.
 TriplesIterator describe(AllegroGraph ag, java.lang.String query)
          Run a SPARQL query that retrieves a set of statements.
 TriplesIterator describe(java.lang.String query)
          Run a SPARQL query that retrieves a set of statements.
 boolean getBooleanResult()
          Query the result of a query that has a boolean result.
 java.lang.String getDefaultBase()
          Query the default base value of the query.
 java.lang.String getDefaultDatasetBehavior()
          Query the default dataset behavior for this SPARQL query.
 java.lang.String[] getDefaultPrefixes()
          Query the default-prefixes option.
 SPARQLQueryConstants.ENGINE getEngine()
          Query the engine that was or will be used for the SPARQL query.
 java.lang.Boolean getExtended()
          Query the extended option.
 java.lang.String[] getFrom()
          Query the from option.
 java.lang.String[] getFromNamed()
          Query the from-named option.
 java.lang.Boolean getHasValue()
          Query the hasValue option.
 long getLimit()
          Query the limit option.
 java.lang.String getLoadFunction()
          Query the name of the load-function.
 java.lang.Boolean getMemoized()
          Query the memoize option.
 java.lang.String getMemoTable()
          Query the name of the memo table.
 long getOffset()
          Query the offset option.
 SPARQLQueryConstants.PLANNER getPlanner()
          Query the engine that was or will be used for the SPARQL query.
 java.lang.String getQuery()
          Get the query string.
 java.lang.String getRDFFormat()
          Query the RDFFormat option.
 long getResultCount()
          Query the count value of a query that returns a numeric result.
 TriplesIterator getResultCursor()
          Query the result of a SPARQL query that returns a collection of triples.
 java.lang.String[] getResultNames()
          Query the names and order of the variables in a SELECT query result.
 ValueSetIterator getResultSets()
          Query the results of a SPARQL query that returns sets of bindings.
 java.lang.String getResultsFormat()
          Query the resultsFormat option.
 java.lang.String getResultString()
          Query the result of a SPARQL query that returns a string result.
 AllegroGraph getTripleStore()
          Query the triple store against which this SPARQL query has or will run.
 java.lang.String getVars()
          Query the vars option.
 java.lang.Object[] getWithVariables()
          Query the with-variables option.
 boolean isIncludeInferred()
          Query the includeInferred option.
 java.lang.String run()
          Run a SPARQL query that returns a serialized string result.
 java.lang.String run(AllegroGraph ag)
           
 java.lang.String run(AllegroGraph ag, java.lang.String query)
           
 java.lang.String run(java.lang.String query)
           
 ValueSetIterator select()
          Run a SPARQL query that retrieves a set of variable bindings.
 ValueSetIterator select(AllegroGraph ag)
          Run a SPARQL query that retrieves a set of variable bindings.
 ValueSetIterator select(AllegroGraph ag, java.lang.String query)
           
 ValueSetIterator select(java.lang.String query)
          Run a SPARQL query that retrieves a set of variable bindings.
 void setDefaultBase(java.lang.String base)
          Set the default-base option for this SPARQL query.
 void setDefaultDatasetBehaviorAll()
          Set the default-data-set-behavior option to "all".
 void setDefaultDatasetBehaviorDefault()
          Set the default-data-set-behavior option to "default".
 void setDefaultPrefixes(NamespaceRegistry prefixes)
          Set the default-prefixes option.
 void setDefaultPrefixes(java.lang.String[] prefixes)
          Set the default-prefixes option.
 void setEngine(SPARQLQueryConstants.ENGINE e)
          Set the engine that will be used for the SPARQL query.
 void setExtended(boolean extended)
          Set the extended option.
 void setFrom(java.lang.String[] uriLabels)
          Set the from option,
 void setFromNamed(java.lang.String[] uriLabels)
          Set the from-named option,
 void setHasValue(boolean v)
          Enable or disable hasValue reasoning.
 void setIncludeInferred(boolean includeInferred)
          Modify the includeInferred option.
 void setLimit(int limit)
          Set the limit option.
 void setLoadFunction(java.lang.String name)
          Set the name of a load-function option.
 void setMemoized(boolean memoized)
          Set the memoize option.
 void setMemoTable(java.lang.String name)
          Set the name of a memo table.
 void setOffset(int offset)
          Set the offset option.
 void setPlanner(SPARQLQueryConstants.PLANNER e)
          Set the engine that will be used for the SPARQL query.
 void setQuery(java.lang.String newQuery)
          Set the query string.
 void setRDFFormat(java.lang.String format)
          Set the RDFFormat option.
 void setResultsFormat(java.lang.String resultsFormat)
          Set the resultsFormat option.
 void setTripleStore(AllegroGraph ag)
          Specify the triple store against which this SPARQL query will run.
 void setVars(java.lang.String vars)
          Set the vars option.
 void setWithVariables(AllegroGraph ag, java.lang.Object[] withVariables)
          Set the with-variables option for the SPARQL query.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SPARQLQuery

public SPARQLQuery()
Create a new empty SPARQL query with default arguments.

Method Detail

getQuery

public java.lang.String getQuery()
Get the query string.

Returns:
the query string or null if the instance is not initialized/

setQuery

public void setQuery(java.lang.String newQuery)
Set the query string. Setting the query string clears out any previous results.

Parameters:
newQuery - a string containing a complete well-formed SPARQL query.

getBooleanResult

public boolean getBooleanResult()
Query the result of a query that has a boolean result.

Returns:
the boolean result.
Throws:
java.lang.IllegalStateException - if a boolean result is not available.

getResultCount

public long getResultCount()
Query the count value of a query that returns a numeric result.

Returns:
the number of results returned by a count() call.
Throws:
java.lang.IllegalStateException - if the count is not available.

getResultNames

public java.lang.String[] getResultNames()
Query the names and order of the variables in a SELECT query result.

Returns:
An array of strings.
Throws:
java.lang.IllegalStateException - if the names are not available.

isIncludeInferred

public boolean isIncludeInferred()
Query the includeInferred option.

Returns:
the includeInferred

setIncludeInferred

public void setIncludeInferred(boolean includeInferred)
Modify the includeInferred option.

Parameters:
includeInferred - the desired value.

getHasValue

public java.lang.Boolean getHasValue()
Query the hasValue option. When true, hasValue reasoning is enabled.

Returns:
true or false, null if unspecified (ie server default is false)

setHasValue

public void setHasValue(boolean v)
Enable or disable hasValue reasoning. This option is in effect only if reasoning is enabled.

Parameters:
v - true or false

getLimit

public long getLimit()
Query the limit option. The limit option overrides a LIMIT clause in the query. A value less than 1 specifies that the LIMIT clause in the query applies.

Returns:
the limit

setLimit

public void setLimit(int limit)
Set the limit option. The limit option overrides a LIMIT clause in the query.

Parameters:
limit - the limit to set. A value less than 1 specifies that the LIMIT clause in the query applies.

getOffset

public long getOffset()
Query the offset option. The offset option overrides an OFFSET clause in the query. A value less than 1 specifies that the LIMIT clause in the query applies.

Returns:
the offset.

setOffset

public void setOffset(int offset)
Set the offset option. The offset option overrides an OFFSET clause in the query.

Parameters:
offset - the offset to set. A value less than 1 specifies that the LIMIT clause in the query applies.

getRDFFormat

public java.lang.String getRDFFormat()
Query the RDFFormat option. This option applies to queries that return an RDF XML serialization string.

Returns:
the RDFFormat

setRDFFormat

public void setRDFFormat(java.lang.String format)
Set the RDFFormat option. This option applies to queries that return an RDF XML serialization string.

Parameters:
format - the RDFFormat to set

getResultsFormat

public java.lang.String getResultsFormat()
Query the resultsFormat option. This option applies to queries that return a value set.

Returns:
the resultsFormat

setResultsFormat

public void setResultsFormat(java.lang.String resultsFormat)
Set the resultsFormat option. This option applies to queries that return a value set.

Parameters:
resultsFormat - the resultsFormat to set

getVars

public java.lang.String getVars()
Query the vars option. This option determines the content of the results array.

Returns:
the vars. A null value specifies the default result set which consists of the variables listed in the query, in the order listed in the query.

setVars

public void setVars(java.lang.String vars)
Set the vars option. This option determines the content of the results array.

Parameters:
vars - null or a string containing variable names separated by spaces

getExtended

public java.lang.Boolean getExtended()
Query the extended option. When true, extended SPARQL verbs are available. See the description of *use-extended-sparql-verbs-p* in the server documentation for more details.

Returns:
true or false, null if unspecified (ie server default)

setExtended

public void setExtended(boolean extended)
Set the extended option. When true, extended SPARQL verbs are available.

Parameters:
extended - the extended to set

getMemoized

public java.lang.Boolean getMemoized()
Query the memoize option. When true, query results are memoized for potential time savings. See the description of *build-filter-memoizes-p* in the server documentation for more details.

Returns:
true or false, null if unspecified (ie server default)

setMemoized

public void setMemoized(boolean memoized)
Set the memoize option. When true, query results are memoized for potential time savings.

Parameters:
memoized - the memoized to set

setMemoTable

public void setMemoTable(java.lang.String name)
Set the name of a memo table. The scope of the name is one AllegroGraphConnection instance.

Parameters:
name -

getMemoTable

public java.lang.String getMemoTable()
Query the name of the memo table.

Returns:
the name of the memo table, or null if none is set.

setLoadFunction

public void setLoadFunction(java.lang.String name)
Set the name of a load-function option.

Parameters:
name -

getLoadFunction

public java.lang.String getLoadFunction()
Query the name of the load-function.

Returns:
the name of the load-function, or null if none is set.

setDefaultPrefixes

public void setDefaultPrefixes(java.lang.String[] prefixes)
Set the default-prefixes option.

Parameters:
prefixes - an array of alternating prefix and URI strings.

setDefaultPrefixes

public void setDefaultPrefixes(NamespaceRegistry prefixes)
Set the default-prefixes option.

Parameters:
prefixes - a NamespaceRegistry instance that defines the desired prefixes.

getDefaultPrefixes

public java.lang.String[] getDefaultPrefixes()
Query the default-prefixes option. A user supplied value overrides a PREFIX clause in the query string. See the description of default-prefixes in the server documentation for more details.

Returns:
an array of strings. The content of the array is a list of alternating prefix and URI values.

setDefaultBase

public void setDefaultBase(java.lang.String base)
Set the default-base option for this SPARQL query.

Parameters:
base - a string containing the default base URI.

getDefaultBase

public java.lang.String getDefaultBase()
Query the default base value of the query. A user supplied value overrides a BASE clause in the query string. See the description of default-base in the server documentation for more details.

Returns:
null if the sever default applies, or the string value set by the user.

setFromNamed

public void setFromNamed(java.lang.String[] uriLabels)
Set the from-named option,

Parameters:
uriLabels - an array of URI strings

getFromNamed

public java.lang.String[] getFromNamed()
Query the from-named option.

Returns:
an array of strings containing the from-named URIs.

setFrom

public void setFrom(java.lang.String[] uriLabels)
Set the from option,

Parameters:
uriLabels - an array of URI strings

getFrom

public java.lang.String[] getFrom()
Query the from option.

Returns:
an array of strings containing the from URIs.

setDefaultDatasetBehaviorAll

public void setDefaultDatasetBehaviorAll()
Set the default-data-set-behavior option to "all".


setDefaultDatasetBehaviorDefault

public void setDefaultDatasetBehaviorDefault()
Set the default-data-set-behavior option to "default".


getDefaultDatasetBehavior

public java.lang.String getDefaultDatasetBehavior()
Query the default dataset behavior for this SPARQL query. This option controls how the query engine builds the dataset environment if FROM or FROM NAMED are not provided. See the description of *sparql-default-graph-behavior* in the server documentation for more details.

Returns:
null if the server default applies, or the string "all" or "default".

getEngine

public SPARQLQueryConstants.ENGINE getEngine()
Query the engine that was or will be used for the SPARQL query. See the description of *default-sparql-query-engine* in the server documentation for more details.

Returns:
The setting; a null value indicates that the default server behavior is in effect.

setEngine

public void setEngine(SPARQLQueryConstants.ENGINE e)
Set the engine that will be used for the SPARQL query.

Parameters:
e -

getPlanner

public SPARQLQueryConstants.PLANNER getPlanner()
Query the engine that was or will be used for the SPARQL query. A null value specifies the default engine in the server. See the description of *sparql-query-planner* in the server documentation for more details.

Returns:
the planner

setPlanner

public void setPlanner(SPARQLQueryConstants.PLANNER e)
Set the engine that will be used for the SPARQL query.

Parameters:
e -

getWithVariables

public java.lang.Object[] getWithVariables()
Query the with-variables option.

Returns:
a copy of the array that was used to set this option.

setWithVariables

public void setWithVariables(AllegroGraph ag,
                             java.lang.Object[] withVariables)
Set the with-variables option for the SPARQL query.

Parameters:
ag - the AllegroGraph instance where the variable values are resolved.
withVariables - an array of alternating variable names and values. The variable names must be strings. The variable values may be any valid triple part specifier as in addStatement.

getResultSets

public ValueSetIterator getResultSets()
Query the results of a SPARQL query that returns sets of bindings. This result is available only after a call to one of the select() methods.

Returns:
the resultSet
Throws:
java.lang.IllegalStateException - if the result is not available.

getResultCursor

public TriplesIterator getResultCursor()
Query the result of a SPARQL query that returns a collection of triples. This result is available only after a call to one of the describe() or construct() methods.

Returns:
the resultCursor

getResultString

public java.lang.String getResultString()
Query the result of a SPARQL query that returns a string result. This result is available only after a call to one of the run() methods.

Returns:
the resultString

setTripleStore

public void setTripleStore(AllegroGraph ag)
Specify the triple store against which this SPARQL query will run. Setting the store clears out any previous results.

Parameters:
ag -

getTripleStore

public AllegroGraph getTripleStore()
Query the triple store against which this SPARQL query has or will run.

Returns:
the AllegroGraoh instance or null.

select

public ValueSetIterator select()
                        throws AllegroGraphException
Run a SPARQL query that retrieves a set of variable bindings. The query must be a SPARQL SELECT query.

Returns:
an array of result sets. Each result set is an array of values.
Throws:
AllegroGraphException

select

public ValueSetIterator select(AllegroGraph ag)
                        throws AllegroGraphException
Run a SPARQL query that retrieves a set of variable bindings.

Parameters:
ag - the AllogroGraph instance against which the query will run.
Returns:
an array of result sets. Each result set is an array of values.
Throws:
AllegroGraphException

select

public ValueSetIterator select(java.lang.String query)
                        throws AllegroGraphException
Run a SPARQL query that retrieves a set of variable bindings.

Parameters:
query - the complete and well-formed SPARQL SELECT query string.
Returns:
an array of result sets. Each result set is an array of values.
Throws:
AllegroGraphException

select

public ValueSetIterator select(AllegroGraph ag,
                               java.lang.String query)
                        throws AllegroGraphException
Throws:
AllegroGraphException

count

public long count()
           throws AllegroGraphException
Run a SPARQL query that retrieves a set (or row) of variable bindings. The query must be a SPARQL SELECT query.

Returns:
the number of result sets found. The actual result sets are discarded.

The result may also be obtained subsequently by calling getResultCount().

Throws:
AllegroGraphException

count

public long count(AllegroGraph ag)
           throws AllegroGraphException
Run a SPARQL query that retrieves a set (or row) of variable bindings.

Parameters:
ag - the AllegroGraph instance where the query will run. This instance is remembered as if set with setTripleStore(AllegroGraph).
Returns:
the number of result sets found.

Throws:
AllegroGraphException
See Also:
count().

count

public long count(AllegroGraph ag,
                  java.lang.String query)
           throws AllegroGraphException
Run a SPARQL query that retrieves a set (or row) of variable bindings.

Parameters:
ag - the AllegroGraph instance where the query will run. This instance is remembered as if set with setTripleStore(AllegroGraph).
query - a string containing a well-formed SPARQL SELECT query. The query is remembered as if set with setQuery(String).
Returns:
the number of result sets found.

Throws:
AllegroGraphException
See Also:
count().

count

public long count(java.lang.String query)
           throws AllegroGraphException
Run a SPARQL query that retrieves a set (or row) of variable bindings.

Parameters:
query - a string containing a well-formed SPARQL SELECT query. The query is remembered as if set with setQuery(String).
Returns:
the number of result sets found.

Throws:
AllegroGraphException
See Also:
count().

ask

public boolean ask()
            throws AllegroGraphException
Run a SPARQL query that returns a boolean result. The query must be a SPARQL ASK query.

Returns:
true if the query succeeded.

The result may also be obtained subsequently by calling getBooleanResult().

Throws:
AllegroGraphException

ask

public boolean ask(AllegroGraph ag)
            throws AllegroGraphException
Run a SPARQL query that returns a boolean result.

Parameters:
ag - the AllegroGraph instance where the query will run. This instance is remembered as if set with setTripleStore(AllegroGraph).
Returns:
true if the query succeeded.
Throws:
AllegroGraphException
See Also:
ask().

ask

public boolean ask(AllegroGraph ag,
                   java.lang.String query)
            throws AllegroGraphException
Run a SPARQL query that returns a boolean result.

Parameters:
ag - the AllegroGraph instance where the query will run. This instance is remembered as if set with setTripleStore(AllegroGraph).
query - a string containing a well-formed SPARQL ASK query. The query is remembered as if set with setQuery(String).
Returns:
true if the query succeeded.
Throws:
AllegroGraphException
See Also:
ask().

ask

public boolean ask(java.lang.String query)
            throws AllegroGraphException
Run a SPARQL query that returns a boolean result.

Parameters:
query - a string containing a well-formed SPARQL ASK query. The query is remembered as if set with setQuery(String).
Returns:
true if the query succeeded.
Throws:
AllegroGraphException
See Also:
ask().

describe

public TriplesIterator describe()
                         throws AllegroGraphException
Run a SPARQL query that retrieves a set of statements. The query must be a SPARQL DESCRIBE query.

Returns:
a Cursor instance that will iterate over the resulting statements.

The result may also be obtained subsequently by calling getResultCursor().

Throws:
AllegroGraphException

describe

public TriplesIterator describe(AllegroGraph ag)
                         throws AllegroGraphException
Run a SPARQL query that retrieves a set of statements.

Parameters:
ag - the AllegroGraph instance where the query will run. This instance is remembered as if set with setTripleStore(AllegroGraph).
Returns:
a Cursor instance that will iterate over the resulting statements.

Throws:
AllegroGraphException
See Also:
describe().

describe

public TriplesIterator describe(AllegroGraph ag,
                                java.lang.String query)
                         throws AllegroGraphException
Run a SPARQL query that retrieves a set of statements.

Parameters:
ag - the AllegroGraph instance where the query will run. This instance is remembered as if set with setTripleStore(AllegroGraph).
query - a string containing a well-formed SPARQL DESCRIBE query. The query is remembered as if set with setQuery(String).
Returns:
a Cursor instance that will iterate over the resulting statements.

Throws:
AllegroGraphException
See Also:
describe().

describe

public TriplesIterator describe(java.lang.String query)
                         throws AllegroGraphException
Run a SPARQL query that retrieves a set of statements.

Parameters:
query - a string containing a well-formed SPARQL DESCRIBE query. The query is remembered as if set with setQuery(String).
Returns:
a Cursor instance that will iterate over the resulting statements.

Throws:
AllegroGraphException
See Also:
describe().

construct

public TriplesIterator construct()
                          throws AllegroGraphException
Run a SPARQL query that retrieves a set of statements. The query must be a SPARQL CONSTRUCT query.

Returns:
a Cursor instance that will iterate over the resulting statements.

The result may also be obtained subsequently by calling getResultCursor().

Throws:
AllegroGraphException

construct

public TriplesIterator construct(AllegroGraph ag)
                          throws AllegroGraphException
Run a SPARQL query that retrieves a set of statements.

Parameters:
ag - the AllegroGraph instance where the query will run. This instance is remembered as if set with setTripleStore(AllegroGraph).
Returns:
a Cursor instance that will iterate over the resulting statements.

Throws:
AllegroGraphException
See Also:
construct().

construct

public TriplesIterator construct(AllegroGraph ag,
                                 java.lang.String query)
                          throws AllegroGraphException
Run a SPARQL query that retrieves a set of statements.

Parameters:
ag - the AllegroGraph instance where the query will run. This instance is remembered as if set with setTripleStore(AllegroGraph).
query - a string containing a well-formed SPARQL CONSTRUCT query. The query is remembered as if set with setQuery(String).
Returns:
a Cursor instance that will iterate over the resulting statements.

Throws:
AllegroGraphException
See Also:
construct().

construct

public TriplesIterator construct(java.lang.String query)
                          throws AllegroGraphException
Run a SPARQL query that retrieves a set of statements.

Parameters:
query - a string containing a well-formed SPARQL CONSTRUCT query. The query is remembered as if set with setQuery(String).
Returns:
a Cursor instance that will iterate over the resulting statements.

Throws:
AllegroGraphException
See Also:
construct().

run

public java.lang.String run()
                     throws AllegroGraphException
Run a SPARQL query that returns a serialized string result.

Returns:
the string containing the serialized result.
Throws:
AllegroGraphException - if a problem was encountered during the search.
java.lang.IllegalArgumentException - if this instance is not properly initialized.

run

public java.lang.String run(AllegroGraph ag)
                     throws AllegroGraphException
Throws:
AllegroGraphException

run

public java.lang.String run(AllegroGraph ag,
                            java.lang.String query)
                     throws AllegroGraphException
Throws:
AllegroGraphException

run

public java.lang.String run(java.lang.String query)
                     throws AllegroGraphException
Throws:
AllegroGraphException