AbstractBTreeTupleCursor (Blazegraph Database Platform 2.1.5 API)

java.lang.Object
- com.bigdata.btree.AbstractBTreeTupleCursor<I,L,E>

All Implemented Interfaces:

ITupleCursor<E>, ITupleCursor2<E>, ITupleIterator<E>, Iterator<ITuple<E>>

Direct Known Subclasses:

AbstractBTreeTupleCursor.ReadOnlyBTreeTupleCursor, IndexSegment.IndexSegmentTupleCursor
```
public abstract class AbstractBTreeTupleCursor<I extends AbstractBTree,L extends Leaf,E>
extends Object
implements ITupleCursor2<E>
```
Class supporting random access to tuples and sequential tuple-based cursor movement for an AbstractBTree.
The tuple position is defined in terms of the current key on which the tuple "rests". If there is no tuple associated with that key in the index then you will not be able to read the value or optional metadata (delete markers or version timestamps) for the key. If the key is associated with a deleted tuple then you can not read the value associated with the key, but you can read the (optional) delete marker and version metadata if the cursor was provisioned to visit deleted tuples.

Author:

Bryan Thompson

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`AbstractBTreeTupleCursor.MutableBTreeTupleCursor<E>` An `ITuple` that directly supports forward and reverse cursor operations on a local mutable `BTree`.
`static class`	`AbstractBTreeTupleCursor.ReadOnlyBTreeTupleCursor<E>` An `ITuple` that directly supports forward and reverse cursor operations on a local `BTree`.

Field Summary

Fields
Modifier and Type	Field and Description
`protected I`	`btree` From the ctor.
`protected com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E>`	`currentPosition` The current cursor position (initially `null`).
`protected static boolean`	`DEBUG`
`protected byte[]`	`fromKey` from the ctor.
`protected static boolean`	`INFO`
`protected static org.apache.log4j.Logger`	`log`
`protected byte[]`	`toKey` from the ctor.
`protected Tuple<E>`	`tuple` From the ctor.
`protected boolean`	`visitDeleted` true iff the cursor was provisioned to visit deleted tuples.

Constructor Summary

Constructors
Constructor and Description
`AbstractBTreeTupleCursor(I btree, Tuple<E> tuple, byte[] fromKey, byte[] toKey)` Create a new cursor.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`assertCursorPositionDefined()` The cursor position is undefined until `#first(boolean)`, `#last(boolean)`, or `seek(byte[])` is used to position the cursor.
`byte[]`	`currentKey()` Return the key corresponding to the current cursor position (even if there is no tuple in the index for that key).
`ITuple<E>`	`first()` Position the cursor on the first visitable tuple in the natural index order for the index or index partition over which the cursor is defined.
`protected com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E>`	`firstPosition()` Return a new `ICursorPosition` that is initially positioned on the inclusive lower bound and on `new byte[]{}` if there is no inclusive lower bound.
`protected byte[]`	`getExclusiveUpperBound()` The optional exclusive upper bound.
`byte[]`	`getFromKey()` The optional inclusive lower bound imposed by the `ITupleCursor`.
`protected byte[]`	`getInclusiveLowerBound()` The optional inclusive lower bound.
`I`	`getIndex()` The backing index being traversed by the `ITupleCursor`.
`byte[]`	`getToKey()` The optional exclusive upper bound imposed 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.
`boolean`	`isCursorPositionDefined()` Return `true` if the cursor position is defined.
`boolean`	`isDeletedTupleVisitor()` Return `true` if the cursor is willing to visit deleted tuples.
`ITuple<E>`	`last()` Position the cursor on the last visitable tuple in the natural index order for the index or index partition over which the cursor is defined.
`protected com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E>`	`lastPosition()` Return a new `ICursorPosition` that is initially positioned on the last tuple in the key-range (does not skip over deleted tuples).
`protected com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E>`	`newPosition(byte[] key)` Return a new `ICursorPosition` that is initially positioned on the given key.
`protected abstract com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E>`	`newPosition(ILeafCursor<L> leafCursor, int index, byte[] key)` Return a new `ICursorPosition` from the leafCursor, tuple index, and key
`protected abstract com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E>`	`newTemporaryPosition(com.bigdata.btree.AbstractBTreeTupleCursor.ICursorPosition<L,E> p)` Deprecated. This is never used.
`ITuple<E>`	`next()` Position the cursor on the next tuple in the natural key order of the index.
`ITuple<E>`	`nextTuple()` Position the cursor on the first visitable tuple ordered greater than the current cursor position in the natural key order of the index and return that tuple.
`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.
`ITuple<E>`	`priorTuple()` 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.
`protected boolean`	`rangeCheck(byte[] key)` Return `true` if the key lies inside of the optional half-open range constraint.
`void`	`remove()` FIXME This needs to be overridden for the `IsolatedFusedView` in order to correctly propagate the version timestamp onto the tuple.
`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.
`String`	`toString()`
`ITuple<E>`	`tuple()` The tuple reflecting the data in the index at the current cursor position.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - log
```
protected static final org.apache.log4j.Logger log
```
  - INFO
