com.franz.agbase
Class TriplesQuery

java.lang.Object
  com.franz.agbase.TriplesQuery

public class TriplesQuery
extends java.lang.Object

This class collects the parameters and results of a query that retrieves triples by patterns of triple parts.

A triple is located by a pattern of four components, the subject, predicate, object, and graph. Each of these may be specified as a string in NTriples notation, a Value instance, a UPI instance. A null value is a wild card that matches anything. The graph position can also be the empty string to denote the null context or default graph of the triple store.

The initial value of the subject predicate and object positions is null. The initial value of the graph position is the empty string.

Each of the triple components can also match a range of values if the corresponding end parameter is set. In order to specify a range, the start and end must be specified as an EncodedLiteral instance or a UPI instance that denotes an encoded UPI. The strings "min" and "max" can also be used to denote the minimum and maximum values of the corresponding UPI type.

The search can be managed in more detail by setting various attributes that control what triples are examined and what triples are returned.

An instance can be used many times to repeat the same query with identical or different parameters. The result fields are reset every time a parameter is modified.

Constructor Summary

TriplesQuery()
Create a new empty query with default arguments.

Method Summary

boolean	ask() Determine if a triple matching a pattern exists..
boolean	ask(AllegroGraph ag)
long	count() Count the number of triples located by a pattern of parts.
long	count(AllegroGraph ag) Count the number of triples located by a pattern of parts.
long	estimate(boolean roughly) Estimate the number of triples located by a pattern of parts using only the information in indices.
long	estimate(boolean roughly, AllegroGraph ag)
Triple	find() Find one triple that matches a pattern.
Triple	find(AllegroGraph ag)
boolean	getBooleanResult() Query the result of a query that had a boolean result.
java.lang.Object	getContext()
java.lang.Object	getContextEnd()
int	getHasValue() Query the hasValue option.
int	getIncludeDeleted() Query the includeDeleted option.
int	getIndexedOnly() Query the indexedOnly option.
java.lang.String	getLoadFunction() Query the name of the filter function.
int	getLookAhead() Query the lookahead parameter for the query.
java.lang.Object	getObject()
java.lang.Object	getObjectEnd()
int	getOmitEncoded() Query the omitEncoded option.
int	getOmitNonEncoded() Query the omitEncoded option.
java.lang.Object	getPredicate()
java.lang.Object	getPredicateEnd()
long	getResultCount() Query the count value of a query that returns a numeric result.
TriplesIterator	getResultCursor() Query the result of a triples query that returns a collection of triples.
java.lang.Object	getSubject()
java.lang.Object	getSubjectEnd()
AGInternals	getTripleStore() Query the triple store agaist which this query has or will run.
boolean	isIncludeInferred() Query the includeInferred option.
TriplesIterator	run() Find all the triples that match the pattern.
TriplesIterator	run(AllegroGraph ag)
void	setContext(java.lang.Object context) Set the context component of the query.
void	setContextEnd(java.lang.Object contextEnd)
void	setFilterFunction(java.lang.String name) Set the name of a filter function option.
void	setHasValue(boolean v) Enable or disable hasValue reasoning.
void	setIncludeDeleted(boolean v) Set the includeDeleted option.
void	setIncludeInferred(boolean includeInferred) Modify the includeInferred option.
void	setIndexedOnly(boolean v) Set the indexedOnly option.
void	setLookAhead(int lh) Set the initial lookahead parameter for this query.
void	setObject(java.lang.Object object)
void	setObjectEnd(java.lang.Object objectEnd)
void	setOmitEncoded(boolean v) Set the omitEncoded option.
void	setOmitNonEncoded(boolean v) Set the omitNonEncoded option.
void	setPredicate(java.lang.Object predicate)
void	setPredicateEnd(java.lang.Object predicateEnd)
void	setSubject(java.lang.Object subject)
void	setSubjectEnd(java.lang.Object subjectEnd)
void	setTripleStore(AllegroGraph ag) Specify the triple store against which this query will run.

Methods inherited from class java.lang.Object

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

Constructor Detail

TriplesQuery

public TriplesQuery()

Create a new empty query with default arguments.

Method Detail

getContext

public java.lang.Object getContext()

Returns:

the context component of the query.

setContext

public void setContext(java.lang.Object context)
                throws AllegroGraphException

Set the context component of the query.

Parameters:

context - the context to set. A null value is a wild card that matches anything. The empty string denote the default context, or null graph.

Throws:

AllegroGraphException

getContextEnd

public java.lang.Object getContextEnd()

Returns:

the contextEnd component of the query.

setContextEnd

public void setContextEnd(java.lang.Object contextEnd)
                   throws AllegroGraphException

Parameters:

contextEnd - the contextEnd to set

Throws:

AllegroGraphException

getObject

public java.lang.Object getObject()

Returns:

the object component of the query.

setObject

public void setObject(java.lang.Object object)

Parameters:

object - the object to set

getObjectEnd

public java.lang.Object getObjectEnd()

Returns:

the objectEnd component of the query.

setObjectEnd

public void setObjectEnd(java.lang.Object objectEnd)

Parameters:

objectEnd - the objectEnd to set

getPredicate

public java.lang.Object getPredicate()

Returns:

the predicate component of the query.

setPredicate

public void setPredicate(java.lang.Object predicate)

Parameters:

predicate - the predicate to set

getPredicateEnd

public java.lang.Object getPredicateEnd()

Returns:

the predicateEnd component of the query.

setPredicateEnd

public void setPredicateEnd(java.lang.Object predicateEnd)

Parameters:

predicateEnd - the predicateEnd to set

getSubject

public java.lang.Object getSubject()

Returns:

the subject component of the query.

setSubject

public void setSubject(java.lang.Object subject)

Parameters:

