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.awt.RenderingHints;
019: import java.io.IOException;
020: import java.util.Set;
021: import com.vividsolutions.jts.geom.Envelope;
022: import org.opengis.filter.Filter;
023: import org.geotools.feature.FeatureCollection;
024: import org.geotools.feature.FeatureType;
025:
026: /**
027: * Highlevel API for Features from a specific location.
028: *
029: * <p>
030: * Individual Shapefiles, databases tables , etc. are referenced through this
031: * interface. Compare and constrast with DataStore.
032: * </p>
033: *
034: * <p>
035: * Differences from DataStore:
036: * </p>
037: *
038: * <ul>
039: * <li>
040: * This is a prototype DataSource replacement, the Transaction methods have
041: * been moved to an external object, and the locking api has been intergrated.
042: * </li>
043: * <li>
044: * FeatureCollection has been replaced with FeatureResult as we do not wish to
045: * indicate that results can be stored in memory.
046: * </li>
047: * <li>
048: * FeatureSource has been split into three interfaces, the intention is to use
049: * the instanceof opperator to check capabilities rather than the previous
050: * DataSourceMetaData.
051: * </li>
052: * </ul>
053: *
054: *
055: * @author Jody Garnett
056: * @author Ray Gallagher
057: * @author Rob Hranac, TOPP
058: * @author Chris Holmes, TOPP
059: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/data/FeatureSource.java $
060: * @version $Id: FeatureSource.java 26489 2007-08-08 15:36:02Z aaime $
061: */
062: public interface FeatureSource {
063: /**
064: * Access to the DataStore implementing this FeatureStore.
065: *
066: * <p>
067: * You may use this to access such as <code>namespace</code> provided by
068: * DataStore.
069: * </p>
070: *
071: * @return DataStore implementing this FeatureStore
072: */
073: DataStore getDataStore();
074:
075: /**
076: * Adds a listener to the list that's notified each time a change to the
077: * FeatureStore occurs.
078: *
079: * @param listener FeatureListener
080: */
081: void addFeatureListener(FeatureListener listener);
082:
083: /**
084: * Removes a listener from the list that's notified each time a change to
085: * the FeatureStore occurs.
086: *
087: * @param listener FeatureListener
088: */
089: void removeFeatureListener(FeatureListener listener);
090:
091: /**
092: * Loads features from the datasource into the returned FeatureResults,
093: * based on the passed query.
094: *
095: * @param query a datasource query object. It encapsulates requested
096: * information, such as typeName, maxFeatures and filter.
097: *
098: * @return Collection The collection to put the features into.
099: *
100: * @throws IOException For all data source errors.
101: *
102: * @see Query
103: */
104: FeatureCollection getFeatures(Query query) throws IOException;
105:
106: /**
107: * Loads features from the datasource into the returned FeatureResults,
108: * based on the passed filter.
109: *
110: * @param filter An OpenGIS filter; specifies which features to retrieve.
111: * <tt>null</tt> is not allowed, use Filter.INCLUDE instead.
112: *
113: * @return Collection The collection to put the features into.
114: *
115: * @throws IOException For all data source errors.
116: */
117: FeatureCollection getFeatures(Filter filter) throws IOException;
118:
119: /**
120: * Loads all features from the datasource into the return FeatureResults.
121: *
122: * <p>
123: * Filter.INCLUDE can also be used to get all features. Calling this function
124: * is equivalent to using {@link Query#ALL}
125: * </p>
126: *
127: * @return Collection The collection to put the features into.
128: *
129: * @throws IOException For all data source errors.
130: */
131: FeatureCollection getFeatures() throws IOException;
132:
133: /**
134: * Retrieves the featureType that features extracted from this datasource
135: * will be created with.
136: *
137: * <p>
138: * The schema returned is the LCD supported by all available Features. In
139: * the common case of shapfiles and database table this schema will match
140: * that of every feature available. In the degenerate GML case this will
141: * simply reflect the gml:AbstractFeatureType.
142: * </p>
143: *
144: * @return the schema of features created by this datasource.
145: *
146: * @task REVISIT: Our current FeatureType model is not yet advanced enough
147: * to handle multiple featureTypes. Should getSchema take a
148: * typeName now that a query takes a typeName, and thus DataSources
149: * can now support multiple types? Or just wait until we can
150: * programmatically make powerful enough schemas?
151: * @task REVISIT: we could also just use DataStore to capture multi
152: * FeatureTypes?
153: */
154: FeatureType getSchema();
155:
156: /**
157: * Gets the bounding box of this datasource.
158: *
159: * <p>
160: * With getBounds(Query) this becomes a convenience method for
161: * getBounds(Query.ALL), that is the bounds for all features contained
162: * here.
163: * </p>
164: *
165: * <p>
166: * If getBounds() returns <code>null</code> due to expense consider using
167: * <code>getFeatures().getBounds()</code> as a an alternative.
168: * </p>
169: *
170: * @return The bounding box of the datasource or null if unknown and too
171: * expensive for the method to calculate.
172: *
173: * @throws IOException if there are errors getting the bounding box.
174: *
175: * @task REVISIT: Do we need this or can we use getBounds( Query.ALL )?
176: */
177: Envelope getBounds() throws IOException;
178:
179: /**
180: * Gets the bounding box of the features that would be returned by this
181: * query.
182: *
183: * <p>
184: * To retrieve the bounds of the DataSource please use <code>getBounds(
185: * Query.ALL )</code>.
186: * </p>
187: *
188: * <p>
189: * This method is needed if we are to stream features to a gml out, since a
190: * FeatureCollection must have a boundedBy element.
191: * </p>
192: *
193: * <p>
194: * If getBounds(Query) returns <code>null</code> due to expense consider
195: * using <code>getFeatures(Query).getBounds()</code> as a an alternative.
196: * </p>
197: *
198: * @param query Contains the Filter and MaxFeatures to find the bounds for.
199: *
200: * @return The bounding box of the datasource or null if unknown and too
201: * expensive for the method to calculate or any errors occur.
202: *
203: * @throws IOException DOCUMENT ME!
204: */
205: Envelope getBounds(Query query) throws IOException;
206:
207: /**
208: * Gets the number of the features that would be returned by this query.
209: *
210: * <p></p>
211: *
212: * <p>
213: * If getBounds(Query) returns <code>-1</code> due to expense consider
214: * using <code>getFeatures(Query).getCount()</code> as a an alternative.
215: * </p>
216: *
217: * @param query Contains the Filter and MaxFeatures to find the bounds for.
218: *
219: * @return The number of Features provided by the Query or <code>-1</code>
220: * if count is too expensive to calculate or any errors or occur.
221: *
222: * @throws IOException if there are errors getting the count
223: */
224: int getCount(Query query) throws IOException;
225:
226: /**
227: * Returns the set of hints this {@link FeatureSource} is able to support.<p>
228: * Hints are to be specified in the {@link Query}, for each data access where they
229: * may be required.<br>
230: * Depending on the actual value provide by the user, the {@link FeatureSource}
231: * may decide not to honor the hint.
232: * @return a set of {@link RenderingHints#Key} objects (eventually empty, never null).
233: */
234: public Set /*<RenderingHints.Key>*/getSupportedHints();
235: }
|