```
protected static final boolean INFO
```
  - DEBUG
```
protected static final boolean DEBUG
```
  - btree
```
protected final I extends AbstractBTree btree
```
    From the ctor.
  - tuple
```
protected final Tuple<E> tuple
```
    From the ctor.
  - fromKey
```
protected final byte[] fromKey
```
    from the ctor.
  - toKey
```
protected final byte[] toKey
```
    from the ctor.
  - visitDeleted
```
protected final boolean visitDeleted
```
    true iff the cursor was provisioned to visit deleted tuples.
  - currentPosition
```
protected com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L extends Leaf,E> currentPosition
```
    The current cursor position (initially null).
- Constructor Detail
  - AbstractBTreeTupleCursor
```
public AbstractBTreeTupleCursor(I btree,
                        Tuple<E> tuple,
                        byte[] fromKey,
                        byte[] toKey)
```
    Create a new cursor.
    
    Parameters:
    btree - The B+Tree whose tuples are visited by this cursor.
    tuple - The tuple into which the data will be copied. IRangeQuery.KEYS MUST be specified for that Tuple. The keys of the index will always be copied into the Tuple, but the flags on the Tuple will determine whether the values paired to the key will be copied and whether or not deleted tuples will be visited.
    fromKey - The optional inclusive lower bound.
    toKey - The optional exclusive upper bound.
    
    Throws:
    
    IllegalArgumentException - if the btree is null.
    
    IllegalArgumentException - if the tuple is null.
    
    IllegalArgumentException - if the tuple is not associated with that btree.
    
    IllegalArgumentException - if the fromKey is GTE the toKey.
- Method Detail
  - getIndex
```
public final I getIndex()
```
    Description copied from interface: ITupleCursor
    
    The backing index being traversed by the ITupleCursor.
    
    Specified by:
    
    getIndex in interface ITupleCursor<E>
  - getFromKey
```
public final byte[] getFromKey()
```
    The optional inclusive lower bound imposed by the ITupleCursor.
    From the ctor.
    
    Specified by:
    
    getFromKey in interface ITupleCursor2<E>
  - getToKey
```
public final byte[] getToKey()
```
    The optional exclusive upper bound imposed by the ITupleCursor.
    From the ctor.
    
    Specified by:
    
    getToKey in interface ITupleCursor2<E>
  - isDeletedTupleVisitor
```
public final boolean isDeletedTupleVisitor()
```
    Description copied from interface: ITupleCursor2
    
    Return true if the cursor is willing to visit deleted tuples. In order to observe deleted tuples the index must have been provisioned with support for delete markers enabled.
    Note: When delete markers are enabled in the index and a tuple is deleted, the tuple is NOT removed from the index. Instead a "delete" marker is set and the value associated with the key is cleared to null.
    
    Specified by:
    
    isDeletedTupleVisitor in interface ITupleCursor2<E>
    
    See Also:
    IndexMetadata.getDeleteMarkers()
  - isCursorPositionDefined
```
public final boolean isCursorPositionDefined()
```
    Description copied from interface: ITupleCursor2
    
    Return true if the cursor position is defined.
    Note: Use ITupleCursor2.currentKey() to obtain the key corresponding to the current cursor position and ITupleCursor2.tuple() to obtain the visitable tuple in the index corresponding to that cursor position (if any).
    
    Specified by:
    
    isCursorPositionDefined in interface ITupleCursor2<E>
  - assertCursorPositionDefined
