com.franz.agbase
Class SPARQLQuery

java.lang.Object
  SPARQLQueryInternals
      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

• Create an instance.
• Set or modify some of the optional parameters.
• Call one of the action methods
  • ask()
  • construct()
  • count()
  • describe()
  • run()
  • select()
• Use the value returned by the action method, or extract the result from the instance.

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