tap.data

Interface TableIterator

All Known Implementing Classes:

LimitedTableIterator, ResultSetTableIterator, VOTableIterator

public interface TableIterator

Let's iterate on each row and then on each column over a table dataset.

Initially, no rows are loaded and the "cursor" inside the dataset is set before the first row. Thus, a first call to nextRow() is required to read each of the column values of the first row.

Example of an expected usage:

        TableIterator it = ...;
        try{
                while(it.nextRow()){
                        while(it.hasNextCol()){
                                Object colValue = it.nextCol();
                                String colType = it.getColType();
                                ...
                        }
                }
        }catch(DataReadException dre){
                ...
        }finally{
                try{
                        it.close();
                }catch(DataReadException dre){ ... }
        }
 

Since:

2.0

Version:

2.0 (12/2014)

Author:

Grégory Mantelet (ARI)

Method Summary

Modifier and Type	Method and Description
void	close() Close the stream or input over which this class iterates.
DBType	getColType() Get the type of the current column value.
TAPColumn[]	getMetadata() Get all the metadata column that have been successfully extracted at the creation of this iterator.
boolean	hasNextCol() Tell whether another column is available.
java.lang.Object	nextCol() Return the value of the next column.
boolean	nextRow() Go to the next row if there is one.

Method Detail

getMetadata

TAPColumn[] getMetadata()
                 throws DataReadException

Get all the metadata column that have been successfully extracted at the creation of this iterator.

Important: This function should be callable at any moment from the creation of the iterator until the end of the table dataset has been reached.

Note: This function MAY BE NOT IMPLEMENTED or the metadata can not be fetched. In this case, NULL will be returned.

Warning: If the metadata part of the original document is corrupted (i.e. false number of columns), the column type information should be fetched thanks to getColType() while iterating over rows and columns.

Returns:

An array of TAPColumn objects (each for a column of any row), or NULL if this function is not implemented OR if it was not possible to get these metadata.

Throws:

DataReadException

See Also:

getColType()

nextRow

boolean nextRow()
         throws DataReadException

Go to the next row if there is one.

Note: After a call to this function the columns must be fetched individually using nextCol() IF this function returned true.

Returns:

true if the next row has been successfully reached, false if no more rows can be read.

Throws:

DataReadException - If an error occurs while reading the table dataset.

hasNextCol

boolean hasNextCol()
            throws java.lang.IllegalStateException,
                   DataReadException

Tell whether another column is available.

Returns:

true if nextCol() will return the value of the next column with no error, false otherwise.

Throws:

java.lang.IllegalStateException - If nextRow() has not yet been called.

DataReadException - If an error occurs while reading the table dataset.

nextCol

java.lang.Object nextCol()
                  throws java.util.NoSuchElementException,
                         java.lang.IllegalStateException,
                         DataReadException

Return the value of the next column.

Note: The column type can be fetched using getColType() after a call to nextCol().

Returns:

Get the value of the next column.

Throws:

java.util.NoSuchElementException - If no more column value is available.

java.lang.IllegalStateException - If nextRow() has not yet been called.

DataReadException - If an error occurs while reading the table dataset.

getColType

DBType getColType()
           throws java.lang.IllegalStateException,
                  DataReadException

Get the type of the current column value.

Note 1: "Current column value" means here "the value last returned by nextCol()".

Note 2: This function MAY BE NOT IMPLEMENTED or the type information can not be fetched. If this is the case, NULL will be returned.

Warning: In some cases, the metadata part of the original document does not match with the data it should have represented. In such case, the types returned here and by getMetadata() would be different. In case of such mismatch, the type returned by getColType() should be considered as more correct/accurate.

Returns:

Type of the current column value, or NULL if this information is not available or if this function is not implemented.

Throws:

java.lang.IllegalStateException - If nextCol() has not yet been called.

DataReadException - If an error occurs while reading the table dataset.

close

void close()
    throws DataReadException

Close the stream or input over which this class iterates.

Throws:

DataReadException - If any error occurs while closing it.