com.franz.ag
Class Cursor

java.lang.Object
  com.franz.ag.Cursor

All Implemented Interfaces:

StatementIterator

public class Cursor

extends java.lang.Object

implements StatementIterator

This class implements a generator 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.

There are no public constructors. 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.
static int	getDefaultLookAhead() Query the default look-ahead value for this 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.
Triple	queryTriple() Create a Triple instance from the current triple in the Cursor.
void	remove() Discard the current triple in the Cursor.
static void	setDefaultLookAhead(int lh) Set the default look-ahead value for this cursor instance.
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.

Methods inherited from class java.lang.Object

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

Method Detail

getDefaultLookAhead

public static int getDefaultLookAhead()

Query the default look-ahead value for this cursor instance.

Returns:

an integer

See Also:

setDefaultLookAhead(int)

setDefaultLookAhead

public static void setDefaultLookAhead(int lh)

Set the default look-ahead value for this cursor instance.

Parameters:

lh - an integer. Any value less than 1 denotes the built-in default of 1000.

See Also:

setLookAhead(int)

getLookAhead

public int getLookAhead()

Query the look-ahead value for this cursor instance.

Returns:

an integer

See Also:

setLookAhead(int)

setLookAhead

public 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.

See Also:

setDefaultLookAhead(int)

get_id

public 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

public 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

public 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

public 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

public 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

public 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

public 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 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 almost always requires a round-trip to the AllegroGraph server.

getSubject

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public 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

public Triple 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

public 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

public 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

public 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

public boolean atTriple()

Query the state of a Cursor instance.

Returns:

true if the Cursor is positioned on a triple.

hasNext

public 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

public 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

public 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

public boolean step()
             throws AllegroGraphException

Advance the Cursor instance to the next triple.

Returns:

true if a new triple was retrieved.

Throws:

AllegroGraphException

step

public 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

public java.lang.String toString()

Override the default method to give a more informatve representation.

Returns:

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

remove

public 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()