com.bigdata.btree

Interface ITupleCursor<E>

Type Parameters:

E - The generic type for the de-serialized objects stored as the value under the key in the index.

All Superinterfaces:

Iterator<ITuple<E>>, ITupleIterator<E>

All Known Subinterfaces:

ITupleCursor2<E>

All Known Implementing Classes:

AbstractBTreeTupleCursor, AbstractBTreeTupleCursor.MutableBTreeTupleCursor, AbstractBTreeTupleCursor.ReadOnlyBTreeTupleCursor, FusedTupleCursor, IndexSegment.IndexSegmentTupleCursor, Reverserator

public interface ITupleCursor<E>
extends ITupleIterator<E>

Interface for sequential and random-access cursor-based ITuple operations on an index or index partition. The interface extends the standard Iterator for forward sequential scans and also provides symmetric methods for reverse sequential scans using hasPrior() and prior(). Random access is supported using seek(byte[]). This interface is intentionally kept small and does not include methods such as first() or last() whose semantics would be misleading when applied to an index partition vs a partitioned index.

Note: Normally ITupleCursors are provisioned such that deleted tuples are not visited (they are skipped over if delete markers are used by the index). This corresponds to the most common application requirement. However, cursors MAY be provisioned using IRangeQuery.DELETED to visit deleted tuples for indices that maintain delete markers.

Version:

$Id$

Author:

Bryan Thompson

Method Summary

Methods

Modifier and Type	Method and Description
IIndex	getIndex() The backing index being traversed by the ITupleCursor.
boolean	hasNext() Return true if there is another tuple that orders after the current cursor position in the natural order of the index and that lies within the optional constraints key-range on the cursor or on the index partition.
boolean	hasPrior() Return true if there is another tuple that orders before the current cursor position in the natural order of the index and that lies within the optional key-range constraints on the cursor or on the index partition.
ITuple<E>	next() Position the cursor on the next tuple in the natural key order of the index.
ITuple<E>	prior() Position the cursor on the first visitable tuple ordered less than the current cursor position in the natural key order of the index and return that tuple.
void	remove() Removes the tuple (if any) from the index corresponding to the current cursor position.
ITuple<E>	seek(byte[] key) Positions the cursor on the specified key.
ITuple<E>	seek(Object key) Variant that first encodes the key using the object returned by IndexMetadata.getTupleSerializer() for the backing index.

Method Detail

getIndex

IIndex getIndex()

The backing index being traversed by the ITupleCursor.

seek

ITuple<E> seek(byte[] key)

Positions the cursor on the specified key.

If there is a corresponding visitable tuple in the index then it is returned.

If there is no visitable tuple in the index for that key then null is returned. You can use prior() or next() to locate the first visitable tuple to either side of the cursor position.

The cursor position is updated to the specified key regardless of whether there is a visitable tuple in the index for that key.

Parameters:

key - The key (required).

Returns:

The tuple corresponding to key if it exists and is visitable in the index and null otherwise.

Throws:

IllegalArgumentException - if the key is null.

KeyOutOfRangeException - if the key lies outside of the optional constrain on the ITupleCursor.

KeyOutOfRangeException - if the key lies outside of the key-range constraint on an index partition.

seek

ITuple<E> seek(Object key)

Variant that first encodes the key using the object returned by IndexMetadata.getTupleSerializer() for the backing index.

Parameters:

key - The key (required).

Returns:

The tuple corresponding to the encoded key if it exists and is visitable in the index and null otherwise.

Throws:

IllegalArgumentException - if the encoded key lies outside of the optional key-range constraint on the cursor or on the index partition.

hasNext

boolean hasNext()

Return true if there is another tuple that orders after the current cursor position in the natural order of the index and that lies within the optional constraints key-range on the cursor or on the index partition.

Note: in order to maintain standard iterator semantics, this method will return true if the current cursor position is undefined and #first() would report the existence of a visitable tuple.

Specified by:

hasNext in interface Iterator<ITuple<E>>

next

ITuple<E> next()

Position the cursor on the next tuple in the natural key order of the index.

Note: in order to maintain standard iterator semantics, this method will visit the #first() visitable tuple if the current cursor position is undefined.

Specified by:

next in interface Iterator<ITuple<E>>

Specified by:

next in interface ITupleIterator<E>

Returns:

The ITuple containing the data and metadata for the current index entry.

Throws:

NoSuchElementException - if hasNext() would return false.

hasPrior

boolean hasPrior()

Return true if there is another tuple that orders before the current cursor position in the natural order of the index and that lies within the optional key-range constraints on the cursor or on the index partition.

Note: in order to maintain semantics parallel to standard iterator semantics, this method will return true if the current cursor position is undefined and #last() would report the existence of a visitable tuple.

prior

ITuple<E> prior()

Position the cursor on the first visitable tuple ordered less than the current cursor position in the natural key order of the index and return that tuple.

Note: in order to maintain semantics parallel to standard iterator semantics, this method will visit the #last() visitable tuple if the current cursor position is undefined.

Throws:

NoSuchElementException - if hasPrior() would return false.

remove

void remove()

Removes the tuple (if any) from the index corresponding to the current cursor position. The cursor position is NOT changed by this method. After removing the current tuple, ITupleCursor2.tuple() will return null to indicate that there is no tuple in the index corresponding to the deleted tuple. (When delete markers are enabled and deleted tuples are being visited, then ITupleCursor2.tuple() will return the new state of the tuple with its delete marker set.)

Specified by:

remove in interface Iterator<ITuple<E>>

Throws:

IllegalStateException - if the cursor position is not defined.