Menu
▾
▴
[Geotools-commits] svn - r38832 - trunk/modules/library/api/src/main/java/org/geotools/feature
|
From: <svn...@os...> - 2012-06-24 14:42:18
|
Author: jive
Date: 2012-06-24 07:42:11 -0700 (Sun, 24 Jun 2012)
New Revision: 38832
Modified:
trunk/modules/library/api/src/main/java/org/geotools/feature/FeatureCollection.java
Log:
Update javadocs with an example using FeatureIterator and remove some notes for future GeoTools 2.2 plans.
Signed-off-by: Jody Garnett <jod...@gm...>
Modified: trunk/modules/library/api/src/main/java/org/geotools/feature/FeatureCollection.java
===================================================================
--- trunk/modules/library/api/src/main/java/org/geotools/feature/FeatureCollection.java 2012-06-24 14:41:56 UTC (rev 38831)
+++ trunk/modules/library/api/src/main/java/org/geotools/feature/FeatureCollection.java 2012-06-24 14:42:11 UTC (rev 38832)
@@ -20,10 +20,10 @@
import java.util.Collection;
import java.util.Iterator;
+import org.geotools.data.FeatureSource;
import org.geotools.geometry.jts.ReferencedEnvelope;
import org.opengis.feature.Feature;
import org.opengis.feature.FeatureVisitor;
-import org.opengis.feature.type.AttributeDescriptor;
import org.opengis.feature.type.FeatureType;
import org.opengis.filter.Filter;
import org.opengis.filter.sort.SortBy;
@@ -31,40 +31,39 @@
/**
- * Represents a collection of features.
+ * Collection of features, often handled as a result set.
* <p>
- * Implementations (and client code) should adhere to the rules set forth
- * by java.util.Collection. That is, some methods are
- * optional to implement, and may throw an UnsupportedOperationException.
+ * Where possible FeatureCollection is method compatible with {@link Collection}.
+ * In keeping with the rules set for by {@link Collection}, some methods are
+ * optional, and may throw an UnsupportedOperationException.
* </p>
* <p>
* SimpleFeatureCollection house rules:
* <ul>
- * <li>FeatureCollection.close( iterator ) must be called (see example below)
- * <li>Features are not specifically ordered within the SimpleFeatureCollection (see FeatureList)
- * <li>Two instances cannot exist with the same Feature ID (Feature contract)
- * <li>(unsure) the same Instance can be in the collection more then once
+ * <li>Each iterator is considered a connection which my be closed (see example below)</li>
+ * <li>Features are not specifically ordered within the SimpleFeatureCollection</li>
+ * <li>Two instances cannot exist with the same {@link FeatureId}</li>
* </ul>
- * In programmer speak a SimpleFeatureCollection is a "Bag" with an index based ID.
* </p>
* <p>
- * <h3>Life Cycle of Iterator</h3>
+ * <h3>FeatureIterator close</h3>
* <p>
- * We have also adopted an additional constraint on the use of iterator.
- * You must call FeatureCollection.close( iterator ) to allow FeatureCollection
- * to clean up any operating system resources used to acces information.
+ * FeatureCollection provides streaming access. With this in mind we have
+ * a restriction on the use of {@link FeatureIterator}: You must call
+ * {@link FeatureIterator#close()}. This allows FeatureCollection
+ * to clean up any operating system resources used to access information.
* </p>
* <p>
* Example (safe) use:<pre><code>
- * Iterator iterator = collection.iterator();
+ * FeatureIterator iterator = collection.features();
* try {
- * for( Iterator i=collection.iterator(); i.hasNext();){
- * Feature feature = (Feature) i.hasNext();
+ * while( iterator.hasNext() ){
+ * Feature feature = iterator.hasNext();
* System.out.println( feature.getID() );
* }
* }
* finally {
- * collection.close( iterator );
+ * iterator.close();
* }
* </code></pre>
* </p>
@@ -73,31 +72,26 @@
* to release resources at when the iterator has reached the end of its contents
* this is not something you should rely on.
* </p>
- * <h2>Notes for SimpleFeatureCollection Implementors</h2>
+ * <h2>FeatureCollection Implementation Tips</h2>
* <p>
- * Many users will be treating this as a straight forward Collection,
- * there code will break often enough due to latency - try and close
- * up resources for them when you can detect that an Iterator is not
- * useful anymore.
+ * Try and close up resources when you can detect that an Iterator is no
+ * longer in use.
* </p>
* <p>
- * Collections are used in two fashions, basically as you see them,
- * and also as "range" for common opperations. You can see this with
- * List.subCollection( Filter ). Existing RnD effort is
- * going towards supporting this kind of use at the FeatureCollection
- * level.
+ * FeatureCollection is used in two fashions, as a result set, where each iterator acts
+ * as a cursor over the content. Also as a predefined query which can be refined
+ * further. An example is using featureCollection.subCollection( Filter ) or
+ * featureCollection.sort( SortBy ) before listing features out of a FeatureCollection.
* </p>
*
- * @see java.util.Collection, org.geotools.Feature
+ * @see org.geotools.Feature
* @author Ian Turton, CCG
* @author Rob Hranac, VFNY
* @author Ian Schneider, USDA-ARS
* @author Jody Garnett, Refractions Research, Inc.
*
- *
* @source $URL$
* @version $Id$
- *
*/
public interface FeatureCollection<T extends FeatureType, F extends Feature> {
/**
@@ -204,87 +198,25 @@
void removeListener(CollectionListener listener) throws NullPointerException;
/**
- * Gets a reference to the type of this feature collection.
+ * The schema for the child feature members of this collection.
* <p>
- * There are several limitations on the use of FeatureType with respect to a FeatureCollection.
- * </p>
- * <p>
- * GML 3.x: all FeatureCollections decend from gml:AbstractFeatureCollectionType:
+ * Represents the most general FeatureType in common to all the features in this
+ * collection.
* <ul>
- * <li>featureMember 0..* allows _Feature or xlink:ref
- * <li>featureMembers 0..1 contents treated as _Feature
- * </ul>
- * The contents defined in this manner is returned the collection
- * iterator() method.
- * </p>
- * <p>
- * GML 3.x: gml:AbstractFeatureCollectionType decends from gml:BoundedFeatureType:
- * <ul>
- * <li>metaDataProperty 0..*
- * <li>description 0..1
- * <li>name 0..*
- * <li>boundedBy 1..1 (required)
- * <li>location 0..1
- * </ul>
- * The value of the boundedBy attribute should be derived from the contents
- * of the collection.
- * </p>
- * <h3>Implementation Notes</h3>
- * <p>
- * There is a difference between getFeatureType() and getSchema(), getSchema is named
- * for historical reasons and reprensets the LCD FeatureType that best represents the
- * contents of this collection.
- * <ul>
- * <li>The degenerate case returns the "_Feature" FeatureType, where the
- * onlything known is that the contents are Features.
- * <li>For a collection backed by a shapefiles (or database tables) the
- * FeatureType returned by getSchema() will complete describe each and every child in the collection.
- * <li>For mixed content FeatureCollections you will need to check the FeatureType
- * of each Feature as it is retrived from the collection
- * </ul>
- * </p>
- *
- * @return A reference to this collections type
- */
-
- //FeatureType getFeatureType();
-
- /**
- * The schema for the child features of this collection.
- * <p>
- * There is a difference between getFeatureType() and getSchema()represents the LCD
- * FeatureType that best represents the contents of this collection.
- * <ul>
- * <li>The degenerate case returns the "_Feature" FeatureType, where the
- * onlything known is that the contents are Features.
* <li>For a collection backed by a shapefiles (or database tables) the FeatureType returned by getSchema() will
* complete describe each and every child in the collection.
* <li>For mixed content FeatureCollections you will need to check the FeatureType of each Feature as it
* is retrived from the collection
+ * <li>The degenerate case returns the "_Feature" FeatureType, where the
+ * only thing known is that the contents are Features.
* </ul>
* </p>
- * <p>
- * The method getSchema() is named for compatability with the geotools 2.0 API. In the
- * Geotools 2.2 time frame we should be able to replace this method with a careful check
- * of getFeatureType() and its attributes.
- * </p>
* @return FeatureType describing the "common" schema to all child features of this collection
*/
T getSchema();
- /**
- * The type for feature members of this FeatureCollection.
- */
- // T getType();
/**
- * The feature member AttributeDescriptor.
- *
- * @return
- */
- // AttributeDescriptor getDescriptor();
-
- /**
* ID used when serializing to GML
*/
String getID();
|
