org.geotools.feature
Interface FeatureCollection<T extends org.opengis.feature.type.FeatureType,F extends org.opengis.feature.Feature>

All Known Subinterfaces:
RandomFeatureAccess, XmlFeatureCollection
All Known Implementing Classes:
AbstractFeatureCollection, AdaptorFeatureCollection, ArcSdeFeatureCollection, CompositeFeatureCollection, ContentFeatureCollection, DataFeatureCollection, DecoratingFeatureCollection, DefaultFeatureCollection, DefaultFeatureResults, EmptyFeatureCollection, FilteringFeatureCollection, ForceCoordinateSystemFeatureResults, GMLFeatureCollection, GridCachingFeatureCollection, IndexedFeatureResults, JDBCFeatureCollection, MappingFeatureCollection, MaxFeaturesFeatureCollection, MemoryFeatureCollection, PostgisFeatureCollection, PreGeneralizedFeatureCollection, ReprojectFeatureResults, ReprojectingFeatureCollection, ReTypingFeatureCollection, SampleDataAccessFeatureCollection, SubFeatureCollection, SubFeatureList, WFSFeatureSource.WFSFeatureResults

public interface FeatureCollection<T extends org.opengis.feature.type.FeatureType,F extends org.opengis.feature.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 34003 2009-09-27 18:12:13Z jive $
Author:
Ian Turton, CCG, Rob Hranac, VFNY, Ian Schneider, USDA-ARS, Jody Garnett, Refractions Research, Inc.
See Also:
java.util.Collection, org.geotools.Feature

Method Summary
 void accepts(org.opengis.feature.FeatureVisitor visitor, org.opengis.util.ProgressListener progress)
          Visit the contents of a feature collection.
 boolean add(F obj)
          Add object to this collection.
 boolean addAll(java.util.Collection<? extends F> collection)
          Add all the objects to the collection.
 boolean addAll(FeatureCollection<? extends T,? extends F> resource)
           
 void addListener(CollectionListener listener)
          Adds a listener for collection events.
 void clear()
           
 void close(FeatureIterator<F> close)
          Clean up after any resources associated with this FeatureIterator in a manner similar to JDO collections.
 void close(java.util.Iterator<F> close)
          Clean up after any resources associated with this itterator in a manner similar to JDO collections.
 boolean contains(java.lang.Object o)
           
 boolean containsAll(java.util.Collection<?> o)
           
 FeatureIterator<F> features()
          Obtain a FeatureIterator of the Features within this collection.
 ReferencedEnvelope getBounds()
          Get the total bounds of this collection which is calculated by doing a union of the bounds of each feature inside of it
 java.lang.String getID()
          ID used when serializing to GML
 T getSchema()
          The schema for the child features of this collection.
 boolean isEmpty()
           
 java.util.Iterator<F> iterator()
          An iterator over this collection, which must be closed after use.
 void purge()
          Deprecated. No longer needed as iterator use by java for each construct not available
 boolean remove(java.lang.Object o)
           
 boolean removeAll(java.util.Collection<?> c)
           
 void removeListener(CollectionListener listener)
          Removes a listener for collection events.
 boolean retainAll(java.util.Collection<?> c)
           
 int size()
           
 FeatureCollection<T,F> sort(org.opengis.filter.sort.SortBy order)
          collection.subCollection( myFilter ).sort( {"foo","bar"} ); collection.subCollection( myFilter ).sort( "bar" ).sort("foo")
 FeatureCollection<T,F> subCollection(org.opengis.filter.Filter filter)
          FeatureCollection "view" indicated by provided filter.
 java.lang.Object[] toArray()
           
<O> O[]
toArray(O[] a)
           
 

Method Detail

features

FeatureIterator<F> 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:

  • a Type-Safe call to: getAttribute(getFeatureType().getAttributeType(0).getName()).iterator();.
  • A Java 5:Iterator<Feature>

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

void close(FeatureIterator<F> close)
Clean up after any resources associated with this FeatureIterator in a manner similar to JDO collections.

Example (safe) use:

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

Parameters:
close -

close

void close(java.util.Iterator<F> close)
Clean up after any resources associated 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 );
 }
 

Parameters:
close -

addListener

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

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.

getSchema

T 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 degenerate case returns the "_Feature" FeatureType, where the onlything known is that the contents are Features.
  • 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.
  • For mixed content FeatureCollections you will need to check the FeatureType of each Feature as it is retrived from the 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.

Returns:
FeatureType describing the "common" schema to all child features of this collection

getID

java.lang.String getID()
ID used when serializing to GML


accepts

void accepts(org.opengis.feature.FeatureVisitor visitor,
             org.opengis.util.ProgressListener progress)
             throws java.io.IOException
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.

Parameters:
visitor - Closure applied to each feature in turn.
progress - Used to report progress, may be used to interrupt the operation
Throws:
java.io.IOException
Since:
2.5

subCollection

FeatureCollection<T,F> subCollection(org.opengis.filter.Filter filter)
FeatureCollection "view" indicated by provided filter.

The contents of the returned FeatureCollection 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 FeatureCollection 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 above recommended use is agreement with the Collections API precident of List.subList( start, end ).

The results of subCollection:

  • are to be considered unordered
  • may be an ordered FeatureList if requested when sortBy is indicated

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

sort

FeatureCollection<T,F> sort(org.opengis.filter.sort.SortBy order)
collection.subCollection( myFilter ).sort( {"foo","bar"} ); collection.subCollection( myFilter ).sort( "bar" ).sort("foo")

Parameters:
order -
Returns:
FeatureCollection sorted in the indicated order

getBounds

ReferencedEnvelope getBounds()
Get the total bounds of this collection which is calculated by doing a union of the bounds of each feature inside of it

Returns:
An Envelope containing the total bounds of this collection.

iterator

java.util.Iterator<F> iterator()
An iterator over this collection, which must be closed after use.

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

Returns:
Iterator

purge

void purge()
Deprecated. No longer needed as iterator use by java for each construct not available

Close any outstanding resources released by this resources.

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


add

boolean add(F obj)
Add object to this collection.

This method is often not impelmented for collections produced as the result of a query.

Returns:
true of the element was added
See Also:
Collection.add(Object)

addAll

boolean addAll(java.util.Collection<? extends F> collection)
Add all the objects to the collection.

This method is often not implemented for collections produced as the results of a query.

See Also:
Collection.addAll(Collection)

addAll

boolean addAll(FeatureCollection<? extends T,? extends F> resource)
See Also:
addAll(Collection)

clear

void clear()
See Also:
Collection.clear()

contains

boolean contains(java.lang.Object o)
See Also:
Collection.contains(Object)

containsAll

boolean containsAll(java.util.Collection<?> o)
See Also:
Collection.containsAll(Collection)

isEmpty

boolean isEmpty()
See Also:
Collection.isEmpty()

remove

boolean remove(java.lang.Object o)
See Also:
Collection.remove(Object)

removeAll

boolean removeAll(java.util.Collection<?> c)
See Also:
Collection.removeAll(Collection)

retainAll

boolean retainAll(java.util.Collection<?> c)
See Also:
Collection.retainAll(Collection)

size

int size()
See Also:
Collection.size()

toArray

java.lang.Object[] toArray()
See Also:
Collection.toArray()

toArray

<O> O[] toArray(O[] a)
See Also:
Collection.toArray(Object[])


Copyright © 1996-2010 Geotools. All Rights Reserved.