com.franz.ag
Class SPARQLQuery

java.lang.Object
  com.franz.ag.SPARQLQuery

public class SPARQLQuery
extends java.lang.Object

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.

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.
Cursor	construct() Run a SPARQL query that retrieves a set of statements.
Cursor	construct(AllegroGraph ag) Run a SPARQL query that retrieves a set of statements.
Cursor	construct(AllegroGraph ag, java.lang.String query) Run a SPARQL query that retrieves a set of statements.
Cursor	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.
Cursor	describe() Run a SPARQL query that retrieves a set of statements.
Cursor	describe(AllegroGraph ag) Run a SPARQL query that retrieves a set of statements.
Cursor	describe(AllegroGraph ag, java.lang.String query) Run a SPARQL query that retrieves a set of statements.
Cursor	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.
int	getExtended() Query the extended option.
java.lang.String[]	getFrom() Query the from option.
java.lang.String[]	getFromNamed() Query the from-named option.
long	getLimit() Query the limit option.
java.lang.String	getLoadFunction() Query the name of the load-function.
int	getMemoized() Query the memoize option.
java.lang.String	getMemoTable() Query the name of the memo table.
long	getOffset() Query the offset option.
java.lang.String	getQuery() Get the query string.
java.lang.String	getRDFFormat() Query the RDFFormat option.
ValueObject[]	getResultArray() Query the results of a SPARQL query that returns a one-dimensional array of results.
ValueObject[][]	getResultArrays() Query the results of a SPARQL query that returns an array of result arrays.
long	getResultCount() Query the count value of a query that returns a numeric result.
Cursor	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.
java.lang.String	getResultsFormat() Query the resultsFormat option.
java.lang.String	getResultString() Query the result of a SPARQL query that returns a string result.
AGInternals	getTripleStore() Query the triple store agaist 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)
ValueObject[][]	select() Run a SPARQL query that retrieves a set of variable bindings.
ValueObject[][]	select(AllegroGraph ag) Run a SPARQL query that retrieves a set of variable bindings.
ValueObject[][]	select(AllegroGraph ag, java.lang.String query)
ValueObject[][]	select(java.lang.String query) Run a SPARQL query that retrieves a set of variable bindings.
ValueObject[]	selectSingle() Run a SPARQL query that retrieves all the bindings of a single variable.
ValueObject[]	selectSingle(AllegroGraph ag)
ValueObject[]	selectSingle(AllegroGraph ag, java.lang.String query)
ValueObject[]	selectSingle(java.lang.String query)
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(java.lang.String[] prefixes) Set the default-prefixes option.
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	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	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 agaist which this SPARQL query will run.
void	setVars(java.lang.String vars) Set the vars option.
void	setWithVariables(AGInternals 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.

getLimit

public long getLimit()

Query the limit option. The limit option overrides a LIMIT clause in the query.

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 zero or negative value is ignored.

getOffset

public long getOffset()

Query the offset option. The offset option overrides an OFFSET clause in the query.

Returns:

the offset. A zero or negative value is ignored.

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 zero or negative value is ignored.

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 int getExtended()

Query the extended option. When true, extended SPARQL verbs are available.

Returns:

1 if true, 0 if false, -1 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 int getMemoized()

Query the memoize option. When true, query results are memoized for potential time savings.

Returns:

1 if true, 0 if false, -1 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.

getDefaultPrefixes

public java.lang.String[] getDefaultPrefixes()

Query the default-prefixes option.

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.

Returns:

null if the sever default applies, or the steing 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.

Returns:

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

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(AGInternals 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.

getResultArray

public ValueObject[] getResultArray()

Query the results of a SPARQL query that returns a one-dimensional array of results. This result is available only after a call to one of the selectSingle() methods.

Returns:

the resultArray

Throws:

java.lang.IllegalStateException - if the array is not available.

getResultArrays

public ValueObject[][] getResultArrays()

Query the results of a SPARQL query that returns an array of result arrays. This result is available only after a call to one of the select() methods.

Returns:

the resultArrays

getResultCursor

public Cursor 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 agaist which this SPARQL query will run. Setting the store clears out any previous results.

Parameters:

ag -

getTripleStore

public AGInternals getTripleStore()

Query the triple store agaist which this SPARQL query has or will run.

Returns:

the AllegroGraoh instance or null.

select

public ValueObject[][] 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 ValueObject[][] 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 ValueObject[][] select(java.lang.String query)
                       throws AllegroGraphException

Run a SPARQL query that retrieves a set of variable bindings.

Parameters:

query - the omplet 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 ValueObject[][] select(AllegroGraph ag,
                              java.lang.String query)
                       throws AllegroGraphException

Throws:

AllegroGraphException

selectSingle

public ValueObject[] selectSingle()
                           throws AllegroGraphException

Run a SPARQL query that retrieves all the bindings of a single variable. The query must be a SPARQL SELECT query that returns a single value in each result set.

Returns:

an array of results.

Throws:

AllegroGraphException

selectSingle

public ValueObject[] selectSingle(AllegroGraph ag,
                                  java.lang.String query)
                           throws AllegroGraphException

Throws:

AllegroGraphException

selectSingle

public ValueObject[] selectSingle(java.lang.String query)
                           throws AllegroGraphException

Throws:

AllegroGraphException

selectSingle

public ValueObject[] selectSingle(AllegroGraph ag)
                           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 Cursor 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 Cursor 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 Cursor 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 Cursor 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 Cursor 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 Cursor 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 Cursor 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 Cursor 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