xxl.relational
Class BufferedResultSet

java.lang.Object
  |
  +--xxl.relational.AbstractResultSet
        |
        +--xxl.relational.BufferedResultSet

public class BufferedResultSet

extends AbstractResultSet

This class decorates a ResultSet by buffering selected tuples with a bag.

One can use a BufferedResultSet as a normal ResultSet.
At first, every requested tuple will directly be retrieved from the underlying ResultSet. While handling the actual tuple one can call the store() method to store this tuple in the bag. For each tuple only the first call of store() has an effect, all further calls are ignored.

use-case:
After some tuples of the underlying ResultSet have been read, one can call the reset() method and then all bufferd tuples can be reread from the BufferedResultSet. They appear in the same order as bag.cursor returns them. reset() can be called repeatedly.

Example (1a):

	ResultSet r = new BufferedResultSet(resultSet);
	while (r.next()) {
		"handle the actual tuple"  // it is read from the underlying ResultSet
		if (willBeNeededAgain(tuple))
			r.store();  // stores this tuple in the bag for future use
	}
	while (!finished) {  // handling all stored tuples many times
		r.reset();
		while (r.next())
			"handle stored tuple"  // it is read from the bag
	}
	

The store() method is ignored while reading tuples from the bag, i.e. a tuple is iserted into the Bag at most once.

Example (1b):

	ResultSet r = new BufferedResultSet(resultSet);
	while (!finished) {  // handling many times
		while (r.next()) {
			"handle tuple"  // it is read from whatever
			if (willBeNeededAgain(tuple))
				r.store();  // stores the tupel (if not already stored)
		}
		r.reset();
	}
	

While reading tuples from the Bag one can remove these tuples by calling the remove() method (if the bag.cursor supports remove()). For each tuple only the first call of remove() has an effect.
Tuples can not be removed from the underlying ResultSet. If the actual tuple has been read from the underlying ResultSet (and not from the bag), the call of remove() will be ignored.

Example (2):

	ResultSet r = new BufferedResultSet(resultSet);
	while (!finished) {  // handling many times
		while (r.next()) {
			"handle tuple"  // it is read from whatever
			if (willBeNeededAgain(tuple))
				r.store();  // stores the tupel (if not already stored)
			else
				r.remove();  // removes the tupel from the bag (if stored)
		}
		r.reset();
	}
	

Now in each loop tuples that are not needed anymore can be removed from the bag, i.e. the bag can shrink in each loop.

One can also call the reset() method if next() returned false. In this case, the actual tuple is deprecated and a new bag.cursor is generated from which the next requested tuple is taken. After the bag cursor is empty, this class proceeds with reading the underlying ResultSet.

The easiest constructor creates a BufferedResultSet with a main memory Bag and all tuples are stored as ArrayTuples.

More advanced constructors allow to pass a Bag for storing Tuples and a Tuple factory-method to create new Tuples.

Example (3):

	new BufferedResultSet((Bag)Bag.FACTORY_METHOD.invoke(), ListTuple.FACTORY_METHOD, resultSet);
	

This creates a BufferedResultSet that stores the tuples from resultSet as ListTuples in the default Bag implementation.

Field Summary

protected boolean	alreadyRemoved
protected boolean	alreadyStored
protected Bag	bag
protected Cursor	bagCursor
protected Function	createTuple
protected boolean	onBag
protected java.sql.ResultSet	resultSet
protected Tuple	tuple
protected boolean	wasNull

Constructor Summary

BufferedResultSet(Bag bag, Function createTuple, java.sql.ResultSet resultSet)

BufferedResultSet(Bag bag, java.sql.ResultSet resultSet)

BufferedResultSet(java.sql.ResultSet resultSet)

Method Summary

void	close()
int	findColumn(java.lang.String columnName)
byte[]	getBytes(int columnIndex)
java.sql.ResultSetMetaData	getMetaData()
java.lang.Object	getObject(int columnIndex)
Tuple	getTuple()
boolean	next()
void	remove()
void	reset()
void	store()
boolean	wasNull()

Methods inherited from class xxl.relational.AbstractResultSet

absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, deleteRow, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getColumnCount, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getInt, getInt, getLong, getLong, getObject, getObject, getObject, getRef, getRef, getRow, getShort, getShort, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getWarnings, insertRow, isAfterLast, isBeforeFirst, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRow, updateShort, updateShort, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp

Methods inherited from class java.lang.Object

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

Field Detail

resultSet

protected java.sql.ResultSet resultSet

createTuple

protected Function createTuple

bag

protected Bag bag

bagCursor

protected Cursor bagCursor

tuple

protected Tuple tuple

onBag

protected boolean onBag

wasNull

protected boolean wasNull

alreadyStored

protected boolean alreadyStored

alreadyRemoved

protected boolean alreadyRemoved

Constructor Detail

BufferedResultSet

public BufferedResultSet(Bag bag,
                         Function createTuple,
                         java.sql.ResultSet resultSet)

BufferedResultSet

public BufferedResultSet(Bag bag,
                         java.sql.ResultSet resultSet)

BufferedResultSet

public BufferedResultSet(java.sql.ResultSet resultSet)

Method Detail

store

public void store()
           throws java.sql.SQLException

reset

public void reset()

remove

public void remove()

getTuple

public Tuple getTuple()
               throws java.sql.SQLException

next

public boolean next()
             throws java.sql.SQLException

Overrides:

next in class AbstractResultSet

getObject

public java.lang.Object getObject(int columnIndex)
                           throws java.sql.SQLException

Overrides:

getObject in class AbstractResultSet

getBytes

public byte[] getBytes(int columnIndex)
                throws java.sql.SQLException

Overrides:

getBytes in class AbstractResultSet

wasNull

public boolean wasNull()
                throws java.sql.SQLException

Overrides:

wasNull in class AbstractResultSet

findColumn

public int findColumn(java.lang.String columnName)
               throws java.sql.SQLException

Overrides:

findColumn in class AbstractResultSet

getMetaData

public java.sql.ResultSetMetaData getMetaData()
                                       throws java.sql.SQLException

Overrides:

getMetaData in class AbstractResultSet

close

public void close()
           throws java.sql.SQLException

Overrides:

close in class AbstractResultSet