/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 * 
 *    (C) 2008, Open Source Geospatial Foundation (OSGeo)
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */
package org.geotools.data;

import java.io.IOException;
import java.util.NoSuchElementException;

import org.opengis.feature.Feature;
import org.opengis.feature.type.FeatureType;

/**
 * The low-level interface for reading Features. Will use the underlying
 * AttributeReader and the given FeatureType to create new Features.
 *
 * <p>
 * Typical use is as follows:
 * <pre><code>
 *   FeatureReader reader = null;
 *   try{
 *      for( reader = data.getFeatureReader( filter ); reader.hasNext(); ){
 *          f = reader.next();
 *          ...
 *      }
 *   }
 *   catch (IOException problem){
 *      ...
 *   }
 *   finally {
 *      if( reader != null ){
 *          try {
 *             reader.close();
 *          }
 *          catch( IOException eek){
 *          }
 *      }
 *   }
 * </code></pre>
 *
 * <h2>Questions and Suggestions</h2>
 * <ul>
 * <li>Q: Should FeatureReader provide access to the AttributeReaders it uses?
 * <br>A:
 *       No, it looks like we will make a lazy Feature in order to cleanly
 *       allow for lazy parsing of attribtues.
 * </li>
 * <li>Q:FeatureReader has a close method, but no open method?
 * <br>A: This is by design allowing FeatureReader to encapsulate its InputStream
 *     or Rowset). Please assume that FeatureReaders are a single use proposition.
 * </li>
 * <li>Q: All that exception handling is a pain!
 *     A:
 *        Yes it is, we have constructed semi-normal Java iterators to cut down on the
 *        pain. But you *do* still have to close 'em - this is IO after all.
 * </li>
 * <li>Q: Can we include skip(int) - SeanG
 *     A:
 *        The order of the contents is not "known" or predicatable to the end user, so
 *        skip( int ) would be useless. For random access (a higher order
 *        of abstraction then FeatureReader) please look at FeatureList.
 * </li>
 * </ul>
 * </p>
 *
 * @author Ian Schneider
 * @author Sean Geoghegan, Defence Science and Technology Organisation.
 *
 * @source $URL$
 * @version $Id$
 */
public interface FeatureReader<T extends FeatureType, F extends Feature> {
    /**
     * Return the FeatureType this reader has been configured to create.
     *
     * @return the FeatureType of the Features this FeatureReader will create.
     */
    T getFeatureType();

    /**
     * Reads the next Feature in the FeatureReader.
     *
     * @return The next feature in the reader.
     *
     * @throws IOException If an error occurs reading the Feature.
     * @throws IllegalAttributeException If the attributes read do not comply
     *         with the FeatureType.
     * @throws NoSuchElementException If there are no more Features in the
     *         Reader.
     */
    F next() throws IOException, IllegalArgumentException, NoSuchElementException;

    /**
     * Query whether this FeatureReader has another Feature.
     *
     * @return True if there are more Features to be read. In other words, true
     *         if calls to next would return a feature rather than throwing an
     *         exception.
     *
     * @throws IOException If an error occurs determining if there are more
     *         Features.
     */
    boolean hasNext() throws IOException;

    /**
     * Release the underlying resources associated with this stream.
     *
     * @throws IOException DOCUMENT ME!
     */
    void close() throws IOException;
}