Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fix Javadoc examples

  • Loading branch information...
commit 6a2e8ef2ef4f849cfb68ed686f4c43177608ed18 1 parent 3a6ff05
@jodygarnett jodygarnett authored
View
63 modules/library/api/src/main/java/org/geotools/data/simple/SimpleFeatureCollection.java
@@ -1,6 +1,7 @@
package org.geotools.data.simple;
import org.geotools.feature.FeatureCollection;
+import org.geotools.feature.FeatureIterator;
import org.opengis.feature.simple.SimpleFeature;
import org.opengis.feature.simple.SimpleFeatureType;
import org.opengis.filter.Filter;
@@ -9,15 +10,67 @@
/**
* Access to "simple" Feature content where each feature has the same SimpleFeatureType.
* <p>
- * Please keep in mind that a FeatureCollection is similar to a result set; and may not
+ * Please keep in mind that a SimpleFeatureCollection is similar to a result set; and may not
* necessarily load everything in to memory. Treat each iterator as a forward only cursor
- * in the JDBC sense; and take care to close iterators when not in use.
- *
- *
+ * in the JDBC sense; and take care to FeatureIterator.close() after use.
+ *
+* <h3>SimpleFeatureIterator close</h3>
+ * <p>
+ * SimpleFeatureCollection provides streaming access with
+ * the following restrictions on use of {@link SimpleFeatureIterator}:
+ * You must call {@link SimpleFeatureIterator#close()}. This allows
+ * FeatureCollection to clean up any operating system resources used
+ * to access information.
+ * </p>
+ * <p>
+ * Example (safe) use:<pre><code>
+ * SimpleFeatureIterator iterator = simpleFeatureCollection.features();
+ * try {
+ * while( iterator.hasNext() ){
+ * SimpleFeature feature = iterator.hasNext();
+ * System.out.println( feature.getID() );
+ * }
+ * }
+ * finally {
+ * iterator.close();
+ * }
+ * </code></pre>
+ * </p>
+ * And in Java 7:<pre><code>
+ * try ( SimpleFeatureIterator iterator = simpleFeatureCollection.features() ){
+ * while( iterator.hasNext() ){
+ * SimpleFeature feature = iterator.hasNext();
+ * System.out.println( feature.getID() );
+ * }
+ * }
+ * </code></pre>
+ * <p>
+ *
* @source $URL$
*/
public interface SimpleFeatureCollection extends FeatureCollection<SimpleFeatureType,SimpleFeature>{
-
+ /**
+ * Obtain a SimpleFeatureIterator of the Features within this SimpleFeatureCollection.
+ * <p>
+ * The implementation of FeatureIterator must adhere to the rules of
+ * fail-fast concurrent modification. In addition (to allow for
+ * resource backed collections) the <code>SimpleFeatureIterator.close()</code>
+ * method must be called.
+ * <p>
+ * Example use:<pre><code>
+ * SimpleFeatureIterator iterator=collection.features();
+ * try {
+ * while( iterator.hasNext() ){
+ * SimpleFeature feature = iterator.next();
+ * System.out.println( feature.getID() );
+ * }
+ * }
+ * finally {
+ * iterator.close();
+ * }
+ * </code></pre>
+ * </p>
+ */
public SimpleFeatureIterator features();
public SimpleFeatureCollection subCollection(Filter filter);
View
48 modules/library/api/src/main/java/org/geotools/feature/FeatureCollection.java
@@ -34,28 +34,26 @@
* Collection of features, often handled as a result set.
* <p>
* 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>Each iterator is considered a connection which my be closed (see example below)</li>
+ * <li>Each iterator is considered a live connection which must 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>
+ * <li>Two Feature instances cannot exist with the same {@link FeatureId}</li>
* </ul>
* </p>
* <p>
* <h3>FeatureIterator close</h3>
* <p>
- * FeatureCollection provides streaming access. With this in mind we have
- * a restriction on the use of {@link FeatureIterator}: You must call
+ * FeatureCollection provides streaming access with the following 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>
- * FeatureIterator iterator = collection.features();
+ * FeatureIterator iterator = featureCollection.features();
* try {
* while( iterator.hasNext() ){
* Feature feature = iterator.hasNext();
@@ -67,6 +65,14 @@
* }
* </code></pre>
* </p>
+ * And in Java 7:<pre><code>
+ * try ( FeatureIterator iterator = featureCollection.features() ){
+ * while( iterator.hasNext() ){
+ * Feature feature = iterator.hasNext();
+ * System.out.println( feature.getID() );
+ * }
+ * }
+ * </code></pre>
* <p>
* Handy Tip: Although many resource backed collections will choose
* to release resources at when the iterator has reached the end of its contents
@@ -74,11 +80,11 @@
* </p>
* <h2>FeatureCollection Implementation Tips</h2>
* <p>
- * Try and close up resources when you can detect that an Iterator is no
+ * Auto close: Try and close up resources when you can detect that an Iterator is no
* longer in use.
* </p>
* <p>
- * FeatureCollection is used in two fashions, as a result set, where each iterator acts
+ * Lazy Connect: 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.
@@ -88,29 +94,21 @@
* @author Ian Turton, CCG
* @author Rob Hranac, VFNY
* @author Ian Schneider, USDA-ARS
- * @author Jody Garnett, Refractions Research, Inc.
+ * @author Jody Garnett, LISAsoft
*
* @source $URL$
* @version $Id$
*/
public interface FeatureCollection<T extends FeatureType, F extends Feature> {
/**
- * Obtain a FeatureIterator<SimpleFeature> of the Features within this collection.
+ * Obtain a FeatureIterator<SimpleFeature> of the Features within this FeatureCollection.
* <p>
- * The implementation of Collection must adhere to the rules of
+ * The implementation of FeatureIterator must adhere to the rules of
* fail-fast concurrent modification. In addition (to allow for
- * resource backed collections, the <code>close( Iterator )</code>
+ * resource backed collections) the <code>FeatureIterator.close()</code>
* method must be called.
* <p>
- *
- * This is almost equivalent to:
- * <ul>
- * <li>a Type-Safe call to:
- * <code>getAttribute(getFeatureType().getAttributeType(0).getName()).iterator();</code>.
- * <li>A Java 5:<code>Iterator&lt;Feature&gt;</code>
- * </ul>
- * </p>
- * Example (safe) use:<pre><code>
+ * Example use:<pre><code>
* FeatureIterator<SimpleFeature> iterator=collection.features();
* try {
* while( iterator.hasNext() ){
@@ -119,7 +117,7 @@
* }
* }
* finally {
- * collection.close( iterator );
+ * iterator.close();
* }
* </code></pre>
* </p>
@@ -251,9 +249,9 @@
*/
int size();
- /** @see java.util.Collection#toArray() */
+ /** @see java.util.Collection#toArray() */
Object[] toArray();
- /** @see java.util.Collection#toArray(Object[]) */
+ /** @see java.util.Collection#toArray(Object[]) */
<O> O[] toArray(O[] a);
}
Please sign in to comment.
Something went wrong with that request. Please try again.