com.bigdata.btree
Class ResultSet

java.lang.Object
  com.bigdata.btree.ResultSet

All Implemented Interfaces:

IAbstractNodeData, ILeafData, IDataRecordAccess, Externalizable, Serializable

public class ResultSet
extends Object
implements ILeafData, Externalizable

An object used to stream key scan results back to the client.

Note: The IRangeQuery bit flags may be used to indicate which data and metadata are returned. If the corresponding data was not requested then the access methods for that data will throw an UnsupportedOperationException. You can test this using hasDeleteMarkers(), hasVersionTimestamps() and related methods. FIXME Do not decode the delete flags or version timestamps. Code per ReadOnlyLeafData and then use the coded representations in place.

Version:

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

Author:

Bryan Thompson

See Also:

Serialized Form

Field Summary

protected static boolean	DEBUG
protected static boolean	INFO
protected static org.apache.log4j.Logger	log
protected static short	VERSION0

Constructor Summary

	ResultSet() Deserialization constructor.
protected	ResultSet(IIndex ndx, int flags) The basic approach is: Create a new ResultSet Invoke init(int) to setup the internal buffers. Apply the source ITupleIterator, using copyTuple(ITuple) to copy data into those buffers. Signal completion using done(boolean, byte[])
	ResultSet(IIndex ndx, int capacity, int flags, ITupleIterator itr) Constructor used to populate the ResultSet directly from an iterator.

Method Summary

protected void	assertRunning() true once init(int) has been called and until #done(byte[]) is called.
protected void	copyTuple(ITuple<?> tuple) Copies the data from the tuple into the internal buffers.
AbstractFixedByteArrayBuffer	data() FIXME If we extend DefaultLeafCoder or implement "ResultSetCoder" then we can really adhere to these semantics.
protected void	done(boolean exhausted, byte[] lastKey) Notify that the iterator is done and communicate metadata back to the client about whether or not a continuation query should be issued against this index partition.
long	getCommitTime() Return the commitTime of the index view from which this result set was read.
boolean	getDeleteMarker(int index) Return true iff the entry at the specified index is marked as deleted.
int	getKeyCount() Return the #of keys in the node or leaf.
IRaba	getKeys() Return the keys.
byte[]	getLastKey() The last key visited by the iterator regardless of the filter imposed -or- null iff no keys were visited by the iterator for the specified key range.
protected int	getLimit() The value of the limit specified to the ctor.
long	getMaximumVersionTimestamp() The most recent tuple revision timestamp associated with any tuple spanned by this node or leaf.
long	getMinimumVersionTimestamp() The earliest tuple revision timestamp associated with any tuple spanned by this node or leaf.
long	getNextAddr() The address of the next leaf in key order, 0L if it is known that there is no next leaf, and -1L if either: (a) it is not known whether there is a next leaf; or (b) it is known but the address of that leaf is not known to the caller.
int	getNumTuples() Actual #of key-value pairs in the ResultSet
long	getPriorAddr() The address of the previous leaf in key order, 0L if it is known that there is no previous leaf, and -1L if either: (a) it is not known whether there is a previous leaf; or (b) it is known but the address of that leaf is not known to the caller.
int	getSourceIndex(int index) The values returned by ITuple.getSourceIndex() for each visited index entry.
IResourceMetadata[]	getSources() Return the ordered array of sources from which the iterator read and the ResultSet was populated.
int	getSpannedTupleCount() The #of tuples visited by the iterator.
ITupleSerializer	getTupleSerializer() The ITupleSerializer that should be used to de-serialize the tuples in the ResultSet.
int	getValueCount() The #of values in the leaf (this MUST be equal to the #of keys for a leaf).
IRaba	getValues() Return the values.
long	getVersionTimestamp(int index) The version timestamp for the entry at the specified index.
boolean	hasDeleteMarkers() Return true iff the leaf maintains delete markers.
boolean	hasVersionTimestamps() Return true iff the leaf maintains version timestamps.
protected void	init(int limit) Setup the internal buffers.
boolean	isCoded() true iff this is a coded data structure.
boolean	isDoubleLinked() No.
boolean	isExhausted() True iff the iterator exhausted the available keys such that no more results would be available if you formed the successor of the lastKey.
protected boolean	isFull() true iff the internal buffers are full.
boolean	isLeaf() Yes (this data structure logically corresponds to a leaf since it implements the ILeafData API).
boolean	isReadOnly() Yes (the data structure is populated during the ctor and is read-only thereafter).
void	readExternal(ObjectInput in)
void	writeExternal(ObjectOutput out)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

log

protected static final transient org.apache.log4j.Logger log

INFO

protected static final transient boolean INFO

DEBUG

protected static final transient boolean DEBUG

VERSION0

protected static short VERSION0

