Class TableIterator

java.lang.Object

TableIterator

public class TableIterator
extends Object

A class that serves as an iterator over some or all of the rows in a stored table. For a given table, there may be more than one TableIterator open at the same time -- for example, when performing the cross product of a table with itself.

Constructor Summary

Constructors

Constructor and Description
TableIterator(SQLStatement stmt, Table table, boolean evalWhere) Constructs a TableIterator object for the subset of the specified table that is defined by the given SQLStatement.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the iterator, which closes any BDB handles that it is using.
boolean	first() Positions the iterator on the first tuple in the relation, without taking the a WHERE clause (if any) into effect.
Column	getColumn(int colIndex) Gets the column at the specified index in the relation that this iterator iterates over.
Object	getColumnVal(int colIndex) Gets the value of the column at the specified index in the row on which this iterator is currently positioned.
boolean	next() Advances the iterator to the next tuple in the relation.
int	numColumns() Gets the number of columns in the table being iterated over
int	numTuples() Gets the number of tuples that the iterator has visited.
void	printAll(PrintStream out) Iterates over all rows in the relation and prints them to the specified PrintStream (e.g., System.out).

Methods inherited from class java.lang.Object

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

Constructor Detail

TableIterator

public TableIterator(SQLStatement stmt,
                     Table table,
                     boolean evalWhere)
              throws DatabaseException

Constructs a TableIterator object for the subset of the specified table that is defined by the given SQLStatement. If the SQLStatement has a WHERE clause and the evalWhere parameter has a value of true, the iterator will only visit rows that satisfy the WHERE clause.

Parameters:

stmt - the SQL statement that defines the subset of the table

table - the table to iterate over

evalWhere - should the WHERE clause in stmt be evaluated by this iterator? If this iterator is being used by a higher-level iterator, then we can specify false so that the WHERE clause will not be evaluated at this level.

Throws:

IllegalStateException - if the specified Table object has not already been opened

DatabaseException - if Berkeley DB encounters a problem while accessing one of the underlying database(s)

Method Detail

close

public void close()
           throws DatabaseException

Closes the iterator, which closes any BDB handles that it is using.

Throws:

DatabaseException - if Berkeley DB encounters a problem while closing a handle

first

public boolean first()
              throws DeadlockException,
                     DatabaseException

Positions the iterator on the first tuple in the relation, without taking the a WHERE clause (if any) into effect. Because this method ignores the WHERE clause, it should ordinarily be used only when you need to reposition the cursor at the start of the relation after having completed a previous iteration.

Returns:

true if the iterator was advanced to the first tuple, and false if there are no tuples to visit

Throws:

DeadlockException - if deadlock occurs while accessing the underlying BDB database(s)

DatabaseException - if Berkeley DB encounters another problem while accessing the underlying database(s)

next

public boolean next()
             throws DeadlockException,
                    DatabaseException

Advances the iterator to the next tuple in the relation. If there is a WHERE clause that limits which tuples should be included in the relation, this method will advance the iterator to the next tuple that satisfies the WHERE clause. If the iterator is newly created, this method will position it on the first tuple in the relation (that satisfies the WHERE clause). Provided that the iterator can be positioned on a tuple, the count of the number of tuples visited by the iterator is incremented.

Returns:

true if the iterator was advanced to a new tuple, and false if there are no more tuples to visit

Throws:

DeadlockException - if deadlock occurs while accessing the underlying BDB database(s)

DatabaseException - if Berkeley DB encounters another problem while accessing the underlying database(s)

getColumn

public Column getColumn(int colIndex)

Gets the column at the specified index in the relation that this iterator iterates over. The leftmost column has an index of 0.

Returns:

the column

Throws:

IndexOutOfBoundsException - if the specified index is invalid

getColumnVal

public Object getColumnVal(int colIndex)

Gets the value of the column at the specified index in the row on which this iterator is currently positioned. The leftmost column has an index of 0. This method will unmarshall the relevant bytes from the key/data pair and return the corresponding Object -- i.e., an object of type String for CHAR and VARCHAR values, an object of type Integer for INTEGER values, or an object of type Double for REAL values.

Returns:

the value of the column

Throws:

IllegalStateException - if the iterator has not yet been been positioned on a tuple using first() or next()

IndexOutOfBoundsException - if the specified index is invalid

numTuples

public int numTuples()

Gets the number of tuples that the iterator has visited.

Returns:

the number of tuples visited

numColumns

public int numColumns()

Gets the number of columns in the table being iterated over

Returns:

the number of columns

printAll

public void printAll(PrintStream out)
              throws DeadlockException,
                     DatabaseException

Iterates over all rows in the relation and prints them to the specified PrintStream (e.g., System.out).

Throws:

DeadlockException - if deadlock occurs while accessing the underlying BDB database(s)

DatabaseException - if Berkeley DB encounters another problem while accessing the underlying database(s)