001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.data;
017:
018: import java.io.IOException;
019: import java.util.NoSuchElementException;
020: import org.geotools.feature.Feature;
021: import org.geotools.feature.FeatureType;
022: import org.geotools.feature.IllegalAttributeException;
023:
024: /**
025: * The low-level interface for reading Features. Will use the underlying
026: * AttributeReader and the given FeatureType to create new Features.
027: *
028: * <p>
029: * Typical use is as follows:
030: * <pre><code>
031: * FeatureReader reader = null;
032: * try{
033: * for( reader = data.getFeatureReader( filter ); reader.hasNext(); ){
034: * f = reader.next();
035: * ...
036: * }
037: * }
038: * catch (IOException problem){
039: * ...
040: * }
041: * finally {
042: * if( reader != null ){
043: * try {
044: * reader.close();
045: * }
046: * catch( IOException eek){
047: * }
048: * }
049: * }
050: * </code></pre>
051: *
052: * <h2>Questions and Suggestions</h2>
053: * <ul>
054: * <li>Q: Should FeatureReader provide access to the AttributeReaders it uses?
055: * <br>A:
056: * No, it looks like we will make a lazy Feature in order to cleanly
057: * allow for lazy parsing of attribtues.
058: * </li>
059: * <li>Q:FeatureReader has a close method, but no open method?
060: * <br>A: This is by design allowing FeatureReader to encapsulate its InputStream
061: * or Rowset). Please assume that FeatureReaders are a single use proposition.
062: * </li>
063: * <li>Q: All that exception handling is a pain!
064: * A:
065: * Yes it is, we have constructed semi-normal Java iterators to cut down on the
066: * pain. But you *do* still have to close 'em - this is IO after all.
067: * </li>
068: * <li>Q: Can we include skip(int) - SeanG
069: * A:
070: * The order of the contents is not "known" or predicatable to the end user, so
071: * skip( int ) would be useless. For random access (a higher order
072: * of abstraction then FeatureReader) please look at FeatureList.
073: * </li>
074: * </ul>
075: * </p>
076: *
077: * @author Ian Schneider
078: * @author Sean Geoghegan, Defence Science and Technology Organisation.
079: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/data/FeatureReader.java $
080: * @version $Id: FeatureReader.java 22294 2006-10-20 00:55:40Z desruisseaux $
081: */
082: public interface FeatureReader {
083: /**
084: * Return the FeatureType this reader has been configured to create.
085: *
086: * @return the FeatureType of the Features this FeatureReader will create.
087: */
088: FeatureType getFeatureType();
089:
090: /**
091: * Reads the next Feature in the FeatureReader.
092: *
093: * @return The next feature in the reader.
094: *
095: * @throws IOException If an error occurs reading the Feature.
096: * @throws IllegalAttributeException If the attributes read do not comply
097: * with the FeatureType.
098: * @throws NoSuchElementException If there are no more Features in the
099: * Reader.
100: */
101: Feature next() throws IOException, IllegalAttributeException,
102: NoSuchElementException;
103:
104: /**
105: * Query whether this FeatureReader has another Feature.
106: *
107: * @return True if there are more Features to be read. In other words, true
108: * if calls to next would return a feature rather than throwing an
109: * exception.
110: *
111: * @throws IOException If an error occurs determining if there are more
112: * Features.
113: */
114: boolean hasNext() throws IOException;
115:
116: /**
117: * Release the underlying resources associated with this stream.
118: *
119: * @throws IOException DOCUMENT ME!
120: */
121: void close() throws IOException;
122: }
|