com.franz.ag
Interface Cursor

All Superinterfaces:

StatementIterator

public interface Cursor
extends StatementIterator

This interface defines an iterator for multiple Triple instances.

Many triple store search operations may generate an indeterminate number of results. These operations return a Cursor instance which may be used to iterate through the available results.

Instances are created by search operations.

Method Summary

boolean	atTriple() Query the state of a Cursor instance.
void	close() Discard the remote reference to the AllegroGraph cursor instance.
long	get_id() Retrieve the id number of the current triple in the Cursor instance.
UPI	getC() Retrieve the context node UPI of the current triple in the Cursor instance.
ValueNode	getContext() Retrieve the Value instance that identifies the context of the current triple in the Cursor.
java.lang.String	getContextLabel() Retrieve the string label of the context of the current triple in the Cursor instance.
int	getLookAhead() Query the look-ahead value for this cursor instance.
Triple	getNext() Advance the Cursor and return a Triple instance.
UPI	getO() Retrieve the object node UPI of the current triple in the Cursor instance.
ValueNode	getObject() Retrieve the Value instance that identifies the object of the current triple in the Cursor.
java.lang.String	getObjectLabel() Retrieve the literal string for the object of the current triple in the Cursor instance.
UPI	getP() Retrieve the predicate node UPI of the current triple in the Cursor instance.
ValueNode	getPredicate() Retrieve the Value instance that identifies the predicate of the current triple in the Cursor.
java.lang.String	getPredicateLabel() Retrieve the literal string for the predicate of the current triple in the Cursor instance.
UPI	getS() Retrieve the subject node UPI of the current triple in the Cursor instance.
ValueNode	getSubject() Retrieve the Value instance that identifies the subject of the current triple in the Cursor.
java.lang.String	getSubjectLabel() Retrieve the literal string for the subject of the current triple in the Cursor instance.
Triple	getTriple() Create a Triple instance from the current triple in the Cursor.
boolean	hasNext() Query the state of a Cursor instance.
boolean	limitReached() Query the state of a Cursor instance.
Statement	next() Advance the Cursor and return a Triple instance.
java.lang.String	queryContext() Retrieve the string label for the context of the current triple in the Cursor instance.
java.lang.String	queryObject() Retrieve the string label for the object of the current triple in the Cursor instance.
java.lang.String	queryPredicate() Retrieve the string label for the predicate of the current triple in the Cursor instance.
java.lang.String	querySubject() Retrieve the string label for the subject of the current triple in the Cursor instance.
TripleImpl	queryTriple() Create a Triple instance from the current triple in the Cursor.
void	remove() Discard the current triple in the Cursor.
void	setLookAhead(int lh) Set the look-ahead value for this cursor instance.
boolean	step() Advance the Cursor instance to the next triple.
Triple[]	step(int n) This method returns an array of Triple instances.
java.lang.String	toString() Override the default method to give a more informatve representation.

Method Detail

getLookAhead

int getLookAhead()

Query the look-ahead value for this cursor instance.

Returns:

an integer

See Also:

setLookAhead(int)

setLookAhead

void setLookAhead(int lh)

Set the look-ahead value for this cursor instance. The look-ahead value determines how many results are cached in the cursor instance. The cached values may be retrieved without a round-trip to the AllegroGraph server.

A large value optimizes access in the Java application but may incur a large delay when the cursor is created.

Parameters:

lh - An integer. Any value less than 1 specifies the defaultLookAhead value.

get_id

long get_id()

Retrieve the id number of the current triple in the Cursor instance.

Returns:

integer id or -1 if the cursor is not positioned on a triple.

getS

UPI getS()

Retrieve the subject node UPI of the current triple in the Cursor instance.

Returns:

UPI or null if the cursor is not positioned on a triple.

querySubject

java.lang.String querySubject()

Retrieve the string label for the subject of the current triple in the Cursor instance.

Returns:

null if the Cursor is not positioned at a triple, or if the subject label is not in the Java cache.

queryObject

java.lang.String queryObject()

Retrieve the string label for the object of the current triple in the Cursor instance.

Returns:

null if the Cursor is not positioned at a triple, or if the object label is not in the Java cache.

queryPredicate

java.lang.String queryPredicate()

Retrieve the string label for the predicate of the current triple in the Cursor instance.

Returns:

null if the Cursor is not positioned at a triple, or if the predicate label is not in the Java cache.

queryContext

java.lang.String queryContext()

Retrieve the string label for the context of the current triple in the Cursor instance.

Returns:

null if the Cursor is not positioned at a triple, or if the context label is not in the Java cache.

getSubjectLabel

java.lang.String getSubjectLabel()
                                 throws AllegroGraphException

Retrieve the literal string for the subject of the current triple in the Cursor instance. Note that the label does not provide all the information describing the part of the triple. When the part is a literal with a language or datatype modifier, the modifiers are missing. A literal label may also appear to be a URL or a blank node id.

Returns:

a string, or null if the cursor is not positioned on a triple.

Throws:

AllegroGraphException - if there is a problem during the operation.

This method almost almost always requires a round-trip to the AllegroGraph server.

getSubject

ValueNode getSubject()
                     throws AllegroGraphException

Retrieve the Value instance that identifies the subject of the current triple in the Cursor.

Returns:

