com.bigdata.btree.AbstractBTreeTupleCursor<I,L,E>
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public abstract class AbstractBTreeTupleCursor<I extends AbstractBTree,L extends Leaf,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.
| Nested Class Summary | |
|---|---|
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 | |
|---|---|
protected I |
btree
From the ctor. |
protected com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> |
currentPosition
The current cursor position. |
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 | |
|---|---|
AbstractBTreeTupleCursor(I btree,
Tuple<E> tuple,
byte[] fromKey,
byte[] toKey)
Create a new cursor. |
|
| Method Summary | |
|---|---|
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()
From the ctor. |
protected byte[] |
getInclusiveLowerBound()
The optional inclusive lower bound. |
I |
getIndex()
The backing index being traversed by the ITupleCursor. |
byte[] |
getToKey()
From the ctor. |
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)
Return a clone of the given ICursorPosition designed for use by
hasNext() and hasPrior() (temporary test without
side-effects). |
ITuple<E> |
next()
Position the cursor on the next tuple in the natural key order of the index. |
ITuple<E> |
nextTuple()
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. |
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()
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. |
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 |
|---|
protected static final org.apache.log4j.Logger log
protected static final boolean INFO
protected static final boolean DEBUG
protected final I extends AbstractBTree btree
protected final Tuple<E> tuple
protected final byte[] fromKey
protected final byte[] toKey
protected final boolean visitDeleted
protected com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L extends Leaf,E> currentPosition
| Constructor Detail |
|---|
public AbstractBTreeTupleCursor(I btree,
Tuple<E> tuple,
byte[] fromKey,
byte[] toKey)
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.
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 |
|---|
public final I getIndex()
ITupleCursorITupleCursor.
getIndex in interface ITupleCursor<E>public final byte[] getFromKey()
getFromKey in interface ITupleCursor2<E>public final byte[] getToKey()
getToKey in interface ITupleCursor2<E>public final boolean isDeletedTupleVisitor()
ITupleCursor2true 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.
isDeletedTupleVisitor in interface ITupleCursor2<E>IndexMetadata.getDeleteMarkers()public final boolean isCursorPositionDefined()
ITupleCursor2true 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).
isCursorPositionDefined in interface ITupleCursor2<E>protected final void assertCursorPositionDefined()
#first(boolean),
#last(boolean), or seek(byte[]) is used to position the
cursor.
IllegalStateException - if the cursor position is not defined.public String toString()
toString in class Objectprotected final boolean rangeCheck(byte[] key)
true if the key lies inside of the optional
half-open range constraint.
true unless the key is LT [fromKey] or GTE
[toKey].protected final byte[] getInclusiveLowerBound()
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.
protected final byte[] getExclusiveUpperBound()
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.
protected abstract com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> newPosition(ILeafCursor<L> leafCursor,
int index,
byte[] key)
ICursorPosition from the leafCursor, tuple
index, and key
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.
ICursorPosition.
IllegalArgumentException - if leafCursor is null.
IllegalArgumentException - if key is null.protected abstract com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> newTemporaryPosition(com.bigdata.btree.AbstractBTreeTupleCursor.ICursorPosition<L,E> p)
ICursorPosition designed for use by
hasNext() and hasPrior() (temporary test without
side-effects).
p - The cursor position.
protected final com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> firstPosition()
ICursorPosition that is initially positioned on the
inclusive lower bound and on new byte[]{} if there is no
inclusive lower bound.
protected final com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> newPosition(byte[] key)
ICursorPosition that is initially positioned on the
given key.
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).
ICursorPosition.
IllegalArgumentException - if the key is null.
KeyOutOfRangeException - if the key lies outside of the optional constrain on the
ITupleCursor.protected final com.bigdata.btree.AbstractBTreeTupleCursor.AbstractCursorPosition<L,E> lastPosition()
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).
getExclusiveUpperBound().public byte[] currentKey()
ITupleCursor2
currentKey in interface ITupleCursor2<E>null iff the cursor position is undefined.public ITuple<E> tuple()
ITupleCursor2
tuple in interface ITupleCursor2<E>null either if there is no visitable tuple
corresponding to the current cursor position or if the current
cursor position is undefined.public ITuple<E> first()
ITupleCursor2
first in interface ITupleCursor2<E>null iff there is no
visitable tuple corresponding to the current cursor position.public ITuple<E> last()
ITupleCursor2
last in interface ITupleCursor2<E>true if the cursor was positioned on a tuple.public final ITuple<E> seek(Object key)
ITupleCursorIndexMetadata.getTupleSerializer() for the backing index.
seek in interface ITupleCursor<E>key - The key (required).
null otherwise.public ITuple<E> seek(byte[] key)
ITupleCursorIf 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.
seek in interface ITupleCursor<E>key - The key (required).
null otherwise.public ITuple<E> nextTuple()
hasNext() and next()
since it does not need to scan to verify that the next position exists
before visiting that tuple.
nextTuple in interface ITupleCursor2<E>null iff there is no such visitable
tuple.public ITuple<E> next()
ITupleCursor
Note: in order to maintain standard iterator semantics, this method will
visit the #first() visitable tuple if the current cursor position
is undefined.
next in interface ITupleCursor<E>next in interface ITupleIterator<E>next in interface Iterator<ITuple<E>>ITuple containing the data and metadata for the
current index entry.public boolean hasNext()
ITupleCursortrue 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.
hasNext in interface ITupleCursor<E>hasNext in interface Iterator<ITuple<E>>public ITuple<E> priorTuple()
hasNext() and next()
since it does not need to scan to verify that the prior position exists
before visiting that tuple.
priorTuple in interface ITupleCursor2<E>null iff there is no such visitable
tuple.public ITuple<E> prior()
ITupleCursor
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.
prior in interface ITupleCursor<E>public boolean hasPrior()
ITupleCursortrue 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.
hasPrior in interface ITupleCursor<E>public void remove()
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.
remove in interface ITupleCursor<E>remove in interface Iterator<ITuple<E>>
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||