Constructor Detail

ResultSet

public ResultSet()

Deserialization constructor.

ResultSet

protected ResultSet(IIndex ndx,
                    int flags)

The basic approach is:

1. Create a new ResultSet
2. Invoke init(int) to setup the internal buffers.
3. Apply the source ITupleIterator, using copyTuple(ITuple) to copy data into those buffers.
4. Signal completion using done(boolean, byte[])

Parameters:

ndx - The index.

flags - The flags specified for the iterator. See IRangeQuery.

ResultSet

public ResultSet(IIndex ndx,
                 int capacity,
                 int flags,
                 ITupleIterator itr)

Constructor used to populate the ResultSet directly from an iterator.

Note: The itr provided to this method MUST be created with IRangeQuery.KEYS so that we can report the lastKey visited for continuation queries.

Parameters:

ndx - The index.

capacity - The requested capacity for the operation.

flags - The flags specified for the iterator.

itr - The source iterator.

Method Detail

getNumTuples

public final int getNumTuples()

Actual #of key-value pairs in the ResultSet

isExhausted

public final boolean isExhausted()

True iff the iterator exhausted the available keys such that no more results would be available if you formed the successor of the lastKey.

getLastKey

public final byte[] getLastKey()

The last key visited by the iterator regardless of the filter imposed -or- null iff no keys were visited by the iterator for the specified key range.

See Also:

#successor()

getTupleSerializer

public final ITupleSerializer getTupleSerializer()

The ITupleSerializer that should be used to de-serialize the tuples in the ResultSet.

getKeys

public final IRaba getKeys()

Return the keys.

Specified by:

getKeys in interface IAbstractNodeData

Throws:

UnsupportedOperationException - if the keys were not retrieved.

getValues

public final IRaba getValues()

Return the values.

Specified by:

getValues in interface ILeafData

Throws:

UnsupportedOperationException - if the values were not retrieved.

See Also:

ILeafData.hasDeleteMarkers(), ILeafData.getDeleteMarker(int)

getSourceIndex

public final int getSourceIndex(int index)

The values returned by ITuple.getSourceIndex() for each visited index entry.

getCommitTime

public final long getCommitTime()

Return the commitTime of the index view from which this result set was read. This may be used to force a ITx.UNISOLATED or ITx.READ_COMMITTED chunked iterator to produce a consistent view by issuing continuation queries for the commitTime that was returned by the initial ResultSet.

Returns:

getSources

public final IResourceMetadata[] getSources()

Return the ordered array of sources from which the iterator read and the ResultSet was populated.

The values returned by ITuple.getSourceIndex() may be used to identify the resource from which a given tuple was read. That information is used to direct ITuple.readBlock(long) requests to the correct resource on the IDataService.

getLimit

protected int getLimit()

The value of the limit specified to the ctor. This is the dimension of the internal arrays used to buffer the data for the tuples.

Note: This field is transient - it does not get (de-)serialized.

init

protected void init(int limit)

Setup the internal buffers.

Parameters:

limit - The maximum #of tuples that will be materialized. Use (-limit) for a soft limit. The caller should either use the suggested capacity, compute either an actual limit or the upper bound based on additional information, such as a range count, or treat the suggested capacity as a soft limit if it is not possible to determine the upper bound.

done

protected void done(boolean exhausted,
                    byte[] lastKey)

Notify that the iterator is done and communicate metadata back to the client about whether or not a continuation query should be issued against this index partition.

Note: the point of this method is to communicate the restart point for a continuation query (or that no continuation query is necessary). If you are scanning ahead to decide whether or not the next coherent chunk of tuples (e.g., a logical row) would fit in the buffer, then the restart point is the point from which the continuation query should start and the key to report is the last key before the start of the first logical row that was rejected because it would overflow the internal buffers.

Note: !exhausted the caller will issue a continuation query against this index partition whose fromKey is the successor of lastKey (the successor is formed using BytesUtil.successor(byte[])).

Note: If an index partition is exhausted there may still be data for the key range on subsequent index partitions the caller will discover the locator for the next index partition in key order whose left separator key is LE the toKey and query it for more results. If there is no such index partition then the aggregate iterator is finished.

Parameters:

exhausted - true iff the source iterator will not visit any more tuples Iterator.hasNext() is false.

lastKey - The key from the last tuple scanned by the source iterator regardless of whether it was included in the result set -or- null iff no tuples were scanned (this implies that there is no data for the query in the key range on this index partition and hence that it is exhausted).

isFull

protected boolean isFull()

true iff the internal buffers are full.

copyTuple

protected void copyTuple(ITuple<?> tuple)

Copies the data from the tuple into the internal buffers.

Parameters:

tuple - The tuple.

assertRunning

protected void assertRunning()

