com.bigdata.btree
Interface ITuple<E>

All Known Implementing Classes:

AbstractChunkedTupleIterator.ResultSetTuple, AbstractTuple, DelegateTuple, Tuple

public interface ITuple<E>

Interface exposes more direct access to keys and values visited by an ITupleIterator.

Version:

$Id: ITuple.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

TODO:

consider only the getKeyStream() and getValueStream() vs the getKeyBuffer() and getValueBuffer() methods. do we need both?

Method Summary

int	flags() The IRangeQuery flags
byte[]	getKey() Returns a copy of the current key.
ByteArrayBuffer	getKeyBuffer() The buffer into which the keys are being copied.
boolean	getKeysRequested() True iff IRangeQuery.KEYS was specified.
DataInputBuffer	getKeyStream() Return a stream from which the key may be read.
E	getObject() De-serializes the object from the key and/or value.
int	getSourceIndex() The index of the source from which the tuple was read.
ITupleSerializer	getTupleSerializer() Return the object that can be used to de-serialize the tuple.
byte[]	getValue() The value in the index under the key.
ByteArrayBuffer	getValueBuffer() The buffer into which the values are being copied.
boolean	getValuesRequested() True iff IRangeQuery.VALS was specified.
DataInputBuffer	getValueStream() Return a stream from which the value may be read.
long	getVersionTimestamp() Return the timestamp associated with the index entry -or- 0L IFF the index does not support transactional isolation.
long	getVisitCount() The #of entries that have been visited so far and ZERO (0) until the first entry has been visited.
boolean	isDeletedVersion() Return true iff the index entry was marked as deleted.
boolean	isNull() true iff the value stored under the index entry is null.
IBlock	readBlock(long addr) Return an object that may be used to perform a streaming read of a large record from the IRawStore that provided this tuple.

Method Detail

flags

int flags()

The IRangeQuery flags

 
 if ((flags & IRangeQuery.KEYS) != 0) {
 
     // keys requested.
 
 }
 
 

Note: the IRangeQuery.DELETED flag state is a property of the iterator NOT the tuple. Whether or not a tuple is deleted is detected using isDeletedVersion().

getKeysRequested

boolean getKeysRequested()

True iff IRangeQuery.KEYS was specified.

getValuesRequested

boolean getValuesRequested()

True iff IRangeQuery.VALS was specified.

getSourceIndex

int getSourceIndex()

The index of the source from which the tuple was read. This is zero (0) if there is only a single source, e.g., a BTree or IndexSegment. When reading on a FusedView this is the index of the element of the view which reported the tuple.

Throws:

IllegalStateException - if nothing has been visited.

getVisitCount

long getVisitCount()

The #of entries that have been visited so far and ZERO (0) until the first entry has been visited.

getKey

byte[] getKey()

Returns a copy of the current key.

Note: This can cause a heap allocation depending on how the keys are buffered. See getKeyBuffer() to avoid that allocation.

Throws:

UnsupportedOperationException - if keys are not being materialized.

getKeyBuffer

ByteArrayBuffer getKeyBuffer()

The buffer into which the keys are being copied.

Returns:

The buffer.

Throws:

UnsupportedOperationException - if keys are not being materialized.

getKeyStream

DataInputBuffer getKeyStream()

Return a stream from which the key may be read.

Throws:

UnsupportedOperationException - if the keys were not requested.

isNull

boolean isNull()

true iff the value stored under the index entry is null.

getValue

byte[] getValue()

The value in the index under the key.

Note: This causes a heap allocation. See getValueBuffer() to avoid that allocation.

Returns:

The value in the index under the key -or- null if version metadata is being maintained and the the index entry is marked as deleted.

Throws:

UnsupportedOperationException - if values are not being materialized.

getValueBuffer

ByteArrayBuffer getValueBuffer()

The buffer into which the values are being copied.

Note: If the index supports delete markers then you MUST test isDeletedVersion() in order to determine whether or not the value buffer contains data for the current index entry.

Returns:

The buffer.

Throws:

UnsupportedOperationException - if values are not being materialized.

UnsupportedOperationException - if the value is null.

UnsupportedOperationException - if the index entry is deleted.

getValueStream

DataInputBuffer getValueStream()

Return a stream from which the value may be read. Callers SHOULD prefer getValueStream() to getValue() as it can avoid some heap churn.

Throws:

UnsupportedOperationException - if the values were not requested.

UnsupportedOperationException - if the value is null.

UnsupportedOperationException - if the index entry is deleted.

getObject

E getObject()

De-serializes the object from the key and/or value.

Returns:

The de-serialized object.

Throws:

UnsupportedOperationException - if IRangeQuery.KEYS and/or IRangeQuery.VALS are required to de-serialize the object but were not specified when the ITupleIterator was created.

See Also:

ITupleSerializer.deserialize(ITuple)

readBlock

IBlock readBlock(long addr)

Return an object that may be used to perform a streaming read of a large record from the IRawStore that provided this tuple.

Parameters:

addr - The address of the record.

Returns:

The object that may be used to read that record.

getVersionTimestamp

long getVersionTimestamp()

Return the timestamp associated with the index entry -or- 0L IFF the index does not support transactional isolation.

isDeletedVersion

boolean isDeletedVersion()

Return true iff the index entry was marked as deleted.

Note: If the index does not support deletion markers then this method MUST return false.

Note: the IRangeQuery.DELETED flag state is a property of the iterator NOT the tuple. Whether or not a tuple is deleted is detected using isDeletedVersion().

getTupleSerializer

ITupleSerializer getTupleSerializer()

Return the object that can be used to de-serialize the tuple.