subject - the subject to set

getSubjectEnd

public java.lang.Object getSubjectEnd()

Returns:

the subjectEnd component of the query.

setSubjectEnd

public void setSubjectEnd(java.lang.Object subjectEnd)

Parameters:

subjectEnd - the subjectEnd to set

getBooleanResult

public boolean getBooleanResult()

Query the result of a query that had 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.

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.

getIncludeDeleted

public int getIncludeDeleted()

Query the includeDeleted option. When true, deleted triples are included in the result.

Returns:

1 if true, 0 if false, -1 if unspecified (ie server default)

setIncludeDeleted

public void setIncludeDeleted(boolean v)

Set the includeDeleted option. When true, deleted triples are included in the result.

Parameters:

v - true or false

setOmitEncoded

public void setOmitEncoded(boolean v)

Set the omitEncoded option. When true, encoded triples are not included in the search result.

Parameters:

v - true or false

getOmitEncoded

public int getOmitEncoded()

Query the omitEncoded option. When true, encoded triples are not included in the search result.

Returns:

1 if true, 0 if false, -1 if unspecified (ie server default)

getHasValue

public int getHasValue()

Query the hasValue option. When true, hasValue reasoning is enabled.

Returns:

1 if true, 0 if false, -1 if unspecified (ie server default)

setHasValue

public void setHasValue(boolean v)

Enable or disable hasValue reasoning. This option is in effect only if reasoning is ebabled.

Parameters:

v - true or false

setLookAhead

public void setLookAhead(int lh)

Set the initial lookahead parameter for this query. The lookahead parameter specifies how many results are cached in the client. A large value allows quick access to results but may incur a delay when the results are transmitted immediately after the query. A small value implies more round-trips to the server.

A zero value specifies that all the search results remain on the server. This option creates a TriplesIterator that can be passed to a serializer in the server.

A negative value reverts the setting to the default specified in the AllegroGraph class.

Parameters:

lh - the desired lookahead value. The initial setting is 1000.

getLookAhead

public int getLookAhead()

Query the lookahead parameter for the query.

Returns:

The lookahead parameter specifies how many results are cached in the client. A large value allows quick access to results but may incur a delay when the results are transmitted immediately after the query. A small value implies more round-trips to the server.

A zero value specifies that all the search results remain on the server. This option creates a Cursor that can be passed to a serializer in the server.

A negative value means that the current system default will be used.

setOmitNonEncoded

public void setOmitNonEncoded(boolean v)

Set the omitNonEncoded option. When true, non-encoded triples are not included in the search result.

Parameters:

v - true or false

getOmitNonEncoded

public int getOmitNonEncoded()

Query the omitEncoded option. When true, encoded triples are not included in the search result.

Returns:

1 if true, 0 if false, -1 if unspecified (ie server default)

setIndexedOnly

public void setIndexedOnly(boolean v)

Set the indexedOnly option. When true, only indexed triples are included in the search result.

Parameters:

v - true or false

getIndexedOnly

public int getIndexedOnly()

Query the indexedOnly option. When true, only indexed triples are included included in the search result.

Returns:

1 if true, 0 if false, -1 if unspecified (ie server default)

setFilterFunction

public void setFilterFunction(java.lang.String name)

Set the name of a filter function option.

Parameters:

name -

getLoadFunction

public java.lang.String getLoadFunction()

Query the name of the filter function.

Returns:

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

getResultCursor

public TriplesIterator getResultCursor()

Query the result of a triples 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

setTripleStore

public void setTripleStore(AllegroGraph ag)

Specify the triple store against which this query will run. Setting the store clears out any previous results.

Parameters:

ag -

getTripleStore

public AGInternals getTripleStore()

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

Returns:

the AllegroGraoh instance or null.

count

public long count()
           throws AllegroGraphException

Count the number of triples located by a pattern of parts.

Returns:

the number of results found. The actual results are discarded.

Throws:

AllegroGraphException

count

public long count(AllegroGraph ag)
           throws AllegroGraphException

Count the number of triples located by a pattern of parts.

Parameters:

ag - The triple store where the query should run.

Returns:

the number of results found. The actual results are discarded.

Throws:

AllegroGraphException

estimate

public long estimate(boolean roughly)
              throws AllegroGraphException

Estimate the number of triples located by a pattern of parts using only the information in indices. Unindexed triples are not included in the estimate.

Parameters:

roughly - When true, the estimate can be off by as much as twice the triple store's metaindex-skip-size for each index chunk involved. When false, return a more accurate (but slower) estimate.

Returns:

the number of results estimated. The actual results are never located.

Throws:

AllegroGraphException

estimate

public long estimate(boolean roughly,
                     AllegroGraph ag)
              throws AllegroGraphException

Throws:

AllegroGraphException

ask

public boolean ask()
            throws AllegroGraphException

Determine if a triple matching a pattern exists..

Returns:

true if a triple exists. The triple is not returned.

Throws:

AllegroGraphException

ask

public boolean ask(AllegroGraph ag)
            throws AllegroGraphException

Throws:

AllegroGraphException

find

public Triple find()
            throws AllegroGraphException

Find one triple that matches a pattern. Any additional triples are ignored.

Returns:

the Triple instance or null.

Throws:

AllegroGraphException

find

public Triple find(AllegroGraph ag)
            throws AllegroGraphException

Throws:

AllegroGraphException

run

public TriplesIterator run()
                    throws AllegroGraphException

Find all the triples that match the pattern.

Returns:

A Cursor instance that can iterate over the results.

Throws:

AllegroGraphException - if a problem was encountered during the search.

java.lang.IllegalArgumentException - if this instance is not properly initialized.

run

public TriplesIterator run(AllegroGraph ag)
                    throws AllegroGraphException

Throws:

AllegroGraphException