```
protected final void assertCursorPositionDefined()
```
    The cursor position is undefined until #first(boolean), #last(boolean), or seek(byte[]) is used to position the cursor.
    
    Throws:
    
    IllegalStateException - if the cursor position is not defined.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - rangeCheck
```
protected final boolean rangeCheck(byte[] key)
```
    Return true if the key lies inside of the optional half-open range constraint.
    
    Returns:
    true unless the key is LT [fromKey] or GTE [toKey].
  - getInclusiveLowerBound
```
protected final byte[] getInclusiveLowerBound()
```
    The optional inclusive lower bound. If the fromKey constraint was specified when the ITupleCursor was created, then that value is returned. Otherwise, if the index is an index partition then the LocalPartitionMetadata.getLeftSeparatorKey() is returned. Finally, null is returned if there is no inclusive lower bound.
  - getExclusiveUpperBound
```
protected final byte[] getExclusiveUpperBound()
```
    The optional exclusive upper bound. If the toKey constraint was specified when the ITupleCursor was created, then that value is returned. Otherwise, if the index is an index partition then the LocalPartitionMetadata.getRightSeparatorKey() is returned. Finally, null is returned if there is no exclusive upper bound.
  - newPosition
```
protected abstract com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> newPosition(ILeafCursor<L> leafCursor,
                                                                                 int index,
                                                                                 byte[] key)
```
    Return a new ICursorPosition from the leafCursor, tuple index, and key
    
    Parameters:
    leafCursor - The ILeafCursor (already positioned on the desired leaf).
    index - The index of the tuple corresponding to the key within the current leaf of the leafCursor -or- a negative integer representing the insertion point for the key if the key is spanned by that leaf but there is no tuple for that key in the leaf.
    key - The key.
    
    Returns:
    The new ICursorPosition.
    
    Throws:
    
    IllegalArgumentException - if leafCursor is null.
    
    IllegalArgumentException - if key is null.
  - newTemporaryPosition
```
protected abstract com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> newTemporaryPosition(com.bigdata.btree.AbstractBTreeTupleCursor.ICursorPosition<L,E> p)
```
    Deprecated. This is never used.
    
    Return a clone of the given ICursorPosition designed for use by hasNext() and hasPrior() (temporary test without side-effects).
    
    Parameters:
    p - The cursor position.
    
    Returns:
    A clone of that cursor position.
  - firstPosition
```
protected final com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> firstPosition()
```
    Return a new ICursorPosition that is initially positioned on the inclusive lower bound and on new byte[]{} if there is no inclusive lower bound.
  - newPosition
```
protected final com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> newPosition(byte[] key)
```
    Return a new ICursorPosition that is initially positioned on the given key.
    
    Parameters:
    leaf - A leaf (required).
    key - A key that is spanned by that leaf (required, but there is no requirement that a tuple corresponding to that key is present in the leaf).
    
    Returns:
    The new ICursorPosition.
    
    Throws:
    
    IllegalArgumentException - if the key is null.
    
    KeyOutOfRangeException - if the key lies outside of the optional constrain on the ITupleCursor.
  - lastPosition
```
protected final com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> lastPosition()
```
    Return a new ICursorPosition that is initially positioned on the last tuple in the key-range (does not skip over deleted tuples).
    Note: If there is no exclusive upper bound and there are no tuples in the index then the position is set to new byte[]{} (the same behavior as first for an empty index).
    
    Returns:
    The leaf spanning getExclusiveUpperBound().
  - currentKey
```
public byte[] currentKey()
```
    Description copied from interface: ITupleCursor2
    
    Return the key corresponding to the current cursor position (even if there is no tuple in the index for that key).
    
    Specified by:
    
    currentKey in interface ITupleCursor2<E>
    
    Returns:
    The key corresponding to the current current position -or- null iff the cursor position is undefined.
  - tuple
```
public ITuple<E> tuple()
```
    Description copied from interface: ITupleCursor2
    
    The tuple reflecting the data in the index at the current cursor position.
    
    Specified by:
    
    tuple in interface ITupleCursor2<E>
    
    Returns:
    The tuple associated with the current cursor position -or- null either if there is no visitable tuple corresponding to the current cursor position or if the current cursor position is undefined.
  - first
