LimitedTableIterator

java.lang.Object
- tap.data.LimitedTableIterator

All Implemented Interfaces:

TableIterator
```
public class LimitedTableIterator
extends java.lang.Object
implements TableIterator
```
Wrap a TableIterator in order to limit its reading to a fixed number of rows.

This wrapper can be "mixed" with a LimitedSizeInputStream, by wrapping the original input stream by a LimitedSizeInputStream and then by wrapping the TableIterator based on this wrapped input stream by LimitedTableIterator. Thus, this wrapper will be able to detect embedded ExceededSizeException thrown by a LimitedSizeInputStream through another TableIterator. If a such exception is detected, it will declare this wrapper as overflowed as it would be if a rows limit is reached.

Warning: To work together with a LimitedSizeInputStream, this wrapper relies on the hypothesis that any IOException (including ExceededSizeException) will be embedded in a DataReadException as cause of this exception (using DataReadException.DataReadException(Throwable) or DataReadException.DataReadException(String, Throwable)). If it is not the case, no overflow detection could be done and the exception will just be forwarded.

If a limit - either of rows or of bytes - is reached, a flag "overflow" is set to true. This flag can be got with isOverflow(). Thus, when a DataReadException is caught, it will be easy to detect whether the error occurred because of an overflow or of another problem.

Since:

2.0

Version:

2.0 (01/2015)

Author:

Grégory Mantelet (ARI)

Constructor Summary

Constructors
Constructor and Description
`LimitedTableIterator(java.lang.Class<T> classIt, java.io.InputStream input, ServiceConnection.LimitUnit type, int limit)` Build the specified `TableIterator` instance and wrap it so that limiting the number of rows OR bytes to read.
`LimitedTableIterator(TableIterator it, int nbMaxRows)` Wrap the given `TableIterator` so that limiting the number of rows to read.

Method Summary

All Methods Instance Methods Concrete Methods
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.
`TableIterator`	`getWrappedIterator()` Get the iterator wrapped by this `TableIterator` instance.
`boolean`	`hasNextCol()` Tell whether another column is available.
`boolean`	`isOverflow()` Tell whether a limit (in rows or bytes) has been reached.
`java.lang.Object`	`nextCol()` Return the value of the next column.
`boolean`	`nextRow()` Go to the next row if there is one.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - LimitedTableIterator
```
public LimitedTableIterator(TableIterator it,
                            int nbMaxRows)
                     throws DataReadException
```
    Wrap the given TableIterator so that limiting the number of rows to read.
    
    Parameters:
    
    it - The iterator to wrap. MUST NOT be NULL
    
    nbMaxRows - Maximum number of rows that can be read. There is overflow if more than this number of rows is asked. A negative value means "no limit".
    
    Throws:
    
    DataReadException
  - LimitedTableIterator
```
public LimitedTableIterator(java.lang.Class<T> classIt,
                            java.io.InputStream input,
                            ServiceConnection.LimitUnit type,
                            int limit)
                     throws DataReadException
```
    Build the specified TableIterator instance and wrap it so that limiting the number of rows OR bytes to read.
    
    If the limit is on the number of bytes, the given input stream will be first wrapped inside a LimitedSizeInputStream. Then, it will be given as only parameter of the constructor of the specified TableIterator instance.
    
    If the limit is on the number of rows, this LimitedTableIterator will count and limit itself the number of rows.
    
    IMPORTANT: The specified class must:
    
    extend TableIterator,
    
    be a concrete class,
    
    have at least one constructor with only one parameter of type InputStream.
    
    Note: If the given limit type is NULL (or different from ROWS and BYTES), or the limit value is <=0, no limit will be set. All rows and bytes will be read until the end of input is reached.
    Parameters:
    
    classIt - Class of the TableIterator implementation to create and whose the output must be limited.
    
    input - Input stream toward the table to read.
    
    type - Type of the limit: ROWS or BYTES. MAY be NULL
    
    limit - Limit in rows or bytes, depending of the "type" parameter. MAY BE <=0
    
    Throws:
    
    DataReadException - If no instance of the given class can be created, or if the TableIterator instance can not be initialized, or if the limit (in rows or bytes) has been reached.
- Method Detail
  - getWrappedIterator
```
public final TableIterator getWrappedIterator()
```
    Get the iterator wrapped by this TableIterator instance.
    
    Returns:
    
    The wrapped iterator.
  - isOverflow
```
public final boolean isOverflow()
```
    Tell whether a limit (in rows or bytes) has been reached.
    
    Note: If true is returned (that's to say, if a limit has been reached) no more rows or column values can be read ; an IllegalStateException would then be thrown.
    
    Returns:
    
    true if a limit has been reached, false otherwise.
  - close
```
public void close()
           throws DataReadException
```
    Description copied from interface: TableIterator
    
    Close the stream or input over which this class iterates.
    
    Specified by:
    
    close in interface TableIterator
    
    Throws:
    
    DataReadException - If any error occurs while closing it.
  - getMetadata
```
public TAPColumn[] getMetadata()
                        throws DataReadException
```
    Description copied from interface: TableIterator
    
    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 TableIterator.getColType() while iterating over rows and columns.
    
    Specified by:
    
    getMetadata in interface TableIterator
    
    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:
    
    TableIterator.getColType()
  - nextRow
```
public boolean nextRow()
                throws DataReadException
```
    Description copied from interface: TableIterator
    
    Go to the next row if there is one.
    
    Note: After a call to this function the columns must be fetched individually using TableIterator.nextCol() IF this function returned true.
    
    Specified by:
    
    nextRow in interface TableIterator
    
    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
```
public boolean hasNextCol()
                   throws java.lang.IllegalStateException,
                          DataReadException
```
    Description copied from interface: TableIterator
    
    Tell whether another column is available.
    
    Specified by:
    
    hasNextCol in interface TableIterator
    
    Returns:
    
    true if TableIterator.nextCol() will return the value of the next column with no error, false otherwise.
    
    Throws:
    
    java.lang.IllegalStateException - If TableIterator.nextRow() has not yet been called.
    
    DataReadException - If an error occurs while reading the table dataset.
  - nextCol
```
public java.lang.Object nextCol()
                         throws java.util.NoSuchElementException,
                                java.lang.IllegalStateException,
                                DataReadException
```
    Description copied from interface: TableIterator
    
    Return the value of the next column.
    
    Note: The column type can be fetched using TableIterator.getColType() after a call to TableIterator.nextCol().
    
    Specified by:
    
    nextCol in interface TableIterator
    
    Returns:
    
    Get the value of the next column.
    
    Throws:
    
    java.util.NoSuchElementException - If no more column value is available.
    
    java.lang.IllegalStateException - If TableIterator.nextRow() has not yet been called.
    
    DataReadException - If an error occurs while reading the table dataset.
  - getColType
```
public DBType getColType()
                  throws java.lang.IllegalStateException,
                         DataReadException
```
    Description copied from interface: TableIterator
    
    Get the type of the current column value.
    
    Note 1: "Current column value" means here "the value last returned by TableIterator.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 TableIterator.getMetadata() would be different. In case of such mismatch, the type returned by TableIterator.getColType() should be considered as more correct/accurate.
    
    Specified by:
    
    getColType in interface TableIterator
    
    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 TableIterator.nextCol() has not yet been called.
    
    DataReadException - If an error occurs while reading the table dataset.

Class LimitedTableIterator

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LimitedTableIterator

LimitedTableIterator

Method Detail

getWrappedIterator

isOverflow

close

getMetadata

nextRow

hasNextCol

nextCol

getColType