null if the Cursor is not positioned at a triple.

Throws:

AllegroGraphException

getContext

ValueNode getContext()
                     throws AllegroGraphException

Retrieve the Value instance that identifies the context of the current triple in the Cursor.

Returns:

null if the Cursor is not positioned at a triple.

Throws:

AllegroGraphException

getP

UPI getP()

Retrieve the predicate node UPI of the current triple in the Cursor instance.

Returns:

a UPI, or null if the cursor is not positioned on a triple.

getPredicateLabel

java.lang.String getPredicateLabel()
                                   throws AllegroGraphException

Retrieve the literal string for the predicate of the current triple in the Cursor instance. Note that the label does not provide all the information describing the part of the triple. When the part is a literal with a language or datatype modifier, the modifiers are missing. A literal label may alo appear to be a URL or a blank node id.

Returns:

a string or null if the cursor is not positioned on a triple.

Throws:

AllegroGraphException - if there is a problem during the operation.

This method almost always requires a round-trip to the AllegroGraph server.

getPredicate

ValueNode getPredicate()
                       throws AllegroGraphException

Retrieve the Value instance that identifies the predicate of the current triple in the Cursor.

Returns:

null if the Cursor is not positioned at a triple.

Throws:

AllegroGraphException

getO

UPI getO()

Retrieve the object node UPI of the current triple in the Cursor instance.

Returns:

a UPI, or null if the cursor is not positioned on a triple.

getC

UPI getC()

Retrieve the context node UPI of the current triple in the Cursor instance.

Returns:

a UPI, or null if the cursor is not positioned on a triple.

getObjectLabel

java.lang.String getObjectLabel()
                                throws AllegroGraphException

Retrieve the literal string for the object of the current triple in the Cursor instance. Note that the label does not provide all the information describing the part of the triple. When the part is a literal with a language or datatype modifier, the modifiers are missing. A literal label may alo appear to be a URL or a blank node id.

Returns:

a string or null if the cursor is not positioned on a triple.

Throws:

AllegroGraphException - if there is a problem during the operation.

This method almost always requires a round-trip to the AllegroGraph server.

getContextLabel

java.lang.String getContextLabel()
                                 throws AllegroGraphException

Retrieve the string label of the context of the current triple in the Cursor instance. Note that the label does not provide all the information describing the part of the triple. When the part is a literal with a language or datatype modifier, the modifiers are missing. A literal label may also appear to be a URI or a blank node id.

Returns:

a string or null if the cursor is not positioned on a triple.

Throws:

AllegroGraphException - if there is a problem during the operation.

This method almost always requires a round-trip to the AllegroGraph server.

getObject

ValueNode getObject()
                    throws AllegroGraphException

Retrieve the Value instance that identifies the object of the current triple in the Cursor.

Returns:

null if the Cursor is not positioned at a triple.

Throws:

AllegroGraphException

queryTriple

TripleImpl queryTriple()

Create a Triple instance from the current triple in the Cursor. Build the triple from whatever data is immediately available in the Cursor.

Returns:

A Triple instance, or null if the Cursor is not positioned at a triple.

getTriple

Triple getTriple()
                 throws AllegroGraphException

Create a Triple instance from the current triple in the Cursor. This operation may require a round-trip to the server if some of the labels are not yet in the client.

Returns:

A Triple instance, or null if the Cursor is not positioned at a triple.

Throws:

AllegroGraphException

next

Statement next()

Advance the Cursor and return a Triple instance. If the Cursor is exhausted, return null. Build the Triple from whatever parts are available immediately.

Specified by:

next in interface StatementIterator

Returns:

the next statement.

getNext

Triple getNext()

Advance the Cursor and return a Triple instance. If the Cursor is exhausted, return null. This operation may require a trip to the server to fetch any needed label strings.

atTriple

boolean atTriple()

Query the state of a Cursor instance.

Returns:

true if the Cursor is positioned on a triple.

hasNext

boolean hasNext()

Query the state of a Cursor instance.

Specified by:

hasNext in interface StatementIterator

Returns:

true if the Cursor can be advanced to a new triple.

limitReached

boolean limitReached()

Query the state of a Cursor instance.

Returns:

true if the Cursor does not have any more entries because an arbitrary limit was reached but more values were available in the triple store.

close

void close()

Discard the remote reference to the AllegroGraph cursor instance. This method releases the reference and allows the server storage to be reclaimed.

An attempt to call next() will case an exception to be thrown.

Specified by:

close in interface StatementIterator

Throws:

java.lang.IllegalStateException

step

boolean step()
             throws AllegroGraphException

Advance the Cursor instance to the next triple.

Returns:

true if a new triple was retrieved.

Throws:

AllegroGraphException

step

Triple[] step(int n)
              throws AllegroGraphException

This method returns an array of Triple instances.

Parameters:

n - A positive integer number of instances desired.

Returns:

An array of Triple instances. The length of the array may be less than or equal to n.

Throws:

AllegroGraphException

toString

java.lang.String toString()

Override the default method to give a more informatve representation.

Overrides:

toString in class java.lang.Object

Returns:

a string of the form "<Cursor id: s p o>".

remove

void remove()

Discard the current triple in the Cursor.

The program must advance the Cursor in order to access a triple again.

See Also:

Iterator.remove()