```
public ITuple<E> first()
```
    Description copied from interface: ITupleCursor2
    
    Position the cursor on the first visitable tuple in the natural index order for the index or index partition over which the cursor is defined. If there are no visitable tuples then the cursor position will be undefined.
    
    Specified by:
    
    first in interface ITupleCursor2<E>
    
    Returns:
    The current tuple -or- null iff there is no visitable tuple corresponding to the current cursor position.
  - last
```
public ITuple<E> last()
```
    Description copied from interface: ITupleCursor2
    
    Position the cursor on the last visitable tuple in the natural index order for the index or index partition over which the cursor is defined. If there are no visitable tuples then the cursor position will be undefined.
    
    Specified by:
    
    last in interface ITupleCursor2<E>
    
    Returns:
    true if the cursor was positioned on a tuple.
  - seek
```
public final ITuple<E> seek(Object key)
```
    Description copied from interface: ITupleCursor
    
    Variant that first encodes the key using the object returned by IndexMetadata.getTupleSerializer() for the backing index.
    
    Specified by:
    
    seek in interface ITupleCursor<E>
    
    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.
  - seek
```
public ITuple<E> seek(byte[] key)
```
    Description copied from interface: ITupleCursor
    
    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 ITupleCursor.prior() or ITupleCursor.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.
    
    Specified by:
    
    seek in interface ITupleCursor<E>
    
    Parameters:
    key - The key (required).
    
    Returns:
    The tuple corresponding to key if it exists and is visitable in the index and null otherwise.
  - nextTuple
```
public ITuple<E> nextTuple()
```
    Position the cursor on the first visitable tuple ordered greater than the current cursor position in the natural key order of the index and return that tuple.
    Note: This is lighter weight than hasNext() and next() since it does not need to scan to verify that the next position exists before visiting that tuple.
    
    Specified by:
    
    nextTuple in interface ITupleCursor2<E>
    
    Returns:
    The tuple -or- null iff there is no such visitable tuple.
  - next
```
public ITuple<E> next()
```
    Description copied from interface: ITupleCursor
    
    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 ITupleCursor<E>
    
    Specified by:
    
    next in interface ITupleIterator<E>
    
    Specified by:
    
    next in interface Iterator<ITuple<E>>
    
    Returns:
    The ITuple containing the data and metadata for the current index entry.
  - hasNext
```
public boolean hasNext()
```
    Description copied from interface: ITupleCursor
    
    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 ITupleCursor<E>
    
    Specified by:
    
    hasNext in interface Iterator<ITuple<E>>
  - priorTuple
```
public ITuple<E> priorTuple()
```
    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: This is lighter weight than hasNext() and next() since it does not need to scan to verify that the prior position exists before visiting that tuple.
    
    Specified by:
    
    priorTuple in interface ITupleCursor2<E>
    
    Returns:
    The tuple -or- null iff there is no such visitable tuple.
  - prior
```
public ITuple<E> prior()
```
    Description copied from interface: ITupleCursor
    
    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.
    
    Specified by:
    
    prior in interface ITupleCursor<E>
  - hasPrior
```
public boolean hasPrior()
```
    Description copied from interface: ITupleCursor
    
    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.
    
    Specified by:
    
    hasPrior in interface ITupleCursor<E>
  - remove
```
public void remove()
```
    FIXME This needs to be overridden for the IsolatedFusedView in order to correctly propagate the version timestamp onto the tuple. See the insert() and remove() methods on that class. This will probably be done inside of an implementation that extends the FusedView cursor implementation, at which point this notice can be removed.
    
    Specified by:
    
    remove in interface ITupleCursor<E>
    
    Specified by:
    
    remove in interface Iterator<ITuple<E>>

Class AbstractBTreeTupleCursor<I extends AbstractBTree,L extends Leaf,E>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

log

INFO

DEBUG

btree

tuple

fromKey

toKey

visitDeleted

currentPosition

Constructor Detail

AbstractBTreeTupleCursor

Method Detail

getIndex

getFromKey

getToKey

isDeletedTupleVisitor

isCursorPositionDefined

assertCursorPositionDefined

toString

rangeCheck

getInclusiveLowerBound

getExclusiveUpperBound

newPosition

newTemporaryPosition

firstPosition

newPosition

lastPosition

currentKey

tuple

first

last

seek

seek

nextTuple

next

hasNext

priorTuple

prior

hasPrior

remove