org.geotools.feature
Interface FeatureCollection

All Superinterfaces:
java.util.Collection, Feature, FeatureResults, ResourceCollection
All Known Subinterfaces:
FeatureDocument, FeatureList, IndexedFeatureCollection, RandomFeatureAccess
All Known Implementing Classes:
AbstractFeatureCollection, AbstractFeatureCollection, AbstractFeatureList, DataFeatureCollection, DefaultFeatureCollection, MemoryFeatureCollection, SubFeatureCollection, SubFeatureList

public interface FeatureCollection
extends ResourceCollection, FeatureResults, Feature

Represents a collection of features.

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.

FeatureCollection house rules:

In programmer speak a FeatureCollection is a "Bag" with an index based ID.

Life Cycle of Iterator

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.

Notes for FeatureCollection Implementors

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.

Version:
$Id: FeatureCollection.java 17702 2006-01-23 00:08:55Z desruisseaux $
Author:
Ian Turton, CCG, Rob Hranac, VFNY, Ian Schneider, USDA-ARS, Jody Garnett, Refractions Research, Inc.
See Also:
java.util.Collection, org.geotools.Feature

Nested Class Summary
 
Nested classes inherited from class org.geotools.feature.Feature
Feature.NULL
 
Method Summary
 void accepts(FeatureVisitor visitor, ProgressListener progress)
          Will visit the contents of the feature collection.
 void addListener(CollectionListener listener)
          Adds a listener for collection events.
 void close(FeatureIterator close)
          Clean up any resources assocaited with this iterator in a manner similar to JDO collections.
 void close(java.util.Iterator close)
          Clean up after any resources assocaited with this itterator in a manner similar to JDO collections.
 FeatureIterator features()
          Obtain a FeatureIterator of the Features within this collection.
 FeatureType getFeatureType()
          Gets a reference to the type of this feature collection.
 FeatureType getSchema()
          The schema for the child features of this collection.
 void removeListener(CollectionListener listener)
          Removes a listener for collection events.
 FeatureList sort(SortBy order)
          collection.subCollection( myFilter ).sort( {"foo","bar"} ); collection.subCollection( myFilter ).sort( "bar" ).sort("foo")
 FeatureCollection subCollection(Filter filter)
          FeatureCollection "view" indicated by provided filter.
 
Methods inherited from interface org.geotools.data.collection.ResourceCollection
iterator, purge
 
Methods inherited from interface java.util.Collection
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, remove, removeAll, retainAll, size, toArray, toArray
 
Methods inherited from interface org.geotools.data.FeatureResults
collection, getBounds, getCount, reader
 
Methods inherited from interface org.geotools.feature.Feature
getAttribute, getAttribute, getAttributes, getBounds, getDefaultGeometry, getID, getNumberOfAttributes, getParent, setAttribute, setAttribute, setDefaultGeometry, setParent
 

Method Detail

features

public FeatureIterator features()
Obtain a FeatureIterator of the Features within this collection.

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:

Example (safe) use:

 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.

Returns:
A FeatureIterator.

close

public void close(FeatureIterator close)
Clean up any resources assocaited with this iterator in a manner similar to JDO collections.

You must be sure to allow null values, this is because in a try/finally block client code may not be sure if they have actualy succeed in assign a value to an iterator they wish to ensure is closed. By permiting null as an api we prevent a null check in lots of finally statements.

Note: Because of FeatureReader using an interator internally, there is only one implementation of this method that makes any sense:


 public void close( FeatureIterator iterator) {
     if( iterator != null ) iterator.close();
 }
 


close

public void close(java.util.Iterator close)
Clean up after any resources assocaited with this itterator in a manner similar to JDO collections.

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 );
 }
 

Specified by:
close in interface ResourceCollection
Parameters:
close -

addListener

public void addListener(CollectionListener listener)
                 throws java.lang.NullPointerException
Adds a listener for collection events.

When this collection is backed by live data the event notification will follow the guidelines outlined by FeatureListner.

Parameters:
listener - The listener to add
Throws:
java.lang.NullPointerException - If the listener is null.

removeListener

public void removeListener(CollectionListener listener)
                    throws java.lang.NullPointerException
Removes a listener for collection events.

Parameters:
listener - The listener to remove
Throws:
java.lang.NullPointerException - If the listener is null.

getFeatureType

public FeatureType getFeatureType()
Gets a reference to the type of this feature collection.

There are several limitations on the use of FeatureType with respect to a FeatureCollection.

GML 3.x: all FeatureCollections decend from gml:AbstractFeatureCollectionType:

The contents defined in this manner is returned the collection iterator() method.

GML 3.x: gml:AbstractFeatureCollectionType decends from gml:BoundedFeatureType:

The value of the boundedBy attribute should be derived from the contents of the collection.

Implementation Notes

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.

Specified by:
getFeatureType in interface Feature
Returns:
A reference to this collections type

getSchema

public FeatureType getSchema()
The schema for the child features 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.

Specified by:
getSchema in interface FeatureResults
Returns:
FeatureType describing the "common" schema to all child features of this collection

accepts

public void accepts(FeatureVisitor visitor,
                    ProgressListener progress)
             throws java.io.IOException
Will visit the contents of the feature collection.

Note: When performing aggregate calculations please consider using the Filter/Expression/Function API as it may be optimized.

Parameters:
visitor -
Throws:
java.io.IOException

subCollection

public FeatureCollection subCollection(Filter filter)
FeatureCollection "view" indicated by provided filter.

The contents of the returned FeatureCollection are determined by applying the provider Fitler 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 FeatureCollection construct. The FeatureCollections returned really should be considered as a temporary "view" used to control the range of a removeAll, or modify opperation.

Example Use:


 collection.subCollection( filter ).clear();
 
The above recommended use is agreement with the Collections API precident of List.subList( start, end ).

The results of subCollection:

Parameters:
filter -
Returns:
FeatureCollection identified as subset.
See Also:
FeatureList

sort

public FeatureList sort(SortBy order)
collection.subCollection( myFilter ).sort( {"foo","bar"} ); collection.subCollection( myFilter ).sort( "bar" ).sort("foo")

Parameters:
order -
Returns:


Copyright © GeoTools. All Rights Reserved.