* 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. *
** SimpleFeatureCollection house rules: *
*
* 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. *
** Example (safe) use:
* Iterator iterator = collection.iterator();
* try {
* for( Iterator i=collection.iterator(); i.hasNext();){
* Feature feature = (Feature) i.hasNext();
* System.out.println( feature.getID() );
* }
* }
* finally {
* collection.close( iterator );
* }
* * Handy Tip: Although many resource backed collections will choose * to release resources at when the iterator has reached the end of its contents * this is not something you should rely on. *
** 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. *
** 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. *
* * @see java.util.Collection, org.geotools.Feature * @author Ian Turton, CCG * @author Rob Hranac, VFNY * @author Ian Schneider, USDA-ARS * @author Jody Garnett, Refractions Research, Inc. * * @source $URL: http://svn.osgeo.org/geotools/branches/2.7.x/modules/library/api/src/main/java/org/geotools/feature/FeatureCollection.java $ * @version $Id: FeatureCollection.java 37280 2011-05-24 07:53:02Z mbedward $ * */ public interface FeatureCollection
* The implementation of Collection must adhere to the rules of
* fail-fast concurrent modification. In addition (to allow for
* resource backed collections, the close( Iterator )
* method must be called.
*
* * This is almost equivalent to: *
getAttribute(getFeatureType().getAttributeType(0).getName()).iterator();.
* Iterator<Feature>
*
* FeatureIterator iterator=collection.features();
* try {
* while( iterator.hasNext() ){
* Feature feature = iterator.next();
* System.out.println( feature.getID() );
* }
* }
* finally {
* collection.close( iterator );
* }
* * GML Note: The contents of this iterator are considered to be defined by * featureMember tags (and/or the single allowed FeatureMembers tag). * Please see getFeatureType for more details. *
* * @return A FeatureIterator. */ FeatureIterator
* Iterator iterator = collection.iterator();
* try {
* for( Iterator i=collection.iterator(); i.hasNext();){
* Feature feature = i.hasNext();
* System.out.println( feature.getID() );
* }
* }
* finally {
* collection.close( iterator );
* }
*
* Iterator iterator = collection.iterator();
* try {
* for( Iterator i=collection.iterator(); i.hasNext();){
* Feature feature = (Feature) i.hasNext();
* System.out.println( feature.getID() );
* }
* }
* finally {
* collection.close( iterator );
* }
* * There are several limitations on the use of FeatureType with respect to a FeatureCollection. *
** GML 3.x: all FeatureCollections decend from gml:AbstractFeatureCollectionType: *
* GML 3.x: gml:AbstractFeatureCollectionType decends from gml:BoundedFeatureType: *
* 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. *
* There is a difference between getFeatureType() and getSchema()represents the LCD * FeatureType that best represents the contents of this collection. *
* 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. *
* @return FeatureType describing the "common" schema to all child features of this collection */ T getSchema(); /** ID used when serializing to GML */ String getID(); /** * Visit the contents of a feature collection. ** The order of traversal is dependent on the FeatureCollection implementation; some * collections are able to make efficient use of an internal index in order to quickly * visit features located in the same region. *
* * @param visitor Closure applied to each feature in turn. * @param progress Used to report progress, may be used to interrupt the operation * * @since 2.5 */ void accepts(FeatureVisitor visitor, ProgressListener progress) throws IOException; /** * SimpleFeatureCollection "view" indicated by provided filter. ** The contents of the returned SimpleFeatureCollection are determined by * applying the provider Filter to the entire contents of this * FeatureCollection. The result is "live" and modifications will * be shared. *
* This method is used cut down on the number of filter based methods * required for a useful SimpleFeatureCollection construct. The FeatureCollections * returned really should be considered as a temporary "view" used to * control the range of a removeAll, or modify operation. *
* Example Use: *
* collection.subCollection( filter ).clear();
* * The results of subCollection: *
* Collection is not guaranteed to be ordered in any manner. *
*
* The implementation of Collection must adhere to the rules of
* fail-fast concurrent modification. In addition (to allow for
* resource backed collections, the close( Iterator )
* method must be called.
*
*
* Example (safe) use:
* Iterator iterator = collection.iterator();
* try {
* while( iterator.hasNext();){
* Feature feature = (Feature) iterator.hasNext();
* System.out.println( feature.getID() );
* }
* }
* finally {
* collection.close( iterator );
* }
* * This method should be used with great caution, it is however available * to allow the use of the ResourceCollection with algorthims that are * unaware of the need to close iterators after use. *
** Example of using a normal Collections utility method:
* Collections.sort( collection );
* collection.purge();
* * This method is often not impelmented for collections produced as the result of a query. * * @return true of the element was added * @see java.util.Collection#add(Object) */ boolean add(F obj); /** * Add all the objects to the collection. *
* This method is often not implemented for collections produced as the results of a query.
* @see java.util.Collection#addAll(Collection)
*/
boolean addAll(Collection collection);
/** @see #addAll(Collection) */
boolean addAll(FeatureCollection resource);
/** @see java.util.Collection#clear() */
void clear();
/**
* @see java.util.Collection#contains(Object)
*/
boolean contains(Object o);
/**
* @see java.util.Collection#containsAll(Collection)
*/
boolean containsAll(Collection o);
/** @see java.util.Collection#isEmpty() */
boolean isEmpty();
/** @see java.util.Collection#remove(Object) */
boolean remove(Object o);
/** @see java.util.Collection#removeAll(Collection) */
public boolean removeAll(Collection c);
/** @see java.util.Collection#retainAll(Collection) */
public boolean retainAll(Collection c);
/**
* @see java.util.Collection#size()
*/
int size();
/** @see java.util.Collection#toArray() */
Object[] toArray();
/** @see java.util.Collection#toArray(Object[]) */