true once init(int) has been called and until #done(byte[]) is called.

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

hasDeleteMarkers

public final boolean hasDeleteMarkers()

Description copied from interface: ILeafData

Return true iff the leaf maintains delete markers.

Specified by:

hasDeleteMarkers in interface ILeafData

hasVersionTimestamps

public final boolean hasVersionTimestamps()

Description copied from interface: ILeafData

Return true iff the leaf maintains version timestamps.

Specified by:

hasVersionTimestamps in interface IAbstractNodeData

Specified by:

hasVersionTimestamps in interface ILeafData

getVersionTimestamp

public final long getVersionTimestamp(int index)

Description copied from interface: ILeafData

The version timestamp for the entry at the specified index.

Specified by:

getVersionTimestamp in interface ILeafData

Returns:

The version timestamp for the index entry.

getDeleteMarker

public final boolean getDeleteMarker(int index)

Description copied from interface: ILeafData

Return true iff the entry at the specified index is marked as deleted.

Specified by:

getDeleteMarker in interface ILeafData

getKeyCount

public final int getKeyCount()

Description copied from interface: IAbstractNodeData

Return the #of keys in the node or leaf. A node has nkeys+1 children. A leaf has nkeys keys and values. The maximum #of keys for a node is one less than the branching factor of the B+Tree. The maximum #of keys for a leaf is the branching factor of the B+Tree.

Specified by:

getKeyCount in interface IAbstractNodeData

Returns:

The #of defined keys.

getValueCount

public final int getValueCount()

Description copied from interface: ILeafData

The #of values in the leaf (this MUST be equal to the #of keys for a leaf).

Specified by:

getValueCount in interface ILeafData

Returns:

The #of values in the leaf.

getSpannedTupleCount

public int getSpannedTupleCount()

The #of tuples visited by the iterator.

Note: This is is the same as the values returned by getKeyCount() or getValueCount(). It DOES NOT report the #of tuples spanned by the key range. Use IRangeQuery.rangeCount(byte[], byte[]) for that purpose.

Specified by:

getSpannedTupleCount in interface IAbstractNodeData

See Also:

INodeData#getChildEntryCounts()

isLeaf

public final boolean isLeaf()

Yes (this data structure logically corresponds to a leaf since it implements the ILeafData API).

Specified by:

isLeaf in interface IAbstractNodeData

isReadOnly

public final boolean isReadOnly()

Yes (the data structure is populated during the ctor and is read-only thereafter).

Specified by:

isReadOnly in interface IAbstractNodeData

isCoded

public final boolean isCoded()

Description copied from interface: IAbstractNodeData

true iff this is a coded data structure.

Specified by:

isCoded in interface IAbstractNodeData

TODO:

The ResultSet is not coded while it is being generated, but it is coded when it is deserialized (at present, only the keys and values remain coded during deserialization).

data

public final AbstractFixedByteArrayBuffer data()

FIXME If we extend DefaultLeafCoder or implement "ResultSetCoder" then we can really adhere to these semantics.

Specified by:

data in interface IAbstractNodeData

Specified by:

data in interface IDataRecordAccess

isDoubleLinked

public final boolean isDoubleLinked()

No.

Specified by:

isDoubleLinked in interface ILeafData

getNextAddr

public final long getNextAddr()

Description copied from interface: ILeafData

The address of the next leaf in key order, 0L if it is known that there is no next leaf, and -1L if either: (a) it is not known whether there is a next leaf; or (b) it is known but the address of that leaf is not known to the caller.

Specified by:

getNextAddr in interface ILeafData

getPriorAddr

public final long getPriorAddr()

Description copied from interface: ILeafData

The address of the previous leaf in key order, 0L if it is known that there is no previous leaf, and -1L if either: (a) it is not known whether there is a previous leaf; or (b) it is known but the address of that leaf is not known to the caller.

Specified by:

getPriorAddr in interface ILeafData

getMinimumVersionTimestamp

public final long getMinimumVersionTimestamp()

Description copied from interface: IAbstractNodeData

The earliest tuple revision timestamp associated with any tuple spanned by this node or leaf. If there are NO tuples for the leaf, then this MUST return Long.MAX_VALUE since the initial value of the minimum version timestamp is always the largest possible long integer.

Specified by:

getMinimumVersionTimestamp in interface IAbstractNodeData

getMaximumVersionTimestamp

public final long getMaximumVersionTimestamp()

Description copied from interface: IAbstractNodeData

The most recent tuple revision timestamp associated with any tuple spanned by this node or leaf. If there are NO tuples for the leaf, then this MUST return Long.MIN_VALUE since the initial value of the maximum version timestamp is always the smallest possible long integer.

Specified by:

getMaximumVersionTimestamp in interface IAbstractNodeData