IterableInput
##############

Overview
---------

com.partnersoft.io.IterableInput is an extension of the java.util.Iterable interface for objects that adds some
important methods for handling status and dealing with the exceptions that commonly occur during iteration of streaming I/O.

Handling Exceptions
---------------------

Rather than throw a nasty RuntimeException during normal Iterator methods, IterableInput does a prefetch and halts the iteration. 
This provides for a robust no-complaints-but-no-data behavior. However, if an error did occur you can access it via getException().

Here is an example Groovy script that illustrates handling an exception generated
by an IterableInput - in this case, an SqlDataRecordSource::

    import com.partnersoft.sql.*;
    
    database = new SqlDatabase();
    database.setType("SQLite");
    database.setPath("test/testdb");
    
    connection = database.openConnection();
    try {
        // invalid query
        source = connection.query("some invalid sql, heck this IS invalid");
        // no exception thrown
        for (record in source) {
            // won't happen
            log.info(record);
        }
        
        if (source.getException() != null) {
            // here it is, throw it
            throw source.getException();
        }
    }
    catch (Exception oopsie) {
        // catching it here
        log.info("error", oopsie);
    }
    connection.close();